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. If the web
43 server is started dynamically at runtime, a file can still be specified
44 but also the complete property list.
45 {proplist_file, path()}:
47 If this property is defined, Inets expects to find all other prop‐
48 erties defined in this file. The file must include all properties
49 listed under mandatory properties.
50 Note:
52 Note support for legacy configuration file with Apache syntax is
53 dropped in OTP-23.
54 Mandatory Properties
57 {port, integer()} :
59 The port that the HTTP server listen to. If zero is specified as
60 port, an arbitrary available port is picked and function
61 httpd:info/2 can be used to determine which port was picked.
62 {server_name, string()}:
64 The name of your server, normally a fully qualified domain name.
65 {server_root, path()}:
67 Defines the home directory of the server, where log files, and so
68 on, can be stored. Relative paths specified in other properties re‐
69 fer to this directory.
70 {document_root, path()}:
72 Defines the top directory for the documents that are available on
73 the HTTP server.
74 Communication Properties
76 {bind_address, ip_address() | hostname() | any}:
78 Default is any
79 {profile, atom()}:
81 Used together with bind_address and port to uniquely identify a
82 HTTP server. This can be useful in a virtualized environment, where
83 there can be more that one server that has the same bind_address
84 and port. If this property is not explicitly set, it is assumed
85 that the bind_address and port uniquely identifies the HTTP server.
86 {socket_type, ip_comm | {ip_comm, Config::proplist()} | {ssl, Con‐
88 fig::proplist()}}:
89 For ip_comm configuration options, see gen_tcp:listen/2, some op‐
90 tions that are used internally by httpd cannot be set.
91 For SSL configuration options, see ssl:listen/2.
93 Default is ip_comm.
95 Note:
97 OTP-25 deprecates the communication properties {socket_type, ip_comm
98 | {ip_comm, Config::proplist()} | {essl, Config::proplist()}} replac‐
99 ing it by {socket_type, ip_comm | {ip_comm, Config::proplist()} |
100 {ssl, Config::proplist()}}.
101 {ipfamily, inet | inet6}:
104 Default is inet, legacy option inet6fb4 no longer makes sense and
105 will be translated to inet.
106 {minimum_bytes_per_second, integer()}:
108 If given, sets a minimum of bytes per second value for connections.
109 If the value is unreached, the socket closes for that connection.
111 The option is good for reducing the risk of "slow DoS" attacks.
113 Erlang Web Server API Modules
115 {modules, [atom()]} :
117 Defines which modules the HTTP server uses when handling requests.
118 Default is [mod_alias, mod_auth, mod_esi, mod_actions, mod_cgi,
119 mod_dir, mod_get, mod_head, mod_log, mod_disk_log]. Notice that
120 some mod-modules are dependent on others, so the order cannot be
121 entirely arbitrary. See the Inets Web Server Modules in the User's
122 Guide for details.
123 Limit properties
125 {customize, atom()}:
127 A callback module to customize the inets HTTP servers behaviour see
128 httpd_custom_api
129 {disable_chunked_transfer_encoding_send, boolean()}:
131 Allows you to disable chunked transfer-encoding when sending a re‐
132 sponse to an HTTP/1.1 client. Default is false.
133 {keep_alive, boolean()}:
135 Instructs the server whether to use persistent connections when the
136 client claims to be HTTP/1.1 compliant. Default is true.
137 {keep_alive_timeout, integer()}:
139 The number of seconds the server waits for a subsequent request
140 from the client before closing the connection. Default is 150.
141 {max_body_size, integer()}:
143 Limits the size of the message body of an HTTP request. Default is
144 no limit.
145 {max_clients, integer()}:
147 Limits the number of simultaneous requests that can be supported.
148 Default is 150.
149 {max_header_size, integer()}:
151 Limits the size of the message header of an HTTP request. Default
152 is 10240.
153 {max_content_length, integer()}:
155 Maximum content-length in an incoming request, in bytes. Requests
156 with content larger than this are answered with status 413. Default
157 is 100000000 (100 MB).
158 {max_uri_size, integer()}:
160 Limits the size of the HTTP request URI. Default is no limit.
161 {max_keep_alive_request, integer()}:
163 The number of requests that a client can do on one connection. When
164 the server has responded to the number of requests defined by
165 max_keep_alive_requests, the server closes the connection. The
166 server closes it even if there are queued request. Default is no
167 limit.
168 {max_client_body_chunk, integer()}:
170 Enforces chunking of a HTTP PUT or POST body data to be delivered
171 to the mod_esi callback. Note this is not supported for mod_cgi.
172 Default is no limit e.i the whole body is delivered as one entity,
173 which could be very memory consuming. mod_esi(3).
174 Administrative Properties
176 {mime_types, [{MimeType, Extension}] | path()}:
178 MimeType = string() and Extension = string(). Files delivered to
179 the client are MIME typed according to RFC 1590. File suffixes are
180 mapped to MIME types before file delivery. The mapping between file
181 suffixes and MIME types can be specified in the property list.
182 Default is [{"html","text/html"},{"htm","text/html"}].
184 {mime_type, string()}:
186 When the server is asked to provide a document type that cannot be
187 determined by the MIME Type Settings, the server uses this default
188 type.
189 {server_admin, string()}:
191 Defines the email-address of the server administrator to be in‐
192 cluded in any error messages returned by the server.
193 {server_tokens, none|prod|major|minor|minimal|os|full|{private,
195 string()}}:
196 Defines the look of the value of the server header.
197 Example: Assuming the version of Inets is 5.8.1, the server header
199 string can look as follows for the different values of server-to‐
200 kens:
201 none:
203 "" % A Server: header will not be generated
204 prod:
206 "inets"
207 major:
209 "inets/5"
210 minor:
212 "inets/5.8"
213 minimal:
215 "inets/5.8.1"
216 os:
218 "inets/5.8.1 (unix)"
219 full:
221 "inets/5.8.1 (unix/linux) OTP/R15B"
222 {private, "foo/bar"}:
224 "foo/bar"
225 By default, the value is as before, that is, minimal.
227 {logger, Options::list()}:
229 Currently only one option is supported:
230 {error, ServerID::atom()}:
232 Produces logger events on logger level error under the hierarchi‐
233 cal logger domain: [otp, inets, httpd, ServerID, error] The built
234 in logger formatting function produces log entries from the error
235 reports:
236 #{server_name => string()
238 protocol => internal | 'TCP' | 'TLS' | 'HTTP',
239 transport => "TCP "| "TLS", %% Present when protocol = 'HTTP'
240 uri => string(), %% Present when protocol = 'HTTP' and URI is valid
241 peer => inet:peername(),
242 host => inet:hostname(),
243 reason => term()
244 }
245 An example of a log entry with only default settings of logger
248 =ERROR REPORT==== 9-Oct-2019::09:33:27.350235 ===
250 Server: My Server
251 Protocol: HTTP
252 Transport: TLS
253 URI: /not_there
254 Host: 127.0.1.1:80
255 Peer: 127.0.0.1:45253
256 Reason: [{statuscode,404},{description,"Object Not Found"}]
257 Using this option makes mod_log and mod_disk_log error logs re‐
260 dundant.
261 Add the filter
263 {fun logger_filters:domain/2,
265 {log,equal,[otp,inets, httpd, ServerID, error]}
266 [{kernel,
268 [{logger,
269 [{handler, http_error_test, logger_std_h,
270 #{config => #{ file => "log/http_error.log" },
271 filters => [{inets_httpd, {fun logger_filters:domain/2,
272 {log, equal,
273 [otp, inets, httpd, my_server, error]
274 }}}],
275 filter_default => stop }}]}]}].
276 or if you want to add it to the default logger via an API:
279 logger:add_handler_filter(default,
281 inets_httpd,
282 {fun logger_filters:domain/2,
283 {log, equal,
284 [otp, inets, httpd, my_server, error]}}).
285 {log_format, common | combined}:
287 Defines if access logs are to be written according to the common
288 log format or the extended common log format. The common format is
289 one line looking like this: remotehost rfc931 authuser [date] "re‐
290 quest" status bytes.
291 Here:
293 remotehost:
295 Remote.
296 rfc931:
298 The remote username of the client (RFC 931).
299 authuser:
301 The username used for authentication.
302 [date]:
304 Date and time of the request (RFC 1123).
305 "request":
307 The request line as it came from the client (RFC 1945).
308 status:
310 The HTTP status code returned to the client (RFC 1945).
311 bytes:
313 The content-length of the document transferred.
314 The combined format is one line looking like this: remotehost
316 rfc931 authuser [date] "request" status bytes "referer"
317 "user_agent"
318 In addition to the earlier:
320 "referer":
322 The URL the client was on before requesting the URL (if it could
323 not be determined, a minus sign is placed in this field).
324 "user_agent":
326 The software the client claims to be using (if it could not be
327 determined, a minus sign is placed in this field).
328 This affects the access logs written by mod_log and mod_disk_log.
330 {error_log_format, pretty | compact}:
332 Default is pretty. If the error log is meant to be read directly by
333 a human, pretty is the best option.
334 pretty has a format corresponding to:
336 io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).
338 compact has a format corresponding to:
340 io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).
342 This affects the error logs written by mod_log and mod_disk_log.
344 URL Aliasing Properties - Requires mod_alias
346 {alias, {Alias, RealName}}:
348 Alias = string() and RealName = string(). alias allows documents to
349 be stored in the local file system instead of the document_root lo‐
350 cation. URLs with a path beginning with url-path is mapped to local
351 files beginning with directory-filename, for example:
352 {alias, {"/image", "/ftp/pub/image"}}
354 Access to http://your.server.org/image/foo.gif would refer to the
356 file /ftp/pub/image/foo.gif.
357 {re_write, {Re, Replacement}}:
359 Re = string() and Replacement = string(). re_write allows documents
360 to be stored in the local file system instead of the document_root
361 location. URLs are rewritten by re:replace/3 to produce a path in
362 the local file-system, for example:
363 {re_write, {"^/[~]([^/]+)(.*)$", "/home/\\1/public\\2"}}
365 Access to http://your.server.org/~bob/foo.gif would refer to the
367 file /home/bob/public/foo.gif.
368 {directory_index, [string()]}:
370 directory_index specifies a list of resources to look for if a
371 client requests a directory using a / at the end of the directory
372 name. file depicts the name of a file in the directory. Several
373 files can be given, in which case the server returns the first it
374 finds, for example:
375 {directory_index, ["index.html", "welcome.html"]}
377 Access to http://your.server.org/docs/ would return
379 http://your.server.org/docs/index.html or
380 http://your.server.org/docs/welcome.html if index.html does not ex‐
381 ist.
382 CGI Properties - Requires mod_cgi
384 {script_alias, {Alias, RealName}}:
386 Alias = string() and RealName = string(). Have the same behavior as
387 property alias, except that they also mark the target directory as
388 containing CGI scripts. URLs with a path beginning with url-path
389 are mapped to scripts beginning with directory-filename, for exam‐
390 ple:
391 {script_alias, {"/cgi-bin/", "/web/cgi-bin/"}}
393 Access to http://your.server.org/cgi-bin/foo would cause the server
395 to run the script /web/cgi-bin/foo.
396 {script_re_write, {Re, Replacement}}:
398 Re = string() and Replacement = string(). Have the same behavior as
399 property re_write, except that they also mark the target directory
400 as containing CGI scripts. URLs with a path beginning with url-path
401 are mapped to scripts beginning with directory-filename, for exam‐
402 ple:
403 {script_re_write, {"^/cgi-bin/(\\d+)/", "/web/\\1/cgi-bin/"}}
405 Access to http://your.server.org/cgi-bin/17/foo would cause the
407 server to run the script /web/17/cgi-bin/foo.
408 {script_nocache, boolean()}:
410 If script_nocache is set to true, the HTTP server by default adds
411 the header fields necessary to prevent proxies from caching the
412 page. Generally this is preferred. Default to false.
413 {script_timeout, integer()}:
415 The time in seconds the web server waits between each chunk of data
416 from the script. If the CGI script does not deliver any data before
417 the timeout, the connection to the client is closed. Default is 15.
418 {action, {MimeType, CgiScript}} - requires mod_action:
420 MimeType = string() and CgiScript = string(). action adds an action
421 activating a CGI script whenever a file of a certain MIME type is
422 requested. It propagates the URL and file path of the requested
423 document using the standard CGI PATH_INFO and PATH_TRANSLATED envi‐
424 ronment variables.
425 Example:
427 {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}}
429 {script, {Method, CgiScript}} - requires mod_action:
431 Method = string() and CgiScript = string(). script adds an action
432 activating a CGI script whenever a file is requested using a cer‐
433 tain HTTP method. The method is either GET or POST, as defined in
434 RFC 1945. It propagates the URL and file path of the requested doc‐
435 ument using the standard CGI PATH_INFO and PATH_TRANSLATED environ‐
436 ment variables.
437 Example:
439 {script, {"PUT", "/cgi-bin/put"}}
441 ESI Properties - Requires mod_esi
443 {erl_script_alias, {URLPath, [AllowedModule]}}:
445 URLPath = string() and AllowedModule = atom(). erl_script_alias
446 marks all URLs matching url-path as erl scheme scripts. A matching
447 URL is mapped into a specific module and function, for example:
448 {erl_script_alias, {"/cgi-bin/example", [httpd_example]}}
450 A request to http://your.server.org/cgi-bin/example/httpd_exam‐
452 ple:yahoo would refer to httpd_example:yahoo/3 or, if that does not
453 exist, httpd_example:yahoo/2 and http://your.server.org/cgi-bin/ex‐
454 ample/other:yahoo would not be allowed to execute.
455 {erl_script_nocache, boolean()}:
457 If erl_script_nocache is set to true, the server adds HTTP header
458 fields preventing proxies from caching the page. This is generally
459 a good idea for dynamic content, as the content often varies be‐
460 tween each request. Default is false.
461 {erl_script_timeout, integer()}:
463 If erl_script_timeout sets the time in seconds the server waits be‐
464 tween each chunk of data to be delivered through mod_esi:deliver/2.
465 Default is 15. This is only relevant for scripts that use the erl
466 scheme.
467 Log Properties - Requires mod_log
469 {error_log, path()}:
471 Defines the filename of the error log file to be used to log server
472 errors. If the filename does not begin with a slash (/), it is as‐
473 sumed to be relative to the server_root.
474 {security_log, path()}:
476 Defines the filename of the access log file to be used to log secu‐
477 rity events. If the filename does not begin with a slash (/), it is
478 assumed to be relative to the server_root.
479 {transfer_log, path()}:
481 Defines the filename of the access log file to be used to log in‐
482 coming requests. If the filename does not begin with a slash (/),
483 it is assumed to be relative to the server_root.
484 Disk Log Properties - Requires mod_disk_log
486 {disk_log_format, internal | external}:
488 Defines the file format of the log files. See disk_log for details.
489 If the internal file format is used, the log file is repaired after
490 a crash. When a log file is repaired, data can disappear. When the
491 external file format is used, httpd does not start if the log file
492 is broken. Default is external.
493 {error_disk_log, path()}:
495 Defines the filename of the (disk_log(3)) error log file to be used
496 to log server errors. If the filename does not begin with a slash
497 (/), it is assumed to be relative to the server_root.
498 {error_disk_log_size, {MaxBytes, MaxFiles}}:
500 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
501 ties of the (disk_log(3)) error log file. This file is of type wrap
502 log and max bytes is written to each file and max files is used be‐
503 fore the first file is truncated and reused.
504 {security_disk_log, path()}:
506 Defines the filename of the (disk_log(3)) access log file logging
507 incoming security events, that is, authenticated requests. If the
508 filename does not begin with a slash (/), it is assumed to be rela‐
509 tive to the server_root.
510 {security_disk_log_size, {MaxBytes, MaxFiles}}:
512 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
513 ties of the disk_log(3) access log file. This file is of type wrap
514 log and max bytes is written to each file and max files is used be‐
515 fore the first file is truncated and reused.
516 {transfer_disk_log, path()}:
518 Defines the filename of the (disk_log(3)) access log file logging
519 incoming requests. If the filename does not begin with a slash (/),
520 it is assumed to be relative to the server_root.
521 {transfer_disk_log_size, {MaxBytes, MaxFiles}}:
523 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
524 ties of the disk_log(3) access log file. This file is of type wrap
525 log and max bytes is written to each file and max files is used be‐
526 fore the first file is truncated and reused.
527 Authentication Properties - Requires mod_auth
529 {directory, {path(), [{property(), term()}]}}
531 The properties for directories are as follows:
533 {allow_from, all | [RegxpHostString]}:
535 Defines a set of hosts to be granted access to a given directory,
536 for example:
537 {allow_from, ["123.34.56.11", "150.100.23"]}
539 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
541 allowed access.
542 {deny_from, all | [RegxpHostString]}:
544 Defines a set of hosts to be denied access to a given directory,
545 for example:
546 {deny_from, ["123.34.56.11", "150.100.23"]}
548 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
550 not allowed access.
551 {auth_type, plain | dets | mnesia}:
553 Sets the type of authentication database that is used for the di‐
554 rectory. The key difference between the different methods is that
555 dynamic data can be saved when Mnesia and Dets are used.
556 {auth_user_file, path()}:
558 Sets the name of a file containing the list of users and passwords
559 for user authentication. The filename can be either absolute or
560 relative to the server_root. If using the plain storage method,
561 this file is a plain text file where each line contains a username
562 followed by a colon, followed by the non-encrypted password. If
563 usernames are duplicated, the behavior is undefined.
564 Example:
566 ragnar:s7Xxv7
568 edward:wwjau8
569 If the Dets storage method is used, the user database is maintained
571 by Dets and must not be edited by hand. Use the API functions in
572 module mod_auth to create/edit the user database. This directive is
573 ignored if the Mnesia storage method is used. For security reasons,
574 ensure that auth_user_file is stored outside the document tree of
575 the web server. If it is placed in the directory that it protects,
576 clients can download it.
577 {auth_group_file, path()}:
579 Sets the name of a file containing the list of user groups for user
580 authentication. The filename can be either absolute or relative to
581 the server_root. If the plain storage method is used, the group
582 file is a plain text file, where each line contains a group name
583 followed by a colon, followed by the members usernames separated by
584 spaces.
585 Example:
587 group1: bob joe ante
589 If the Dets storage method is used, the group database is main‐
591 tained by Dets and must not be edited by hand. Use the API for mod‐
592 ule mod_auth to create/edit the group database. This directive is
593 ignored if the Mnesia storage method is used. For security reasons,
594 ensure that the auth_group_file is stored outside the document tree
595 of the web server. If it is placed in the directory that it pro‐
596 tects, clients can download it.
597 {auth_name, string()}:
599 Sets the name of the authorization realm (auth-domain) for a direc‐
600 tory. This string informs the client about which username and pass‐
601 word to use.
602 {auth_access_password, string()}:
604 If set to other than "NoPassword", the password is required for all
605 API calls. If the password is set to "DummyPassword", the password
606 must be changed before any other API calls. To secure the authenti‐
607 cating data, the password must be changed after the web server is
608 started. Otherwise it is written in clear text in the configuration
609 file.
610 {require_user, [string()]}:
612 Defines users to grant access to a given directory using a secret
613 password.
614 {require_group, [string()]}:
616 Defines users to grant access to a given directory using a secret
617 password.
618 Security Properties - Requires mod_security
620 {security_directory, {path(), [{property(), term()}]}}
622 The properties for the security directories are as follows:
624 {data_file, path()}:
626 Name of the security data file. The filename can either be absolute
627 or relative to the server_root. This file is used to store persis‐
628 tent data for module mod_security.
629 {max_retries, integer()}:
631 Specifies the maximum number of attempts to authenticate a user be‐
632 fore the user is blocked out. If a user successfully authenticates
633 while blocked, the user receives a 403 (Forbidden) response from
634 the server. If the user makes a failed attempt while blocked, the
635 server returns 401 (Unauthorized), for security reasons. Default is
636 3. Can be set to infinity.
637 {block_time, integer()}:
639 Specifies the number of minutes a user is blocked. After this time
640 has passed, the user automatically regains access. Default is 60.
641 {fail_expire_time, integer()}:
643 Specifies the number of minutes a failed user authentication is re‐
644 membered. If a user authenticates after this time has passed, the
645 previous failed authentications are forgotten. Default is 30.
646 {auth_timeout, integer()}:
648 Specifies the number of seconds a successful user authentication
649 is remembered. After this time has passed, the authentication is no
650 longer reported. Default is 30.
651
653 info(Pid) -> HttpInformation
654 info(Pid, Properties) -> HttpInformation
656 Types:
658 Pid = pid()
660 Properties = [atom()]
661 HttpInformation =
662 [CommonOption] |
663 [CommunicationOption] |
664 [ModOption] |
665 [LimitOption] |
666 [AdminOption]
667 CommonOption =
668 {port, integer() >= 0} |
669 {server_name, string()} |
670 {server_root, Path} |
671 {document_root, Path}
672 CommunicationOption =
673 {bind_address, inet:ip_address() | inet:hostname() | any}
674 |
675 {profile, atom()} |
676 {socket_type,
677 ip_comm |
678 {ip_comm, ssl:tls_option() | gen_tcp:option()} |
679 {ssl, ssl:tls_option() | gen_tcp:option()}} |
680 {ipfamily, inet | inet6} |
681 {minimum_bytes_per_second, integer()}
682 ModOption = {modules, atom()}
683 LimitOption =
684 {customize, atom()} |
685 {disable_chunked_transfer_encoding_send, boolean()} |
686 {keep_alive, boolean()} |
687 {keep_alive_timeout, integer()} |
688 {max_body_size, integer()} |
689 {max_clients, integer()} |
690 {max_header_size, integer()} |
691 {max_content_length, integer()} |
692 {max_uri_size, integer()} |
693 {max_keep_alive_request, integer()} |
694 {max_client_body_chunk, integer()}
695 AdminOption =
696 {mime_types,
697 [{MimeType :: string(), Extension :: string()}] | Path}
698 |
699 {mime_type, string()} |
700 {server_admin, string()} |
701 {server_tokens,
702 none | prod | major | minor | minimal | os | full |
703 {private, string()}} |
704 {logger, Options :: list()} |
705 {log_format, common | combined} |
706 {error_log_format, pretty | compact}
707 Fetches information about the HTTP server. When called with only
709 the pid, all properties are fetched. When called with a list of
710 specific properties, they are fetched. The available properties
711 are the same as the start options of the server.
712 Note:
714 Pid is the pid returned from inets:start/[2,3]. Can also be re‐
715 trieved form inets:services/0 and inets:services_info/0, see in‐
716 ets(3).
717 info(Address, Port) -> HttpInformation
720 info(Address, Port, Profile) -> HttpInformation
722 info(Address, Port, Properties) -> HttpInformation
724 info(Address, Port, Profile, Properties) -> HttpInformation
726 Types:
728 Address = inet:ip_address() | any
730 Port = integer()
731 Profile = atom()
732 Properties = [atom()]
733 Path = file:name_all()
734 HttpInformation =
735 [CommonOption] |
736 [CommunicationOption] |
737 [ModOption] |
738 [LimitOption] |
739 [AdminOption]
740 CommonOption =
741 {port, integer() >= 0} |
742 {server_name, string()} |
743 {server_root, Path} |
744 {document_root, Path}
745 CommunicationOption =
746 {bind_address, inet:ip_address() | inet:hostname() | any}
747 |
748 {profile, atom()} |
749 {socket_type,
750 ip_comm |
751 {ip_comm, ssl:tls_option() | gen_tcp:option()} |
752 {ssl, ssl:tls_option() | gen_tcp:option()}} |
753 {ipfamily, inet | inet6} |
754 {minimum_bytes_per_second, integer()}
755 ModOption = {modules, atom()}
756 LimitOption =
757 {customize, atom()} |
758 {disable_chunked_transfer_encoding_send, boolean()} |
759 {keep_alive, boolean()} |
760 {keep_alive_timeout, integer()} |
761 {max_body_size, integer()} |
762 {max_clients, integer()} |
763 {max_header_size, integer()} |
764 {max_content_length, integer()} |
765 {max_uri_size, integer()} |
766 {max_keep_alive_request, integer()} |
767 {max_client_body_chunk, integer()}
768 AdminOption =
769 {mime_types,
770 [{MimeType :: string(), Extension :: string()}] | Path}
771 |
772 {mime_type, string()} |
773 {server_admin, string()} |
774 {server_tokens,
775 none | prod | major | minor | minimal | os | full |
776 {private, string()}} |
777 {logger, Options :: list()} |
778 {log_format, common | combined} |
779 {error_log_format, pretty | compact}
780 Fetches information about the HTTP server. When called with only
782 Address and Port, all properties are fetched. When called with a
783 list of specific properties, they are fetched. The available
784 properties are the same as the start options of the server.
785 Note:
787 The Address must be the IP address and cannot be the hostname.
788 reload_config(Config, Mode) -> ok | {error, Reason} | no_return()
791 Types:
793 Config = file:name_all() | [{Option, Value}]
795 Mode = non_disturbing | disturbing | blocked
796 Option = atom()
797 Value = Reason = term()
798 Reloads the HTTP server configuration without restarting the
800 server. Incoming requests are answered with a temporary down
801 message during the reload time.
802 Note:
804 Available properties are the same as the start options of the
805 server, but the properties bind_address and port cannot be
806 changed.
807 If mode is disturbing, the server is blocked forcefully, all on‐
810 going requests terminates, and the reload starts immediately. If
811 mode is non-disturbing, no new connections are accepted, but on‐
812 going requests are allowed to complete before the reload is
813 done.
814
816 The Erlang web server API data types are as follows:
817 ModData = #mod{}
819 -record(mod, {
821 data = [],
822 socket_type = ip_comm,
823 socket,
824 config_db,
825 method,
826 absolute_uri,
827 request_uri,
828 http_version,
829 request_line,
830 parsed_header = [],
831 entity_body,
832 connection
833 }).
834 To access the record in your callback-module use:
836 -include_lib("inets/include/httpd.hrl").
838 The fields of record mod have the following meaning:
840 data:
842 Type [{InteractionKey,InteractionValue}] is used to propagate data
843 between modules. Depicted interaction_data() in function type dec‐
844 larations.
845 socket_type:
847 socket_type() indicates whether it is an IP socket or an ssl
848 socket.
849 socket:
851 The socket, in format ip_comm or ssl, depending on socket_type.
852 config_db:
854 The config file directives stored as key-value tuples in an ETS ta‐
855 ble. Depicted config_db() in function type declarations.
856 method:
858 Type "GET" | "POST" | "HEAD" | "TRACE", that is, the HTTP method.
859 absolute_uri:
861 If the request is an HTTP/1.1 request, the URI can be in the abso‐
862 lute URI format. In that case, httpd saves the absolute URI in this
863 field. An Example of an absolute URI is "http://Server‐
864 Name:Part/cgi-bin/find.pl?person=jocke"
865 request_uri:
867 The Request-URI as defined in RFC 1945, for example, "/cgi-
868 bin/find.pl?person=jocke".
869 http_version:
871 The HTTP version of the request, that is, "HTTP/1.0", or
872 "HTTP/1.1".
873 request_line:
875 The Request-Line as defined inRFC 1945, for example, "GET /cgi-
876 bin/find.pl?person=jocke HTTP/1.0".
877 parsed_header:
879 Type [{HeaderKey,HeaderValue}]. parsed_header contains all HTTP
880 header fields from the HTTP request stored in a list as key-value
881 tuples. See RFC 2616 for a listing of all header fields. For exam‐
882 ple, the date field is stored as {"date","Wed, 15 Oct 1997 14:35:17
883 GMT"}. RFC 2616 defines that HTTP is a case-insensitive protocol
884 and the header fields can be in lower case or upper case. httpd en‐
885 sures that all header field names are in lower case.
886 entity_body:
888 The entity-Body as defined in RFC 2616, for example, data sent from
889 a CGI script using the POST method.
890 connection:
892 true | false. If set to true, the connection to the client is a
893 persistent connection and is not closed when the request is served.
894
897 Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break,
898 NewData} | done
899 Types:
901 OldData = list()
903 NewData = [{response,{StatusCode,Body}}]
904 | [{response,{response,Head,Body}}]
905 | [{response,{already_sent,Statuscode,Size}}]
906 StatusCode = integer()
907 Body = io_list() | nobody | {Fun, Arg}
908 Head = [HeaderOption]
909 HeaderOption = {Option, Value} | {code, StatusCode}
910 Option = accept_ranges | allow
911 | cache_control | content_MD5
912 | content_encoding | content_language
913 | content_length | content_location
914 | content_range | content_type | date
915 | etag | expires | last_modified
916 | location | pragma | retry_after
917 | server | trailer | transfer_encoding
918 Value = string()
919 Fun = fun( Arg ) -> sent| close | Body
920 Arg = [term()]
921 When a valid request reaches httpd, it calls do/1 in each mod‐
923 ule, defined by the configuration option of Module. The function
924 can generate data for other modules or a response that can be
925 sent back to the client.
926 The field data in ModData is a list. This list is the list re‐
928 turned from the last call to do/1.
929 Body is the body of the HTTP response that is sent back to the
931 client. An appropriate header is appended to the message. Sta‐
932 tusCode is the status code of the response, see RFC 2616 for the
933 appropriate values.
934 Head is a key value list of HTTP header fields. The server con‐
936 structs an HTTP header from this data. See RFC 2616 for the ap‐
937 propriate value for each header field. If the client is an
938 HTTP/1.0 client, the server filters the list so that only
939 HTTP/1.0 header fields are sent back to the client.
940 If Body is returned and equal to {Fun,Arg}, the web server tries
942 apply/2 on Fun with Arg as argument. The web server expects that
943 the fun either returns a list (Body) that is an HTTP response,
944 or the atom sent if the HTTP response is sent back to the
945 client. If close is returned from the fun, something has gone
946 wrong and the server signals this to the client by closing the
947 connection.
948 Module:remove(ConfigDB) -> ok | {error, Reason}
950 Types:
952 ConfigDB = ets_table()
954 Reason = term()
955 When httpd is shut down, it tries to execute remove/1 in each
957 Erlang web server callback module. The programmer can use this
958 function to clean up resources created in the store function.
959 Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} | {er‐
961 ror, Reason}
962 Types:
964 Line = string()
966 Option = property()
967 Config = [{Option, Value}]
968 Value = term()
969 Reason = term()
970 Checks the validity of the configuration options before saving
972 them in the internal database. This function can also have a
973 side effect, that is, setup of necessary extra resources implied
974 by the configuration option. It can also resolve possible depen‐
975 dencies among configuration options by changing the value of the
976 option. This function only needs clauses for the options imple‐
977 mented by this particular callback module.
978
981 parse_query(QueryString) -> QueryList | uri_string:error()
982 Types:
984 QueryString = string()
986 QueryList = [{unicode:chardata(), unicode:chardata() | true}]
987 parse_query/1 parses incoming data to erl and eval scripts (see
989 mod_esi(3)) as defined in the standard URL format, that is, '+'
990 becomes 'space' and decoding of hexadecimal characters (%xx).
991
993 RFC 2616, inets(3), ssl(3)
994Ericsson AB inets 8.2.1 httpd(3)
