The R13B03 release.OTP_R13B03

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>
+