aboutsummaryrefslogtreecommitdiffstats
path: root/lib/inets/doc/src/http_server.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/inets/doc/src/http_server.xml')
-rw-r--r--lib/inets/doc/src/http_server.xml1004
1 files changed, 1004 insertions, 0 deletions
diff --git a/lib/inets/doc/src/http_server.xml b/lib/inets/doc/src/http_server.xml
new file mode 100644
index 0000000000..56317d647c
--- /dev/null
+++ b/lib/inets/doc/src/http_server.xml
@@ -0,0 +1,1004 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</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>HTTP server </title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file>http_server.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+
+ <p>The HTTP server, also referred to as httpd, handles HTTP requests
+ as described in RFC 2616 with a few exceptions such as gateway
+ and proxy functionality. The server supports ipv6 as long as the
+ underlying mechanisms also do so. </p>
+
+ <p>The server implements numerous features such as SSL (Secure Sockets
+ Layer), ESI (Erlang Scripting Interface), CGI (Common Gateway
+ Interface), User Authentication(using Mnesia, dets or plain text
+ database), Common Logfile Format (with or without disk_log(3)
+ support), URL Aliasing, Action Mappings, Directory Listings and SSI
+ (Server-Side Includes).</p>
+
+ <p>The configuration of the server is provided as an erlang
+ property list, and for backwards compatibility also a configuration
+ file using apache-style configuration directives is
+ supported.</p>
+
+ <p>As of inets version 5.0 the HTTP server is an easy to
+ start/stop and customize web server that provides the most basic
+ web server functionality. Depending on your needs there
+ are also other erlang based web servers that may be of interest
+ such as Yaws, http://yaws.hyber.org, that for instance has its own
+ markup support to generate html, and supports certain buzzword
+ technologies such as SOAP.</p>
+
+ <p>Allmost all server functionality has been implemented using an
+ especially crafted server API, it is described in the Erlang Web
+ Server API. This API can be used to advantage by all who wants
+ to enhance the server core functionality, for example custom
+ logging and authentication.</p>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <p> What to put in the erlang node application configuration file
+ in order to start a http server at application startup.</p>
+
+ <code type="erl">
+ [{inets, [{services, [{httpd, [{proplist_file,
+ "/var/tmp/server_root/conf/8888_props.conf"}]},
+ {httpd, [{proplist_file,
+ "/var/tmp/server_root/conf/8080_props.conf"}]}]}]}].
+ </code>
+
+ <p>The server is configured using an erlang property list.
+ For the available properties see
+ <seealso marker="inets:inets">httpd(3)</seealso>
+ For backwards compatibility also apache-like config files
+ are supported.
+ </p>
+
+ <p>All possible config properties are as follows </p>
+ <code type="none">
+ httpd_service() -> {httpd, httpd()}
+ httpd() -> [httpd_config()]
+ httpd_config() -> {file, file()} |
+ {proplist_file, file()}
+ {debug, debug()} |
+ {accept_timeout, integer()}
+ debug() -> disable | [debug_options()]
+ debug_options() -> {all_functions, modules()} |
+ {exported_functions, modules()} |
+ {disable, modules()}
+ modules() -> [atom()]
+ </code>
+ <p>{proplist_file, file()} File containing an erlang property
+ list, followed by a full stop, describing the HTTP server
+ configuration.</p>
+ <p>{file, file()} If you use an old apace-like configuration file.</p>
+ <p>{debug, debug()} - Can enable trace on all
+ functions or only exported functions on chosen modules.</p>
+ <p>{accept_timeout, integer()} sets the wanted timeout value for
+ the server to set up a request connection.</p>
+ </section>
+
+ <section>
+ <title>Using the HTTP Server API</title>
+ <code type="none">
+ 1 > inets:start().
+ ok
+ </code>
+ <p> Start a HTTP server with minimal
+ required configuration. Note that if you
+ specify port 0 an arbitrary available port will be
+ used and you can use the info function to find out
+ which port number that was picked.
+ </p>
+
+ <code type="none">
+ 2 > {ok, Pid} = inets:start(httpd, [{port, 0},
+ {server_name,"httpd_test"}, {server_root,"/tmp"},
+ {document_root,"/tmp/htdocs"}, {bind_address, "localhost"}]).
+ {ok, 0.79.0}
+ </code>
+
+ <code type="none">
+ 3 > httpd:info(Pid).
+ [{mime_types,[{"html","text/html"},{"htm","text/html"}]},
+ {server_name,"httpd_test"},
+ {bind_address, {127,0,0,1}},
+ {server_root,"/tmp"},
+ {port,59408},
+ {document_root,"/tmp/htdocs"}]
+ </code>
+
+ <p> Reload the configuration without restarting the server.
+ Note port and bind_address can not be changed. Clients
+ trying to access the server during the reload will
+ get a service temporary unavailable answer.
+ </p>
+ <code type="none">
+ 4 > httpd:reload_config([{port, 59408},
+ {server_name,"httpd_test"}, {server_root,"/tmp/www_test"},
+ {document_root,"/tmp/www_test/htdocs"},
+ {bind_address, "localhost"}], non_disturbing).
+ ok.
+ </code>
+
+ <code type="none">
+ 5 > httpd:info(Pid, [server_root, document_root]).
+ [{server_root,"/tmp/www_test"},{document_root,"/tmp/www_test/htdocs"}]
+ </code>
+
+ <code type="none">
+ 6 > ok = inets:stop(httpd, Pid).
+ </code>
+
+ <p> Alternative:</p>
+
+ <code type="none">
+ 6 > ok = inets:stop(httpd, {{127,0,0,1}, 59408}).
+ </code>
+
+ <p>Note that bind_address has to be
+ the ip address reported by the info function and can
+ not be the hostname that is allowed when inputting bind_address.</p>
+
+ </section>
+
+ <section>
+ <title>Htaccess - User Configurable Authentication.</title>
+ <p>If users of the web server needs to manage authentication of
+ web pages that are local to their user and do not have
+ server administrative privileges. They can use the
+ per-directory runtime configurable user-authentication scheme
+ that Inets calls htaccess. It works the following way: </p>
+ <list type="bulleted">
+ <item>Each directory in the path to the requested asset is
+ searched for an access-file (default .htaccess), that restricts
+ the web servers rights to respond to a request. If an access-file
+ is found the rules in that file is applied to the
+ request. </item>
+ <item>The rules in an access-file applies both to files in the same
+ directories and in subdirectories. If there exists more than one
+ access-file in the path to an asset, the rules in the
+ access-file nearest the requested asset will be applied.</item>
+ <item>To change the rules that restricts the use of
+ an asset. The user only needs to have write access
+ to the directory where the asset exists.</item>
+ <item>All the access-files in the path to a requested asset is read
+ once per request, this means that the load on the server will
+ increase when this scheme is used.</item>
+ <item>If a directory is
+ limited both by auth directives in the HTTP server configuration
+ file and by the htaccess files. The user must be allowed to get
+ access the file by both methods for the request to succeed.</item>
+ </list>
+
+ <section>
+ <title>Access Files Directives</title>
+ <p>In every directory under the <c>DocumentRoot</c> or under an
+ <c>Alias</c> a user can place an access-file. An access-file
+ is a plain text file that specify the restrictions that
+ shall be considered before the web server answer to a
+ request. If there are more than one access-file in the path
+ to the requested asset, the directives in the access-file in
+ the directory nearest the asset will be used.</p>
+ <list type="bulleted">
+ <item>
+ <p><em>DIRECTIVE: "allow"</em></p>
+ <p><em>Syntax:</em><c>Allow</c> from subnet subnet|from all <br></br>
+<em>Default:</em><c>from all </c> <br></br>
+</p>
+ <p>Same as the directive allow for the server config file. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AllowOverRide"</em></p>
+ <p><em>Syntax:</em><c>AllowOverRide</c> all | none |
+ Directives <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+<c>AllowOverRide</c> Specify which parameters that not
+ access-files in subdirectories are allowed to alter the value
+ for. If the parameter is set to none no more
+ access-files will be parsed.
+ </p>
+ <p>If only one access-file exists setting this parameter to
+ none can lessen the burden on the server since the server
+ will stop looking for access-files.</p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthGroupfile"</em></p>
+ <p><em>Syntax:</em><c>AuthGroupFile</c> Filename <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+</p>
+ <p>AuthGroupFile indicates which file that contains the list
+ of groups. Filename must contain the absolute path to the
+ file. The format of the file is one group per row and
+ every row contains the name of the group and the members
+ of the group separated by a space, for example:</p>
+ <pre>
+\011 GroupName: Member1 Member2 .... MemberN
+ </pre>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthName"</em></p>
+ <p><em>Syntax:</em><c>AuthName</c> auth-domain <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+</p>
+ <p>Same as the directive AuthName for the server config file. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthType"</em></p>
+ <p><em>Syntax:</em><c>AuthType</c> Basic <br></br>
+<em>Default:</em><c>Basic</c> <br></br>
+</p>
+ <p><c>AuthType</c> Specify which authentication scheme that shall
+ be used. Today only Basic Authenticating using UUEncoding of
+ the password and user ID is implemented. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthUserFile"</em></p>
+ <p><em>Syntax:</em><c>AuthUserFile</c> Filename <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+</p>
+ <p><c>AuthUserFile</c> indicate which file that contains the list
+ of users. Filename must contain the absolute path to the
+ file. The users name and password are not encrypted so do not
+ place the file with users in a directory that is accessible
+ via the web server. The format of the file is one user per row
+ and every row contains User Name and Password separated by a
+ colon, for example:</p>
+ <pre>
+\011 UserName:Password
+\011 UserName:Password
+ </pre>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "deny"</em></p>
+ <p><em>Syntax:</em><c>deny</c> from subnet subnet|from all <br></br>
+<em>Context:</em> Limit</p>
+ <p>Same as the directive deny for the server config file. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "Limit"</em> <br></br>
+</p>
+ <p><em>Syntax:</em><c><![CDATA[<Limit]]></c> RequestMethods<c>></c> <br></br>
+<em>Default:</em> - None - <br></br>
+</p>
+ <p><c><![CDATA[<Limit>]]></c> and &lt;/Limit&gt; are used to enclose
+ a group of directives which applies only to requests using
+ the specified methods. If no request method is specified
+ all request methods are verified against the restrictions.</p>
+ <pre>
+\011 &lt;Limit POST GET HEAD&gt;
+\011 order allow deny
+\011 require group group1
+\011 allow from 123.145.244.5
+\011 &lt;/Limit&gt;
+ </pre>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "order"</em> <br></br>
+<em>Syntax:</em><c>order</c> allow deny | deny allow <br></br>
+<em>Default:</em> allow deny <br></br>
+</p>
+ <p><c>order</c>, defines if the deny or allow control shall
+ be preformed first.</p>
+ <p>If the order is set to allow deny, then first the users
+ network address is controlled to be in the allow subset. If
+ the users network address is not in the allowed subset he will
+ be denied to get the asset. If the network-address is in the
+ allowed subset then a second control will be preformed, that
+ the users network address is not in the subset of network
+ addresses that shall be denied as specified by the deny
+ parameter.</p>
+ <p>If the order is set to deny allow then only users from networks
+ specified to be in the allowed subset will succeed to request
+ assets in the limited area.</p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "require"</em></p>
+ <p><em>Syntax:</em><c>require</c>
+ group group1 group2...|user user1 user2... <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+<em>Context:</em> Limit <br></br>
+</p>
+ <p>See the require directive in the documentation of mod_auth(3)
+ for more information.</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Dynamic Web Pages</title>
+ <p>The Inets HTTP server provides two ways of creating dynamic web
+ pages, each with its own advantages and disadvantages. </p>
+ <p>First there are CGI-scripts that can be written in any programming
+ language. CGI-scripts are standardized and supported by most
+ web servers. The drawback with CGI-scripts is that they are resource
+ intensive because of their design. CGI requires the server to fork a
+ new OS process for each executable it needs to start. </p>
+ <p>Second there are ESI-functions that provide a tight and efficient
+ interface to the execution of Erlang functions, this interface
+ on the other hand is Inets specific. </p>
+
+ <section>
+ <title>The Common Gateway Interface (CGI) Version 1.1, RFC 3875.</title>
+ <p>The mod_cgi module makes it possible to execute CGI scripts
+ in the server. A file that matches the definition of a
+ ScriptAlias config directive is treated as a CGI script. A CGI
+ script is executed by the server and it's output is returned to
+ the client. </p>
+ <p>The CGI Script response comprises a message-header and a
+ message-body, separated by a blank line. The message-header
+ contains one or more header fields. The body may be
+ empty. Example: </p>
+ <code type="none">
+"Content-Type:text/plain\
+Accept-Ranges:none\
+\
+some very
+\011plain text" </code>
+ <p>The server will interpret the cgi-headers and most of them
+ will be transformed into HTTP headers and sent back to the
+ client together with the body.</p>
+ <p>Support for CGI-1.1 is implemented in accordance with the RFC
+ 3875. </p>
+ </section>
+
+ <section>
+ <title>Erlang Server Interface (ESI)</title>
+ <p>The erlang server interface is implemented by the
+ module mod_esi.</p>
+
+ <section>
+ <title>ERL Scheme </title>
+ <p>The erl scheme is designed to mimic plain CGI, but without
+ the extra overhead. An URL which calls an Erlang erl function
+ has the following syntax (regular expression): </p>
+ <code type="none">
+\011 http://your.server.org/***/Module[:/]Function(?QueryString|/PathInfo)
+ </code>
+ <p>*** above depends on how the ErlScriptAlias config
+ directive has been used</p>
+ <p>The module (Module) referred to must be found in the code
+ path, and it must define a function (Function) with an arity
+ of two or three. It is preferable to implement a funtion
+ with arity three as it permits you to send chunks of the
+ webpage beeing generated to the client during the generation
+ phase instead of first generating the whole web page and
+ then sending it to the client. The option to implement a
+ function with arity two is only kept for
+ backwardcompatibilty reasons.
+ See <seealso marker="mod_esi">mod_esi(3)</seealso> for
+ implementation details of the esi callback function.</p>
+ </section>
+
+ <section>
+ <title>EVAL Scheme </title>
+ <p>The eval scheme is straight-forward and does not mimic the
+ behavior of plain CGI. An URL which calls an Erlang eval
+ function has the following syntax:</p>
+ <code type="none">
+http://your.server.org/***/Mod:Func(Arg1,...,ArgN)
+ </code>
+ <p>*** above depends on how the ErlScriptAlias config
+ directive has been used</p>
+ <p>The module (Mod) referred to must be found in the code
+ path, and data returned by the function (Func) is passed
+ back to the client. Data returned from the
+ function must furthermore take the form as specified in
+ the CGI specification. See <seealso marker="mod_esi">mod_esi(3)</seealso> for implementation details of the esi
+ callback function.</p>
+ <note>
+ <p>The eval scheme can seriously threaten the
+ integrity of the Erlang node housing a Web server, for
+ example: </p>
+ <code type="none">
+http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[])))
+ </code>
+ <p>which effectively will close down the Erlang node,
+ that is use the erl scheme instead, until this
+ security breach has been fixed.</p>
+ <p>Today there are no good way of solving this problem
+ and therefore Eval Scheme may be removed in future
+ release of Inets. </p>
+ </note>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Logging </title>
+ <p>There are three types of logs supported. Transfer logs,
+ security logs and error logs. The de-facto standard Common
+ Logfile Format is used for the transfer and security logging.
+ There are numerous statistics programs available to analyze Common
+ Logfile Format. The Common Logfile Format looks as follows:
+ </p>
+ <p><em>remotehost rfc931 authuser [date] "request" status bytes</em></p>
+ <taglist>
+ <tag><em>remotehost</em></tag>
+ <item>Remote hostname</item>
+ <tag><em>rfc931</em></tag>
+ <item>The client's remote username (RFC 931).</item>
+ <tag><em>authuser</em></tag>
+ <item>The username with which the user authenticated himself.</item>
+ <tag><em>[date]</em></tag>
+ <item>Date and time of the request (RFC 1123).</item>
+ <tag><em>"request"</em></tag>
+ <item>The request line exactly as it came from the client (RFC 1945).</item>
+ <tag><em>status</em></tag>
+ <item>The HTTP status code returned to the client (RFC 1945).</item>
+ <tag><em>bytes</em></tag>
+ <item>The content-length of the document transferred. </item>
+ </taglist>
+ <p>Internal server errors are recorde in the error log file. The
+ format of this file is a more ad hoc format than the logs using
+ Common Logfile Format, but conforms to the following syntax:
+ </p>
+ <p><em>[date]</em> access to <em>path</em> failed for
+ <em>remotehost</em>, reason: <em>reason</em></p>
+ </section>
+
+ <section>
+ <title>Server Side Includes</title>
+ <p>Server Side Includes enables the server to run code embedded
+ in HTML pages to generate the response to the client.</p>
+ <note>
+ <p>Having the server parse HTML pages is a double edged sword!
+ It can be costly for a heavily loaded server to perform
+ parsing of HTML pages while sending them. Furthermore, it can
+ be considered a security risk to have average users executing
+ commands in the name of the Erlang node user. Carefully
+ consider these items before activating server-side includes.</p>
+ </note>
+
+ <section>
+ <marker id="ssi_setup"></marker>
+ <title>SERVER-SIDE INCLUDES (SSI) SETUP</title>
+ <p>The server must be told which filename extensions to be used
+ for the parsed files. These files, while very similar to HTML,
+ are not HTML and are thus not treated the same. Internally, the
+ server uses the magic MIME type <c>text/x-server-parsed-html</c>
+ to identify parsed documents. It will then perform a format
+ conversion to change these files into HTML for the
+ client. Update the <c>mime.types</c> file, as described in the
+ Mime Type Settings, to tell the server which extension to use
+ for parsed files, for example:
+ </p>
+ <pre>
+\011text/x-server-parsed-html shtml shtm
+ </pre>
+ <p>This makes files ending with <c>.shtml</c> and <c>.shtm</c>
+ into parsed files. Alternatively, if the performance hit is not a
+ problem, <em>all</em> HTML pages can be marked as parsed:
+ </p>
+ <pre>
+\011text/x-server-parsed-html html htm
+ </pre>
+ </section>
+
+ <section>
+ <marker id="ssi_format"></marker>
+ <title>Server-Side Includes (SSI) Format</title>
+ <p>All server-side include directives to the server are formatted
+ as SGML comments within the HTML page. This is in case the
+ document should ever find itself in the client's hands
+ unparsed. Each directive has the following format:
+ </p>
+ <pre>
+\011&lt;!--#command tag1="value1" tag2="value2" --&gt;
+ </pre>
+ <p>Each command takes different arguments, most only accept one
+ tag at a time. Here is a breakdown of the commands and their
+ associated tags:
+ </p>
+ <p>The config directive controls various aspects of the
+ file parsing. There are two valid tags:
+ </p>
+ <taglist>
+ <tag><c>errmsg</c></tag>
+ <item>
+ <p>controls the message sent back to the client if an
+ error occurred while parsing the document. All errors are
+ logged in the server's error log.</p>
+ </item>
+ <tag><c>sizefmt</c></tag>
+ <item>
+ <p>determines the format used to display the size of
+ a file. Valid choices are <c>bytes</c> or
+ <c>abbrev</c>. <c>bytes</c> for a formatted byte count
+ or <c>abbrev</c> for an abbreviated version displaying
+ the number of kilobytes.</p>
+ </item>
+ </taglist>
+ <p>The include directory
+ will insert the text of a document into the parsed
+ document. This command accepts two tags:</p>
+ <taglist>
+ <tag><c>virtual</c></tag>
+ <item>
+ <p>gives a virtual path to a document on the
+ server. Only normal files and other parsed documents can
+ be accessed in this way.</p>
+ </item>
+ <tag><c>file</c></tag>
+ <item>
+ <p>gives a pathname relative to the current
+ directory. <c>../</c> cannot be used in this pathname, nor
+ can absolute paths. As above, you can send other parsed
+ documents, but you cannot send CGI scripts.</p>
+ </item>
+ </taglist>
+ <p>The echo directive prints the value of one of the include
+ variables (defined below). The only valid tag to this
+ command is <c>var</c>, whose value is the name of the
+ variable you wish to echo.</p>
+ <p>The fsize directive prints the size of the specified
+ file. Valid tags are the same as with the <c>include</c>
+ command. The resulting format of this command is subject
+ to the <c>sizefmt</c> parameter to the <c>config</c>
+ command.</p>
+ <p>The lastmod directive prints the last modification date of
+ the specified file. Valid tags are the same as with the
+ <c>include</c> command.</p>
+ <p>The exec directive executes a given shell command or CGI
+ script. Valid tags are:</p>
+ <taglist>
+ <tag><c>cmd</c></tag>
+ <item>
+ <p>executes the given string using <c>/bin/sh</c>. All
+ of the variables defined below are defined, and can be
+ used in the command.</p>
+ </item>
+ <tag><c>cgi</c></tag>
+ <item>
+ <p>executes the given virtual path to a CGI script and
+ includes its output. The server does not perform error
+ checking on the script output.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <marker id="ssi_environment_variables"></marker>
+ <title>Server-Side Includes (SSI) Environment Variables</title>
+ <p>A number of variables are made available to parsed
+ documents. In addition to the CGI variable set, the following
+ variables are made available:
+ </p>
+ <taglist>
+ <tag><c>DOCUMENT_NAME</c></tag>
+ <item>
+ <p>The current filename.</p>
+ </item>
+ <tag><c>DOCUMENT_URI</c></tag>
+ <item>
+ <p>The virtual path to this document (such as
+ <c>/docs/tutorials/foo.shtml</c>).</p>
+ </item>
+ <tag><c>QUERY_STRING_UNESCAPED</c></tag>
+ <item>
+ <p>The unescaped version of any search query the client
+ sent, with all shell-special characters escaped with
+ <c>\\</c>.</p>
+ </item>
+ <tag><c>DATE_LOCAL</c></tag>
+ <item>
+ <p>The current date, local time zone.</p>
+ </item>
+ <tag><c>DATE_GMT</c></tag>
+ <item>
+ <p>Same as DATE_LOCAL but in Greenwich mean time.</p>
+ </item>
+ <tag><c>LAST_MODIFIED</c></tag>
+ <item>
+ <p>The last modification date of the current document.</p>
+ </item>
+ </taglist>
+ </section>
+ </section>
+
+ <section>
+ <title>The Erlang Web Server API</title>
+ <p>The process of handling a HTTP request involves several steps
+ such as:</p>
+ <list type="bulleted">
+ <item>Seting up connections, sending and receiving data.</item>
+ <item>URI to filename translation</item>
+ <item>Authenication/access checks.</item>
+ <item>Retriving/generating the response.</item>
+ <item>Logging</item>
+ </list>
+ <p>To provide customization and extensibility of the HTTP servers
+ request handling most of these steps are handled by one or more
+ modules that may be replaced or removed at runtime, and of course
+ new ones can be added. For each request all modules will be
+ traversed in the order specified by the modules directive in the
+ server configuration file. Some parts mainly the communication
+ related steps are considered server core functionality and are
+ not implemented using the Erlang Web Server API. A description of
+ functionality implemented by the Erlang Webserver API is described
+ in the section Inets Webserver Modules.</p>
+ <p>A module can use data generated by previous modules in the
+ Erlang Webserver API module sequence or generate data to be used
+ by consecutive Erlang Web Server API modules. This is made
+ possible due to an internal list of key-value tuples, also referred to
+ as interaction data. </p>
+ <note>
+ <p>Interaction data enforces module dependencies and
+ should be avoided if possible. This means the order
+ of modules in the Modules property is significant.</p>
+ </note>
+
+ <section>
+ <title>API Description</title>
+ <p>Each module implements server functionality
+ using the Erlang Web Server API should implement the following
+ call back functions:</p>
+ <list type="bulleted">
+ <item>do/1 (mandatory) - the function called when
+ a request should be handled.</item>
+ <item>load/2</item>
+ <item>store/2</item>
+ <item>remove/1</item>
+ </list>
+ <p>The latter functions are needed only when new config
+ directives are to be introduced. For details see
+ <seealso marker="httpd">httpd(3)</seealso></p>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets Web Server Modules</title> <p>The convention is that
+ all modules implementing some webserver functionality has the
+ name mod_*. When configuring the web server an appropriate
+ selection of these modules should be present in the Module
+ directive. Please note that there are some interaction dependencies
+ to take into account so the order of the modules can not be
+ totally random.</p>
+
+ <section>
+ <title>mod_action - Filetype/Method-Based Script Execution.</title>
+ <p>Runs CGI scripts whenever a file of a
+ certain type or HTTP method (See RFC 1945) is requested.
+ </p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data, if possible:
+ </p>
+ <taglist>
+ <tag><c>{new_request_uri, RequestURI}</c></tag>
+ <item>An alternative <c>RequestURI</c> has been generated.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_alias - URL Aliasing</title>
+ <p>This module makes it possible to map different parts of the
+ host file system into the document tree e.i. creates aliases and
+ redirections.</p>
+ <p>Exports the following Erlang Web Server API interaction data, if possible:
+ </p>
+ <taglist>
+ <tag><c>{real_name, PathData}</c></tag>
+ <item>PathData is the argument used for API function mod_alias:path/3.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_auth - User Authentication </title>
+ <p>This module provides for basic user authentication using
+ textual files, dets databases as well as mnesia databases.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{remote_user, User}</c></tag>
+ <item>The user name with which the user has authenticated himself.</item>
+ </taglist>
+
+
+ <section>
+ <title>Mnesia as Authentication Database</title>
+
+ <p> If Mnesia is used as storage method, Mnesia must be
+ started prio to the HTTP server. The first time Mnesia is
+ started the schema and the tables must be created before
+ Mnesia is started. A naive example of a module with two
+ functions that creates and start mnesia is provided
+ here. The function shall be used the first
+ time. first_start/0 creates the schema and the tables. The
+ second function start/0 shall be used in consecutive
+ startups. start/0 Starts Mnesia and wait for the tables to
+ be initiated. This function must only be used when the
+ schema and the tables already is created. </p>
+
+ <code>
+ -module(mnesia_test).
+ -export([start/0,load_data/0]).
+ -include("mod_auth.hrl").
+
+ first_start()->
+ mnesia:create_schema([node()]),
+ mnesia:start(),
+ mnesia:create_table(httpd_user,
+ [{type,bag},{disc_copies,[node()]},
+ {attributes,record_info(fields,httpd_user)}]),
+ mnesia:create_table(httpd_group,
+ [{type,bag},{disc_copies,[node()]},
+ {attributes,record_info(fields,httpd_group)}]),
+ mnesia:wait_for_tables([httpd_user,httpd_group],60000).
+
+ start()->
+ mnesia:start(),
+ mnesia:wait_for_tables([httpd_user,httpd_group],60000).
+ </code>
+
+ <p>To create the Mnesia tables we use two records defined in
+ mod_auth.hrl so the file must be included. The first
+ function first_start/0 creates a schema that specify on
+ which nodes the database shall reside. Then it starts Mnesia
+ and creates the tables. The first argument is the name of
+ the tables, the second argument is a list of options how the
+ table will be created, see Mnesia documentation for more
+ information. Since the current implementation of the
+ mod_auth_mnesia saves one row for each user the type must be
+ bag. When the schema and the tables is created the second
+ function start/0 shall be used to start Mensia. It starts
+ Mnesia and wait for the tables to be loaded. Mnesia use the
+ directory specified as mnesia_dir at startup if specified,
+ otherwise Mnesia use the current directory. For security
+ reasons, make sure that the Mnesia tables are stored outside
+ the document tree of the HTTP server. If it is placed in the
+ directory which it protects, clients will be able to
+ download the tables. Only the dets and mnesia storage
+ methods allow writing of dynamic user data to disk. plain is
+ a read only method.</p>
+ </section>
+
+ </section>
+
+ <section>
+ <title>mod_cgi - CGI Scripts</title>
+ <p>This module handles invoking of CGI scripts</p>
+ </section>
+
+ <section>
+ <title>mod_dir - Directories</title>
+ <p>This module generates an HTML directory listing
+ (Apache-style) if a client sends a request for a directory
+ instead of a file. This module needs to be removed from the
+ Modules config directive if directory listings is unwanted.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{mime_type, MimeType}</c></tag>
+ <item>The file suffix of the incoming URL mapped into a
+ <c>MimeType</c>.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_disk_log - Logging Using disk_log.</title>
+ <p>Standard logging using the "Common Logfile Format" and
+ disk_log(3).</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>remote_user - from mod_auth</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_esi - Erlang Server Interface</title>
+ <p>This module implements
+ the Erlang Server Interface (ESI) that provides a tight and
+ efficient interface to the execution of Erlang functions. </p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>remote_user - from mod_auth</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{mime_type, MimeType}</c></tag>
+ <item>The file suffix of the incoming URL mapped into a
+ <c>MimeType</c></item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_get - Regular GET Requests</title>
+ <p>This module is responsible for handling GET requests to regular
+ files. GET requests for parts of files is handled by mod_range.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_head - Regular HEAD Requests</title>
+ <p>This module is responsible for handling HEAD requests to regular
+ files. HEAD requests for dynamic content is handled by each module
+ responsible for dynamic content.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_htaccess - User Configurable Access</title>
+ <p>This module provides per-directory user configurable access
+ control.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{remote_user_name, User}</c></tag>
+ <item>The user name with which the user has authenticated himself.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_include - SSI</title>
+ <p>This module makes it possible to expand "macros" embedded in
+ HTML pages before they are delivered to the client, that is
+ Server-Side Includes (SSI).
+ </p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ <item>remote_user - from mod_auth</item>
+ </list>
+ <p>Exports the following Erlang Webserver API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{mime_type, MimeType}</c></tag>
+ <item>The file suffix of the incoming URL mapped into a
+ <c>MimeType</c> as defined in the Mime Type Settings
+ section.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_log - Logging Using Text Files.</title>
+ <p>Standard logging using the "Common Logfile Format" and text
+ files.</p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>remote_user - from mod_auth</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_range - Requests with Range Headers</title>
+ <p>This module response to requests for one or many ranges of a
+ file. This is especially useful when downloading large files,
+ since a broken download may be resumed.</p>
+ <p>Note that request for multiple parts of a document will report a
+ size of zero to the log file.</p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_response_control - Requests with If* Headers</title>
+ <p>This module controls that the conditions in the requests is
+ fulfilled. For example a request may specify that the answer
+ only is of interest if the content is unchanged since last
+ retrieval. Or if the content is changed the range-request shall
+ be converted to a request for the whole file instead.</p> <p>If
+ a client sends more then one of the header fields that restricts
+ the servers right to respond, the standard does not specify how
+ this shall be handled. httpd will control each field in the
+ following order and if one of the fields not match the current
+ state the request will be rejected with a proper response.
+ <br></br>
+
+ 1.If-modified <br></br>
+
+ 2.If-Unmodified <br></br>
+
+ 3.If-Match <br></br>
+
+ 4.If-Nomatch <br></br>
+</p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Webserver API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{if_range, send_file}</c></tag>
+ <item>The conditions for the range request was not fulfilled.
+ The response must not be treated as a range request, instead it
+ must be treated as a ordinary get request. </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_security - Security Filter</title>
+ <p>This module serves as a filter for authenticated requests
+ handled in mod_auth. It provides possibility to restrict users
+ from access for a specified amount of time if they fail to
+ authenticate several times. It logs failed authentication as
+ well as blocking of users, and it also calls a configurable
+ call-back module when the events occur. </p>
+ <p>There is also an
+ API to manually block, unblock and list blocked users or users,
+ who have been authenticated within a configurable amount of
+ time.</p>
+ </section>
+
+ <section>
+ <title>mod_trace - TRACE Request</title>
+ <p>mod_trace is responsible for handling of TRACE requests.
+ Trace is a new request method in HTTP/1.1. The intended use of
+ trace requests is for testing. The body of the trace response is
+ the request message that the responding Web server or proxy
+ received.</p>
+ </section>
+ </section>
+</chapter>
+
+