diff options
Diffstat (limited to 'lib/inets/doc/src/http_server.xml')
| -rw-r--r-- | lib/inets/doc/src/http_server.xml | 1004 |
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 </Limit> 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 <Limit POST GET HEAD> +\011 order allow deny +\011 require group group1 +\011 allow from 123.145.244.5 +\011 </Limit> + </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<!--#command tag1="value1" tag2="value2" --> + </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> + + |