aboutsummaryrefslogtreecommitdiffstats
path: root/lib/inets/doc/src/httpd.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/inets/doc/src/httpd.xml')
-rw-r--r--lib/inets/doc/src/httpd.xml1089
1 files changed, 1089 insertions, 0 deletions
diff --git a/lib/inets/doc/src/httpd.xml b/lib/inets/doc/src/httpd.xml
new file mode 100644
index 0000000000..60afcc6cfe
--- /dev/null
+++ b/lib/inets/doc/src/httpd.xml
@@ -0,0 +1,1089 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>httpd</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>httpd.sgml</file>
+ </header>
+ <module>httpd</module>
+ <modulesummary>An implementation of an HTTP
+ 1.1 compliant Web server, as defined in RFC 2616.
+ </modulesummary>
+ <description>
+ <p>Documents the HTTP server start options, some administrative
+ functions and also specifies the Erlang Web server callback
+ API</p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in
+ this module:</p>
+ <p><c>boolean() = true | false </c></p>
+ <p><c>string() = list of ASCII characters</c></p>
+ <p><c>path() = string() - representing a file or directory path.</c></p>
+ <p><c> ip_address() = {N1,N2,N3,N4} % IPv4
+ | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6</c></p>
+ <p><c>hostname() = string() - representing a host ex "foo.bar.com"</c></p>
+ <p><c>property() = atom()</c></p>
+
+ </section>
+
+ <section>
+ <title>ERLANG HTTP SERVER SERVICE START/STOP </title>
+ <p>A web server can be configured to start when starting the inets
+ application or started dynamically in runtime by calling the
+ Inets application API <c>inets:start(httpd, ServiceConfig)</c>, or
+ <c>inets:start(httpd, ServiceConfig, How)</c>,
+ see <seealso marker="inets">inets(3)</seealso> Below follows a
+ description of the available configuration options, also called
+ properties.</p>
+
+ <marker id="file_prop"></marker>
+ <p><em>File properties</em></p>
+
+ <p>When the web server is started
+ at application start time the properties should be fetched from a
+ configuration file that could consist of a regular erlang property
+ list, e.i. <c>[{Option, Value}] </c> where <c> Option = property()
+ </c> and <c>Value = term()</c>, followed by a full stop, or for
+ backwards compatibility an Apache like configuration file. If the
+ web server is started dynamically at runtime you may still specify
+ a file but you could also just specify the complete property
+ list.</p>
+
+ <taglist>
+ <tag>{proplist_file, path()}</tag>
+ <item>
+ If this property is defined inets will expect to find
+ all other properties defined in this file. Note that the
+ file must include all properties listed under mandatory
+ properties. </item>
+ <tag>{file, path()}</tag>
+
+ <item> If this property is defined
+ inets will expect to find all other properties defined in this
+ file, that uses Apache like syntax. Note that the file must
+ include all properties listed under mandatory properties. The
+ Apache like syntax is the property, written as one word where
+ each new word begins with a capital, followed by a white-space
+ followed by the value followed by a new line. Ex:
+
+ <code>
+ {server_root, "/urs/local/www"} -> ServerRoot /usr/local/www
+ </code>
+
+ <p>With a few exceptions, that are documented
+ for each property that behaves differently,
+ and the special case {directory, {path(), PropertyList}} and
+ {security_directory, {Dir, PropertyList}} that are represented
+ as:</p>
+ <pre>
+ <![CDATA[
+ <Directory Dir>
+ <Properties handled as described above>
+ </Directory>
+ ]]>
+ </pre>
+ </item>
+ </taglist>
+ <note>
+ <p>The properties proplist_file and file are mutually exclusive.</p>
+ </note>
+
+ <marker id="mand_prop"></marker>
+ <p><em>Mandatory properties</em></p>
+ <taglist>
+ <tag>{port, integer()} </tag>
+ <item>
+ The port that the HTTP server shall listen on.
+ If zero is specified as port, an arbitrary available port
+ will be picked and you can use the httpd:info/2 function to find
+ out which port was picked. </item>
+ <tag>{server_name, string()} </tag>
+ <item>
+ The name of your server, normally a fully qualified domain
+ name.
+ </item>
+ <tag>{server_root, path()} </tag>
+ <item>
+ Defines the servers home directory where log files etc can
+ be stored. Relative paths specified in other properties refer
+ to this directory.</item>
+ <tag>{document_root, path()}</tag>
+ <item>
+ Defines the top directory for the documents that
+ are available on the HTTP server.</item>
+ </taglist>
+
+ <marker id="comm_prop"></marker>
+ <p><em>Communication properties</em> </p>
+ <taglist>
+ <tag>{bind_address, ip_address() | hostname() | any} </tag>
+ <item>
+ Defaults to <c>any</c>. Note that <c>any</c> is denoted <em>*</em>
+ in the apache like configuration file.
+ </item>
+
+ <tag>{socket_type, ip_comm | ssl}</tag>
+ <item>
+ <p>Defaults to <c>ip_comm</c>. </p>
+ </item>
+
+ <tag>{ipfamily, inet | inet6 | inet6fb4}</tag>
+ <item>
+ <p>Defaults to <c>inet6fb4. </c> </p>
+ <p>Note that this option is only used when the option
+ <c>socket_type</c> has the value <c>ip_comm</c>. </p>
+ </item>
+
+ </taglist>
+
+ <p><em>Erlang Web server API modules</em> </p>
+ <taglist>
+ <tag>{modules, [atom()]} </tag>
+ <item>
+ Defines which modules the HTTP server will use to handle
+ requests. Defaults to: <c>[mod_alias, mod_auth, mod_esi,
+ mod_actions, mod_cgi, mod_dir, mod_get, mod_head, mod_log,
+ mod_disk_log] </c>
+ Note that some mod-modules are dependent on
+ others, so the order can not be entirely arbitrary. See the
+ <seealso marker="http_server"> Inets Web server Modules in the
+ Users guide</seealso> for more information.
+ </item>
+ </taglist>
+
+ <marker id="limit_prop"></marker>
+ <p><em>Limit properties</em> </p>
+ <taglist>
+ <tag>{disable_chunked_transfer_encoding_send, boolean()}</tag>
+ <item>
+ This property allows you to disable chunked
+ transfer-encoding when sending a response to a HTTP/1.1
+ client, by default this is false.</item>
+
+ <tag>{keep_alive, boolean()}</tag>
+ <item>
+ Instructs the server whether or not to use persistent
+ connections when the client claims to be HTTP/1.1
+ compliant, default is true.</item>
+
+ <tag>{keep_alive_timeout, integer()}</tag>
+ <item>
+ The number of seconds the server will wait for a
+ subsequent request from the client before closing the
+ connection. Default is 150.</item>
+
+ <tag>{max_body_size, integer()}</tag>
+ <item>
+ Limits the size of the message body of HTTP request.
+ By the default there is no limit.</item>
+
+ <tag>{max_clients, integer()}</tag>
+ <item>
+ Limits the number of simultaneous requests that can be
+ supported. Defaults to 150. </item>
+
+ <tag>{max_header_size, integer()}</tag>
+ <item>
+ Limits the size of the message header of HTTP request.
+ Defaults to 10240.
+ </item>
+
+ <tag>{max_uri, integer()}</tag>
+ <item>
+ Limits the size of the HTTP request URI. By
+ default there is no limit.</item>
+
+ <tag>{max_keep_alive_requests, integer()}</tag>
+ <item> The number of request that a client can do on one
+ connection. When the server has responded to the number of
+ requests defined by max_keep_alive_requests the server close the
+ connection. The server will close it even if there are queued
+ request. Defaults to no limit.</item>
+ </taglist>
+
+ <marker id="admin_prop"></marker>
+ <p><em>Administrative properties</em></p>
+ <taglist>
+ <tag>{mime_types, [{MimeType, Extension}] | path()}</tag>
+ <item>
+ <p>Where MimeType = string() and Extension = string().
+ Files delivered to the client are MIME typed according to RFC
+ 1590. File suffixes are mapped to MIME types before file delivery.
+ The mapping between file suffixes and MIME types can be specified
+ as an Apache like file as well as directly in the property list. Such
+ a file may look like:</p>
+ <pre>
+ \011 # MIME type\011\011\011Extension
+ \011 text/html\011\011\011html htm
+ \011 text/plain\011\011\011asc txt
+ </pre>
+
+ <p>Defaults to [{"html","text/html"},{"htm","text/html"}]</p>
+ </item>
+
+ <tag>{mime_type, string()}</tag>
+
+ <item>
+ When the server is asked to provide a document type which
+ cannot be determined by the MIME Type Settings, the server will
+ use this default type. </item>
+
+ <tag>{server_admin, string()}</tag>
+ <item>
+ ServerAdmin defines the email-address of the server
+ administrator, to be included in any error messages returned by
+ the server.</item>
+
+ <tag>{log_format, common | combined}</tag>
+ <item>
+ <p>Defines if access logs should be written according to the common
+ log format or to the extended common log format.
+ The <c>common</c> format is one line that looks like this:
+ <c>remotehost rfc931 authuser [date] "request" status bytes</c></p>
+
+ <pre>remotehost
+ Remote
+rfc931
+ The client's remote username (RFC 931).
+authuser
+ The username with which the user authenticated himself.
+[date]
+ Date and time of the request (RFC 1123).
+"request"
+ The request line exactly as it came from the client(RFC 1945).
+status
+ The HTTP status code returned to the client (RFC 1945).
+bytes
+ The content-length of the document transferred.
+ </pre>
+
+ <p>The <c>combined</c> format is on line that look like this:
+ <c>remotehost rfc931 authuser [date] "request" status bytes "referer" "user_agent" </c></p>
+
+ <pre>"referer"
+ The url the client was on before
+ requesting your url. (If it could not be determined a minus
+ sign will be placed in this field)
+"user_agent"
+ The software the client claims to be using. (If it
+ could not be determined a minus sign will be placed in
+ this field)
+ </pre>
+
+ <p>This affects the access logs written by mod_log and mod_disk_log.
+ </p>
+
+ </item>
+
+ <tag>{error_log_format, pretty | compact}</tag>
+ <item>
+ <p>Defaults to pretty. If the error log is meant to be read
+ directly by a human <c>pretty</c> will be the best
+ option. <c>pretty</c> has the format corresponding to:
+ </p>
+
+ <code>io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).
+ </code>
+
+ <p><c>compact</c> has the format corresponding to:</p>
+
+ <code>io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).
+ </code>
+
+ <p>This affects the error logs written by mod_log and mod_disk_log.
+ </p>
+ </item>
+
+ </taglist>
+
+ <marker id="ssl_prop"></marker>
+ <p><em>ssl properties</em></p>
+ <taglist>
+ <tag>{ssl_ca_certificate_file, path()}</tag>
+ <item>
+ Used as cacertfile option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso> </item>
+
+ <tag>{ssl_certificate_file, path()}</tag>
+ <item>
+ Used as certfile option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </item>
+
+ <tag>{ssl_ciphers, list()}</tag>
+ <item>
+ Used as ciphers option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </item>
+
+ <tag>{ssl_verify_client, integer()}</tag>
+ <item>
+ Used as verify option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso> </item>
+
+ <tag>{ssl_verify_depth, integer()}</tag>
+ <item>
+ Used as depth option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso> </item>
+
+ <tag>{ssl_password_callback_function, atom()}</tag>
+ <item>
+ Used together with ssl_password_callback_module
+ to retrieve a value to use as password option to ssl:listen/2
+ see <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </item>
+
+ <tag>{ssl_password_callback_arguments, list()}</tag>
+ <item>
+ Used together with ssl_password_callback_function to supply a
+ list of arguments to the callback function. If not specified
+ the callback function will be assumed to have arity 0. </item>
+
+ <tag>{ssl_password_callback_module, atom()}</tag>
+ <item>
+ Used together with ssl_password_callback_function
+ to retrieve a value to use as password option to ssl:listen/2
+ see <seealso marker="ssl:ssl">ssl(3)</seealso></item>
+
+ </taglist>
+
+ <marker id="alias_prop"></marker>
+ <p><em>URL aliasing properties - requires mod_alias</em></p>
+ <taglist>
+ <tag>{alias, {Alias, RealName}}</tag>
+
+ <item> Where Alias = string() and RealName = string().
+ The Alias property allows documents to be stored in the local file
+ system instead of the document_root location. URLs with a path that
+ begins with url-path is mapped to local files that begins with
+ directory-filename, for example:
+
+ <code>{alias, {"/image", "/ftp/pub/image"}</code>
+
+ and an access to http://your.server.org/image/foo.gif would refer to
+ the file /ftp/pub/image/foo.gif.</item>
+
+ <tag>{directory_index, [string()]}</tag>
+
+ <item>
+ DirectoryIndex specifies a list of resources to look for
+ if a client requests a directory using a / at the end of the
+ directory name. file depicts the name of a file in the
+ directory. Several files may be given, in which case the server
+ will return the first it finds, for example:
+
+ <code>{directory_index, ["index.hml", "welcome.html"]}</code>
+
+ and access to http://your.server.org/docs/ would return
+ http://your.server.org/docs/index.html or
+ http://your.server.org/docs/welcome.html if index.html do not
+ exist.
+ </item>
+ </taglist>
+
+ <marker id="cgi_prop"></marker>
+ <p><em>CGI properties - requires mod_cgi</em></p>
+ <taglist>
+ <tag>{script_alias, {Alias, RealName}}</tag>
+ <item> Where Alias = string() and RealName = string().
+ Has the same behavior as the Alias property, except that
+ it also marks the target directory as containing CGI
+ scripts. URLs with a path beginning with url-path are mapped to
+ scripts beginning with directory-filename, for example:
+
+ <code> {script_alias, {"/cgi-bin/", "/web/cgi-bin/"}</code>
+
+ and an access to http://your.server.org/cgi-bin/foo would cause
+ the server to run the script /web/cgi-bin/foo.
+ </item>
+
+ <tag>{script_nocache, boolean()}</tag>
+
+ <item>
+ If ScriptNoCache is set to true the HTTP server will by
+ default add the header fields necessary to prevent proxies from
+ caching the page. Generally this is something you want. Defaults
+ to false.</item>
+
+ <tag>{script_timeout, integer()}</tag>
+
+ <item>
+ The time in seconds the web server will wait between each
+ chunk of data from the script. If the CGI-script not delivers
+ any data before the timeout the connection to the client will be
+ closed. Defaults to 15. </item>
+
+ <tag>{action, {MimeType, CgiScript}} - requires mod_action</tag>
+
+ <item>Where MimeType = string() and CgiScript = string().
+ Action adds an action, which will activate a cgi-script
+ whenever a file of a certain mime-type is requested. It
+ propagates the URL and file path of the requested document using
+ the standard CGI PATH_INFO and PATH_TRANSLATED environment
+ variables.
+ <code> {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}
+ </code>
+ </item>
+
+ <tag>{script, {Method, CgiScript}} - requires mod_action</tag>
+
+ <item>Where Method = string() and CgiScript = string().
+ Script adds an action, which will activate a cgi-script
+ whenever a file is requested using a certain HTTP method. The
+ method is either GET or POST as defined in RFC 1945. It
+ propagates the URL and file path of the requested document using
+ the standard CGI PATH_INFO and PATH_TRANSLATED environment
+ variables.
+
+ <code> {script, {"PUT", "/cgi-bin/put"}
+ </code>
+
+ </item>
+ </taglist>
+
+ <marker id="esi_prop"></marker>
+ <p><em>ESI properties - requires mod_esi</em></p>
+ <taglist>
+ <tag>{erl_script_alias, {URLPath, [AllowedModule]}}</tag>
+
+ <item>Where URLPath = string() and AllowedModule = atom().
+ erl_script_alias marks all URLs matching url-path as erl
+ scheme scripts. A matching URL is mapped into a specific module
+ and function. For example:
+
+ <code>{erl_script_alias, {"/cgi-bin/example" [httpd_example]}
+ </code>
+
+ and a request to
+ http://your.server.org/cgi-bin/example/httpd_example:yahoo
+ would refer to httpd_example:yahoo/2 and
+ http://your.server.org/cgi-bin/example/other:yahoo would
+ not be allowed to execute.
+ </item>
+
+ <tag>{erl_script_nocache, boolean()}</tag>
+
+ <item>
+ If erl_script_nocache is set to true the server will add
+ http header fields that prevents proxies from caching the
+ page. This is generally a good idea for dynamic content, since
+ the content often vary between each request. Defaults to false.
+ </item>
+
+ <tag>{erl_script_timeout, integer()}</tag>
+
+ <item>
+ If erl_script_timeout sets the time in seconds the server will
+ wait between each chunk of data to be delivered through
+ mod_esi:deliver/2. Defaults to 15. This is only relevant
+ for scripts that uses the erl scheme.
+ </item>
+
+ <tag>{eval_script_alias, {URLPath, [AllowedModule]}}</tag>
+
+ <item>Where URLPath = string() and AllowedModule = atom().
+ Same as erl_script_alias but for scripts
+ using the eval scheme. Note that this is only supported
+ for backwards compatibility. The eval scheme is deprecated.</item>
+ </taglist>
+
+ <marker id="log_prop"></marker>
+ <p><em>Log properties - requires mod_log</em></p>
+ <taglist>
+ <tag>{error_log, path()}</tag>
+
+ <item>
+ Defines the filename of the error log file to be used to log
+ server errors. If the filename does not begin with a slash (/)
+ it is assumed to be relative to the server_root</item>
+
+ <tag>{security_log, path()}</tag>
+
+ <item>
+ Defines the filename of the access log file to be used to
+ log security events. If the filename does not begin with a slash
+ (/) it is assumed to be relative to the server_root.
+ </item>
+
+ <tag>{transfer_log, path()}</tag>
+
+ <item>
+ Defines the filename of the access log file to be used to
+ log incoming requests. If the filename does not begin with a
+ slash (/) it is assumed to be relative to the server_root.
+ </item>
+ </taglist>
+
+ <marker id="dlog_prop"></marker>
+ <p><em>Disk Log properties - requires mod_disk_log</em></p>
+ <taglist>
+ <tag>{disk_log_format, internal | external}</tag>
+
+ <item>
+ Defines the file-format of the log files see disk_log for
+ more information. If the internal file-format is used, the
+ logfile will be repaired after a crash. When a log file is
+ repaired data might get lost. When the external file-format is
+ used httpd will not start if the log file is broken. Defaults to
+ external.
+ </item>
+
+ <tag>{error_disk_log, internal | external}</tag>
+
+ <item>
+ Defines the filename of the (disk_log(3)) error log file
+ to be used to log server errors. If the filename does not begin
+ with a slash (/) it is assumed to be relative to the server_root.
+ </item>
+
+ <tag>{error_disk_log_size, {MaxBytes, MaxFiles}}</tag>
+
+ <item>Where MaxBytes = integer() and MaxFiles = integer().
+ Defines the properties of the (disk_log(3)) error log
+ file. The disk_log(3) error log file is of type wrap log and
+ max-bytes will be written to each file and max-files will be
+ used before the first file is truncated and reused. </item>
+
+ <tag>{security_disk_log, path()}</tag>
+
+ <item>
+ Defines the filename of the (disk_log(3)) access log file
+ which logs incoming security events i.e authenticated
+ requests. If the filename does not begin with a slash (/) it
+ is assumed to be relative to the server_root.
+ </item>
+
+ <tag>{security_disk_log_size, {MaxBytes, MaxFiles}}</tag>
+
+ <item>Where MaxBytes = integer() and MaxFiles = integer().
+ Defines the properties of the disk_log(3) access log
+ file. The disk_log(3) access log file is of type wrap log and
+ max-bytes will be written to each file and max-files will be
+ used before the first file is truncated and reused.</item>
+
+ <tag>{transfer_disk_log, path()}</tag>
+
+ <item>
+ Defines the filename of the (disk_log(3)) access log file
+ which logs incoming requests. If the filename does not begin
+ with a slash (/) it is assumed to be relative to the
+ server_root.
+ </item>
+
+ <tag>{transfer_disk_log_size, {MaxBytes, MaxFiles}}</tag>
+
+ <item>Where MaxBytes = integer() and MaxFiles = integer().
+ Defines the properties of the disk_log(3) access log
+ file. The disk_log(3) access log file is of type wrap log and
+ max-bytes will be written to each file and max-files will be
+ used before the first file is truncated and reused.</item>
+ </taglist>
+
+ <marker id="auth_prop"></marker>
+ <p><em>Authentication properties - requires mod_auth</em></p>
+
+ <p><em>{directory, {path(), [{property(), term()}]}}</em></p>
+
+ <marker id="dir_prop"></marker>
+ <p>Here follows the valid properties for directories </p>
+
+ <taglist>
+ <tag>{allow_from, all | [RegxpHostString]}</tag>
+
+ <item>
+ Defines a set of hosts which should be granted access to a
+ given directory.
+
+ For example:
+
+ <code>{allow_from, ["123.34.56.11", "150.100.23"] </code>
+
+ The host 123.34.56.11 and all machines on the 150.100.23
+ subnet are allowed access.</item>
+
+ <tag>{deny_from, all | [RegxpHostString]}</tag>
+
+ <item>
+ Defines a set of hosts
+ which should be denied access to a given directory.
+ For example:
+
+ <code>{deny_from, ["123.34.56.11", "150.100.23"] </code>
+
+ The host 123.34.56.11 and all machines on the 150.100.23
+ subnet are not allowed access.</item>
+
+ <tag>{auth_type, plain | dets | mnesia}</tag>
+
+ <item>
+ Sets the type of authentication database that is used for the
+ directory.The key difference between the different methods is
+ that dynamic data can be saved when Mnesia and Dets is used.
+ This property is called AuthDbType in the Apache like
+ configuration files.
+ </item>
+
+ <tag>{auth_user_file, path()}</tag>
+
+ <item>
+ Sets the name of a file which contains the list of users and
+ passwords for user authentication. filename can be either
+ absolute or relative to the <c>server_root</c>. If using the
+ plain storage method, this file is a plain text file, where
+ each line contains a user name followed by a colon, followed
+ by the non-encrypted password. If user names are duplicated,
+ the behavior is undefined. For example:
+
+ <code> ragnar:s7Xxv7
+ edward:wwjau8 </code>
+
+ If using the dets storage method, the user database is
+ maintained by dets and should not be edited by hand. Use the
+ API functions in mod_auth module to create / edit the user
+ database. This directive is ignored if using the mnesia
+ storage method. For security reasons, make sure that the
+ <c>auth_user_file</c> is stored outside the document tree of the Web
+ server. If it is placed in the directory which it protects,
+ clients will be able to download it.
+ </item>
+
+ <tag>{auth_group_file, path()}</tag>
+
+ <item> Sets the name of a file which contains the list of user
+ groups for user authentication. Filename can be either
+ absolute or relative to the <c>server_root</c>. If you use the plain
+ storage method, the group file is a plain text file, where
+ each line contains a group name followed by a colon, followed
+ by the member user names separated by spaces. For example:
+
+ <code>group1: bob joe ante</code>
+
+ If using the dets storage method, the group database is
+ maintained by dets and should not be edited by hand. Use the
+ API for mod_auth module to create / edit the group database.
+ This directive is ignored if using the mnesia storage method.
+ For security reasons, make sure that the <c>auth_group_file</c> is
+ stored outside the document tree of the Web server. If it is
+ placed in the directory which it protects, clients will be
+ able to download it.</item>
+
+ <tag>{auth_name, string()}</tag>
+
+ <item>
+ Sets the name of the authorization realm (auth-domain) for
+ a directory. This string informs the client about which user
+ name and password to use. </item>
+
+ <tag>{auth_access_password, string()}</tag>
+
+ <item> If set to other than "NoPassword" the password is required
+ for all API calls. If the password is set to "DummyPassword" the
+ password must be changed before any other API calls. To secure
+ the authenticating data the password must be changed after the
+ web server is started since it otherwise is written in clear
+ text in the configuration file.</item>
+
+ <tag>{require_user, [string()]}</tag>
+ <item>
+ Defines users which should be granted access to a given
+ directory using a secret password.
+ </item>
+
+ <tag>{require_group, [string()]}</tag>
+ <item>
+ Defines users which should be granted access to a given
+ directory using a secret password.
+ </item>
+
+ </taglist>
+
+ <marker id="htaccess_prop"></marker>
+ <p><em>Htaccess authentication properties - requires mod_htaccess</em></p>
+ <taglist>
+ <tag>{access_files, [path()]}</tag>
+
+ <item> Specify which filenames that are used for
+ access-files. When a request comes every directory in the path
+ to the requested asset will be searched after files with the
+ names specified by this parameter. If such a file is found the
+ file will be parsed and the restrictions specified in it will
+ be applied to the request.
+ </item>
+ </taglist>
+
+ <marker id="sec_prop"></marker>
+ <p><em>Security properties - requires mod_security </em></p>
+
+ <p><em>{security_directory, {path(), [{property(), term()}]}</em></p>
+
+ <marker id="sdir_prop"></marker>
+ <p> Here follows the valid properties for security directories</p>
+ <taglist>
+ <tag>{security_data_file, path()}</tag>
+
+ <item>
+ Name of the security data file. The filename can either
+ absolute or relative to the server_root. This file is used to
+ store persistent data for the mod_security module. </item>
+
+ <tag>{security_max_retries, integer()}</tag>
+
+ <item> Specifies the maximum number of tries to authenticate a
+ user has before the user is blocked out. If a user
+ successfully authenticates when the user has been blocked, the
+ user will receive a 403 (Forbidden) response from the
+ server. If the user makes a failed attempt while blocked the
+ server will return 401 (Unauthorized), for security
+ reasons. Defaults to 3 may also be set to infinity.</item>
+
+ <tag>{security_block_time, integer()}</tag>
+
+ <item> Specifies the number of minutes a user is blocked. After
+ this amount of time, he automatically regains access.
+ Defaults to 60</item>
+
+ <tag>{security_fail_expire_time, integer()}</tag>
+
+ <item>
+ Specifies the number of minutes a failed user authentication
+ is remembered. If a user authenticates after this amount of
+ time, his previous failed authentications are
+ forgotten. Defaults to 30</item>
+
+ <tag>{security_auth_timeout, integer()}</tag>
+
+ <item>
+ Specifies the number of seconds a successful user
+ authentication is remembered. After this time has passed, the
+ authentication will no longer be reported. Defaults to 30.
+ </item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>info(Pid) -></name>
+ <name>info(Pid, Properties) -> [{Option, Value}]</name>
+ <fsummary>Fetches information about the HTTP server</fsummary>
+ <type>
+ <v>Properties = [property()]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Fetches information about the HTTP server. When called
+ with only the pid all properties are fetched, when called
+ with a list of specific properties they are fetched.
+ Available properties are the same as the servers start options.
+ </p>
+
+ <note><p>Pid is the pid returned from inets:start/[2,3].
+ Can also be retrieved form inets:services/0, inets:services_info/0
+ see <seealso marker="inets">inets(3)</seealso>
+ </p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name>info(Address, Port) -> </name>
+ <name>info(Address, Port, Properties) -> [{Option, Value}] </name>
+ <fsummary>Fetches information about the HTTP server</fsummary>
+ <type>
+ <v>Address = ip_address()</v>
+ <v>Port = integer()</v>
+ <v>Properties = [property()]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Fetches information about the HTTP server. When called with
+ only the Address and Port all properties are fetched, when
+ called with a list of specific properties they are fetched.
+ Available properties are the same as the servers start
+ options.
+ </p>
+
+ <note><p> Address has to be the ip-address and can not be
+ the hostname.
+ </p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name>reload_config(Config, Mode) -> ok | {error, Reason}</name>
+ <fsummary>Reloads the HTTP server configuration without
+ restarting the server.</fsummary>
+ <type>
+ <v>Config = path() | [{Option, Value}]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ <v>Mode = non_disturbing | disturbing</v>
+ </type>
+ <desc>
+ <p>Reloads the HTTP server configuration without restarting the
+ server. Incoming requests will be answered with a temporary
+ down message during the time the it takes to reload.</p>
+
+ <note><p>Available properties are the same as the servers
+ start options, although the properties bind_address and
+ port can not be changed.</p></note>
+
+ <p>If mode is disturbing, the server is blocked forcefully and
+ all ongoing requests are terminated and the reload will
+ start immediately. If mode is non-disturbing, no new
+ connections are accepted, but the ongoing requests are
+ allowed to complete before the reload is done.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>ERLANG WEB SERVER API DATA TYPES </title>
+ <code type="none">
+ ModData = #mod{}
+
+ -record(mod, {
+\011\011data = [],
+\011\011socket_type = ip_comm,
+\011\011socket,
+\011\011config_db,
+\011\011method,
+\011\011absolute_uri,
+\011\011request_uri,
+\011\011http_version,
+\011\011request_line,
+\011\011parsed_header = [],
+\011\011entity_body,
+\011\011connection
+\011 }).
+ </code>
+ <p>The fields of the <c>mod</c> record has the following meaning:
+ </p>
+ <taglist>
+ <tag><c>data</c></tag>
+ <item>Type <c>[{InteractionKey,InteractionValue}]</c> is used to
+ propagate data between modules. Depicted
+ <c>interaction_data()</c> in function type declarations.
+ </item>
+ <tag><c>socket_type</c></tag>
+ <item><c>socket_type()</c>,
+ Indicates whether it is an ip socket or a ssl socket.
+ </item>
+ <tag><c>socket</c></tag>
+ <item>The actual socket in <c>ip_comm</c> or <c>ssl</c> format
+ depending on the <c>socket_type</c>.
+ </item>
+ <tag><c>config_db</c></tag>
+ <item>The config file directives stored as key-value tuples in
+ an ETS-table. Depicted <c>config_db()</c> in function type
+ declarations.
+ </item>
+ <tag><c>method</c></tag>
+ <item>Type <c>"GET" | "POST" | "HEAD" | "TRACE"</c>, that is the
+ HTTP method.
+ </item>
+ <tag><c>absolute_uri</c></tag>
+ <item>If the request is a HTTP/1.1
+ request the URI might be in the absolute URI format. In that
+ case httpd will save the absolute URI in this field. An Example
+ of an absolute URI could
+ be<c>"http://ServerName:Part/cgi-bin/find.pl?person=jocke"</c></item>
+ <tag><c>request_uri</c></tag>
+ <item>The <c>Request-URI</c> as defined
+ in RFC 1945, for example <c>"/cgi-bin/find.pl?person=jocke"</c></item>
+ <tag><c>http_version</c></tag>
+ <item>The <c>HTTP</c> version of the
+ request, that is "HTTP/0.9", "HTTP/1.0", or "HTTP/1.1".
+ </item>
+ <tag><c>request_line</c></tag>
+ <item>The <c>Request-Line</c> as
+ defined in RFC 1945, for example <c>"GET /cgi-bin/find.pl?person=jocke HTTP/1.0"</c>.
+ </item>
+ <tag><c>parsed_header</c></tag>
+ <item>Type <c>[{HeaderKey,HeaderValue}]</c>,
+ <c>parsed_header</c> contains all HTTP header fields from the
+ HTTP-request stored in a list as key-value tuples. See RFC 2616
+ for a listing of all header fields. For example the date field
+ would be stored as: <c>{"date","Wed, 15 Oct 1997 14:35:17 GMT"}.
+ RFC 2616 defines that HTTP is a case insensitive protocol and
+ the header fields may be in lower case or upper case. Httpd will
+ ensure that all header field names are in lower case. </c>.
+ </item>
+ <tag><c>entity_body</c></tag>
+ <item>The <c>Entity-Body</c> as defined
+ in RFC 2616, for example data sent from a CGI-script using the
+ POST method.
+ </item>
+ <tag><c>connection</c></tag>
+ <item><c>true | false</c> If set to true the connection to the
+ client is a persistent connection and will not be closed when
+ the request is served.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>ERLANG WEB SERVER API CALLBACK FUNCTIONS</title>
+ </section>
+ <funcs>
+ <func>
+ <name>Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break, NewData} | done</name>
+ <fsummary>Called for each request to the Web server.</fsummary>
+ <type>
+ <v>OldData = list()</v>
+ <v>NewData = [{response,{StatusCode,Body}}] | [{response,{response,Head,Body}}] | [{response,{already_sent,Statuscode,Size}] </v>
+ <v>StausCode = integer()</v>
+ <v>Body = io_list() | nobody | {Fun, Arg}</v>
+ <v>Head = [HeaderOption]</v>
+ <v>HeaderOption = {Option, Value} | {code, StatusCode}</v>
+ <v>Option = accept_ranges | allow | cache_control | content_MD5 | content_encoding | content_language | content_length | content_location | content_range | content_type | date | etag | expires | last_modified | location | pragma | retry_after | server | trailer | transfer_encoding</v>
+ <v>Value = string()</v>
+ <v>Fun = fun( Arg ) -> sent| close | Body </v>
+ <v>Arg = [term()]</v>
+ </type>
+ <desc>
+ <p>When a valid request reaches httpd it calls <c>do/1</c> in
+ each module defined by the Modules configuration
+ option. The function may generate data for other modules
+ or a response that can be sent back to the client.</p>
+ <p>The field <c>data</c> in ModData is a list. This list will be
+ the list returned from the last call to
+ <c>do/1</c>.</p>
+ <p><c>Body</c> is the body of the http-response that will be
+ sent back to the client an appropriate header will be
+ appended to the message. <c>StatusCode</c> will be the
+ status code of the response see RFC2616 for the appropriate
+ values.</p>
+ <p><c>Head</c> is a key value list of HTTP header fields. The
+ server will construct a HTTP header from this data. See RFC
+ 2616 for the appropriate value for each header field. If the
+ client is a HTTP/1.0 client then the server will filter the
+ list so that only HTTP/1.0 header fields will be sent back
+ to the client.</p>
+ <p>If <c>Body</c> is returned and equal to <c>{Fun,Arg}</c>,
+ the Web server will try <c>apply/2</c> on <c>Fun</c> with
+ <c>Arg</c> as argument and expect that the fun either
+ returns a list <c>(Body)</c> that is a HTTP-repsonse or the
+ atom sent if the HTTP-response is sent back to the
+ client. If close is returned from the fun something has gone
+ wrong and the server will signal this to the client by
+ closing the connection.</p>
+ </desc>
+ </func>
+ <func>
+ <name>Module:load(Line, AccIn)-> eof | ok | {ok, AccOut} | {ok, AccOut, {Option, Value}} | {ok, AccOut, [{Option, Value}]} | {error, Reason} </name>
+ <fsummary>Load is used to convert a line in a Apache like config
+ file to a <c>{Option, Value}</c> tuple.</fsummary>
+ <type>
+ <v>Line = string()</v>
+ <v>AccIn = [{Option, Value}]</v>
+ <v>AccOut = [{Option, Value}]</v>
+ <v>Option = property()</v>
+ <v>Value = term() </v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Load is used to convert a line in a Apache like
+ configuration file to a <c>{Option, Value}</c> tuple. Some
+ more complex configuration options such as <c>directory</c>
+ and <c>security_directory</c> will create an
+ accumulator.This function does only need clauses for the
+ options implemented by this particular callback module.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} | {error, Reason} </name>
+ <fsummary></fsummary>
+ <type>
+ <v>Line = string()</v>
+ <v>Option = property()</v>
+ <v>Config = [{Option, Value}]</v>
+ <v>Value = term() </v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>This function is used to check the validity of the
+ configuration options before saving them in the internal
+ database. This function may also have a side effect
+ e.i. setup necessary extra resources implied by the
+ configuration option. It can also
+ resolve possible dependencies among
+ configuration options by changing the value of the option.
+ This function does only need clauses for the options
+ implemented by this particular callback module.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:remove(ConfigDB) -> ok | {error, Reason} </name>
+ <fsummary>Callback function that is called when the Web server is closed.</fsummary>
+ <type>
+ <v>ConfigDB = ets_table()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>When httpd is shutdown it will try to execute
+ <c>remove/1</c> in each Erlang web server callback module. The
+ programmer may use this function to clean up resources
+ that may have been created in the store function.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>ERLANG WEB SERVER API HELP FUNCTIONS</title>
+ </section>
+ <funcs>
+ <func>
+ <name>parse_query(QueryString) -> [{Key,Value}]</name>
+ <fsummary>Parse incoming data to <c>erl </c>and <c>eval </c>scripts.</fsummary>
+ <type>
+ <v>QueryString = string()</v>
+ <v>Key = string()</v>
+ <v>Value = string()</v>
+ </type>
+ <desc>
+ <marker id="parse_query"></marker>
+ <p><c>parse_query/1</c> parses incoming data to <c>erl</c> and
+ <c>eval</c> scripts (See <seealso marker="mod_esi">mod_esi(3)</seealso>) as defined in the standard
+ URL format, that is '+' becomes 'space' and decoding of
+ hexadecimal characters (<c>%xx</c>).</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>RFC 2616, <seealso marker="inets">inets(3)</seealso>,
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </p>
+ </section>
+
+</erlref>
+