1httpd(3) Erlang Module Definition httpd(3)
2
6 httpd -
7 HTTP server API
8
11 An implementation of an HTTP 1.1 compliant web server, as defined in
12 RFC 2616. Provides web server start options, administrative functions,
13 and an Erlang callback API.
14
16 Type definitions that are used more than once in this module:
17 boolean() = true | false
19 string() = list of ASCII characters
21 path() = string() representing a file or a directory path
23 ip_address() = {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
25 hostname() = string() representing a host, for example, "foo.bar.com"
27 property() = atom()
29
31 A web server can be configured to start when starting the Inets appli‐
32 cation, or dynamically in runtime by calling the Inets application API
33 inets:start(httpd, ServiceConfig) or inets:start(httpd, ServiceConfig,
34 How), see inets(3). The configuration options, also called properties,
35 are as follows:
36 File Properties
38 When the web server is started at application start time, the proper‐
40 ties are to be fetched from a configuration file that can consist of a
41 regular Erlang property list, that is, [{Option, Value}], where Option
42 = property() and Value = term(), followed by a full stop, or for back‐
43 wards compatibility, an Apache-like configuration file. If the web
44 server is started dynamically at runtime, a file can still be specified
45 but also the complete property list.
46 {proplist_file, path()}:
48 If this property is defined, Inets expects to find all other prop‐
49 erties defined in this file. The file must include all properties
50 listed under mandatory properties.
51 {file, path()}:
53 If this property is defined, Inets expects to find all other prop‐
54 erties defined in this file, which uses Apache-like syntax. The
55 file must include all properties listed under mandatory properties.
56 The Apache-like syntax is the property, written as one word where
57 each new word begins with a capital, followed by a white-space,
58 followed by the value, followed by a new line.
59 Example:
61 {server_root, "/urs/local/www"} -> ServerRoot /usr/local/www
63 A few exceptions are documented for each property that behaves dif‐
65 ferently, and the special cases {directory, {path(), PropertyList}}
66 and {security_directory, {Dir, PropertyList}}, are represented as:
67 <Directory Dir>
70 <Properties handled as described above>
71 </Directory>
72 Note:
75 The properties proplist_file and file are mutually exclusive. Also
76 newer properties may not be supported as Apache-like options, this is a
77 legacy feature.
78 Mandatory Properties
81 {port, integer()} :
83 The port that the HTTP server listen to. If zero is specified as
84 port, an arbitrary available port is picked and function
85 httpd:info/2 can be used to determine which port was picked.
86 {server_name, string()}:
88 The name of your server, normally a fully qualified domain name.
89 {server_root, path()}:
91 Defines the home directory of the server, where log files, and so
92 on, can be stored. Relative paths specified in other properties
93 refer to this directory.
94 {document_root, path()}:
96 Defines the top directory for the documents that are available on
97 the HTTP server.
98 Communication Properties
100 {bind_address, ip_address() | hostname() | any}:
102 Default is any. any is denoted * in the Apache-like configuration
103 file.
104 {profile, atom()}:
106 Used together with bind_address and port to uniquely identify a
107 HTTP server. This can be useful in a virtualized environment, where
108 there can be more that one server that has the same bind_address
109 and port. If this property is not explicitly set, it is assumed
110 that the bind_address and portuniquely identifies the HTTP server.
111 {socket_type, ip_comm | {ip_comm, Config::proplist()} | {essl, Con‐
113 fig::proplist()}}:
114 For ip_comm configuration options, see gen_tcp:listen/2, some
115 options that are used internally by httpd cannot be set.
116 For SSL configuration options, see ssl:listen/2.
118 Default is ip_comm.
120 {ipfamily, inet | inet6}:
122 Default is inet, legacy option inet6fb4 no longer makes sense and
123 will be translated to inet.
124 {minimum_bytes_per_second, integer()}:
126 If given, sets a minimum of bytes per second value for connections.
127 If the value is unreached, the socket closes for that connection.
129 The option is good for reducing the risk of "slow DoS" attacks.
131 Erlang Web Server API Modules
133 {modules, [atom()]} :
135 Defines which modules the HTTP server uses when handling requests.
136 Default is [mod_alias, mod_auth, mod_esi, mod_actions, mod_cgi,
137 mod_dir, mod_get, mod_head, mod_log, mod_disk_log]. Notice that
138 some mod-modules are dependent on others, so the order cannot be
139 entirely arbitrary. See the Inets Web Server Modules in the User's
140 Guide for details.
141 Limit properties
143 {customize, atom()}:
145 A callback module to customize the inets HTTP servers behaviour see
146 httpd_custom_api
147 {disable_chunked_transfer_encoding_send, boolean()}:
149 Allows you to disable chunked transfer-encoding when sending a
150 response to an HTTP/1.1 client. Default is false.
151 {keep_alive, boolean()}:
153 Instructs the server whether to use persistent connections when the
154 client claims to be HTTP/1.1 compliant. Default is true.
155 {keep_alive_timeout, integer()}:
157 The number of seconds the server waits for a subsequent request
158 from the client before closing the connection. Default is 150.
159 {max_body_size, integer()}:
161 Limits the size of the message body of an HTTP request. Default is
162 no limit.
163 {max_clients, integer()}:
165 Limits the number of simultaneous requests that can be supported.
166 Default is 150.
167 {max_header_size, integer()}:
169 Limits the size of the message header of an HTTP request. Default
170 is 10240.
171 {max_content_length, integer()}:
173 Maximum content-length in an incoming request, in bytes. Requests
174 with content larger than this are answered with status 413. Default
175 is 100000000 (100 MB).
176 {max_uri_size, integer()}:
178 Limits the size of the HTTP request URI. Default is no limit.
179 {max_keep_alive_request, integer()}:
181 The number of requests that a client can do on one connection. When
182 the server has responded to the number of requests defined by
183 max_keep_alive_requests, the server closes the connection. The
184 server closes it even if there are queued request. Default is no
185 limit.
186 {max_client_body_chunk, integer()}:
188 Enforces chunking of a HTTP PUT or POST body data to be deliverd to
189 the mod_esi callback. Note this is not supported for mod_cgi.
190 Default is no limit e.i the whole body is deliverd as one entity,
191 which could be very memory consuming. mod_esi(3).
192 Administrative Properties
194 {mime_types, [{MimeType, Extension}] | path()}:
196 MimeType = string() and Extension = string(). Files delivered to
197 the client are MIME typed according to RFC 1590. File suffixes are
198 mapped to MIME types before file delivery. The mapping between file
199 suffixes and MIME types can be specified as an Apache-like file or
200 directly in the property list. Such a file can look like the foll‐
201 woing:
202 # MIME type Extension
204 text/html html htm
205 text/plain asc txt
206 Default is [{"html","text/html"},{"htm","text/html"}].
208 {mime_type, string()}:
210 When the server is asked to provide a document type that cannot be
211 determined by the MIME Type Settings, the server uses this default
212 type.
213 {server_admin, string()}:
215 Defines the email-address of the server administrator to be
216 included in any error messages returned by the server.
217 {server_tokens, none|prod|major|minor|minimal|os|full|{private,
219 string()}}:
220 Defines the look of the value of the server header.
221 Example: Assuming the version of Inets is 5.8.1, the server header
223 string can look as follows for the different values of server-
224 tokens:
225 none:
227 "" % A Server: header will not be generated
228 prod:
230 "inets"
231 major:
233 "inets/5"
234 minor:
236 "inets/5.8"
237 minimal:
239 "inets/5.8.1"
240 os:
242 "inets/5.8.1 (unix)"
243 full:
245 "inets/5.8.1 (unix/linux) OTP/R15B"
246 {private, "foo/bar"}:
248 "foo/bar"
249 By default, the value is as before, that is, minimal.
251 {logger, Options::list()}:
253 Currently only one option is supported:
254 {error, ServerID::atom()}:
256 Produces logger events on logger level error under the hierarchi‐
257 cal logger domain: [otp, inets, httpd, ServerID, error] The built
258 in logger formatting function produces log entries from the error
259 reports:
260 #{server_name => string()
262 protocol => internal | 'TCP' | 'TLS' | 'HTTP',
263 transport => "TCP "| "TLS", %% Present when protocol = 'HTTP'
264 uri => string(), %% Present when protocol = 'HTTP' and URI is valid
265 peer => inet:peername(),
266 host => inet:hostname(),
267 reason => term()
268 }
269 An example of a log entry with only default settings of logger
272 =ERROR REPORT==== 9-Oct-2019::09:33:27.350235 ===
274 Server: My Server
275 Protocol: HTTP
276 Transport: TLS
277 URI: /not_there
278 Host: 127.0.1.1:80
279 Peer: 127.0.0.1:45253
280 Reason: [{statuscode,404},{description,"Object Not Found"}]
281 Using this option makes mod_log and mod_disk_log error logs
284 redundant.
285 Add the filter
287 {fun logger_filters:domain/2,
289 {log,equal,[otp,inets, httpd, ServerID, error]}
290 [{kernel,
292 [{logger,
293 [{handler, http_error_test, logger_std_h,
294 #{config => #{ file => "log/http_error.log" },
295 filters => [{inets_httpd, {fun logger_filters:domain/2,
296 {log, equal,
297 [otp, inets, httpd, my_server, error]
298 }}}],
299 filter_default => stop }}]}]}].
300 or if you want to add it to the default logger via an API:
303 logger:add_handler_filter(default,
305 inets_httpd,
306 {fun logger_filters:domain/2,
307 {log, equal,
308 [otp, inets, httpd, my_server, error]}}).
309 {log_format, common | combined}:
311 Defines if access logs are to be written according to the common
312 log format or the extended common log format. The common format is
313 one line looking like this: remotehost rfc931 authuser [date]
314 "request" status bytes.
315 Here:
317 remotehost:
319 Remote.
320 rfc931:
322 The remote username of the client (RFC 931).
323 authuser:
325 The username used for authentication.
326 [date]:
328 Date and time of the request (RFC 1123).
329 "request":
331 The request line as it came from the client (RFC 1945).
332 status:
334 The HTTP status code returned to the client (RFC 1945).
335 bytes:
337 The content-length of the document transferred.
338 The combined format is one line looking like this: remotehost
340 rfc931 authuser [date] "request" status bytes "referer"
341 "user_agent"
342 In addition to the earlier:
344 "referer":
346 The URL the client was on before requesting the URL (if it could
347 not be determined, a minus sign is placed in this field).
348 "user_agent":
350 The software the client claims to be using (if it could not be
351 determined, a minus sign is placed in this field).
352 This affects the access logs written by mod_log and mod_disk_log.
354 {error_log_format, pretty | compact}:
356 Default is pretty. If the error log is meant to be read directly by
357 a human, pretty is the best option.
358 pretty has a format corresponding to:
360 io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).
362 compact has a format corresponding to:
364 io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).
366 This affects the error logs written by mod_log and mod_disk_log.
368 URL Aliasing Properties - Requires mod_alias
370 {alias, {Alias, RealName}}:
372 Alias = string() and RealName = string(). alias allows documents to
373 be stored in the local file system instead of the document_root
374 location. URLs with a path beginning with url-path is mapped to
375 local files beginning with directory-filename, for example:
376 {alias, {"/image", "/ftp/pub/image"}}
378 Access to http://your.server.org/image/foo.gif would refer to the
380 file /ftp/pub/image/foo.gif.
381 {re_write, {Re, Replacement}}:
383 Re = string() and Replacement = string(). re_write allows documents
384 to be stored in the local file system instead of the document_root
385 location. URLs are rewritten by re:replace/3 to produce a path in
386 the local file-system, for example:
387 {re_write, {"^/[~]([^/]+)(.*)$", "/home/\\1/public\\2"}}
389 Access to http://your.server.org/~bob/foo.gif would refer to the
391 file /home/bob/public/foo.gif. In an Apache-like configuration
392 file, Re is separated from Replacement with one single space, and
393 as expected backslashes do not need to be backslash escaped, the
394 same example would become:
395 ReWrite ^/[~]([^/]+)(.*)$ /home/\1/public\2
397 Beware of trailing space in Replacement to be used. If you must
399 have a space in Re, use, for example, the character encoding \040,
400 see re(3).
401 {directory_index, [string()]}:
403 directory_index specifies a list of resources to look for if a
404 client requests a directory using a / at the end of the directory
405 name. file depicts the name of a file in the directory. Several
406 files can be given, in which case the server returns the first it
407 finds, for example:
408 {directory_index, ["index.html", "welcome.html"]}
410 Access to http://your.server.org/docs/ would return
412 http://your.server.org/docs/index.html or
413 http://your.server.org/docs/welcome.html if index.html does not
414 exist.
415 CGI Properties - Requires mod_cgi
417 {script_alias, {Alias, RealName}}:
419 Alias = string() and RealName = string(). Have the same behavior as
420 property alias, except that they also mark the target directory as
421 containing CGI scripts. URLs with a path beginning with url-path
422 are mapped to scripts beginning with directory-filename, for exam‐
423 ple:
424 {script_alias, {"/cgi-bin/", "/web/cgi-bin/"}}
426 Access to http://your.server.org/cgi-bin/foo would cause the server
428 to run the script /web/cgi-bin/foo.
429 {script_re_write, {Re, Replacement}}:
431 Re = string() and Replacement = string(). Have the same behavior as
432 property re_write, except that they also mark the target directory
433 as containing CGI scripts. URLs with a path beginning with url-path
434 are mapped to scripts beginning with directory-filename, for exam‐
435 ple:
436 {script_re_write, {"^/cgi-bin/(\\d+)/", "/web/\\1/cgi-bin/"}}
438 Access to http://your.server.org/cgi-bin/17/foo would cause the
440 server to run the script /web/17/cgi-bin/foo.
441 {script_nocache, boolean()}:
443 If script_nocache is set to true, the HTTP server by default adds
444 the header fields necessary to prevent proxies from caching the
445 page. Generally this is preferred. Default to false.
446 {script_timeout, integer()}:
448 The time in seconds the web server waits between each chunk of data
449 from the script. If the CGI script does not deliver any data before
450 the timeout, the connection to the client is closed. Default is 15.
451 {action, {MimeType, CgiScript}} - requires mod_action:
453 MimeType = string() and CgiScript = string(). action adds an action
454 activating a CGI script whenever a file of a certain MIME type is
455 requested. It propagates the URL and file path of the requested
456 document using the standard CGI PATH_INFO and PATH_TRANSLATED envi‐
457 ronment variables.
458 Example:
460 {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}}
462 {script, {Method, CgiScript}} - requires mod_action:
464 Method = string() and CgiScript = string(). script adds an action
465 activating a CGI script whenever a file is requested using a cer‐
466 tain HTTP method. The method is either GET or POST, as defined in
467 RFC 1945. It propagates the URL and file path of the requested doc‐
468 ument using the standard CGI PATH_INFO and PATH_TRANSLATED environ‐
469 ment variables.
470 Example:
472 {script, {"PUT", "/cgi-bin/put"}}
474 ESI Properties - Requires mod_esi
476 {erl_script_alias, {URLPath, [AllowedModule]}}:
478 URLPath = string() and AllowedModule = atom(). erl_script_alias
479 marks all URLs matching url-path as erl scheme scripts. A matching
480 URL is mapped into a specific module and function, for example:
481 {erl_script_alias, {"/cgi-bin/example", [httpd_example]}}
483 A request to http://your.server.org/cgi-bin/example/httpd_exam‐
485 ple:yahoo would refer to httpd_example:yahoo/3 or, if that does not
486 exist, httpd_example:yahoo/2 and http://your.server.org/cgi-
487 bin/example/other:yahoo would not be allowed to execute.
488 {erl_script_nocache, boolean()}:
490 If erl_script_nocache is set to true, the server adds HTTP header
491 fields preventing proxies from caching the page. This is generally
492 a good idea for dynamic content, as the content often varies
493 between each request. Default is false.
494 {erl_script_timeout, integer()}:
496 If erl_script_timeout sets the time in seconds the server waits
497 between each chunk of data to be delivered through
498 mod_esi:deliver/2. Default is 15. This is only relevant for scripts
499 that use the erl scheme.
500 Log Properties - Requires mod_log
502 {error_log, path()}:
504 Defines the filename of the error log file to be used to log server
505 errors. If the filename does not begin with a slash (/), it is
506 assumed to be relative to the server_root.
507 {security_log, path()}:
509 Defines the filename of the access log file to be used to log secu‐
510 rity events. If the filename does not begin with a slash (/), it is
511 assumed to be relative to the server_root.
512 {transfer_log, path()}:
514 Defines the filename of the access log file to be used to log
515 incoming requests. If the filename does not begin with a slash (/),
516 it is assumed to be relative to the server_root.
517 Disk Log Properties - Requires mod_disk_log
519 {disk_log_format, internal | external}:
521 Defines the file format of the log files. See disk_log for details.
522 If the internal file format is used, the log file is repaired after
523 a crash. When a log file is repaired, data can disappear. When the
524 external file format is used, httpd does not start if the log file
525 is broken. Default is external.
526 {error_disk_log, path()}:
528 Defines the filename of the (disk_log(3)) error log file to be used
529 to log server errors. If the filename does not begin with a slash
530 (/), it is assumed to be relative to the server_root.
531 {error_disk_log_size, {MaxBytes, MaxFiles}}:
533 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
534 ties of the (disk_log(3)) error log file. This file is of type wrap
535 log and max bytes is written to each file and max files is used
536 before the first file is truncated and reused.
537 {security_disk_log, path()}:
539 Defines the filename of the (disk_log(3)) access log file logging
540 incoming security events, that is, authenticated requests. If the
541 filename does not begin with a slash (/), it is assumed to be rela‐
542 tive to the server_root.
543 {security_disk_log_size, {MaxBytes, MaxFiles}}:
545 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
546 ties of the disk_log(3) access log file. This file is of type wrap
547 log and max bytes is written to each file and max files is used
548 before the first file is truncated and reused.
549 {transfer_disk_log, path()}:
551 Defines the filename of the (disk_log(3)) access log file logging
552 incoming requests. If the filename does not begin with a slash (/),
553 it is assumed to be relative to the server_root.
554 {transfer_disk_log_size, {MaxBytes, MaxFiles}}:
556 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
557 ties of the disk_log(3) access log file. This file is of type wrap
558 log and max bytes is written to each file and max files is used
559 before the first file is truncated and reused.
560 Authentication Properties - Requires mod_auth
562 {directory, {path(), [{property(), term()}]}}
564 The properties for directories are as follows:
566 {allow_from, all | [RegxpHostString]}:
568 Defines a set of hosts to be granted access to a given directory,
569 for example:
570 {allow_from, ["123.34.56.11", "150.100.23"]}
572 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
574 allowed access.
575 {deny_from, all | [RegxpHostString]}:
577 Defines a set of hosts to be denied access to a given directory,
578 for example:
579 {deny_from, ["123.34.56.11", "150.100.23"]}
581 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
583 not allowed access.
584 {auth_type, plain | dets | mnesia}:
586 Sets the type of authentication database that is used for the
587 directory. The key difference between the different methods is that
588 dynamic data can be saved when Mnesia and Dets are used. This prop‐
589 erty is called AuthDbType in the Apache-like configuration files.
590 {auth_user_file, path()}:
592 Sets the name of a file containing the list of users and passwords
593 for user authentication. The filename can be either absolute or
594 relative to the server_root. If using the plain storage method,
595 this file is a plain text file where each line contains a username
596 followed by a colon, followed by the non-encrypted password. If
597 usernames are duplicated, the behavior is undefined.
598 Example:
600 ragnar:s7Xxv7
602 edward:wwjau8
603 If the Dets storage method is used, the user database is maintained
605 by Dets and must not be edited by hand. Use the API functions in
606 module mod_auth to create/edit the user database. This directive is
607 ignored if the Mnesia storage method is used. For security reasons,
608 ensure that auth_user_file is stored outside the document tree of
609 the web server. If it is placed in the directory that it protects,
610 clients can download it.
611 {auth_group_file, path()}:
613 Sets the name of a file containing the list of user groups for user
614 authentication. The filename can be either absolute or relative to
615 the server_root. If the plain storage method is used, the group
616 file is a plain text file, where each line contains a group name
617 followed by a colon, followed by the members usernames separated by
618 spaces.
619 Example:
621 group1: bob joe ante
623 If the Dets storage method is used, the group database is main‐
625 tained by Dets and must not be edited by hand. Use the API for mod‐
626 ule mod_auth to create/edit the group database. This directive is
627 ignored if the Mnesia storage method is used. For security reasons,
628 ensure that the auth_group_file is stored outside the document tree
629 of the web server. If it is placed in the directory that it pro‐
630 tects, clients can download it.
631 {auth_name, string()}:
633 Sets the name of the authorization realm (auth-domain) for a direc‐
634 tory. This string informs the client about which username and pass‐
635 word to use.
636 {auth_access_password, string()}:
638 If set to other than "NoPassword", the password is required for all
639 API calls. If the password is set to "DummyPassword", the password
640 must be changed before any other API calls. To secure the authenti‐
641 cating data, the password must be changed after the web server is
642 started. Otherwise it is written in clear text in the configuration
643 file.
644 {require_user, [string()]}:
646 Defines users to grant access to a given directory using a secret
647 password.
648 {require_group, [string()]}:
650 Defines users to grant access to a given directory using a secret
651 password.
652 Htaccess Authentication Properties - Requires mod_htaccess
654 {access_files, [path()]}:
656 Specifies the filenames that are used for access files. When a
657 request comes, every directory in the path to the requested asset
658 are searched after files with the names specified by this parame‐
659 ter. If such a file is found, the file is parsed and the restric‐
660 tions specified in it are applied to the request.
661 Security Properties - Requires mod_security
663 {security_directory, {path(), [{property(), term()}]}}
665 The properties for the security directories are as follows:
667 {data_file, path()}:
669 Name of the security data file. The filename can either be absolute
670 or relative to the server_root. This file is used to store persis‐
671 tent data for module mod_security.
672 {max_retries, integer()}:
674 Specifies the maximum number of attempts to authenticate a user
675 before the user is blocked out. If a user successfully authenti‐
676 cates while blocked, the user receives a 403 (Forbidden) response
677 from the server. If the user makes a failed attempt while blocked,
678 the server returns 401 (Unauthorized), for security reasons.
679 Default is 3. Can be set to infinity.
680 {block_time, integer()}:
682 Specifies the number of minutes a user is blocked. After this time‐
683 has passed, the user automatically regains access. Default is 60.
684 {fail_expire_time, integer()}:
686 Specifies the number of minutes a failed user authentication is
687 remembered. If a user authenticates after this time has passed, the
688 previous failed authentications are forgotten. Default is 30.
689 {auth_timeout, integer()}:
691 Specifies the number of seconds a successful user authentication
692 is remembered. After this time has passed, the authentication is no
693 longer reported. Default is 30.
694
696 info(Pid) ->
697 info(Pid, Properties) -> [{Option, Value}]
698 Types:
700 Properties = [property()]
702 Option = property()
703 Value = term()
704 Fetches information about the HTTP server. When called with only
706 the pid, all properties are fetched. When called with a list of
707 specific properties, they are fetched. The available properties
708 are the same as the start options of the server.
709 Note:
711 Pid is the pid returned from inets:start/[2,3]. Can also be
712 retrieved form inets:services/0 and inets:services_info/0, see
713 inets(3).
714 info(Address, Port) ->
717 info(Address, Port, Profile) ->
718 info(Address, Port, Profile, Properties) -> [{Option, Value}]
719 info(Address, Port, Properties) -> [{Option, Value}]
720 Types:
722 Address = ip_address()
724 Port = integer()
725 Profile = atom()
726 Properties = [property()]
727 Option = property()
728 Value = term()
729 Fetches information about the HTTP server. When called with only
731 Address and Port, all properties are fetched. When called with a
732 list of specific properties, they are fetched. The available
733 properties are the same as the start options of the server.
734 Note:
736 The address must be the IP address and cannot be the hostname.
737 reload_config(Config, Mode) -> ok | {error, Reason}
740 Types:
742 Config = path() | [{Option, Value}]
744 Option = property()
745 Value = term()
746 Mode = non_disturbing | disturbing
747 Reloads the HTTP server configuration without restarting the
749 server. Incoming requests are answered with a temporary down
750 message during the reload time.
751 Note:
753 Available properties are the same as the start options of the
754 server, but the properties bind_address and port cannot be
755 changed.
756 If mode is disturbing, the server is blocked forcefully, all
759 ongoing requests terminates, and the reload starts immediately.
760 If mode is non-disturbing, no new connections are accepted, but
761 ongoing requests are allowed to complete before the reload is
762 done.
763
765 The Erlang web server API data types are as follows:
766 ModData = #mod{}
768 -record(mod, {
770 data = [],
771 socket_type = ip_comm,
772 socket,
773 config_db,
774 method,
775 absolute_uri,
776 request_uri,
777 http_version,
778 request_line,
779 parsed_header = [],
780 entity_body,
781 connection
782 }).
783 To acess the record in your callback-module use:
785 -include_lib("inets/include/httpd.hrl").
787 The fields of record mod have the following meaning:
789 data:
791 Type [{InteractionKey,InteractionValue}] is used to propagate data
792 between modules. Depicted interaction_data() in function type dec‐
793 larations.
794 socket_type:
796 socket_type() indicates whether it is an IP socket or an ssl
797 socket.
798 socket:
800 The socket, in format ip_comm or ssl, depending on socket_type.
801 config_db:
803 The config file directives stored as key-value tuples in an ETS ta‐
804 ble. Depicted config_db() in function type declarations.
805 method:
807 Type "GET" | "POST" | "HEAD" | "TRACE", that is, the HTTP method.
808 absolute_uri:
810 If the request is an HTTP/1.1 request, the URI can be in the abso‐
811 lute URI format. In that case, httpd saves the absolute URI in this
812 field. An Example of an absolute URI is "http://Server‐
813 Name:Part/cgi-bin/find.pl?person=jocke"
814 request_uri:
816 The Request-URI as defined in RFC 1945, for example, "/cgi-
817 bin/find.pl?person=jocke".
818 http_version:
820 The HTTP version of the request, that is, "HTTP/0.9", "HTTP/1.0",
821 or "HTTP/1.1".
822 request_line:
824 The Request-Line as defined inRFC 1945, for example, "GET /cgi-
825 bin/find.pl?person=jocke HTTP/1.0".
826 parsed_header:
828 Type [{HeaderKey,HeaderValue}]. parsed_header contains all HTTP
829 header fields from the HTTP request stored in a list as key-value
830 tuples. See RFC 2616 for a listing of all header fields. For exam‐
831 ple, the date field is stored as {"date","Wed, 15 Oct 1997 14:35:17
832 GMT"}. RFC 2616 defines that HTTP is a case-insensitive protocol
833 and the header fields can be in lower case or upper case. httpd
834 ensures that all header field names are in lower case.
835 entity_body:
837 The entity-Body as defined in RFC 2616, for example, data sent from
838 a CGI script using the POST method.
839 connection:
841 true | false. If set to true, the connection to the client is a
842 persistent connection and is not closed when the request is served.
843
846 Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break,
847 NewData} | done
848 Types:
850 OldData = list()
852 NewData = [{response,{StatusCode,Body}}]
853 | [{response,{response,Head,Body}}]
854 | [{response,{already_sent,Statuscode,Size}}]
855 StatusCode = integer()
856 Body = io_list() | nobody | {Fun, Arg}
857 Head = [HeaderOption]
858 HeaderOption = {Option, Value} | {code, StatusCode}
859 Option = accept_ranges | allow
860 | cache_control | content_MD5
861 | content_encoding | content_language
862 | content_length | content_location
863 | content_range | content_type | date
864 | etag | expires | last_modified
865 | location | pragma | retry_after
866 | server | trailer | transfer_encoding
867 Value = string()
868 Fun = fun( Arg ) -> sent| close | Body
869 Arg = [term()]
870 When a valid request reaches httpd, it calls do/1 in each mod‐
872 ule, defined by the configuration option of Module. The function
873 can generate data for other modules or a response that can be
874 sent back to the client.
875 The field data in ModData is a list. This list is the list
877 returned from the last call to do/1.
878 Body is the body of the HTTP response that is sent back to the
880 client. An appropriate header is appended to the message. Sta‐
881 tusCode is the status code of the response, see RFC 2616 for the
882 appropriate values.
883 Head is a key value list of HTTP header fields. The server con‐
885 structs an HTTP header from this data. See RFC 2616 for the
886 appropriate value for each header field. If the client is an
887 HTTP/1.0 client, the server filters the list so that only
888 HTTP/1.0 header fields are sent back to the client.
889 If Body is returned and equal to {Fun,Arg}, the web server tries
891 apply/2 on Fun with Arg as argument. The web server expects that
892 the fun either returns a list (Body) that is an HTTP repsonse,
893 or the atom sent if the HTTP response is sent back to the
894 client. If close is returned from the fun, something has gone
895 wrong and the server signals this to the client by closing the
896 connection.
897 Module:load(Line, AccIn)-> eof | ok | {ok, AccOut} | {ok, AccOut,
899 {Option, Value}} | {ok, AccOut, [{Option, Value}]} | {error, Reason}
900 Types:
902 Line = string()
904 AccIn = [{Option, Value}]
905 AccOut = [{Option, Value}]
906 Option = property()
907 Value = term()
908 Reason = term()
909 Converts a line in an Apache-like configuration file to an
911 {Option, Value} tuple. Some more complex configuration options,
912 such as directory and security_directory, create an accumulator.
913 This function only needs clauses for the options implemented by
914 this particular callback module.
915 Module:remove(ConfigDB) -> ok | {error, Reason}
917 Types:
919 ConfigDB = ets_table()
921 Reason = term()
922 When httpd is shut down, it tries to execute remove/1 in each
924 Erlang web server callback module. The programmer can use this
925 function to clean up resources created in the store function.
926 Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} |
928 {error, Reason}
929 Types:
931 Line = string()
933 Option = property()
934 Config = [{Option, Value}]
935 Value = term()
936 Reason = term()
937 Checks the validity of the configuration options before saving
939 them in the internal database. This function can also have a
940 side effect, that is, setup of necessary extra resources implied
941 by the configuration option. It can also resolve possible depen‐
942 dencies among configuration options by changing the value of the
943 option. This function only needs clauses for the options imple‐
944 mented by this particular callback module.
945
948 parse_query(QueryString) -> [{Key,Value}]
949 Types:
951 QueryString = string()
953 Key = string()
954 Value = string()
955 parse_query/1 parses incoming data to erl and eval scripts (see
957 mod_esi(3)) as defined in the standard URL format, that is, '+'
958 becomes 'space' and decoding of hexadecimal characters (%xx).
959
961 RFC 2616, inets(3), ssl(3)
962Ericsson AB inets 7.1.3 httpd(3)
