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()} | {essl, 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 {ipfamily, inet | inet6}:
97 Default is inet, legacy option inet6fb4 no longer makes sense and
98 will be translated to inet.
99 {minimum_bytes_per_second, integer()}:
101 If given, sets a minimum of bytes per second value for connections.
102 If the value is unreached, the socket closes for that connection.
104 The option is good for reducing the risk of "slow DoS" attacks.
106 Erlang Web Server API Modules
108 {modules, [atom()]} :
110 Defines which modules the HTTP server uses when handling requests.
111 Default is [mod_alias, mod_auth, mod_esi, mod_actions, mod_cgi,
112 mod_dir, mod_get, mod_head, mod_log, mod_disk_log]. Notice that
113 some mod-modules are dependent on others, so the order cannot be
114 entirely arbitrary. See the Inets Web Server Modules in the User's
115 Guide for details.
116 Limit properties
118 {customize, atom()}:
120 A callback module to customize the inets HTTP servers behaviour see
121 httpd_custom_api
122 {disable_chunked_transfer_encoding_send, boolean()}:
124 Allows you to disable chunked transfer-encoding when sending a re‐
125 sponse to an HTTP/1.1 client. Default is false.
126 {keep_alive, boolean()}:
128 Instructs the server whether to use persistent connections when the
129 client claims to be HTTP/1.1 compliant. Default is true.
130 {keep_alive_timeout, integer()}:
132 The number of seconds the server waits for a subsequent request
133 from the client before closing the connection. Default is 150.
134 {max_body_size, integer()}:
136 Limits the size of the message body of an HTTP request. Default is
137 no limit.
138 {max_clients, integer()}:
140 Limits the number of simultaneous requests that can be supported.
141 Default is 150.
142 {max_header_size, integer()}:
144 Limits the size of the message header of an HTTP request. Default
145 is 10240.
146 {max_content_length, integer()}:
148 Maximum content-length in an incoming request, in bytes. Requests
149 with content larger than this are answered with status 413. Default
150 is 100000000 (100 MB).
151 {max_uri_size, integer()}:
153 Limits the size of the HTTP request URI. Default is no limit.
154 {max_keep_alive_request, integer()}:
156 The number of requests that a client can do on one connection. When
157 the server has responded to the number of requests defined by
158 max_keep_alive_requests, the server closes the connection. The
159 server closes it even if there are queued request. Default is no
160 limit.
161 {max_client_body_chunk, integer()}:
163 Enforces chunking of a HTTP PUT or POST body data to be delivered
164 to the mod_esi callback. Note this is not supported for mod_cgi.
165 Default is no limit e.i the whole body is delivered as one entity,
166 which could be very memory consuming. mod_esi(3).
167 Administrative Properties
169 {mime_types, [{MimeType, Extension}] | path()}:
171 MimeType = string() and Extension = string(). Files delivered to
172 the client are MIME typed according to RFC 1590. File suffixes are
173 mapped to MIME types before file delivery. The mapping between file
174 suffixes and MIME types can be specified as an Apache-like file or
175 directly in the property list. Such a file can look like the fol‐
176 lowing:
177 # MIME type Extension
179 text/html html htm
180 text/plain asc txt
181 Default is [{"html","text/html"},{"htm","text/html"}].
183 {mime_type, string()}:
185 When the server is asked to provide a document type that cannot be
186 determined by the MIME Type Settings, the server uses this default
187 type.
188 {server_admin, string()}:
190 Defines the email-address of the server administrator to be in‐
191 cluded in any error messages returned by the server.
192 {server_tokens, none|prod|major|minor|minimal|os|full|{private,
194 string()}}:
195 Defines the look of the value of the server header.
196 Example: Assuming the version of Inets is 5.8.1, the server header
198 string can look as follows for the different values of server-to‐
199 kens:
200 none:
202 "" % A Server: header will not be generated
203 prod:
205 "inets"
206 major:
208 "inets/5"
209 minor:
211 "inets/5.8"
212 minimal:
214 "inets/5.8.1"
215 os:
217 "inets/5.8.1 (unix)"
218 full:
220 "inets/5.8.1 (unix/linux) OTP/R15B"
221 {private, "foo/bar"}:
223 "foo/bar"
224 By default, the value is as before, that is, minimal.
226 {logger, Options::list()}:
228 Currently only one option is supported:
229 {error, ServerID::atom()}:
231 Produces logger events on logger level error under the hierarchi‐
232 cal logger domain: [otp, inets, httpd, ServerID, error] The built
233 in logger formatting function produces log entries from the error
234 reports:
235 #{server_name => string()
237 protocol => internal | 'TCP' | 'TLS' | 'HTTP',
238 transport => "TCP "| "TLS", %% Present when protocol = 'HTTP'
239 uri => string(), %% Present when protocol = 'HTTP' and URI is valid
240 peer => inet:peername(),
241 host => inet:hostname(),
242 reason => term()
243 }
244 An example of a log entry with only default settings of logger
247 =ERROR REPORT==== 9-Oct-2019::09:33:27.350235 ===
249 Server: My Server
250 Protocol: HTTP
251 Transport: TLS
252 URI: /not_there
253 Host: 127.0.1.1:80
254 Peer: 127.0.0.1:45253
255 Reason: [{statuscode,404},{description,"Object Not Found"}]
256 Using this option makes mod_log and mod_disk_log error logs re‐
259 dundant.
260 Add the filter
262 {fun logger_filters:domain/2,
264 {log,equal,[otp,inets, httpd, ServerID, error]}
265 [{kernel,
267 [{logger,
268 [{handler, http_error_test, logger_std_h,
269 #{config => #{ file => "log/http_error.log" },
270 filters => [{inets_httpd, {fun logger_filters:domain/2,
271 {log, equal,
272 [otp, inets, httpd, my_server, error]
273 }}}],
274 filter_default => stop }}]}]}].
275 or if you want to add it to the default logger via an API:
278 logger:add_handler_filter(default,
280 inets_httpd,
281 {fun logger_filters:domain/2,
282 {log, equal,
283 [otp, inets, httpd, my_server, error]}}).
284 {log_format, common | combined}:
286 Defines if access logs are to be written according to the common
287 log format or the extended common log format. The common format is
288 one line looking like this: remotehost rfc931 authuser [date] "re‐
289 quest" status bytes.
290 Here:
292 remotehost:
294 Remote.
295 rfc931:
297 The remote username of the client (RFC 931).
298 authuser:
300 The username used for authentication.
301 [date]:
303 Date and time of the request (RFC 1123).
304 "request":
306 The request line as it came from the client (RFC 1945).
307 status:
309 The HTTP status code returned to the client (RFC 1945).
310 bytes:
312 The content-length of the document transferred.
313 The combined format is one line looking like this: remotehost
315 rfc931 authuser [date] "request" status bytes "referer"
316 "user_agent"
317 In addition to the earlier:
319 "referer":
321 The URL the client was on before requesting the URL (if it could
322 not be determined, a minus sign is placed in this field).
323 "user_agent":
325 The software the client claims to be using (if it could not be
326 determined, a minus sign is placed in this field).
327 This affects the access logs written by mod_log and mod_disk_log.
329 {error_log_format, pretty | compact}:
331 Default is pretty. If the error log is meant to be read directly by
332 a human, pretty is the best option.
333 pretty has a format corresponding to:
335 io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).
337 compact has a format corresponding to:
339 io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).
341 This affects the error logs written by mod_log and mod_disk_log.
343 URL Aliasing Properties - Requires mod_alias
345 {alias, {Alias, RealName}}:
347 Alias = string() and RealName = string(). alias allows documents to
348 be stored in the local file system instead of the document_root lo‐
349 cation. URLs with a path beginning with url-path is mapped to local
350 files beginning with directory-filename, for example:
351 {alias, {"/image", "/ftp/pub/image"}}
353 Access to http://your.server.org/image/foo.gif would refer to the
355 file /ftp/pub/image/foo.gif.
356 {re_write, {Re, Replacement}}:
358 Re = string() and Replacement = string(). re_write allows documents
359 to be stored in the local file system instead of the document_root
360 location. URLs are rewritten by re:replace/3 to produce a path in
361 the local file-system, for example:
362 {re_write, {"^/[~]([^/]+)(.*)$", "/home/\\1/public\\2"}}
364 Access to http://your.server.org/~bob/foo.gif would refer to the
366 file /home/bob/public/foo.gif.
367 {directory_index, [string()]}:
369 directory_index specifies a list of resources to look for if a
370 client requests a directory using a / at the end of the directory
371 name. file depicts the name of a file in the directory. Several
372 files can be given, in which case the server returns the first it
373 finds, for example:
374 {directory_index, ["index.html", "welcome.html"]}
376 Access to http://your.server.org/docs/ would return
378 http://your.server.org/docs/index.html or
379 http://your.server.org/docs/welcome.html if index.html does not ex‐
380 ist.
381 CGI Properties - Requires mod_cgi
383 {script_alias, {Alias, RealName}}:
385 Alias = string() and RealName = string(). Have the same behavior as
386 property alias, except that they also mark the target directory as
387 containing CGI scripts. URLs with a path beginning with url-path
388 are mapped to scripts beginning with directory-filename, for exam‐
389 ple:
390 {script_alias, {"/cgi-bin/", "/web/cgi-bin/"}}
392 Access to http://your.server.org/cgi-bin/foo would cause the server
394 to run the script /web/cgi-bin/foo.
395 {script_re_write, {Re, Replacement}}:
397 Re = string() and Replacement = string(). Have the same behavior as
398 property re_write, except that they also mark the target directory
399 as containing CGI scripts. URLs with a path beginning with url-path
400 are mapped to scripts beginning with directory-filename, for exam‐
401 ple:
402 {script_re_write, {"^/cgi-bin/(\\d+)/", "/web/\\1/cgi-bin/"}}
404 Access to http://your.server.org/cgi-bin/17/foo would cause the
406 server to run the script /web/17/cgi-bin/foo.
407 {script_nocache, boolean()}:
409 If script_nocache is set to true, the HTTP server by default adds
410 the header fields necessary to prevent proxies from caching the
411 page. Generally this is preferred. Default to false.
412 {script_timeout, integer()}:
414 The time in seconds the web server waits between each chunk of data
415 from the script. If the CGI script does not deliver any data before
416 the timeout, the connection to the client is closed. Default is 15.
417 {action, {MimeType, CgiScript}} - requires mod_action:
419 MimeType = string() and CgiScript = string(). action adds an action
420 activating a CGI script whenever a file of a certain MIME type is
421 requested. It propagates the URL and file path of the requested
422 document using the standard CGI PATH_INFO and PATH_TRANSLATED envi‐
423 ronment variables.
424 Example:
426 {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}}
428 {script, {Method, CgiScript}} - requires mod_action:
430 Method = string() and CgiScript = string(). script adds an action
431 activating a CGI script whenever a file is requested using a cer‐
432 tain HTTP method. The method is either GET or POST, as defined in
433 RFC 1945. It propagates the URL and file path of the requested doc‐
434 ument using the standard CGI PATH_INFO and PATH_TRANSLATED environ‐
435 ment variables.
436 Example:
438 {script, {"PUT", "/cgi-bin/put"}}
440 ESI Properties - Requires mod_esi
442 {erl_script_alias, {URLPath, [AllowedModule]}}:
444 URLPath = string() and AllowedModule = atom(). erl_script_alias
445 marks all URLs matching url-path as erl scheme scripts. A matching
446 URL is mapped into a specific module and function, for example:
447 {erl_script_alias, {"/cgi-bin/example", [httpd_example]}}
449 A request to http://your.server.org/cgi-bin/example/httpd_exam‐
451 ple:yahoo would refer to httpd_example:yahoo/3 or, if that does not
452 exist, httpd_example:yahoo/2 and http://your.server.org/cgi-bin/ex‐
453 ample/other:yahoo would not be allowed to execute.
454 {erl_script_nocache, boolean()}:
456 If erl_script_nocache is set to true, the server adds HTTP header
457 fields preventing proxies from caching the page. This is generally
458 a good idea for dynamic content, as the content often varies be‐
459 tween each request. Default is false.
460 {erl_script_timeout, integer()}:
462 If erl_script_timeout sets the time in seconds the server waits be‐
463 tween each chunk of data to be delivered through mod_esi:deliver/2.
464 Default is 15. This is only relevant for scripts that use the erl
465 scheme.
466 Log Properties - Requires mod_log
468 {error_log, path()}:
470 Defines the filename of the error log file to be used to log server
471 errors. If the filename does not begin with a slash (/), it is as‐
472 sumed to be relative to the server_root.
473 {security_log, path()}:
475 Defines the filename of the access log file to be used to log secu‐
476 rity events. If the filename does not begin with a slash (/), it is
477 assumed to be relative to the server_root.
478 {transfer_log, path()}:
480 Defines the filename of the access log file to be used to log in‐
481 coming requests. If the filename does not begin with a slash (/),
482 it is assumed to be relative to the server_root.
483 Disk Log Properties - Requires mod_disk_log
485 {disk_log_format, internal | external}:
487 Defines the file format of the log files. See disk_log for details.
488 If the internal file format is used, the log file is repaired after
489 a crash. When a log file is repaired, data can disappear. When the
490 external file format is used, httpd does not start if the log file
491 is broken. Default is external.
492 {error_disk_log, path()}:
494 Defines the filename of the (disk_log(3)) error log file to be used
495 to log server errors. If the filename does not begin with a slash
496 (/), it is assumed to be relative to the server_root.
497 {error_disk_log_size, {MaxBytes, MaxFiles}}:
499 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
500 ties of the (disk_log(3)) error log file. This file is of type wrap
501 log and max bytes is written to each file and max files is used be‐
502 fore the first file is truncated and reused.
503 {security_disk_log, path()}:
505 Defines the filename of the (disk_log(3)) access log file logging
506 incoming security events, that is, authenticated requests. If the
507 filename does not begin with a slash (/), it is assumed to be rela‐
508 tive to the server_root.
509 {security_disk_log_size, {MaxBytes, MaxFiles}}:
511 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
512 ties of the disk_log(3) access log file. This file is of type wrap
513 log and max bytes is written to each file and max files is used be‐
514 fore the first file is truncated and reused.
515 {transfer_disk_log, path()}:
517 Defines the filename of the (disk_log(3)) access log file logging
518 incoming requests. If the filename does not begin with a slash (/),
519 it is assumed to be relative to the server_root.
520 {transfer_disk_log_size, {MaxBytes, MaxFiles}}:
522 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
523 ties of the disk_log(3) access log file. This file is of type wrap
524 log and max bytes is written to each file and max files is used be‐
525 fore the first file is truncated and reused.
526 Authentication Properties - Requires mod_auth
528 {directory, {path(), [{property(), term()}]}}
530 The properties for directories are as follows:
532 {allow_from, all | [RegxpHostString]}:
534 Defines a set of hosts to be granted access to a given directory,
535 for example:
536 {allow_from, ["123.34.56.11", "150.100.23"]}
538 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
540 allowed access.
541 {deny_from, all | [RegxpHostString]}:
543 Defines a set of hosts to be denied access to a given directory,
544 for example:
545 {deny_from, ["123.34.56.11", "150.100.23"]}
547 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
549 not allowed access.
550 {auth_type, plain | dets | mnesia}:
552 Sets the type of authentication database that is used for the di‐
553 rectory. The key difference between the different methods is that
554 dynamic data can be saved when Mnesia and Dets are used.
555 {auth_user_file, path()}:
557 Sets the name of a file containing the list of users and passwords
558 for user authentication. The filename can be either absolute or
559 relative to the server_root. If using the plain storage method,
560 this file is a plain text file where each line contains a username
561 followed by a colon, followed by the non-encrypted password. If
562 usernames are duplicated, the behavior is undefined.
563 Example:
565 ragnar:s7Xxv7
567 edward:wwjau8
568 If the Dets storage method is used, the user database is maintained
570 by Dets and must not be edited by hand. Use the API functions in
571 module mod_auth to create/edit the user database. This directive is
572 ignored if the Mnesia storage method is used. For security reasons,
573 ensure that auth_user_file is stored outside the document tree of
574 the web server. If it is placed in the directory that it protects,
575 clients can download it.
576 {auth_group_file, path()}:
578 Sets the name of a file containing the list of user groups for user
579 authentication. The filename can be either absolute or relative to
580 the server_root. If the plain storage method is used, the group
581 file is a plain text file, where each line contains a group name
582 followed by a colon, followed by the members usernames separated by
583 spaces.
584 Example:
586 group1: bob joe ante
588 If the Dets storage method is used, the group database is main‐
590 tained by Dets and must not be edited by hand. Use the API for mod‐
591 ule mod_auth to create/edit the group database. This directive is
592 ignored if the Mnesia storage method is used. For security reasons,
593 ensure that the auth_group_file is stored outside the document tree
594 of the web server. If it is placed in the directory that it pro‐
595 tects, clients can download it.
596 {auth_name, string()}:
598 Sets the name of the authorization realm (auth-domain) for a direc‐
599 tory. This string informs the client about which username and pass‐
600 word to use.
601 {auth_access_password, string()}:
603 If set to other than "NoPassword", the password is required for all
604 API calls. If the password is set to "DummyPassword", the password
605 must be changed before any other API calls. To secure the authenti‐
606 cating data, the password must be changed after the web server is
607 started. Otherwise it is written in clear text in the configuration
608 file.
609 {require_user, [string()]}:
611 Defines users to grant access to a given directory using a secret
612 password.
613 {require_group, [string()]}:
615 Defines users to grant access to a given directory using a secret
616 password.
617 Security Properties - Requires mod_security
619 {security_directory, {path(), [{property(), term()}]}}
621 The properties for the security directories are as follows:
623 {data_file, path()}:
625 Name of the security data file. The filename can either be absolute
626 or relative to the server_root. This file is used to store persis‐
627 tent data for module mod_security.
628 {max_retries, integer()}:
630 Specifies the maximum number of attempts to authenticate a user be‐
631 fore the user is blocked out. If a user successfully authenticates
632 while blocked, the user receives a 403 (Forbidden) response from
633 the server. If the user makes a failed attempt while blocked, the
634 server returns 401 (Unauthorized), for security reasons. Default is
635 3. Can be set to infinity.
636 {block_time, integer()}:
638 Specifies the number of minutes a user is blocked. After this time
639 has passed, the user automatically regains access. Default is 60.
640 {fail_expire_time, integer()}:
642 Specifies the number of minutes a failed user authentication is re‐
643 membered. If a user authenticates after this time has passed, the
644 previous failed authentications are forgotten. Default is 30.
645 {auth_timeout, integer()}:
647 Specifies the number of seconds a successful user authentication
648 is remembered. After this time has passed, the authentication is no
649 longer reported. Default is 30.
650
652 info(Pid) ->
653 info(Pid, Properties) -> [{Option, Value}]
654 Types:
656 Properties = [property()]
658 Option = property()
659 Value = term()
660 Fetches information about the HTTP server. When called with only
662 the pid, all properties are fetched. When called with a list of
663 specific properties, they are fetched. The available properties
664 are the same as the start options of the server.
665 Note:
667 Pid is the pid returned from inets:start/[2,3]. Can also be re‐
668 trieved form inets:services/0 and inets:services_info/0, see in‐
669 ets(3).
670 info(Address, Port) ->
673 info(Address, Port, Profile) ->
674 info(Address, Port, Profile, Properties) -> [{Option, Value}]
675 info(Address, Port, Properties) -> [{Option, Value}]
676 Types:
678 Address = ip_address()
680 Port = integer()
681 Profile = atom()
682 Properties = [property()]
683 Option = property()
684 Value = term()
685 Fetches information about the HTTP server. When called with only
687 Address and Port, all properties are fetched. When called with a
688 list of specific properties, they are fetched. The available
689 properties are the same as the start options of the server.
690 Note:
692 The address must be the IP address and cannot be the hostname.
693 reload_config(Config, Mode) -> ok | {error, Reason}
696 Types:
698 Config = path() | [{Option, Value}]
700 Option = property()
701 Value = term()
702 Mode = non_disturbing | disturbing
703 Reloads the HTTP server configuration without restarting the
705 server. Incoming requests are answered with a temporary down
706 message during the reload time.
707 Note:
709 Available properties are the same as the start options of the
710 server, but the properties bind_address and port cannot be
711 changed.
712 If mode is disturbing, the server is blocked forcefully, all on‐
715 going requests terminates, and the reload starts immediately. If
716 mode is non-disturbing, no new connections are accepted, but on‐
717 going requests are allowed to complete before the reload is
718 done.
719
721 The Erlang web server API data types are as follows:
722 ModData = #mod{}
724 -record(mod, {
726 data = [],
727 socket_type = ip_comm,
728 socket,
729 config_db,
730 method,
731 absolute_uri,
732 request_uri,
733 http_version,
734 request_line,
735 parsed_header = [],
736 entity_body,
737 connection
738 }).
739 To acess the record in your callback-module use:
741 -include_lib("inets/include/httpd.hrl").
743 The fields of record mod have the following meaning:
745 data:
747 Type [{InteractionKey,InteractionValue}] is used to propagate data
748 between modules. Depicted interaction_data() in function type dec‐
749 larations.
750 socket_type:
752 socket_type() indicates whether it is an IP socket or an ssl
753 socket.
754 socket:
756 The socket, in format ip_comm or ssl, depending on socket_type.
757 config_db:
759 The config file directives stored as key-value tuples in an ETS ta‐
760 ble. Depicted config_db() in function type declarations.
761 method:
763 Type "GET" | "POST" | "HEAD" | "TRACE", that is, the HTTP method.
764 absolute_uri:
766 If the request is an HTTP/1.1 request, the URI can be in the abso‐
767 lute URI format. In that case, httpd saves the absolute URI in this
768 field. An Example of an absolute URI is "http://Server‐
769 Name:Part/cgi-bin/find.pl?person=jocke"
770 request_uri:
772 The Request-URI as defined in RFC 1945, for example, "/cgi-
773 bin/find.pl?person=jocke".
774 http_version:
776 The HTTP version of the request, that is, "HTTP/1.0", or
777 "HTTP/1.1".
778 request_line:
780 The Request-Line as defined inRFC 1945, for example, "GET /cgi-
781 bin/find.pl?person=jocke HTTP/1.0".
782 parsed_header:
784 Type [{HeaderKey,HeaderValue}]. parsed_header contains all HTTP
785 header fields from the HTTP request stored in a list as key-value
786 tuples. See RFC 2616 for a listing of all header fields. For exam‐
787 ple, the date field is stored as {"date","Wed, 15 Oct 1997 14:35:17
788 GMT"}. RFC 2616 defines that HTTP is a case-insensitive protocol
789 and the header fields can be in lower case or upper case. httpd en‐
790 sures that all header field names are in lower case.
791 entity_body:
793 The entity-Body as defined in RFC 2616, for example, data sent from
794 a CGI script using the POST method.
795 connection:
797 true | false. If set to true, the connection to the client is a
798 persistent connection and is not closed when the request is served.
799
802 Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break,
803 NewData} | done
804 Types:
806 OldData = list()
808 NewData = [{response,{StatusCode,Body}}]
809 | [{response,{response,Head,Body}}]
810 | [{response,{already_sent,Statuscode,Size}}]
811 StatusCode = integer()
812 Body = io_list() | nobody | {Fun, Arg}
813 Head = [HeaderOption]
814 HeaderOption = {Option, Value} | {code, StatusCode}
815 Option = accept_ranges | allow
816 | cache_control | content_MD5
817 | content_encoding | content_language
818 | content_length | content_location
819 | content_range | content_type | date
820 | etag | expires | last_modified
821 | location | pragma | retry_after
822 | server | trailer | transfer_encoding
823 Value = string()
824 Fun = fun( Arg ) -> sent| close | Body
825 Arg = [term()]
826 When a valid request reaches httpd, it calls do/1 in each mod‐
828 ule, defined by the configuration option of Module. The function
829 can generate data for other modules or a response that can be
830 sent back to the client.
831 The field data in ModData is a list. This list is the list re‐
833 turned from the last call to do/1.
834 Body is the body of the HTTP response that is sent back to the
836 client. An appropriate header is appended to the message. Sta‐
837 tusCode is the status code of the response, see RFC 2616 for the
838 appropriate values.
839 Head is a key value list of HTTP header fields. The server con‐
841 structs an HTTP header from this data. See RFC 2616 for the ap‐
842 propriate value for each header field. If the client is an
843 HTTP/1.0 client, the server filters the list so that only
844 HTTP/1.0 header fields are sent back to the client.
845 If Body is returned and equal to {Fun,Arg}, the web server tries
847 apply/2 on Fun with Arg as argument. The web server expects that
848 the fun either returns a list (Body) that is an HTTP response,
849 or the atom sent if the HTTP response is sent back to the
850 client. If close is returned from the fun, something has gone
851 wrong and the server signals this to the client by closing the
852 connection.
853 Module:remove(ConfigDB) -> ok | {error, Reason}
855 Types:
857 ConfigDB = ets_table()
859 Reason = term()
860 When httpd is shut down, it tries to execute remove/1 in each
862 Erlang web server callback module. The programmer can use this
863 function to clean up resources created in the store function.
864 Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} | {er‐
866 ror, Reason}
867 Types:
869 Line = string()
871 Option = property()
872 Config = [{Option, Value}]
873 Value = term()
874 Reason = term()
875 Checks the validity of the configuration options before saving
877 them in the internal database. This function can also have a
878 side effect, that is, setup of necessary extra resources implied
879 by the configuration option. It can also resolve possible depen‐
880 dencies among configuration options by changing the value of the
881 option. This function only needs clauses for the options imple‐
882 mented by this particular callback module.
883
886 parse_query(QueryString) -> [{Key,Value}]
887 Types:
889 QueryString = string()
891 Key = string()
892 Value = string()
893 parse_query/1 parses incoming data to erl and eval scripts (see
895 mod_esi(3)) as defined in the standard URL format, that is, '+'
896 becomes 'space' and decoding of hexadecimal characters (%xx).
897
899 RFC 2616, inets(3), ssl(3)
900Ericsson AB inets 7.4.2 httpd(3)
