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 {eval_script_alias, {URLPath, [AllowedModule]}}:
502 URLPath = string() and AllowedModule = atom(). Same as
503 erl_script_alias but for scripts using the eval scheme. This is
504 only supported for backwards compatibility. The eval scheme is dep‐
505 recated.
506 Log Properties - Requires mod_log
508 {error_log, path()}:
510 Defines the filename of the error log file to be used to log server
511 errors. If the filename does not begin with a slash (/), it is
512 assumed to be relative to the server_root.
513 {security_log, path()}:
515 Defines the filename of the access log file to be used to log secu‐
516 rity events. If the filename does not begin with a slash (/), it is
517 assumed to be relative to the server_root.
518 {transfer_log, path()}:
520 Defines the filename of the access log file to be used to log
521 incoming requests. If the filename does not begin with a slash (/),
522 it is assumed to be relative to the server_root.
523 Disk Log Properties - Requires mod_disk_log
525 {disk_log_format, internal | external}:
527 Defines the file format of the log files. See disk_log for details.
528 If the internal file format is used, the log file is repaired after
529 a crash. When a log file is repaired, data can disappear. When the
530 external file format is used, httpd does not start if the log file
531 is broken. Default is external.
532 {error_disk_log, path()}:
534 Defines the filename of the (disk_log(3)) error log file to be used
535 to log server errors. If the filename does not begin with a slash
536 (/), it is assumed to be relative to the server_root.
537 {error_disk_log_size, {MaxBytes, MaxFiles}}:
539 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
540 ties of the (disk_log(3)) error log file. This file is of type wrap
541 log and max bytes is written to each file and max files is used
542 before the first file is truncated and reused.
543 {security_disk_log, path()}:
545 Defines the filename of the (disk_log(3)) access log file logging
546 incoming security events, that is, authenticated requests. If the
547 filename does not begin with a slash (/), it is assumed to be rela‐
548 tive to the server_root.
549 {security_disk_log_size, {MaxBytes, MaxFiles}}:
551 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
552 ties of the disk_log(3) access log file. This file is of type wrap
553 log and max bytes is written to each file and max files is used
554 before the first file is truncated and reused.
555 {transfer_disk_log, path()}:
557 Defines the filename of the (disk_log(3)) access log file logging
558 incoming requests. If the filename does not begin with a slash (/),
559 it is assumed to be relative to the server_root.
560 {transfer_disk_log_size, {MaxBytes, MaxFiles}}:
562 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
563 ties of the disk_log(3) access log file. This file is of type wrap
564 log and max bytes is written to each file and max files is used
565 before the first file is truncated and reused.
566 Authentication Properties - Requires mod_auth
568 {directory, {path(), [{property(), term()}]}}
570 The properties for directories are as follows:
572 {allow_from, all | [RegxpHostString]}:
574 Defines a set of hosts to be granted access to a given directory,
575 for example:
576 {allow_from, ["123.34.56.11", "150.100.23"]}
578 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
580 allowed access.
581 {deny_from, all | [RegxpHostString]}:
583 Defines a set of hosts to be denied access to a given directory,
584 for example:
585 {deny_from, ["123.34.56.11", "150.100.23"]}
587 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
589 not allowed access.
590 {auth_type, plain | dets | mnesia}:
592 Sets the type of authentication database that is used for the
593 directory. The key difference between the different methods is that
594 dynamic data can be saved when Mnesia and Dets are used. This prop‐
595 erty is called AuthDbType in the Apache-like configuration files.
596 {auth_user_file, path()}:
598 Sets the name of a file containing the list of users and passwords
599 for user authentication. The filename can be either absolute or
600 relative to the server_root. If using the plain storage method,
601 this file is a plain text file where each line contains a username
602 followed by a colon, followed by the non-encrypted password. If
603 usernames are duplicated, the behavior is undefined.
604 Example:
606 ragnar:s7Xxv7
608 edward:wwjau8
609 If the Dets storage method is used, the user database is maintained
611 by Dets and must not be edited by hand. Use the API functions in
612 module mod_auth to create/edit the user database. This directive is
613 ignored if the Mnesia storage method is used. For security reasons,
614 ensure that auth_user_file is stored outside the document tree of
615 the web server. If it is placed in the directory that it protects,
616 clients can download it.
617 {auth_group_file, path()}:
619 Sets the name of a file containing the list of user groups for user
620 authentication. The filename can be either absolute or relative to
621 the server_root. If the plain storage method is used, the group
622 file is a plain text file, where each line contains a group name
623 followed by a colon, followed by the members usernames separated by
624 spaces.
625 Example:
627 group1: bob joe ante
629 If the Dets storage method is used, the group database is main‐
631 tained by Dets and must not be edited by hand. Use the API for mod‐
632 ule mod_auth to create/edit the group database. This directive is
633 ignored if the Mnesia storage method is used. For security reasons,
634 ensure that the auth_group_file is stored outside the document tree
635 of the web server. If it is placed in the directory that it pro‐
636 tects, clients can download it.
637 {auth_name, string()}:
639 Sets the name of the authorization realm (auth-domain) for a direc‐
640 tory. This string informs the client about which username and pass‐
641 word to use.
642 {auth_access_password, string()}:
644 If set to other than "NoPassword", the password is required for all
645 API calls. If the password is set to "DummyPassword", the password
646 must be changed before any other API calls. To secure the authenti‐
647 cating data, the password must be changed after the web server is
648 started. Otherwise it is written in clear text in the configuration
649 file.
650 {require_user, [string()]}:
652 Defines users to grant access to a given directory using a secret
653 password.
654 {require_group, [string()]}:
656 Defines users to grant access to a given directory using a secret
657 password.
658 Htaccess Authentication Properties - Requires mod_htaccess
660 {access_files, [path()]}:
662 Specifies the filenames that are used for access files. When a
663 request comes, every directory in the path to the requested asset
664 are searched after files with the names specified by this parame‐
665 ter. If such a file is found, the file is parsed and the restric‐
666 tions specified in it are applied to the request.
667 Security Properties - Requires mod_security
669 {security_directory, {path(), [{property(), term()}]}}
671 The properties for the security directories are as follows:
673 {data_file, path()}:
675 Name of the security data file. The filename can either be absolute
676 or relative to the server_root. This file is used to store persis‐
677 tent data for module mod_security.
678 {max_retries, integer()}:
680 Specifies the maximum number of attempts to authenticate a user
681 before the user is blocked out. If a user successfully authenti‐
682 cates while blocked, the user receives a 403 (Forbidden) response
683 from the server. If the user makes a failed attempt while blocked,
684 the server returns 401 (Unauthorized), for security reasons.
685 Default is 3. Can be set to infinity.
686 {block_time, integer()}:
688 Specifies the number of minutes a user is blocked. After this time‐
689 has passed, the user automatically regains access. Default is 60.
690 {fail_expire_time, integer()}:
692 Specifies the number of minutes a failed user authentication is
693 remembered. If a user authenticates after this time has passed, the
694 previous failed authentications are forgotten. Default is 30.
695 {auth_timeout, integer()}:
697 Specifies the number of seconds a successful user authentication
698 is remembered. After this time has passed, the authentication is no
699 longer reported. Default is 30.
700
702 info(Pid) ->
703 info(Pid, Properties) -> [{Option, Value}]
704 Types:
706 Properties = [property()]
708 Option = property()
709 Value = term()
710 Fetches information about the HTTP server. When called with only
712 the pid, all properties are fetched. When called with a list of
713 specific properties, they are fetched. The available properties
714 are the same as the start options of the server.
715 Note:
717 Pid is the pid returned from inets:start/[2,3]. Can also be
718 retrieved form inets:services/0 and inets:services_info/0, see
719 inets(3).
720 info(Address, Port) ->
723 info(Address, Port, Profile) ->
724 info(Address, Port, Profile, Properties) -> [{Option, Value}]
725 info(Address, Port, Properties) -> [{Option, Value}]
726 Types:
728 Address = ip_address()
730 Port = integer()
731 Profile = atom()
732 Properties = [property()]
733 Option = property()
734 Value = term()
735 Fetches information about the HTTP server. When called with only
737 Address and Port, all properties are fetched. When called with a
738 list of specific properties, they are fetched. The available
739 properties are the same as the start options of the server.
740 Note:
742 The address must be the IP address and cannot be the hostname.
743 reload_config(Config, Mode) -> ok | {error, Reason}
746 Types:
748 Config = path() | [{Option, Value}]
750 Option = property()
751 Value = term()
752 Mode = non_disturbing | disturbing
753 Reloads the HTTP server configuration without restarting the
755 server. Incoming requests are answered with a temporary down
756 message during the reload time.
757 Note:
759 Available properties are the same as the start options of the
760 server, but the properties bind_address and port cannot be
761 changed.
762 If mode is disturbing, the server is blocked forcefully, all
765 ongoing requests terminates, and the reload starts immediately.
766 If mode is non-disturbing, no new connections are accepted, but
767 ongoing requests are allowed to complete before the reload is
768 done.
769
771 The Erlang web server API data types are as follows:
772 ModData = #mod{}
774 -record(mod, {
776 data = [],
777 socket_type = ip_comm,
778 socket,
779 config_db,
780 method,
781 absolute_uri,
782 request_uri,
783 http_version,
784 request_line,
785 parsed_header = [],
786 entity_body,
787 connection
788 }).
789 To acess the record in your callback-module use:
791 -include_lib("inets/include/httpd.hrl").
793 The fields of record mod have the following meaning:
795 data:
797 Type [{InteractionKey,InteractionValue}] is used to propagate data
798 between modules. Depicted interaction_data() in function type dec‐
799 larations.
800 socket_type:
802 socket_type() indicates whether it is an IP socket or an ssl
803 socket.
804 socket:
806 The socket, in format ip_comm or ssl, depending on socket_type.
807 config_db:
809 The config file directives stored as key-value tuples in an ETS ta‐
810 ble. Depicted config_db() in function type declarations.
811 method:
813 Type "GET" | "POST" | "HEAD" | "TRACE", that is, the HTTP method.
814 absolute_uri:
816 If the request is an HTTP/1.1 request, the URI can be in the abso‐
817 lute URI format. In that case, httpd saves the absolute URI in this
818 field. An Example of an absolute URI is "http://Server‐
819 Name:Part/cgi-bin/find.pl?person=jocke"
820 request_uri:
822 The Request-URI as defined in RFC 1945, for example, "/cgi-
823 bin/find.pl?person=jocke".
824 http_version:
826 The HTTP version of the request, that is, "HTTP/0.9", "HTTP/1.0",
827 or "HTTP/1.1".
828 request_line:
830 The Request-Line as defined inRFC 1945, for example, "GET /cgi-
831 bin/find.pl?person=jocke HTTP/1.0".
832 parsed_header:
834 Type [{HeaderKey,HeaderValue}]. parsed_header contains all HTTP
835 header fields from the HTTP request stored in a list as key-value
836 tuples. See RFC 2616 for a listing of all header fields. For exam‐
837 ple, the date field is stored as {"date","Wed, 15 Oct 1997 14:35:17
838 GMT"}. RFC 2616 defines that HTTP is a case-insensitive protocol
839 and the header fields can be in lower case or upper case. httpd
840 ensures that all header field names are in lower case.
841 entity_body:
843 The entity-Body as defined in RFC 2616, for example, data sent from
844 a CGI script using the POST method.
845 connection:
847 true | false. If set to true, the connection to the client is a
848 persistent connection and is not closed when the request is served.
849
852 Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break,
853 NewData} | done
854 Types:
856 OldData = list()
858 NewData = [{response,{StatusCode,Body}}]
859 | [{response,{response,Head,Body}}]
860 | [{response,{already_sent,Statuscode,Size}}]
861 StatusCode = integer()
862 Body = io_list() | nobody | {Fun, Arg}
863 Head = [HeaderOption]
864 HeaderOption = {Option, Value} | {code, StatusCode}
865 Option = accept_ranges | allow
866 | cache_control | content_MD5
867 | content_encoding | content_language
868 | content_length | content_location
869 | content_range | content_type | date
870 | etag | expires | last_modified
871 | location | pragma | retry_after
872 | server | trailer | transfer_encoding
873 Value = string()
874 Fun = fun( Arg ) -> sent| close | Body
875 Arg = [term()]
876 When a valid request reaches httpd, it calls do/1 in each mod‐
878 ule, defined by the configuration option of Module. The function
879 can generate data for other modules or a response that can be
880 sent back to the client.
881 The field data in ModData is a list. This list is the list
883 returned from the last call to do/1.
884 Body is the body of the HTTP response that is sent back to the
886 client. An appropriate header is appended to the message. Sta‐
887 tusCode is the status code of the response, see RFC 2616 for the
888 appropriate values.
889 Head is a key value list of HTTP header fields. The server con‐
891 structs an HTTP header from this data. See RFC 2616 for the
892 appropriate value for each header field. If the client is an
893 HTTP/1.0 client, the server filters the list so that only
894 HTTP/1.0 header fields are sent back to the client.
895 If Body is returned and equal to {Fun,Arg}, the web server tries
897 apply/2 on Fun with Arg as argument. The web server expects that
898 the fun either returns a list (Body) that is an HTTP repsonse,
899 or the atom sent if the HTTP response is sent back to the
900 client. If close is returned from the fun, something has gone
901 wrong and the server signals this to the client by closing the
902 connection.
903 Module:load(Line, AccIn)-> eof | ok | {ok, AccOut} | {ok, AccOut,
905 {Option, Value}} | {ok, AccOut, [{Option, Value}]} | {error, Reason}
906 Types:
908 Line = string()
910 AccIn = [{Option, Value}]
911 AccOut = [{Option, Value}]
912 Option = property()
913 Value = term()
914 Reason = term()
915 Converts a line in an Apache-like configuration file to an
917 {Option, Value} tuple. Some more complex configuration options,
918 such as directory and security_directory, create an accumulator.
919 This function only needs clauses for the options implemented by
920 this particular callback module.
921 Module:remove(ConfigDB) -> ok | {error, Reason}
923 Types:
925 ConfigDB = ets_table()
927 Reason = term()
928 When httpd is shut down, it tries to execute remove/1 in each
930 Erlang web server callback module. The programmer can use this
931 function to clean up resources created in the store function.
932 Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} |
934 {error, Reason}
935 Types:
937 Line = string()
939 Option = property()
940 Config = [{Option, Value}]
941 Value = term()
942 Reason = term()
943 Checks the validity of the configuration options before saving
945 them in the internal database. This function can also have a
946 side effect, that is, setup of necessary extra resources implied
947 by the configuration option. It can also resolve possible depen‐
948 dencies among configuration options by changing the value of the
949 option. This function only needs clauses for the options imple‐
950 mented by this particular callback module.
951
954 parse_query(QueryString) -> [{Key,Value}]
955 Types:
957 QueryString = string()
959 Key = string()
960 Value = string()
961 parse_query/1 parses incoming data to erl and eval scripts (see
963 mod_esi(3)) as defined in the standard URL format, that is, '+'
964 becomes 'space' and decoding of hexadecimal characters (%xx).
965
967 RFC 2616, inets(3), ssl(3)
968Ericsson AB inets 7.1.1 httpd(3)
