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 can not 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 {log_format, common | combined}:
253 Defines if access logs are to be written according to the common
254 log format or the extended common log format. The common format is
255 one line looking like this: remotehost rfc931 authuser [date]
256 "request" status bytes.
257 Here:
259 remotehost:
261 Remote.
262 rfc931:
264 The remote username of the client (RFC 931).
265 authuser:
267 The username used for authentication.
268 [date]:
270 Date and time of the request (RFC 1123).
271 "request":
273 The request line as it came from the client (RFC 1945).
274 status:
276 The HTTP status code returned to the client (RFC 1945).
277 bytes:
279 The content-length of the document transferred.
280 The combined format is one line looking like this: remotehost
282 rfc931 authuser [date] "request" status bytes "referer"
283 "user_agent"
284 In addition to the earlier:
286 "referer":
288 The URL the client was on before requesting the URL (if it could
289 not be determined, a minus sign is placed in this field).
290 "user_agent":
292 The software the client claims to be using (if it could not be
293 determined, a minus sign is placed in this field).
294 This affects the access logs written by mod_log and mod_disk_log.
296 {error_log_format, pretty | compact}:
298 Default is pretty. If the error log is meant to be read directly by
299 a human, pretty is the best option.
300 pretty has a format corresponding to:
302 io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).
304 compact has a format corresponding to:
306 io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).
308 This affects the error logs written by mod_log and mod_disk_log.
310 URL Aliasing Properties - Requires mod_alias
312 {alias, {Alias, RealName}}:
314 Alias = string() and RealName = string(). alias allows documents to
315 be stored in the local file system instead of the document_root
316 location. URLs with a path beginning with url-path is mapped to
317 local files beginning with directory-filename, for example:
318 {alias, {"/image", "/ftp/pub/image"}}
320 Access to http://your.server.org/image/foo.gif would refer to the
322 file /ftp/pub/image/foo.gif.
323 {re_write, {Re, Replacement}}:
325 Re = string() and Replacement = string(). re_write allows documents
326 to be stored in the local file system instead of the document_root
327 location. URLs are rewritten by re:replace/3 to produce a path in
328 the local file-system, for example:
329 {re_write, {"^/[~]([^/]+)(.*)$", "/home/\\1/public\\2"}}
331 Access to http://your.server.org/~bob/foo.gif would refer to the
333 file /home/bob/public/foo.gif. In an Apache-like configuration
334 file, Re is separated from Replacement with one single space, and
335 as expected backslashes do not need to be backslash escaped, the
336 same example would become:
337 ReWrite ^/[~]([^/]+)(.*)$ /home/\1/public\2
339 Beware of trailing space in Replacement to be used. If you must
341 have a space in Re, use, for example, the character encoding \040,
342 see re(3).
343 {directory_index, [string()]}:
345 directory_index specifies a list of resources to look for if a
346 client requests a directory using a / at the end of the directory
347 name. file depicts the name of a file in the directory. Several
348 files can be given, in which case the server returns the first it
349 finds, for example:
350 {directory_index, ["index.html", "welcome.html"]}
352 Access to http://your.server.org/docs/ would return
354 http://your.server.org/docs/index.html or
355 http://your.server.org/docs/welcome.html if index.html does not
356 exist.
357 CGI Properties - Requires mod_cgi
359 {script_alias, {Alias, RealName}}:
361 Alias = string() and RealName = string(). Have the same behavior as
362 property alias, except that they also mark the target directory as
363 containing CGI scripts. URLs with a path beginning with url-path
364 are mapped to scripts beginning with directory-filename, for exam‐
365 ple:
366 {script_alias, {"/cgi-bin/", "/web/cgi-bin/"}}
368 Access to http://your.server.org/cgi-bin/foo would cause the server
370 to run the script /web/cgi-bin/foo.
371 {script_re_write, {Re, Replacement}}:
373 Re = string() and Replacement = string(). Have the same behavior as
374 property re_write, except that they also mark the target directory
375 as containing CGI scripts. URLs with a path beginning with url-path
376 are mapped to scripts beginning with directory-filename, for exam‐
377 ple:
378 {script_re_write, {"^/cgi-bin/(\\d+)/", "/web/\\1/cgi-bin/"}}
380 Access to http://your.server.org/cgi-bin/17/foo would cause the
382 server to run the script /web/17/cgi-bin/foo.
383 {script_nocache, boolean()}:
385 If script_nocache is set to true, the HTTP server by default adds
386 the header fields necessary to prevent proxies from caching the
387 page. Generally this is preferred. Default to false.
388 {script_timeout, integer()}:
390 The time in seconds the web server waits between each chunk of data
391 from the script. If the CGI script does not deliver any data before
392 the timeout, the connection to the client is closed. Default is 15.
393 {action, {MimeType, CgiScript}} - requires mod_action:
395 MimeType = string() and CgiScript = string(). action adds an action
396 activating a CGI script whenever a file of a certain MIME type is
397 requested. It propagates the URL and file path of the requested
398 document using the standard CGI PATH_INFO and PATH_TRANSLATED envi‐
399 ronment variables.
400 Example:
402 {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}}
404 {script, {Method, CgiScript}} - requires mod_action:
406 Method = string() and CgiScript = string(). script adds an action
407 activating a CGI script whenever a file is requested using a cer‐
408 tain HTTP method. The method is either GET or POST, as defined in
409 RFC 1945. It propagates the URL and file path of the requested doc‐
410 ument using the standard CGI PATH_INFO and PATH_TRANSLATED environ‐
411 ment variables.
412 Example:
414 {script, {"PUT", "/cgi-bin/put"}}
416 ESI Properties - Requires mod_esi
418 {erl_script_alias, {URLPath, [AllowedModule]}}:
420 URLPath = string() and AllowedModule = atom(). erl_script_alias
421 marks all URLs matching url-path as erl scheme scripts. A matching
422 URL is mapped into a specific module and function, for example:
423 {erl_script_alias, {"/cgi-bin/example", [httpd_example]}}
425 A request to http://your.server.org/cgi-bin/example/httpd_exam‐
427 ple:yahoo would refer to httpd_example:yahoo/3 or, if that does not
428 exist, httpd_example:yahoo/2 and http://your.server.org/cgi-
429 bin/example/other:yahoo would not be allowed to execute.
430 {erl_script_nocache, boolean()}:
432 If erl_script_nocache is set to true, the server adds HTTP header
433 fields preventing proxies from caching the page. This is generally
434 a good idea for dynamic content, as the content often varies
435 between each request. Default is false.
436 {erl_script_timeout, integer()}:
438 If erl_script_timeout sets the time in seconds the server waits
439 between each chunk of data to be delivered through
440 mod_esi:deliver/2. Default is 15. This is only relevant for scripts
441 that use the erl scheme.
442 {eval_script_alias, {URLPath, [AllowedModule]}}:
444 URLPath = string() and AllowedModule = atom(). Same as
445 erl_script_alias but for scripts using the eval scheme. This is
446 only supported for backwards compatibility. The eval scheme is dep‐
447 recated.
448 Log Properties - Requires mod_log
450 {error_log, path()}:
452 Defines the filename of the error log file to be used to log server
453 errors. If the filename does not begin with a slash (/), it is
454 assumed to be relative to the server_root.
455 {security_log, path()}:
457 Defines the filename of the access log file to be used to log secu‐
458 rity events. If the filename does not begin with a slash (/), it is
459 assumed to be relative to the server_root.
460 {transfer_log, path()}:
462 Defines the filename of the access log file to be used to log
463 incoming requests. If the filename does not begin with a slash (/),
464 it is assumed to be relative to the server_root.
465 Disk Log Properties - Requires mod_disk_log
467 {disk_log_format, internal | external}:
469 Defines the file format of the log files. See disk_log for details.
470 If the internal file format is used, the log file is repaired after
471 a crash. When a log file is repaired, data can disappear. When the
472 external file format is used, httpd does not start if the log file
473 is broken. Default is external.
474 {error_disk_log, path()}:
476 Defines the filename of the (disk_log(3)) error log file to be used
477 to log server errors. If the filename does not begin with a slash
478 (/), it is assumed to be relative to the server_root.
479 {error_disk_log_size, {MaxBytes, MaxFiles}}:
481 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
482 ties of the (disk_log(3)) error log file. This file is of type wrap
483 log and max bytes is written to each file and max files is used
484 before the first file is truncated and reused.
485 {security_disk_log, path()}:
487 Defines the filename of the (disk_log(3)) access log file logging
488 incoming security events, that is, authenticated requests. If the
489 filename does not begin with a slash (/), it is assumed to be rela‐
490 tive to the server_root.
491 {security_disk_log_size, {MaxBytes, MaxFiles}}:
493 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
494 ties of the disk_log(3) access log file. This file is of type wrap
495 log and max bytes is written to each file and max files is used
496 before the first file is truncated and reused.
497 {transfer_disk_log, path()}:
499 Defines the filename of the (disk_log(3)) access log file logging
500 incoming requests. If the filename does not begin with a slash (/),
501 it is assumed to be relative to the server_root.
502 {transfer_disk_log_size, {MaxBytes, MaxFiles}}:
504 MaxBytes = integer() and MaxFiles = integer(). Defines the proper‐
505 ties of the disk_log(3) access log file. This file is of type wrap
506 log and max bytes is written to each file and max files is used
507 before the first file is truncated and reused.
508 Authentication Properties - Requires mod_auth
510 {directory, {path(), [{property(), term()}]}}
512 The properties for directories are as follows:
514 {allow_from, all | [RegxpHostString]}:
516 Defines a set of hosts to be granted access to a given directory,
517 for example:
518 {allow_from, ["123.34.56.11", "150.100.23"]}
520 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
522 allowed access.
523 {deny_from, all | [RegxpHostString]}:
525 Defines a set of hosts to be denied access to a given directory,
526 for example:
527 {deny_from, ["123.34.56.11", "150.100.23"]}
529 The host 123.34.56.11 and all machines on the 150.100.23 subnet are
531 not allowed access.
532 {auth_type, plain | dets | mnesia}:
534 Sets the type of authentication database that is used for the
535 directory. The key difference between the different methods is that
536 dynamic data can be saved when Mnesia and Dets are used. This prop‐
537 erty is called AuthDbType in the Apache-like configuration files.
538 {auth_user_file, path()}:
540 Sets the name of a file containing the list of users and passwords
541 for user authentication. The filename can be either absolute or
542 relative to the server_root. If using the plain storage method,
543 this file is a plain text file where each line contains a username
544 followed by a colon, followed by the non-encrypted password. If
545 usernames are duplicated, the behavior is undefined.
546 Example:
548 ragnar:s7Xxv7
550 edward:wwjau8
551 If the Dets storage method is used, the user database is maintained
553 by Dets and must not be edited by hand. Use the API functions in
554 module mod_auth to create/edit the user database. This directive is
555 ignored if the Mnesia storage method is used. For security reasons,
556 ensure that auth_user_file is stored outside the document tree of
557 the web server. If it is placed in the directory that it protects,
558 clients can download it.
559 {auth_group_file, path()}:
561 Sets the name of a file containing the list of user groups for user
562 authentication. The filename can be either absolute or relative to
563 the server_root. If the plain storage method is used, the group
564 file is a plain text file, where each line contains a group name
565 followed by a colon, followed by the members usernames separated by
566 spaces.
567 Example:
569 group1: bob joe ante
571 If the Dets storage method is used, the group database is main‐
573 tained by Dets and must not be edited by hand. Use the API for mod‐
574 ule mod_auth to create/edit the group database. This directive is
575 ignored if the Mnesia storage method is used. For security reasons,
576 ensure that the auth_group_file is stored outside the document tree
577 of the web server. If it is placed in the directory that it pro‐
578 tects, clients can download it.
579 {auth_name, string()}:
581 Sets the name of the authorization realm (auth-domain) for a direc‐
582 tory. This string informs the client about which username and pass‐
583 word to use.
584 {auth_access_password, string()}:
586 If set to other than "NoPassword", the password is required for all
587 API calls. If the password is set to "DummyPassword", the password
588 must be changed before any other API calls. To secure the authenti‐
589 cating data, the password must be changed after the web server is
590 started. Otherwise it is written in clear text in the configuration
591 file.
592 {require_user, [string()]}:
594 Defines users to grant access to a given directory using a secret
595 password.
596 {require_group, [string()]}:
598 Defines users to grant access to a given directory using a secret
599 password.
600 Htaccess Authentication Properties - Requires mod_htaccess
602 {access_files, [path()]}:
604 Specifies the filenames that are used for access files. When a
605 request comes, every directory in the path to the requested asset
606 are searched after files with the names specified by this parame‐
607 ter. If such a file is found, the file is parsed and the restric‐
608 tions specified in it are applied to the request.
609 Security Properties - Requires mod_security
611 {security_directory, {path(), [{property(), term()}]}}
613 The properties for the security directories are as follows:
615 {data_file, path()}:
617 Name of the security data file. The filename can either be absolute
618 or relative to the server_root. This file is used to store persis‐
619 tent data for module mod_security.
620 {max_retries, integer()}:
622 Specifies the maximum number of attempts to authenticate a user
623 before the user is blocked out. If a user successfully authenti‐
624 cates while blocked, the user receives a 403 (Forbidden) response
625 from the server. If the user makes a failed attempt while blocked,
626 the server returns 401 (Unauthorized), for security reasons.
627 Default is 3. Can be set to infinity.
628 {block_time, integer()}:
630 Specifies the number of minutes a user is blocked. After this time‐
631 has passed, the user automatically regains access. Default is 60.
632 {fail_expire_time, integer()}:
634 Specifies the number of minutes a failed user authentication is
635 remembered. If a user authenticates after this time has passed, the
636 previous failed authentications are forgotten. Default is 30.
637 {auth_timeout, integer()}:
639 Specifies the number of seconds a successful user authentication
640 is remembered. After this time has passed, the authentication is no
641 longer reported. Default is 30.
642
644 info(Pid) ->
645 info(Pid, Properties) -> [{Option, Value}]
646 Types:
648 Properties = [property()]
650 Option = property()
651 Value = term()
652 Fetches information about the HTTP server. When called with only
654 the pid, all properties are fetched. When called with a list of
655 specific properties, they are fetched. The available properties
656 are the same as the start options of the server.
657 Note:
659 Pid is the pid returned from inets:start/[2,3]. Can also be
660 retrieved form inets:services/0 and inets:services_info/0, see
661 inets(3).
662 info(Address, Port) ->
665 info(Address, Port, Profile) ->
666 info(Address, Port, Profile, Properties) -> [{Option, Value}]
667 info(Address, Port, Properties) -> [{Option, Value}]
668 Types:
670 Address = ip_address()
672 Port = integer()
673 Profile = atom()
674 Properties = [property()]
675 Option = property()
676 Value = term()
677 Fetches information about the HTTP server. When called with only
679 Address and Port, all properties are fetched. When called with a
680 list of specific properties, they are fetched. The available
681 properties are the same as the start options of the server.
682 Note:
684 The address must be the IP address and cannot be the hostname.
685 reload_config(Config, Mode) -> ok | {error, Reason}
688 Types:
690 Config = path() | [{Option, Value}]
692 Option = property()
693 Value = term()
694 Mode = non_disturbing | disturbing
695 Reloads the HTTP server configuration without restarting the
697 server. Incoming requests are answered with a temporary down
698 message during the reload time.
699 Note:
701 Available properties are the same as the start options of the
702 server, but the properties bind_address and port cannot be
703 changed.
704 If mode is disturbing, the server is blocked forcefully, all
707 ongoing requests terminates, and the reload starts immediately.
708 If mode is non-disturbing, no new connections are accepted, but
709 ongoing requests are allowed to complete before the reload is
710 done.
711
713 The Erlang web server API data types are as follows:
714 ModData = #mod{}
716 -record(mod, {
718 data = [],
719 socket_type = ip_comm,
720 socket,
721 config_db,
722 method,
723 absolute_uri,
724 request_uri,
725 http_version,
726 request_line,
727 parsed_header = [],
728 entity_body,
729 connection
730 }).
731 To acess the record in your callback-module use:
733 -include_lib("inets/include/httpd.hrl").
735 The fields of record mod have the following meaning:
737 data:
739 Type [{InteractionKey,InteractionValue}] is used to propagate data
740 between modules. Depicted interaction_data() in function type dec‐
741 larations.
742 socket_type:
744 socket_type() indicates whether it is an IP socket or an ssl
745 socket.
746 socket:
748 The socket, in format ip_comm or ssl, depending on socket_type.
749 config_db:
751 The config file directives stored as key-value tuples in an ETS ta‐
752 ble. Depicted config_db() in function type declarations.
753 method:
755 Type "GET" | "POST" | "HEAD" | "TRACE", that is, the HTTP method.
756 absolute_uri:
758 If the request is an HTTP/1.1 request, the URI can be in the abso‐
759 lute URI format. In that case, httpd saves the absolute URI in this
760 field. An Example of an absolute URI is "http://Server‐
761 Name:Part/cgi-bin/find.pl?person=jocke"
762 request_uri:
764 The Request-URI as defined in RFC 1945, for example, "/cgi-
765 bin/find.pl?person=jocke".
766 http_version:
768 The HTTP version of the request, that is, "HTTP/0.9", "HTTP/1.0",
769 or "HTTP/1.1".
770 request_line:
772 The Request-Line as defined inRFC 1945, for example, "GET /cgi-
773 bin/find.pl?person=jocke HTTP/1.0".
774 parsed_header:
776 Type [{HeaderKey,HeaderValue}]. parsed_header contains all HTTP
777 header fields from the HTTP request stored in a list as key-value
778 tuples. See RFC 2616 for a listing of all header fields. For exam‐
779 ple, the date field is stored as {"date","Wed, 15 Oct 1997 14:35:17
780 GMT"}. RFC 2616 defines that HTTP is a case-insensitive protocol
781 and the header fields can be in lower case or upper case. httpd
782 ensures that all header field names are in lower case.
783 entity_body:
785 The entity-Body as defined in RFC 2616, for example, data sent from
786 a CGI script using the POST method.
787 connection:
789 true | false. If set to true, the connection to the client is a
790 persistent connection and is not closed when the request is served.
791
794 Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break,
795 NewData} | done
796 Types:
798 OldData = list()
800 NewData = [{response,{StatusCode,Body}}]
801 | [{response,{response,Head,Body}}]
802 | [{response,{already_sent,Statuscode,Size}}]
803 StatusCode = integer()
804 Body = io_list() | nobody | {Fun, Arg}
805 Head = [HeaderOption]
806 HeaderOption = {Option, Value} | {code, StatusCode}
807 Option = accept_ranges | allow
808 | cache_control | content_MD5
809 | content_encoding | content_language
810 | content_length | content_location
811 | content_range | content_type | date
812 | etag | expires | last_modified
813 | location | pragma | retry_after
814 | server | trailer | transfer_encoding
815 Value = string()
816 Fun = fun( Arg ) -> sent| close | Body
817 Arg = [term()]
818 When a valid request reaches httpd, it calls do/1 in each mod‐
820 ule, defined by the configuration option of Module. The function
821 can generate data for other modules or a response that can be
822 sent back to the client.
823 The field data in ModData is a list. This list is the list
825 returned from the last call to do/1.
826 Body is the body of the HTTP response that is sent back to the
828 client. An appropriate header is appended to the message. Sta‐
829 tusCode is the status code of the response, see RFC 2616 for the
830 appropriate values.
831 Head is a key value list of HTTP header fields. The server con‐
833 structs an HTTP header from this data. See RFC 2616 for the
834 appropriate value for each header field. If the client is an
835 HTTP/1.0 client, the server filters the list so that only
836 HTTP/1.0 header fields are sent back to the client.
837 If Body is returned and equal to {Fun,Arg}, the web server tries
839 apply/2 on Fun with Arg as argument. The web server expects that
840 the fun either returns a list (Body) that is an HTTP repsonse,
841 or the atom sent if the HTTP response is sent back to the
842 client. If close is returned from the fun, something has gone
843 wrong and the server signals this to the client by closing the
844 connection.
845 Module:load(Line, AccIn)-> eof | ok | {ok, AccOut} | {ok, AccOut,
847 {Option, Value}} | {ok, AccOut, [{Option, Value}]} | {error, Reason}
848 Types:
850 Line = string()
852 AccIn = [{Option, Value}]
853 AccOut = [{Option, Value}]
854 Option = property()
855 Value = term()
856 Reason = term()
857 Converts a line in an Apache-like configuration file to an
859 {Option, Value} tuple. Some more complex configuration options,
860 such as directory and security_directory, create an accumulator.
861 This function only needs clauses for the options implemented by
862 this particular callback module.
863 Module:remove(ConfigDB) -> ok | {error, Reason}
865 Types:
867 ConfigDB = ets_table()
869 Reason = term()
870 When httpd is shut down, it tries to execute remove/1 in each
872 Erlang web server callback module. The programmer can use this
873 function to clean up resources created in the store function.
874 Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} |
876 {error, Reason}
877 Types:
879 Line = string()
881 Option = property()
882 Config = [{Option, Value}]
883 Value = term()
884 Reason = term()
885 Checks the validity of the configuration options before saving
887 them in the internal database. This function can also have a
888 side effect, that is, setup of necessary extra resources implied
889 by the configuration option. It can also resolve possible depen‐
890 dencies among configuration options by changing the value of the
891 option. This function only needs clauses for the options imple‐
892 mented by this particular callback module.
893
896 parse_query(QueryString) -> [{Key,Value}]
897 Types:
899 QueryString = string()
901 Key = string()
902 Value = string()
903 parse_query/1 parses incoming data to erl and eval scripts (see
905 mod_esi(3)) as defined in the standard URL format, that is, '+'
906 becomes 'space' and decoding of hexadecimal characters (%xx).
907
909 RFC 2616, inets(3), ssl(3)
910Ericsson AB inets 6.5.2.4 httpd(3)
