diff options
| author |   beck <beck@openbsd.org> | 1998-03-25 07:08:28 +0000 |
|---|---|---|
| committer | beck <beck@openbsd.org> | 1998-03-25 07:08:28 +0000 |
| commit | c031d3d96950de940122b79f85411f295db3b7ea (patch) | |
| tree | 4ef378a704eec86b2cfb6e65b5dd7019a7f125b8 /usr.sbin/httpd/htdocs/manual/mod | |
| parent | Make directories for /var/www - your basic www root (diff) | |
| download | wireguard-openbsd-c031d3d96950de940122b79f85411f295db3b7ea.tar.xz wireguard-openbsd-c031d3d96950de940122b79f85411f295db3b7ea.zip | |
Initial import from apache 1.2.6
Diffstat (limited to 'usr.sbin/httpd/htdocs/manual/mod')
39 files changed, 8797 insertions, 0 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/mod/core.html b/usr.sbin/httpd/htdocs/manual/mod/core.html new file mode 100644 index 00000000000..27c2a6c00da --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/core.html @@ -0,0 +1,1462 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache Core Features</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Apache Core Features</h1> + +These configuration parameters control the core Apache features, and are +always available. + + +<ul> +<li><A HREF="#accessconfig">AccessConfig</A> +<li><A HREF="#accessfilename">AccessFileName</A> +<li><A HREF="#addmodule">AddModule</A> +<li><A HREF="#allowoverride">AllowOverride</A> +<li><A HREF="#authname">AuthName</A> +<li><A HREF="#authtype">AuthType</A> +<li><A HREF="#bindaddress">BindAddress</A> +<li><A HREF="#clearmodulelist">ClearModuleList</A> +<li><A HREF="#defaulttype">DefaultType</A> +<li><A HREF="#directory"><Directory></A> +<li><A HREF="#documentroot">DocumentRoot</A> +<li><A HREF="#errordocument">ErrorDocument</A> +<li><A HREF="#errorlog">ErrorLog</A> +<li><A HREF="#files"><Files></A> +<li><A HREF="#group">Group</A> +<li><A HREF="#hostnamelookups">HostNameLookups</A> +<li><A HREF="#identitycheck">IdentityCheck</A> +<li><A HREF="#ifmodule"><IfModule></A> +<li><A HREF="#keepalive">KeepAlive</A> +<li><A HREF="#keepalivetimeout">KeepAliveTimeout</A> +<li><A HREF="#limit"><Limit></A> +<li><A HREF="#listen">Listen</A> +<li><A HREF="#location"><Location></A> +<li><A HREF="#lockfile">LockFile</A> +<li><A HREF="#maxclients">MaxClients</A> +<li><A HREF="#maxkeepaliverequests">MaxKeepAliveRequests</a> +<li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A> +<li><A HREF="#maxspareservers">MaxSpareServers</A> +<li><A HREF="#minspareservers">MinSpareServers</A> +<li><A HREF="#options">Options</A> +<li><A HREF="#pidfile">PidFile</A> +<li><A HREF="#port">Port</A> +<li><A HREF="#require">require</A> +<li><A HREF="#resourceconfig">ResourceConfig</A> +<li><A HREF="#rlimitcpu">RLimitCPU</A> +<li><A HREF="#rlimitmem">RLimitMEM</A> +<li><A HREF="#rlimitnproc">RLimitNPROC</A> +<li><A HREF="#satisfy">Satisfy</A> +<li><A HREF="#scoreboardfile">ScoreBoardFile</A> +<li><A HREF="#sendbuffersize">SendBufferSize</A> +<li><A HREF="#serveradmin">ServerAdmin</A> +<li><A HREF="#serveralias">ServerAlias</A> +<li><A HREF="#servername">ServerName</A> +<li><A HREF="#serverpath">ServerPath</A> +<li><A HREF="#serverroot">ServerRoot</A> +<li><A HREF="#servertype">ServerType</A> +<li><A HREF="#startservers">StartServers</A> +<li><A HREF="#timeout">TimeOut</A> +<li><A HREF="#user">User</A> +<li><A HREF="#virtualhost"><VirtualHost></A> +</ul> +<hr> + +<A name="accessconfig"><h2>AccessConfig directive</h2></A> +<!--%plaintext <?INDEX {\tt AccessConfig} directive> --> +<strong>Syntax:</strong> AccessConfig <em>filename</em><br> +<strong>Default:</strong> <code>AccessConfig conf/access.conf</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The server will read this file for more directives after reading the +<A HREF="#resourceconfig">ResourceConfig</A> file. <em>Filename</em> is +relative to the <A HREF="#serverroot">ServerRoot</A>. +This feature can be disabled using: +<blockquote><code>AccessConfig /dev/null</code></blockquote> +Historically, this file only contained +<A HREF="#directory"><Directory></A> sections; in fact it can now +contain any server directive allowed in the <em>server config</em> context. +<p><hr> + +<A name="accessfilename"><h2>AccessFileName directive</h2></A> +<!--%plaintext <?INDEX {\tt AccessFileName} directive> --> +<strong>Syntax:</strong> AccessFileName <em>filename</em><br> +<strong>Default:</strong> <code>AccessFileName .htaccess</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +When returning a document to the client the server looks for an +access control file with this name in every directory of the path to +the document, if access control files are enabled for that directory. + +For example: +<blockquote><code>AccessFileName .acl</code></blockquote> +before returning the document /usr/local/web/index.html, the +server will read /.acl, /usr/.acl, /usr/local/.acl and /usr/local/web/.acl +for directives, unless they have been disabled with +<blockquote><code> +<Directory /><br> +AllowOverride None<br> +</Directory></code></blockquote><p><hr> + +<A name="addmodule"><h2>AddModule directive</h2></A> +<!--%plaintext <?INDEX {\tt AddModule} directive> --> +<strong>Syntax:</strong> AddModule <em>module module ...</em><br> +<strong>Context:</strong> server config <br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> AddModule is only available in Apache 1.2 and later<p> + +The server can have modules compiled in which are not actively in use. +This directive can be used to enable the use of those modules. The +server comes with a pre-loaded list of active modules; this list can +be cleared with the <A HREF="#clearmodulelist">ClearModuleList</A> +directive.<p><hr> + +<A name="allowoverride"><h2>AllowOverride directive</h2></A> +<!--%plaintext <?INDEX {\tt AllowOverride} directive> --> +<strong>Syntax:</strong> AllowOverride <em>override override ...</em><br> +<strong>Default:</strong> <code>AllowOverride All</code><br> +<strong>Context:</strong> directory<br> +<strong>Status:</strong> core<p> + +When the server finds an .htaccess file (as specified by +<A HREF="#accessfilename">AccessFileName</A>) it needs to know which +directives declared in that file can override earlier access information.<p> + +<em>Override</em> can be set to <code>None</code>, in which case the server +will not read the file, <code>All</code> in which case the server will +allow all the directives, or one or more of the following: +<dl> +<dt>AuthConfig +<dd> +<!--%plaintext <?INDEX {\tt AuthConfig} override> --> +Allow use of the authorization directives +(<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A>, +<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>, +<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>, +<A HREF="#authname">AuthName</A>, <A HREF="#authtype">AuthType</A>, +<A HREF="mod_auth.html#authuserfile">AuthUserFile</A>, +<A HREF="#require">require</A>, etc.). +<dt>FileInfo +<dd> +<!--%plaintext <?INDEX {\tt FileInfo} override> --> +Allow use of the directives controlling document types +(<A HREF="mod_mime.html#addencoding">AddEncoding</A>, +<A HREF="mod_mime.html#addlanguage">AddLanguage</A>, +<A HREF="mod_mime.html#addtype">AddType</A>, +<A HREF="#defaulttype">DefaultType</A>, +<A HREF="#errordocument">ErrorDocument</A>, +<A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>, etc.). +<dt>Indexes +<dd> +<!--%plaintext <?INDEX {\tt Indexes} override> --> +Allow use of the directives controlling directory indexing +(<A HREF="mod_dir.html#adddescription">AddDescription</A>, +<A HREF="mod_dir.html#addicon">AddIcon</A>, +<A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A>, +<A HREF="mod_dir.html#addiconbytype">AddIconByType</A>, +<A HREF="mod_dir.html#defaulticon">DefaultIcon</A>, +<A HREF="mod_dir.html#directoryindex">DirectoryIndex</A>, +<A HREF="mod_dir.html#fancyindexing">FancyIndexing</A>, +<A HREF="mod_dir.html#headername">HeaderName</A>, +<A HREF="mod_dir.html#indexignore">IndexIgnore</A>, +<A HREF="mod_dir.html#indexoptions">IndexOptions</A>, +<A HREF="mod_dir.html#readmename">ReadmeName</A>, etc.). +<dt>Limit +<dd> +<!--%plaintext <?INDEX {\tt Limit} override> --> +Allow use of the directives controlling host access (allow, deny and order). +<dt>Options +<dd> +<!--%plaintext <?INDEX {\tt Options} override> --> +Allow use of the directives controlling specific directory features +(<A HREF="#options">Options</A> and +<A HREF="mod_include.html#xbithack">XBitHack</A>). +</dl><p><hr> + +<A name="authname"><h2>AuthName directive</h2></A> +<!--%plaintext <?INDEX {\tt AuthName} directive> --> +<strong>Syntax:</strong> AuthName <em>auth-domain</em><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> core<p> + +This directive sets the name of the authorization realm for a directory. +This realm is given to the client so that the user knows which username and +password to send. +It must be accompanied by <A HREF="#authtype">AuthType</A> and +<A HREF="#require">require</A> directives, and directives such as +<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and +<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr> + +<A name="authtype"><h2>AuthType directive</h2></A> +<!--%plaintext <?INDEX {\tt AuthType} directive> --> +<strong>Syntax:</strong> AuthType <em>type</em><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> core<p> + +This directive selects the type of user authentication for a directory. +Only <code>Basic</code> is currently implemented. +<!--%plaintext <?INDEX {\tt Basic} authentication scheme> --> +It must be accompanied by <A HREF="#authname">AuthName</A> and +<A HREF="#require">require</A> directives, and directives such as +<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and +<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr> + +<A name="bindaddress"><h2>BindAddress directive</h2></A> +<!--%plaintext <?INDEX {\tt BindAddress} directive> --> +<strong>Syntax:</strong> BindAddress <em>saddr</em><br> +<strong>Default:</strong> <code>BindAddress *</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +A Unix® http server can either listen for connections to every +IP address of the server machine, or just one IP address of the server +machine. <em>Saddr</em> can be + +<menu> +<li>* +<li>An IP address +<li>A fully-qualified Internet domain name +</menu> +If the value is *, then the server will listen for connections on +every IP address, otherwise it will only listen on the IP address +specified. <p> + +This option can be used as an alternative method for supporting +<A HREF="../virtual-host.html">virtual hosts</A> instead of using +<A HREF="#virtualhost"><VirtualHost></A> sections. + +<p><strong>See Also:</strong> +<a href="../dns-caveats.html">DNS Issues</a><br> +<strong>See Also:</strong> +<a href="../bind.html">Setting which addresses and ports Apache uses</a></p> + +<hr> + +<A name="clearmodulelist"><h2>ClearModuleList directive</h2></A> +<!--%plaintext <?INDEX {\tt ClearModuleList} directive> --> +<strong>Syntax:</strong> ClearModuleList<br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> ClearModuleList is only available in Apache 1.2 and later<p> + +The server comes with a built-in list of active modules. This +directive clears the list. It is assumed that the list will then be +re-populated using the <A HREF="#addmodule">AddModule</A> directive.<p><hr> + +<A name="defaulttype"><h2>DefaultType directive</h2></A> +<!--%plaintext <?INDEX {\tt DefaultType} directive> --> +<strong>Syntax:</strong> DefaultType <em>mime-type</em><br> +<strong>Default:</strong> <code>DefaultType text/html</code><br> +<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> core<p> + +There will be times when the server is asked to provide a document +whose type cannot be determined by its MIME types mappings.<p> + +The server must inform the client of the content-type of the document, so in +the event of an unknown type it uses the <CODE>DefaultType</CODE>. For +example: +<blockquote><code>DefaultType image/gif</code></blockquote> +would be appropriate for a directory which contained many gif images +with filenames missing the .gif extension.<p><hr> + +<A name="directory"><h2><Directory> directive</h2></A> +<!--%plaintext <?INDEX {\tt Directory} section directive> --> +<strong>Syntax:</strong> <Directory <em>directory</em>> ... </Directory> <br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Core. <p> + +<Directory> and </Directory> are used to enclose a group of +directives which will apply only to the named directory and sub-directories +of that directory. Any directive which is allowed in a directory +context may be used. <em>Directory</em> is either the full path to a directory, +or a wild-card string. In a wild-card string, `?' matches any single character, +and `*' matches any sequences of characters. Example: +<pre> + <Directory /usr/local/httpd/htdocs> + Options Indexes FollowSymLinks + </Directory> +</pre> + +<p><strong>Apache 1.2 and above:</strong> +Extended regular expressions can also be used, with the addition of the +<code>~</code> character. For example:</p> + +<pre> + <Directory ~ "^/www/.*/[0-9]{3}"> +</pre> + +would match directories in /www/ that consisted of three numbers.<p> + +<p>If multiple directory sections match the directory (or its parents) containing +a document, then the directives are applied in the order of shortest match +first, interspersed with the directives from the +<A HREF="#accessfilename">.htaccess</A> files. For example, with +<blockquote><code> +<Directory /><br> +AllowOverride None<br> +</Directory><br><br> +<Directory /home/*><br> +AllowOverride FileInfo<br> +</Directory></code></blockquote> +for access to the document <code>/home/web/dir/doc.html</code> the +steps are: +<menu> +<li>Apply directive <code>AllowOverride None</code> (disabling +<code>.htaccess</code> files). +<li>Apply directive <code>AllowOverride FileInfo</code> (for directory +<code>/home/web</code>). +<li>Apply any FileInfo directives in <code>/home/web/.htaccess</code> +</menu> + +<P> +<STRONG> +Note that the default Apache access for <Directory /> is +<SAMP>Allow from All</SAMP>. This means that Apache will serve any file +mapped from an URL. It is recommended that you change this with a block +such as +</STRONG> +<PRE> + <Directory /> + Order Deny,Allow + Deny from All + </Directory> +</PRE> +<P> +<STRONG> +and then override this for directories you <EM>want</EM> accessible. +See the +<A + HREF="../misc/security_tips.html" +>Security Tips</A> +page for more details. +</STRONG> +</P> + +The directory sections typically occur in the access.conf file, but they +may appear in any configuration file. <Directory> directives cannot +nest, and cannot appear in a <A HREF="#limit"><Limit></A> section. +<p><hr> + +<A NAME="documentroot"><h2>DocumentRoot directive</h2></A> +<!--%plaintext <?INDEX {\tt DocumentRoot} directive> --> +<strong>Syntax:</strong> DocumentRoot <em>directory-filename</em><br> +<strong>Default:</strong> <code>DocumentRoot +/usr/local/etc/httpd/htdocs</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +This directive sets the directory from which httpd will serve files. +Unless matched by a directive like Alias, the server appends the path +from the requested URL to the document root to make the path to the +document. Example: +<blockquote><code>DocumentRoot /usr/web</code></blockquote> +then an access to <code>http://www.my.host.com/index.html</code> refers +to <code>/usr/web/index.html</code>. + +<P>There appears to be a bug in mod_dir which causes problems when the +DocumentRoot has a trailing slash (i.e. "DocumentRoot /usr/web/") so +please avoid that. + +<p><hr> + +<A name="errordocument"><h2>ErrorDocument directive</h2></A> +<!--%plaintext <?INDEX {\tt ErrorDocument} directive> --> +<strong>Syntax:</strong> ErrorDocument <em>error-code document</em><br> +<strong>Context</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> core<br> +<strong>Override:</strong> FileInfo<br> +<strong>Compatibility:</strong> The directory and .htaccess contexts +are only available in Apache 1.1 and later.<p> + +In the event of a problem or error, Apache can be configured to do +one of four things, + +<OL> +<LI>output a simple hardcoded error message +<LI>output a customized message +<LI>redirect to a local URL to handle the problem/error +<LI>redirect to an external URL to handle the problem/error +</OL> + +<P>The first option is the default, while options 2-4 are configured +using the <CODE>ErrorDocument</CODE> directive, which is followed by +the HTTP response code and a message or URL. + +<P><em>Messages</em> in this context begin with a single quote +(<code>"</code>), which does not form part of the message itself. +Apache will sometimes offer additional information regarding the +problem/error. + +<P>URLs can begin with a slash (/) for local URLs, or be a full +URL which the client can resolve. Examples: +<blockquote><code> +ErrorDocument 500 http://foo.example.com/cgi-bin/tester<br> +ErrorDocument 404 /cgi-bin/bad_urls.pl<br> +ErrorDocument 401 /subscription_info.html<br> +ErrorDocument 403 "Sorry can't allow you access today +</code></blockquote> + +<P>Note that when you specify an <CODE>ErrorDocument</CODE> that +points to a remote URL (ie. anything with a method such as "http" in +front of it) Apache will send a redirect to the client to tell it +where to find the document, even if the document ends up being +on the same server.. This has several implications, the +most important being that <STRONG>if you use an "ErrorDocument 401" +directive then it must refer to a local document.</STRONG> This results +from the nature of the HTTP basic authentication scheme. + +<P>See Also: <A HREF="../custom-error.html">documentation of customizable +responses.</A><p><hr> + +<A name="errorlog"><h2>ErrorLog directive</h2></A> +<!--%plaintext <?INDEX {\tt ErrorLog} directive> --> +<strong>Syntax:</strong> ErrorLog <em>filename</em><br> +<strong>Default:</strong> <code>ErrorLog logs/error_log</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The error log directive sets the name of the file to which the server will log +any errors it encounters. If the filename does not begin with a slash (/) +then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. +Example: +<blockquote><code>ErrorLog /dev/null</code></blockquote> +This effectively turns off error logging.<p> + +SECURITY: See the <A HREF="../misc/security_tips.html">security tips</A> +document for details on why your security could be compromised if +the directory where logfiles are stored is writable by anyone other +than the user that starts the server. + +<p><hr> + +<A name="files"><h2><Files></h2></A> +<strong>Syntax:</strong> <Files <em>filename</em>> +... </Files><br> +<strong>Context:</strong> server config, virtual host, htaccess<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> only available in Apache +1.2 and above.<p> + +<p>The <Files> directive provides for access control by +filename. It is comparable to the <a +href="#directory"><Directory></a> directive and +<a href="#location"><Location></a> directives. It +should be matched with a </Files> directive. Directives that +apply to the filename given should be listed +within. <code><Files></code> sections are processed in the +order they appear in the configuration file, after the +<Directory> sections and <code>.htaccess</code> files are +read, but before <Location> sections.</p> + +<p>The <em>filename</em> argument should include a filename, or a +wild-card string, where `?' matches any single character, and `*' matches any +sequences of characters. Extended regular expressions can also be used, with the addition of +the <code>~</code> character. For example:</p> + +<pre> + <Files ~ "\.(gif|jpe?g|png)$"> +</pre> + +would match most common Internet graphics formats. + +<p>Note that unlike <a +href="#directory"><code><Directory></code></a> and <a +href="#location"><code><Location></code></a> sections, +<code><Files></code> sections can be used inside .htaccess +files. This allows users to control access to their own files, at a +file-by-file level. When used in an .htaccess file, if the +<em>filename</em> does not begin with a <code>/</code> character, +the directory being applied will be prefixed automatically. + +<p> <hr> + +<A name="group"><h2>Group directive</h2></A> +<!--%plaintext <?INDEX {\tt Group} directive> --> +<strong>Syntax:</strong> Group <em>unix-group</em><br> +<strong>Default:</strong> <code>Group #-1</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The Group directive sets the group under which the server will answer requests. +In order to use this directive, the stand-alone server must be run initially +as root. <em>Unix-group</em> is one of: +<dl> +<dt>A group name +<dd>Refers to the given group by name. +<dt># followed by a group number. +<dd>Refers to a group by its number. +</dl> + +It is recommended that you set up a new group specifically for running the +server. Some admins use user <code>nobody</code>, but this is not always +possible or desirable.<p> + +Note: if you start the server as a non-root user, it will fail to change +to the specified group, and will instead continue to run as the group of the +original user. <p> + +Special note: Use of this directive in <VirtualHost> requires a +properly configured <A HREF="../suexec.html">suEXEC wrapper</A>. +When used inside a <VirtualHost> in this manner, only the group +that CGIs are run as is affected. Non-CGI requests are still processed +as the group specified in the main Group directive.<p> + +SECURITY: See <A HREF="#user">User</A> for a discussion of the security +considerations.<p><hr> + +<A name="hostnamelookups"><h2>HostNameLookups directive</h2></A> +<!--%plaintext <?INDEX {\tt HostNameLookups} directive> --> +<strong>Syntax:</strong> HostNameLookups <em>boolean</em><br> +<strong>Default:</strong> <code>HostNameLookups on</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +This directive enables DNS lookups so that host names can be logged. +Having this directive set <code>on</code> also enables the use of names +in <Limit> blocks for access control.<p> + +Heavily loaded sites should set this directive <code>off</code>, since DNS +lookups can take considerable amounts of time. The utility <i>logresolve</i>, +provided in the <i>/support</i> directory, can be used to look up host names +from logged IP addresses offline.<p><hr> + +<A name="identitycheck"><h2>IdentityCheck directive</h2></A> +<!--%plaintext <?INDEX {\tt IdentityCheck} directive> --> +<strong>Syntax:</strong> IdentityCheck <em>boolean</em><br> +<strong>Default:</strong> <code>IdentityCheck off</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +This directive enables RFC1413-compliant logging of the remote user name +for each connection, where the client machine runs identd or something similar. +This information is logged in the access log. <em>Boolean</em> is either +<code>on</code> or <code>off</code>.<p> + +The information should not be trusted in any way except for rudimentary usage +tracking.<p> + +Note that this can cause serious latency problems accessing your server +since every request requires one of these lookups to be performed. When +firewalls are involved each lookup might possibly fail and add 30 seconds +of latency to each hit. So in general this is not very useful on public +servers accessible from the Internet. +<p><hr> + +<A NAME="ifmodule"><H2><IfModule></H2></A> +<b>Syntax:</b> <IfModule [!]<i>module-name</i>> <i>...</i> +</IfModule><br> +<b>Default:</b> None<br> +<b>Context:</b> all<br> +<b>Status:</b> Core +<strong>Compatibility:</strong> ScriptLog is only available in 1.2 and +later.<P> + +<p> + +The <IfModule <i>test</i>>...</IfModule> +section is used to mark directives that are conditional. The +directives within an IfModule section are only +processed if the <i>test</i> is true. If <i>test</i> +is false, everything between the start and end markers +is ignored.<p> + +The <i>test</i> in the <IfModule> section directive +can be one of two forms: + +<ul> +<li><i>module name</i> +<li>!<i>module name</i> +</ul> + +<p>In the former case, the directives between the start and end markers +are only processed if the module named <i>module name</i> is compiled +in to Apache. The second format reverses the test, and only processes +the directives if <i>module name</i> is <b>not</b> compiled in. + +<p>The <i>module name</i> argument is a module name as given as the file +name of the module, at the time it was compiled. For example, +<code>mod_rewrite.c</code>. + +<p><IfModule> sections are nest-able, which can be used to implement +simple multiple-module tests. + +<P> <hr> + +<h2><a name="keepalive">KeepAlive</a></h2> +<strong>Syntax: (Apache 1.1)</strong> KeepAlive <em>max-requests</em><br> +<strong>Default: (Apache 1.1)</strong> <code>KeepAlive 5</code><br> +<strong>Syntax: (Apache 1.2)</strong> KeepAlive <em>on/off</em><br> +<strong>Default: (Apache 1.2)</strong> <code>KeepAlive On</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core<br> +<strong>Compatibility:</strong> KeepAlive is only available in Apache +1.1 and later.<p> + +This directive enables +<a href="../keepalive.html">Keep-Alive</a> +support. + +<p><strong>Apache 1.1</strong>: Set <em>max-requests</em> +to the maximum number of requests you want Apache to entertain per +request. A limit is imposed to prevent a client from hogging your +server resources. Set this to <code>0</code> to disable support. + +<p><strong>Apache 1.2 and later</strong>: Set to "On" to enable +persistent connections, "Off" to disable. See also the <a +href="#maxkeepaliverequests">MaxKeepAliveRequests</a> directive.</p> + +<h2><a name="keepalivetimeout">KeepAliveTimeout</a></h2> +<strong>Syntax:</strong> KeepAliveTimeout <em>seconds</em><br> +<strong>Default:</strong> <code>KeepAliveTimeout 15</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core<br> +<strong>Compatibility:</strong> KeepAliveTimeout is only available in Apache +1.1 and later.<p> + +The number of seconds Apache will wait for a subsequent request before +closing the connection. Once a request has been received, the timeout +value specified by the <a +href="#timeout"><code>Timeout</code></a> directive +applies. +<hr> + +<A name="listen"><h2>Listen</h2></A> +<strong>Syntax:</strong> +Listen [<em>IP address</em>:]<em>port number</em><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> Listen is only available in Apache +1.1 and later.<p> + +<p>The Listen directive instructs Apache to listen to more than one IP +address or port; by default it responds to requests on all IP +interfaces, but only on the port given by the <a href="#port">Port</a> +directive.</p> + +<p><strong>See Also:</strong> +<a href="../dns-caveats.html">DNS Issues</a><br> +<strong>See Also:</strong> +<a href="../bind.html">Setting which addresses and ports Apache uses</a><br> +<strong>See Also:</strong> +<a href="../misc/known_bugs.html#listenbug">Known Bugs</a></p> +<hr> + +<A name="limit"><h2><Limit> directive</h2></A> +<!--%plaintext <?INDEX {\tt Limit} section directive> --> +<strong>Syntax:</strong> + <Limit <em>method method</em> ... > ... </Limit><br> +<strong>Context:</strong> any<br> +<strong>Status:</strong> core<p> + +<Limit> and </Limit> are used to enclose a group of +access control directives which will then apply only to the specified +access methods, where <em>method</em> is any valid HTTP method. +Any directive except another <Limit> or +<A HREF="#directory"><Directory></A> may be used; the majority will be +unaffected by the <Limit>. Example: +<blockquote><code> +<Limit GET POST><br> +require valid-user<br> +</Limit></code></blockquote> +If an access control directive appears outside a <Limit> directive, +then it applies to all access methods.<p><hr> + +<h2><a name="location"><Location></a></h2> + +<strong>Syntax:</strong> <Location <em>URL</em>> +... </Location><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> Location is only available in Apache +1.1 and later.<p> + +<p>The <Location> directive provides for access control by +URL. It is comparable to the <a +href="#directory"><Directory></a> directive, and +should be matched with a </Location> directive. Directives that +apply to the URL given should be listed +within. <code><Location></code> sections are processed in the +order they appear in the configuration file, after the +<Directory> sections and <code>.htaccess</code> files are +read.</p> + +<p>Note that, due to the way HTTP functions, <em>URL prefix</em> +should, save for proxy requests, be of the form <code>/path/</code>, +and should not include the <code>http://servername</code>. It doesn't +necessarily have to protect a directory (it can be an individual +file, or a number of files), and can include wild-cards. In a wild-card +string, `?' matches any single character, and `*' matches any +sequences of characters. + +<p><strong>Apache 1.2 and above:</strong> +Extended regular expressions can also be used, with the addition of +the +<code>~</code> character. For example:</p> + +<pre> + <Location ~ "/(extra|special)/data"> +</pre> + +<p>would match URLs that contained the substring "/extra/data" or +"/special/data".</p> + +<p>The <code>Location</code> functionality is especially useful when +combined with the <code><a +href="mod_mime.html#sethandler">SetHandler</a></code> directive. For example, to enable status requests, but allow them only +from browsers at foo.com, you might use: + +<pre> + <Location /status> + SetHandler server-status + order deny,allow + deny from all + allow from .foo.com + </Location> +</pre> +<hr> + +<A NAME="lockfile"><H2>LockFile</H2></A> +<strong>Syntax:</strong> LockFile <em>filename</em><BR> +<strong>Default:</strong> <code>LockFile logs/accept.lock</code><BR> +<strong>Context:</strong> server config<BR> +<strong>Status:</strong> core<P> + +The LockFile directive sets the path to the lockfile used when +Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or +USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be +left at its default value. The main reason for changing it is if +the <code>logs</code> directory is NFS mounted, since the lockfile +should be stored on a local disk if possible. The PID of the main +server process is automatically appended to the filename. + +<P><HR> + +<A name="maxclients"><h2>MaxClients</h2></A> +<!--%plaintext <?INDEX {\tt MaxClients} directive> --> +<strong>Syntax:</strong> MaxClients <em>number</em><br> +<strong>Default:</strong> <code>MaxClients 256</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The MaxClients directive sets the limit on the number of simultaneous +requests that can be supported; not more than this number of child server +processes will be created.<p><hr> + +<A name="maxkeepaliverequests"><h2>MaxKeepAliveRequests</h2></A> +<strong>Syntax:</strong> MaxKeepAliveRequests <em>number</em><br> +<strong>Default:</strong> <code>MaxKeepAliveRequests 100</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> Only available in Apache +1.2 and later. + +<p>The MaxKeepAliveRequests directive limits the number of requests +allowed per connection when <a href="#keepalive">KeepAlive</a> is +on. If it is set to "<code>0</code>", unlimited requests will be +allowed. We recommend that this setting be kept to a high value for +maximum server performance. + +<A name="maxrequestsperchild"><h2>MaxRequestsPerChild directive</h2></A> +<!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> --> +<strong>Syntax:</strong> MaxRequestsPerChild <em>number</em><br> +<strong>Default:</strong> <code>MaxRequestsPerChild 0</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The MaxRequestsPerChild directive sets the limit on the number of requests +that an individual child server process will handle. After MaxRequestsPerChild +requests, the child process will die. If MaxRequestsPerChild is 0, then +the process will never expire.<p> + +Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects: +<ul> +<li>it limits the amount of memory that process can consume by (accidental) +memory leakage; +<li> by giving processes a finite lifetime, it helps reduce the +number of processes when the server load reduces. +</ul><p><hr> + +<A name="maxspareservers"><h2>MaxSpareServers directive</h2></A> +<!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> +<strong>Syntax:</strong> MaxSpareServers <em>number</em><br> +<strong>Default:</strong> <code>MaxSpareServers 10</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The MaxSpareServers directive sets the desired maximum number of <em>idle</em> +child server processes. An idle process is one which is not handling +a request. If there are more than MaxSpareServers idle, then the parent +process will kill off the excess processes.<p> + +Tuning of this parameter should only be necessary on very busy sites. +Setting this parameter to a large number is almost always a bad idea.<p> + +See also <A HREF="#minspareservers">MinSpareServers</A> and +<A HREF="#startservers">StartServers</A>.<p><hr> + +<A name="minspareservers"><h2>MinSpareServers directive</h2></A> +<!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> +<strong>Syntax:</strong> MinSpareServers <em>number</em><br> +<strong>Default:</strong> <code>MinSpareServers 5</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The MinSpareServers directive sets the desired minimum number of <em>idle</em> +child server processes. An idle process is one which is not handling +a request. If there are fewer than MinSpareServers idle, then the parent +process creates new children at a maximum rate of 1 per second.<p> + +Tuning of this parameter should only be necessary on very busy sites. +Setting this parameter to a large number is almost always a bad idea.<p> + +See also <A HREF="#maxspareservers">MaxSpareServers</A> and +<A HREF="#startservers">StartServers</A>.<p><hr> + +<A name="options"><h2>Options directive</h2></A> +<!--%plaintext <?INDEX {\tt Options} directive> --> +<strong>Syntax:</strong> Options <em>[+|-]option [+|-]option ...</em><br> +<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Override:</strong> Options<br> +<strong>Status:</strong> core<p> + +The Options directive controls which server features are available in +a particular directory. +<p> +<em>option</em> can be set to <code>None</code>, in which case none of +the extra features are enabled, or one or more of the following: +<dl> +<dt>All +<dd>All options except for MultiViews. +<dt>ExecCGI +<dd> +<!--%plaintext <?INDEX {\tt ExecCGI} option> --> +Execution of CGI scripts is permitted. +<dt>FollowSymLinks +<dd> +<!--%plaintext <?INDEX {\tt FollowSymLinks} option> --> +The server will follow symbolic links in this directory. +<b>Note</b>: even though the server follows the symlink it does <i>not</i> +change the pathname used to match against <code><Directory></code> +sections. +<dt>Includes +<dd> +<!--%plaintext <?INDEX {\tt Includes} option> --> +Server-side includes are permitted. +<dt>IncludesNOEXEC +<dd> +<!--%plaintext <?INDEX {\tt IncludesNOEXEC} option> --> +Server-side includes are permitted, but the #exec command and +#include of CGI scripts are disabled. +<dt>Indexes +<dd> +<!--%plaintext <?INDEX {\tt Indexes} option> --> +If a URL which maps to a directory is requested, and the there is no +DirectoryIndex (e.g. index.html) in that directory, then the server will +return a formatted listing of the directory. +<dt>MultiViews +<dd> +<!--%plaintext <?INDEX {\tt MultiViews} option> --> +<A HREF="../content-negotiation.html">Content negotiated</A> MultiViews are +allowed. +<dt>SymLinksIfOwnerMatch +<dd> +<!--%plaintext <?INDEX {\tt SymLinksIfOwnerMatch} option> --> +The server will only follow symbolic links for which the target +file or directory is owned by the same user id as the link. +</dl> + +Normally, if multiple <code>Options</code> could apply to a directory, +then the most specific one is taken complete; the options are not +merged. However if <i>all</i> the options on the <code>Options</code> +directive are preceded by a + or - symbol, the options are +merged. Any options preceded by a + are added to the options +currently in force, and any options preceded by a - are removed from +the options currently in force. <P> + +For example, without any + and - symbols: + +<blockquote><code> +<Directory /web/docs> <br> +Options Indexes FollowSymLinks<br> +</Directory><br> +<Directory /web/docs/spec> <br> +Options Includes<br> +</Directory> +</code></blockquote> +then only <code>Includes</code> will be set for the /web/docs/spec +directory. However if the second <code>Options</code> directive uses the + +and - symbols:<p> + +<blockquote><code> +<Directory /web/docs> <br> +Options Indexes FollowSymLinks<br> +</Directory><br> +<Directory /web/docs/spec> <br> +Options +Includes -Indexes<br> +</Directory> +</code></blockquote> +then the options <code>FollowSymLinks</code> and <code>Includes</code> +are set for the /web/docs/spec directory. +<hr> + +<A name="pidfile"><h2>PidFile directive</h2></A> +<!--%plaintext <?INDEX {\tt PidFile} directive> --> +<strong>Syntax:</strong> PidFile <em>filename</em><br> +<strong>Default:</strong> <code>PidFile logs/httpd.pid</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The PidFile directive sets the file to which the server records the +process id of the daemon. If the filename does not begin with a slash (/) +then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. +The PidFile is only used in <A HREF="#servertype">standalone</A> mode.<p> + +It is often useful to be able to send the server a signal, so that it closes +and then reopens its <A HREF="#errorlog">ErrorLog</A> and TransferLog, and +re-reads its configuration files. This is done by sending a SIGHUP (kill -1) +signal to the process id listed in the PidFile.<p> + +The PidFile is subject to the same warnings about log file placement and +<a href="../misc/security_tips.html">security</a>. + +<p><hr> + +<A name="port"><h2>Port directive</h2></A> +<!--%plaintext <?INDEX {\tt Port} directive> --> +<strong>Syntax:</strong> Port <em>number</em><br> +<strong>Default:</strong> <code>Port 80</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +<em>Number</em> is a number from 0 to 65535; some port numbers (especially below +1024) are reserved for particular protocols. See <code>/etc/services</code> +for a list of some defined ports; the standard port for the http protocol +is 80.<p> + +The Port directive has two behaviors, the first of which is necessary for +NCSA backwards compatibility (and which is confusing in the context of +Apache).<p> + +<ul> +<li> +In the absence of any <a href="#listen">Listen</a> or +<a href="#bindaddress">BindAddress</a> directives specifying a port number, +the Port directive sets the network port on which the server listens. +If there are any Listen or BindAddress directives specifying +<code>:number</code> then Port has no effect on what address the server +listens at. + +<li>The Port directive +sets the <code>SERVER_PORT</code> environment variable (for +<a href="mod_cgi.html">CGI</a> and <a href="mod_include.html">SSI</a>), +and is used when the server must generate a URL that refers to itself +(for example when creating an external redirect to itself). +</ul> + +In no event does a Port setting affect +what ports a <a href="#virtualhost">VirtualHost</a> responds on, the +VirtualHost directive itself is used for that.<p> + +The primary behaviour of Port should be considered to be similar to that of +the <a href="#servername">ServerName</a> directive. The ServerName +and Port together specify what you consider to be the <i>canonical</i> +address of the server.<p> + +Port 80 is one of Unix's special ports. All ports numbered +below 1024 are reserved for system use, i.e. regular (non-root) users cannot +make use of them; instead they can only use higher port numbers. +To use port 80, you must start the server from the root account. +After binding to the port and before accepting requests, Apache will change +to a low privileged user as set by the <A HREF="#user">User directive</A>.<p> + +If you cannot use port 80, choose any other unused port. Non-root users +will have to choose a port number higher than 1023, such as 8000.<p> + +SECURITY: if you do start the server as root, be sure +not to set <A HREF="#user">User</A> to root. If you run the server as +root whilst handling connections, your site may be open to a major security +attack.<p><hr> + +<A name="require"><h2>require directive</h2></A> +<!--%plaintext <?INDEX {\tt require} directive> --> +<strong>Syntax:</strong> require <em>entity-name entity entity...</em><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> core<p> + +This directive selects which authenticated users can access a directory. +The allowed syntaxes are: +<ul> +<li>require user <em>userid userid ...</em><p> +Only the named users can access the directory.<p> +<li>require group <em>group-name group-name ...</em><p> +Only users in the named groups can access the directory.<p> +<li>require valid-user<p> +All valid users can access the directory. +</ul> +<p> +If <code>require</code> appears in a <A HREF="#limit"><Limit></A> +section, then it restricts access to the named methods, otherwise +it restricts access for all methods. Example: +<blockquote><code> +AuthType Basic<br> +AuthName somedomain<br> +AuthUserFile /web/users<br> +AuthGroupFile /web/groups<br> +<Limit GET POST><br> +require group admin<br> +</Limit> +</code></blockquote> + +Require must be accompanied by <A HREF="#authname">AuthName</A> and +<A HREF="#authtype">AuthType</A> directives, and directives such as +<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and +<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> (to define users and +groups) in order to work correctly.<p><hr> + +<A name="resourceconfig"><h2>ResourceConfig directive</h2></A> +<!--%plaintext <?INDEX {\tt ResourceConfig} directive> --> +<strong>Syntax:</strong> ResourceConfig <em>filename</em><br> +<strong>Default:</strong> <code>ResourceConfig conf/srm.conf</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The server will read this file for more directives after reading the +httpd.conf file. <em>Filename</em> is relative to the +<A HREF="#serverroot">ServerRoot</A>. +This feature can be disabled using: +<blockquote><code>ResourceConfig /dev/null</code></blockquote> +Historically, this file contained most directives except for server +configuration directives and <A HREF="#directory"><Directory></A> +sections; in fact it can now contain any server directive allowed in the +<em>server config</em> context.<p> + +See also <A HREF="#accessconfig">AccessConfig</A>.<p><hr> + +<A name="rlimit"> </A> +<A name="rlimitcpu"><h2>RLimitCPU directive</h2></A> +<!--%plaintext <?INDEX {\tt RLimitCPU} directive> --> +<strong>Syntax:</strong> RLimitCPU <em># or 'max'</em> <em>[# or 'max']</em><br> +<strong>Default:</strong> <code>Unset uses operating system defaults</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> RLimitCPU is only available in Apache 1.2 and later<p> + +Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all +processes and the second parameter sets the maximum resource limit. Either parameter +can be a number, or <em>max</em> to indicate to the server that the limit should +be set to the maximum allowed by the operating system configuration. Raising the +maximum resource limit requires that the server is running as root, or in the initial +startup phase.<p> + +CPU resource limits are expressed in seconds per process.<p> + +See also <A HREF="#rlimitmem">RLimitMEM</A> or <A HREF="#rlimitnproc">RLimitNPROC</A>.<p><hr> + +<A name="rlimitmem"><h2>RLimitMEM directive</h2></A> +<!--%plaintext <?INDEX {\tt RLimitMEM} directive> --> +<strong>Syntax:</strong> RLimitMEM <em># or 'max'</em> <em>[# or 'max']</em><br> +<strong>Default:</strong> <code>Unset uses operating system defaults</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> RLimitMEM is only available in Apache 1.2 and later<p> + +Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all +processes and the second parameter sets the maximum resource limit. Either parameter +can be a number, or <em>max</em> to indicate to the server that the limit should +be set to the maximum allowed by the operating system configuration. Raising the +maximum resource limit requires that the server is running as root, or in the initial +startup phase.<p> + +Memory resource limits are expressed in bytes per process.<p> + +See also <A HREF="#rlimitcpu">RLimitCPU</A> or <A HREF="#rlimitnproc">RLimitNPROC</A>.<p><hr> + +<A name="rlimitnproc"><h2>RLimitNPROC directive</h2></A> +<!--%plaintext <?INDEX {\tt RLimitNPROC} directive> --> +<strong>Syntax:</strong> RLimitNPROC <em># or 'max'</em> <em>[# or 'max']</em><br> +<strong>Default:</strong> <code>Unset uses operating system defaults</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> RLimitNPROC is only available in Apache 1.2 and later<p> + +Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all +processes and the second parameter sets the maximum resource limit. Either parameter +can be a number, or <em>max</em> to indicate to the server that the limit should +be set to the maximum allowed by the operating system configuration. Raising the +maximum resource limit requires that the server is running as root, or in the initial +startup phase.<p> + +Process limits control the number of processes per user.<p> + +Note: If CGI processes are <b>not</b> running under userids other than the +web server userid, this directive will limit the number of processes that the +server itself can create. Evidence of this situation will be indicated by +<b><em>cannot fork</em></b> messages in the error_log.<p> + +See also <A HREF="#rlimitmem">RLimitMEM</A> or <A HREF="#rlimitcpu">RLimitCPU</A>. + +<p><hr> + +<A name="satisfy"><h2>Satisfy</h2></A> +<!--%plaintext <?INDEX {\tt Satisfy} directive> --> +<strong>Syntax:</strong> Satisfy <em>'any' or 'all'</em><br> +<strong>Default:</strong> Satisfy all<br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> Satisfy is only available in Apache 1.2 and later<p> + +Access policy if both allow and require used. The parameter can be +either <em>'all'</em> or <em>'any'</em>. This directive is only useful +if access to a particular area is being restricted by both +username/password <i>and</i> client host address. In this case the +default behavior ("all") is to require that the client passes the +address access restriction <i>and</i> enters a valid username and +password. With the "any" option the client will be granted access if +they either pass the host restriction or enter a valid username and +password. This can be used to password restrict an area, but to let +clients from particular addresses in without prompting for a password. + + +<p><hr> + +<A name="scoreboardfile"><h2>ScoreBoardFile directive</h2></A> +<!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> --> +<strong>Syntax:</strong> ScoreBoardFile <em>filename</em><br> +<strong>Default:</strong> <code>ScoreBoardFile logs/apache_status</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The ScoreBoardFile directive is required on some architectures to place +a file that the server will use to communicate between its children and +the parent. The easiest way to find out if your architecture requires +a scoreboard file is to run Apache and see if it creates the file named +by the directive. If your architecture requires it then you must ensure +that this file is not used at the same time by more than one invocation +of Apache.<p> + +If you have to use a ScoreBoardFile then you may see improved speed by +placing it on a RAM disk. But be careful that you heed the same warnings +about log file placement and +<a href="../misc/security_tips.html">security</a>.<p> + +Apache 1.2 and above:<p> + +Linux 1.x users might be able to add <code>-DHAVE_SHMGET</code> to +the <code>EXTRA_CFLAGS</code> in your <code>Configuration</code>. This +might work with some 1.x installations, but won't work with all of +them.<p> + +SVR4 users should consider adding <code>-DHAVE_SHMGET</code> to the +<code>EXTRA_CFLAGS</code> in your <code>Configuration</code>. This +is believed to work, but we were unable to test it in time for 1.2 +release.<p> + +<strong>See Also</strong>: +<a href="../stopping.html">Stopping and Restarting Apache</a></p> + +<p><hr> + +<A name="sendbuffersize"><h2>SendBufferSize directive</h2></A> +<!--%plaintext <?INDEX {\tt SendBufferSize} directive> --> +<strong>Syntax:</strong> SendBufferSize <em>bytes</em><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The server will set the TCP buffer size to the number of bytes +specified. Very useful to increase past standard OS defaults on high +speed high latency (i.e. 100ms or so, such as transcontinental +fast pipes) +<p><hr> + +<A name="serveradmin"><h2>ServerAdmin directive</h2></A> +<!--%plaintext <?INDEX {\tt ServerAdmin} directive> --> +<strong>Syntax:</strong> ServerAdmin <em>email-address</em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The ServerAdmin sets the e-mail address that the server includes in any +error messages it returns to the client.<p> + +It may be worth setting up a dedicated address for this, e.g. +<blockquote><code>ServerAdmin www-admin@foo.bar.com</code></blockquote> +as users do not always mention that they are talking about the server!<p><hr> + +<A name="serveralias"><h2>ServerAlias directive</h2></A> + +<strong>Syntax:</strong> ServerAlias <em>host1 host2 ...</em><br> +<strong>Context:</strong> virtual host<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> ServerAlias is only available in Apache +1.1 and later.<p> + +The ServerAlias directive sets the alternate names for a host, for use +with +<a href="../host.html">Host-header based virtual hosts</a>. +<p><strong>See Also</strong>: +<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p> + +<hr> + +<A name="servername"><h2>ServerName directive</h2></A> +<!--%plaintext <?INDEX {\tt ServerName} directive> --> +<strong>Syntax:</strong> ServerName <em>fully-qualified domain name</em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The ServerName directive sets the hostname of the server; this is only +used when creating redirection URLs. If it is not specified, then the +server attempts to deduce it from its own IP address; however this may +not work reliably, or may not return the preferred hostname. For example: +<blockquote><code>ServerName www.wibble.com</code></blockquote> +would be used if the canonical (main) name of the actual machine +were <code>monster.wibble.com</code>.<p> +<p><strong>See Also</strong>: +<a href="../dns-caveats.html">DNS Issues</a></p> +<hr> + +<A name="serverpath"><h2>ServerPath directive</h2></A> + +<strong>Syntax:</strong> ServerPath <em>pathname</em><br> +<strong>Context:</strong> virtual host<br> +<strong>Status:</strong> core<br> +<strong>Compatibility:</strong> ServerPath is only available in Apache +1.1 and later.<p> + +The ServerPath directive sets the legacy URL pathname for a host, for +use with <a href="../host.html">Host-header based virtual hosts</a>. +<p><strong>See Also</strong>: +<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p> +<hr> + +<A name="serverroot"><h2>ServerRoot directive</h2></A> +<!--%plaintext <?INDEX {\tt ServerRoot} directive> --> +<strong>Syntax:</strong> ServerRoot <em>directory-filename</em><br> +<strong>Default:</strong> <code>ServerRoot /usr/local/etc/httpd</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The ServerRoot directive sets the directory in which the server lives. +Typically it will contain the subdirectories <code>conf/</code> and +<code>logs/</code>. Relative paths for other configuration files are taken +as relative to this directory.<br> +See also <a href="../invoking.html">the <code>-d</code> option to httpd</a>.<p><hr> + +<A name="servertype"><h2>ServerType directive</h2></A> +<!--%plaintext <?INDEX {\tt ServerType} directive> --> +<strong>Syntax:</strong> ServerType <em>type</em><br> +<strong>Default:</strong> <code>ServerType standalone</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The ServerType directive sets how the server is executed by the system. +<em>Type</em> is one of +<dl> +<dt>inetd +<dd>The server will be run from the system process inetd; the command to start +the server is added to <code>/etc/inetd.conf</code> +<dt>standalone +<dd>The server will run as a daemon process; the command to start the server +is added to the system startup scripts. (<code>/etc/rc.local</code> or +<code>/etc/rc3.d/...</code>.) +</dl> + +Inetd is the lesser used of the two options. For each http +connection received, a new copy of the server is started from scratch; +after the connection is complete, this program exits. There is a high price to +pay per connection, but for security reasons, some admins prefer this option. +<p> + +Standalone is the most common setting for ServerType since +it is far more efficient. The server is started once, and services all +subsequent connections. If you intend running Apache to serve a busy site, +standalone will probably be your only option.<p> + +SECURITY: if you are paranoid about security, run in inetd mode. Security +cannot be guaranteed in either, but whilst most people are happy to use +standalone, inetd is probably least prone to attack.<p><hr> + +<A name="startservers"><h2>StartServers directive</h2></A> +<!--%plaintext <?INDEX {\tt StartServers} directive> --> +<strong>Syntax:</strong> StartServers <em>number</em><br> +<strong>Default:</strong> <code>StartServers 5</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The StartServers directive sets the number of child server processes created +on startup. As the number of processes is dynamically controlled depending +on the load, there is usually little reason to adjust this parameter.<p> + +See also <A HREF="#minspareservers">MinSpareServers</A> and +<A HREF="#maxspareservers">MaxSpareServers</A>.<p><hr> + +<A name="timeout"><h2>TimeOut directive</h2></A> +<!--%plaintext <?INDEX {\tt TimeOut} directive> --> +<strong>Syntax:</strong> TimeOut <em>number</em><br> +<strong>Default:</strong> <code>TimeOut 300</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> core<p> + +The TimeOut directive currently defines the amount of time Apache will +wait for three things: + +<OL> + <LI>The total amount of time it takes to receive a GET request. + <LI>The amount of time between receipt of TCP packets on a POST or + PUT request. + <LI>The amount of time between ACKs on transmissions of TCP packets + in responses. +</OL> + +We plan on making these separately configurable at some point down the +road. The timer used to default to 1200 before 1.2, but has been +lowered to 300 which is still far more than necessary in most +situations. It is not set any lower by default because there may +still be odd places in the code where the timer is not reset when +a packet is sent. + +<p><hr> + +<A name="user"><h2>User directive</h2></A> +<!--%plaintext <?INDEX {\tt User} directive> --> +<strong>Syntax:</strong> User <em>unix-userid</em><br> +<strong>Default:</strong> <code>User #-1</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<p> + +The User directive sets the userid as which the server will answer requests. +In order to use this directive, the standalone server must be run initially +as root. <em>Unix-userid</em> is one of: +<dl> +<dt>A username +<dd>Refers to the given user by name. +<dt># followed by a user number. +<dd>Refers to a user by their number. +</dl> + +The user should have no privileges which result in it being able to access +files which are not intended to be visible to the outside world, and +similarly, the user should not be able to execute code which is not +meant for httpd requests. It is recommended that you set up a new user and +group specifically for running the server. Some admins use user +<code>nobody</code>, but this is not always possible or desirable.<p> + +Notes: If you start the server as a non-root user, it will fail to change +to the lesser privileged user, and will instead continue to run as +that original user. If you do start the server as root, then it is normal +for the parent process to remain running as root.<p> + +Special note: Use of this directive in <VirtualHost> requires a +properly configured <A HREF="../suexec.html">suEXEC wrapper</A>. +When used inside a <VirtualHost> in this manner, only the user +that CGIs are run as is affected. Non-CGI requests are still processed +with the user specified in the main User directive.<p> + +SECURITY: Don't set User (or <A HREF="#group">Group</A>) to +<code>root</code> unless you know exactly what you are doing, and what the +dangers are.<p><hr> + +<A name="virtualhost"><h2><VirtualHost> directive</h2></A> +<!--%plaintext <?INDEX {\tt VirtualHost} section directive> --> +<strong>Syntax:</strong> <VirtualHost <em>addr</em>[:<em>port</em>] ...> ... +</VirtualHost> <br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core.<br> +<strong>Compatibility:</strong> Non-IP address-based Virtual Hosting only +available in Apache 1.1 and later.<br> +<strong>Compatibility:</strong> Multiple address support only available in +Apache 1.2 and later.<p> + +<VirtualHost> and </VirtualHost> are used to enclose a group of +directives which will apply only to a particular virtual host. +Any directive which is allowed in a virtual host context may be used. +When the server receives a request for a document on a particular virtual +host, it uses the configuration directives enclosed in the <VirtualHost> +section. <em>Addr</em> can be +<menu> +<li>The IP address of the virtual host +<li>A fully qualified domain name for the IP address of the virtual host. +</menu> Example: +<blockquote> +<code> +<VirtualHost 10.1.2.3> <br> +ServerAdmin webmaster@host.foo.com <br> +DocumentRoot /www/docs/host.foo.com <br> +ServerName host.foo.com <br> +ErrorLog logs/host.foo.com-error_log <br> +TransferLog logs/host.foo.com-access_log <br> +</VirtualHost> +</code></blockquote> + +Each VirtualHost must correspond to a different IP address or a +different host name for the server, in the latter case the server +machine must be configured to accept IP packets for multiple +addresses. (If the machine does not have multiple network interfaces, +then this can be accomplished with the <code>ifconfig alias</code> +command (if your OS supports it), or with kernel patches like <A +HREF="../misc/vif-info.html">VIF</A> (for SunOS(TM) 4.1.x)).<p> + +The special name <code>_default_</code> can be specified in which case +this virtual host will match any IP address that is not explicitly listed +in another virtual host. In the absence of any _default_ virtual host +the "main" server config, consisting of all those definitions outside +any VirtualHost section, is used when no match occurs.<p> + +You can specify a <code>:port</code> to change the port that is matched. +If unspecified then it defaults to the same port as the most recent +<code><a href="#port">Port</a></code> statement of the main server. You +may also specify <code>:*</code> to match all ports on that address. +(This is recommended when used with <code>_default_</code>.)<p> + +<strong>SECURITY</strong>: See the +<A HREF="../misc/security_tips.html">security tips</A> +document for details on why your security could be compromised if +the directory where logfiles are stored is writable by anyone other +than the user that starts the server. + +<p><strong>See also:</strong> +<A HREF="../dns-caveats.html">Warnings about DNS and Apache</a><br> +<strong>See also:</strong> +<A HREF="../virtual-host.html">Information on Virtual Hosts. +(multihome)</A><br> +<strong>See also:</strong> +<a href="../host.html">Non-IP address-based Virtual Hosts</a><br> +<strong>See also:</strong> +<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a> +</p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/directives.html b/usr.sbin/httpd/htdocs/manual/mod/directives.html new file mode 100644 index 00000000000..e5d8fb839e1 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/directives.html @@ -0,0 +1,190 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache directives</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache directives</H1> + +<ul> +<li><A HREF="core.html#accessconfig">AccessConfig</A> +<li><A HREF="core.html#accessfilename">AccessFileName</A> +<li><A HREF="mod_actions.html#action">Action</A> +<li><A HREF="mod_dir.html#addalt">AddAlt</A> +<li><A HREF="mod_dir.html#addaltbyencoding">AddAltByEncoding</A> +<li><A HREF="mod_dir.html#addaltbytype">AddAltByType</A> +<li><A HREF="mod_dir.html#adddescription">AddDescription</A> +<li><A HREF="mod_mime.html#addencoding">AddEncoding</A> +<li><A HREF="mod_mime.html#addhandler">AddHandler</A> +<li><A HREF="mod_dir.html#addicon">AddIcon</A> +<li><A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A> +<li><A HREF="mod_dir.html#addiconbytype">AddIconByType</A> +<li><A HREF="mod_mime.html#addlanguage">AddLanguage</A> +<li><A HREF="core.html#addmodule">AddModule</A> +<li><A HREF="mod_mime.html#addtype">AddType</A> +<li><A HREF="mod_log_agent.html#agentlog">AgentLog</A> +<li><A HREF="mod_alias.html#alias">Alias</A> +<li><A HREF="mod_access.html#allow">allow</A> +<li><A HREF="core.html#allowoverride">AllowOverride</A> +<li><A HREF="mod_auth_anon.html#anonymous">Anonymous</A> +<li><A HREF="mod_auth_anon.html#Authoritative">Anonymous_Authoritative</A> +<li><A HREF="mod_auth_anon.html#LogEmail">Anonymous_LogEmail</A> +<li><A HREF="mod_auth_anon.html#MustGiveEmail">Anonymous_MustGiveEmail</A> +<li><A HREF="mod_auth_anon.html#NoUserID">Anonymous_NoUserID</A> +<li><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A> +<li><A HREF="mod_auth.html#authauthoritative">AuthAuthoritative</A> +<li><A HREF="mod_auth_db.html#authdbauthoritative">AuthDBAuthoritative</A> +<li><A HREF="mod_auth_db.html#authdbgroupfile">AuthDBGroupFile</A> +<li><A HREF="mod_auth_dbm.html#authdbmauthoritative">AuthDBMAuthoritative</A> +<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> +<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> +<li><A HREF="mod_auth_db.html#authdbuserfile">AuthDBUserFile</A> +<li><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> +<li><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A> +<li><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> +<li><A HREF="core.html#authname">AuthName</A> +<li><A HREF="core.html#authtype">AuthType</A> +<li><A HREF="mod_auth.html#authuserfile">AuthUserFile</A> +<li><A HREF="core.html#bindaddress">BindAddress</A> +<li><A HREF="mod_browser.html#browsermatch">BrowserMatch</A> +<li><A HREF="mod_browser.html#browsermatchnocase">BrowserMatchNoCase</A> +<li><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A> +<li><A HREF="mod_proxy.html#cachedirlength">CacheDirLength</A> +<li><A HREF="mod_proxy.html#cachedirlevels">CacheDirLevels</A> +<li><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A> +<li><A HREF="mod_proxy.html#cachelastmodifiedfactor">CacheLastModifiedFactor</A> +<li><A HREF="mod_proxy.html#cachemaxexpire">CacheMaxExpire</A> +<li><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A> +<li><A HREF="mod_proxy.html#cacheroot">CacheRoot</A> +<li><A HREF="mod_proxy.html#cachesize">CacheSize</A> +<li><A HREF="core.html#clearmodulelist">ClearModuleList</A> +<li><A HREF="mod_usertrack.html#cookieexpires">CookieExpires</A> +<li><A HREF="mod_cookies.html#cookielog">CookieLog</A> (mod_cookies) +<li><A HREF="mod_log_config.html#cookielog">CookieLog</A> (mod_log_config) +<li><A HREF="mod_usertrack.html#cookietracking">CookieTracking</A> +<li><A HREF="mod_log_config.html#customlog">CustomLog</A> +<li><A HREF="mod_dir.html#defaulticon">DefaultIcon</A> +<li><A HREF="core.html#defaulttype">DefaultType</A> +<li><A HREF="mod_access.html#deny">deny</A> +<li><A HREF="core.html#directory"><Directory></A> +<li><A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> +<li><A HREF="core.html#documentroot">DocumentRoot</A> +<li><A HREF="core.html#errordocument">ErrorDocument</A> +<li><A HREF="core.html#errorlog">ErrorLog</A> +<li><A HREF="mod_example.html#example">Example</A> +<li><A HREF="mod_expires.html#expiresactive">ExpiresActive</A> +<li><A HREF="mod_expires.html#expiresbytype">ExpiresByType</A> +<li><A HREF="mod_expires.html#expiresdefault">ExpiresDefault</A> +<li><A HREF="mod_dir.html#fancyindexing">FancyIndexing</A> +<li><A HREF="core.html#files"><Files></A> +<li><A HREF="mod_mime.html#forcetype">ForceType</A> +<li><A HREF="core.html#group">Group</A> +<li><A HREF="mod_headers.html#header">Header</A> +<li><A HREF="mod_dir.html#headername">HeaderName</A> +<li><A HREF="core.html#hostnamelookups">HostNameLookups</A> +<li><A HREF="core.html#identitycheck">IdentityCheck</A> +<li><A HREF="core.html#ifmodule"><IfModule></A> +<li><A HREF="mod_imap.html#imapbase">ImapBase</A> +<li><A HREF="mod_imap.html#imapdefault">ImapDefault</A> +<li><A HREF="mod_imap.html#imapmenu">ImapMenu</A> +<li><A HREF="mod_dir.html#indexignore">IndexIgnore</A> +<li><A HREF="mod_dir.html#indexoptions">IndexOptions</A> +<li><A HREF="core.html#keepalive">KeepAlive</A> +<li><A HREF="core.html#keepalivetimeout">KeepAliveTimeout</A> +<li><A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A> +<li><A HREF="core.html#limit"><Limit></A> +<li><A HREF="core.html#listen">Listen</A> +<li><A HREF="mod_dld.html#loadfile">LoadFile</A> +<li><A HREF="mod_dld.html#loadmodule">LoadModule</A> +<li><A HREF="core.html#location"><Location></A> +<li><A HREF="core.html#lockfile">LockFile</A> +<li><A HREF="mod_log_config.html#logformat">LogFormat</A> +<li><A HREF="core.html#maxclients">MaxClients</A> +<li><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A> +<li><A HREF="core.html#maxrequestsperchild">MaxRequestsPerChild</A> +<li><A HREF="core.html#maxspareservers">MaxSpareServers</A> +<li><A HREF="mod_cern_meta.html#metadir">MetaDir</A> +<li><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A> +<li><A HREF="core.html#minspareservers">MinSpareServers</A> +<li><A HREF="mod_proxy.html#nocache">NoCache</A> +<li><A HREF="core.html#options">Options</A> +<li><A HREF="mod_access.html#order">order</A> +<li><A HREF="mod_env.html#passenv">PassEnv</A> +<li><A HREF="core.html#pidfile">PidFile</A> +<li><A HREF="core.html#port">Port</A> +<li><A HREF="mod_proxy.html#proxyblock">ProxyBlock</A> +<li><A HREF="mod_proxy.html#proxypass">ProxyPass</A> +<li><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A> +<li><A HREF="mod_proxy.html#proxyrequests">ProxyRequests</A> +<li><A HREF="mod_dir.html#readmename">ReadmeName</A> +<li><A HREF="mod_alias.html#redirect">Redirect</A> +<li><A HREF="mod_alias.html#redirectperm">RedirectPermanent</A> +<li><A HREF="mod_alias.html#redirecttemp">RedirectTemp</A> +<li><A HREF="mod_log_referer.html#refererignore">RefererIgnore</A> +<li><A HREF="mod_log_referer.html#refererlog">RefererLog</A> +<li><A HREF="core.html#require">require</A> +<li><A HREF="core.html#resourceconfig">ResourceConfig</A> +<li><A HREF="mod_rewrite.html#RewriteBase">RewriteBase</A> +<li><A HREF="mod_rewrite.html#RewriteCond">RewriteCond</A> +<li><A HREF="mod_rewrite.html#RewriteEngine">RewriteEngine</A> +<li><A HREF="mod_rewrite.html#RewriteLog">RewriteLog</A> +<li><A HREF="mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</A> +<li><A HREF="mod_rewrite.html#RewriteMap">RewriteMap</A> +<li><A HREF="mod_rewrite.html#RewriteOptions">RewriteOptions</A> +<li><A HREF="mod_rewrite.html#RewriteRule">RewriteRule</A> +<li><A HREF="core.html#rlimitcpu">RLimitCPU</A> +<li><A HREF="core.html#rlimitmem">RLimitMEM</A> +<li><A HREF="core.html#rlimitnproc">RLimitNPROC</A> +<li><A HREF="core.html#satisfy">Satisfy</A> +<li><A HREF="core.html#scoreboardfile">ScoreBoardFile</A> +<li><A HREF="mod_actions.html#script">Script</A> +<li><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> +<li><A HREF="mod_cgi.html#scriptlog">ScriptLog</A> +<li><A HREF="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</A> +<li><A HREF="mod_cgi.html#scriptloglength">ScriptLogLength</A> +<li><A HREF="core.html#sendbuffersize">SendBufferSize</A> +<li><A HREF="core.html#serveradmin">ServerAdmin</A> +<li><A HREF="core.html#serveralias">ServerAlias</A> +<li><A HREF="core.html#servername">ServerName</A> +<li><A HREF="core.html#serverpath">ServerPath</A> +<li><A HREF="core.html#serverroot">ServerRoot</A> +<li><A HREF="core.html#servertype">ServerType</A> +<li><A HREF="mod_env.html#setenv">SetEnv</A> +<li><A HREF="mod_mime.html#sethandler">SetHandler</A> +<li><A HREF="core.html#startservers">StartServers</A> +<li><A HREF="core.html#timeout">TimeOut</A> +<li><A HREF="mod_log_common.html#transferlog">TransferLog</A> (mod_log_common) +<li><A HREF="mod_log_config.html#transferlog">TransferLog</A> (mod_log_config) +<li><A HREF="mod_mime.html#typesconfig">TypesConfig</A> +<li><A HREF="mod_env.html#unsetenv">UnsetEnv</A> +<li><A HREF="core.html#user">User</A> +<li><A HREF="mod_userdir.html#userdir">UserDir</A> +<li><A HREF="core.html#virtualhost"><VirtualHost></A> +<li><A HREF="mod_include.html#xbithack">XBitHack</A> +</ul> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/footer.html b/usr.sbin/httpd/htdocs/manual/mod/footer.html new file mode 100644 index 00000000000..cbbcf9a8e2c --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/footer.html @@ -0,0 +1,7 @@ +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/usr.sbin/httpd/htdocs/manual/mod/header.html b/usr.sbin/httpd/htdocs/manual/mod/header.html new file mode 100644 index 00000000000..3a472e66722 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/header.html @@ -0,0 +1,6 @@ +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> diff --git a/usr.sbin/httpd/htdocs/manual/mod/index.html b/usr.sbin/httpd/htdocs/manual/mod/index.html new file mode 100644 index 00000000000..2a2aecea5a8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/index.html @@ -0,0 +1,116 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache modules</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache modules</h1> + +<P> +Below is a list of all of the modules that come as part of the +Apache distribution. See also the complete alphabetical list of +<A + HREF="directives.html" +>all Apache directives</A>. +</P> + +<dl> +<dt><A HREF="core.html">Core</A> +<dd>Core Apache features. +<dt><A HREF="mod_access.html">mod_access</A> +<dd>Host based access control. +<dt><A HREF="mod_actions.html">mod_actions</A> Apache 1.1 and later. +<dd>Filetype/method-based script execution +<dt><A HREF="mod_alias.html">mod_alias</A> +<dd>Aliases and redirects. +<dt><A HREF="mod_asis.html">mod_asis</A> +<dd>The .asis file handler. +<dt><A HREF="mod_auth.html">mod_auth</A> +<dd>User authentication using text files. +<dt><A HREF="mod_auth_anon.html">mod_auth_anon</A> +<dd>Anonymous user authentication, FTP-style. +<dt><A HREF="mod_auth_db.html">mod_auth_db</A> +<dd>User authentication using Berkeley DB files. +<dt><A HREF="mod_auth_dbm.html">mod_auth_dbm</A> +<dd>User authentication using DBM files. +<dt><A HREF="mod_auth_msql.html">mod_auth_msql</A> +<dd>User authentication using mSQL files. +<dt><A HREF="mod_browser.html">mod_browser</A> Apache 1.2 and up +<dd>Set environment variables based on User-Agent strings +<dt><A HREF="mod_cern_meta.html">mod_cern_meta</a> +<dd>Support for HTTP header metafiles. +<dt><A HREF="mod_cgi.html">mod_cgi</A> +<dd>Invoking CGI scripts. +<dt><A HREF="mod_cookies.html">mod_cookies</A> up to Apache 1.1.1 +<dd>Support for Netscape-like cookies. Replaced in Apache 1.2 by +mod_usertrack +<dt><A HREF="mod_digest.html">mod_digest</A> +<dd>MD5 authentication +<dt><A HREF="mod_dir.html">mod_dir</A> +<dd>Automatic directory listings. +<dt><A HREF="mod_dld.html">mod_dld</A> +<dd>Start-time linking with the GNU libdld. +<dt><A HREF="mod_env.html">mod_env</A> +<dd>Passing of environments to CGI scripts +<dt><A HREF="mod_example.html">mod_example</A> Apache 1.2 and up +<dd>Demonstrates Apache API +<dt><A HREF="mod_expires.html">mod_expires</A> Apache 1.2 and up +<dd>Apply Expires: headers to resources +<dt><A HREF="mod_headers.html">mod_headers</A> Apache 1.2 and up +<dd>Add arbitrary HTTP headers to resources +<dt><A HREF="mod_imap.html">mod_imap</A> +<dd>The imagemap file handler. +<dt><A HREF="mod_include.html">mod_include</A> +<dd>Server-parsed documents. +<dt><A HREF="mod_info.html">mod_info</a> +<dd>Server configuration information +<dt><A HREF="mod_log_agent.html">mod_log_agent</A> +<dd>Logging of User Agents. +<dt><A HREF="mod_log_common.html">mod_log_common</A> up to Apache 1.1.1 +<dd>Standard logging in the Common Logfile Format. Replaced by the +mod_log_config module in Apache 1.2 and up +<dt><A HREF="mod_log_config.html">mod_log_config</A> +<dd>User-configurable logging replacement for mod_log_common. +<dt><A HREF="mod_log_referer.html">mod_log_referer</A> +<dd>Logging of document references. +<dt><A HREF="mod_mime.html">mod_mime</A> +<dd>Determining document types. +<dt><A HREF="mod_negotiation.html">mod_negotiation</A> +<dd>Content negotiation. +<dt><A HREF="mod_rewrite.html">mod_rewrite</a> Apache 1.2 and up +<dd>Powerful URI-to-filename mapping using regular expressions +<dt><A HREF="mod_proxy.html">mod_proxy</A> +<dd>Caching proxy abilities +<dt><A HREF="mod_status.html">mod_status</a> +<dd>Server status display +<dt><A HREF="mod_userdir.html">mod_userdir</A> +<dd>User home directories. +<dt><A HREF="mod_usertrack.html">mod_usertrack</A> Apache 1.2 and up +<dd>User tracking using Cookies (replacement for mod_cookies.c) +</dl> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_access.html b/usr.sbin/httpd/htdocs/manual/mod/mod_access.html new file mode 100644 index 00000000000..0787282a9db --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_access.html @@ -0,0 +1,189 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_access</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Module mod_access</h1> + +This module is contained in the <code>mod_access.c</code> file, and +is compiled in by default. It provides access control based on client +hostname or IP address. + + +<menu> +<li><A HREF="#allow">allow</A> +<li><A HREF="#allowfromenv">allow from env=</A> +<li><A HREF="#deny">deny</A> +<li><A HREF="#denyfromenv">deny from env=</A> +<li><A HREF="#order">order</A> +</menu> +<hr> + + +<A name="allow"><h2>allow</h2></A> +<!--%plaintext <?INDEX {\tt allow} directive> --> +<strong>Syntax:</strong> allow from <em>host host ...</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> Limit<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_access<p> + +The allow directive affects which hosts can access a given directory. +<em>Host</em> is one of the following: +<dl> +<dt><code>all</code> +<dd>all hosts are allowed access +<dt>A (partial) domain-name +<dd>host whose name is, or ends in, this string are allowed access. +<dt>A full IP address +<dd>An IP address of a host allowed access +<dt>A partial IP address +<dd>The first 1 to 3 bytes of an IP address, for subnet restriction. +</dl> + +Example:<blockquote><code>allow from .ncsa.uiuc.edu</code></blockquote> +All hosts in the specified domain are allowed access.<p> + +Note that this compares whole components; <code>bar.edu</code> +would not match <code>foobar.edu</code>.<p> + +See also <A HREF="#deny">deny</A>, <A HREF="#order">order</A>, and +<a href="mod_browser.html#browsermatch">BrowserMatch</a>.<p> + +<a name="allowfromenv"><strong>Syntax:</strong> allow from env=<em>variablename</em></a><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> Limit<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_access<br> +<strong>Compatibility:</strong> Apache 1.2 and above<p> + +The allow from env directive controls access to a directory by the +existence (or non-existence) of an environment variable. + +Example:<blockquote><pre> +BrowserMatch ^KnockKnock/2.0 let_me_in +<Directory /docroot> +order allow,deny +allow from env=let_me_in +deny from all +</Directory> +</pre></blockquote> + +See also <A HREF="#denyfromenv">deny from env</A> +and <A HREF="#order">order</A>.<p><hr> + +<A name="deny"><h2>deny</h2></A> +<!--%plaintext <?INDEX {\tt deny} directive> --> +<strong>Syntax:</strong> deny from <em>host host ...</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> Limit<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_access<p> + +The deny directive affects which hosts can access a given directory. +<em>Host</em> is one of the following: +<dl> +<dt><code>all</code> +<dd>all hosts are denied access +<dt>A (partial) domain-name +<dd>host whose name is, or ends in, this string are denied access. +<dt>A full IP address +<dd>An IP address of a host denied access +<dt>A partial IP address +<dd>The first 1 to 3 bytes of an IP address, for subnet restriction. +</dl> + +Example:<blockquote><code>deny from 16</code></blockquote> +All hosts in the specified network are denied access.<p> + +Note that this compares whole components; <code>bar.edu</code> +would not match <code>foobar.edu</code>.<p> + +See also <A HREF="#allow">allow</A> and <A HREF="#order">order</A>.<p> + +<a name="denyfromenv"><strong>Syntax:</strong> deny from env=<em>variablename</em></a><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> Limit<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_access<br> +<strong>Compatibility:</strong> Apache 1.2 and above<p> + +The deny from env directive controls access to a directory by the +existence (or non-existence) of an environment variable. + +Example:<blockquote><pre> +BrowserMatch ^BadRobot/0.9 go_away +<Directory /docroot> +order deny,allow +deny from env=go_away +allow from all +</Directory> +</pre></blockquote> + +See also <A HREF="#allowfromenv">allow from env</A> +and <A HREF="#order">order</A>.<p><hr> + +<A name="order"><h2>order</h2></A> +<!--%plaintext <?INDEX {\tt order} directive> --> +<strong>Syntax:</strong> order <em>ordering</em><br> +<strong>Default:</strong> <code>order deny,allow</code><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> Limit<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_access<p> + +The order directive controls the order in which <A HREF="#allow">allow</A> and +<A HREF="#deny">deny</A> directives are evaluated. <em>Ordering</em> is one +of +<dl> +<dt>deny,allow +<dd>the deny directives are evaluated before the allow directives. (The +initial state is OK.) +<dt>allow,deny +<dd>the allow directives are evaluated before the deny directives. (The +initial state is FORBIDDEN.) +<dt>mutual-failure +<dd>Only those hosts which appear on the allow list and do not appear +on the deny list are granted access. (The initial state is irrelevant.) +</dl> + +Note that in all cases every <code>allow</code> and <code>deny</code> +statement is evaluated, there is no "short-circuiting". + +<p>Example: +<blockquote><code> +order deny,allow<br> +deny from all<br> +allow from .ncsa.uiuc.edu<br> +</code></blockquote> +Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are +denied access. + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html new file mode 100644 index 00000000000..686760abf26 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html @@ -0,0 +1,98 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Module mod_actions</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_actions</h1> + +This module is contained in the <code>mod_actions.c</code> file, and +is compiled in by default. It provides for +executing CGI scripts based on media type or request method. It is not +present in versions prior to Apache 1.1. + +<h2>Summary</h2> + +This module lets you run CGI scripts whenever a file of a certain type +is requested. This makes it much easier to execute scripts that +process files. + +<h2>Directives</h2> +<ul> +<li><A HREF="#action">Action</A> +<li><A HREF="#script">Script</A> +</ul> + +<hr> + +<A name="action"><h2>Action</h2></A> +<strong>Syntax:</strong> Action <em>mime-type cgi-script</em><br> +<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_actions<br> +<strong>Compatibility:</strong> Action is only available in Apache 1.1 +and later<p> + +This directive adds an action, which will activate <em>cgi-script</em> when +a file of content type <em>mime-type</em> is requested. It sends the +URL and file path of the requested document using the standard +CGI PATH_INFO and PATH_TRANSLATED environment variables. + +<hr> + +<A name="script"><h2>Script</h2></A> +<strong>Syntax:</strong> Script <em>method cgi-script</em><br> +<strong>Context:</strong> server config, virtual host, directory<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_actions<br> +<strong>Compatibility:</strong> Script is only available in Apache 1.1 +and later<p> + +<p>This directive adds an action, which will activate <em>cgi-script</em> when +a file is requested using the method of <em>method</em>, which can be +one of <code>GET</code>, <code>POST</code>, <code>PUT</code> or +<code>DELETE</code>. It sends the +URL and file path of the requested document using the standard +CGI PATH_INFO and PATH_TRANSLATED environment variables. + +<p>Note that the Script command defines default actions only. If a CGI +script is called, or some other resource that is capable of handling +the requested method internally, it will do so. Also note that script +with a method of <code>GET</code> will only be called if there are +query arguments present (e.g. foo.html?hi). Otherwise, the request +will proceed normally. + +<p>Examples: +<pre> + Script GET /cgi-bin/search #e.g. for <ISINDEX>-style searching + Script PUT /~bob/put.cgi + +</pre> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html new file mode 100644 index 00000000000..247cdc35ade --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html @@ -0,0 +1,159 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_alias</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Module mod_alias</h1> + +This module is contained in the <code>mod_alias.c</code> file, and +is compiled in by default. It provides for mapping different parts of the +host filesystem in the the document tree, and for URL redirection. + + +<menu> +<li><A HREF="#alias">Alias</A> +<li><A HREF="#redirect">Redirect</A> +<li><A HREF="#redirecttemp">RedirectTemp</A> +<li><A HREF="#redirectperm">RedirectPermanent</A> +<li><A HREF="#scriptalias">ScriptAlias</A> +</menu> +<hr> + + +<A name="alias"><h2>Alias</h2></A> +<!--%plaintext <?INDEX {\tt Alias} directive> --> +<strong>Syntax:</strong> Alias <em>url-path directory-filename</em><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_alias<br> + +The Alias directive allows documents to be stored in the local filesystem +other than under the <A HREF="core.html#documentroot">DocumentRoot</A>. +URLs with a (%-decoded) path beginning with <em>url-path</em> will be +mapped to local files beginning with <em>directory-filename</em>. +Example: +<blockquote><code>Alias /image /ftp/pub/image</code></blockquote> +A request for http://myserver/image/foo.gif would cause the server to +return the file /ftp/pub/image/foo.gif.<p> + +Note that if you include a trailing / on the <em>url-path</em> then the +server will require a trailing / in order to expand the alias. That is, +if you use <code>Alias /icons/ /usr/local/etc/httpd/icons/</code> then +the url <code>/icons</code> will not be aliased.<p> + +See also <A HREF="#scriptalias">ScriptAlias</A>.<p><hr> + +<A name="redirect"><h2>Redirect</h2></A> +<!--%plaintext <?INDEX {\tt Redirect} directive> --> +<strong>Syntax:</strong> Redirect [ <em>status</em> ] <em>url-path url</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_alias<br> +<strong>Compatibility:</strong> The directory and .htaccess context's +are only available in versions 1.1 and later. The <em>status</em> argument is only available in Apache 1.2 or later.<p> + +The Redirect directive maps an old URL into a new one. The new URL is returned +to the client which attempts to fetch it again with the new address. +<em>Url-path</em> a (%-decoded) path; any requests for documents beginning with +this path will be returned a redirect error to a new (%-encoded) url +beginning with <em>url</em>. Example: +<blockquote><code>Redirect /service +http://foo2.bar.com/service</code></blockquote> +If the client requests http://myserver/service/foo.txt, it will be told to +access http://foo2.bar.com/service/foo.txt instead.<p> + +Note: Redirect directives take precedence over Alias and ScriptAlias +directives, irrespective of their ordering in the configuration file. Also, +<em>Url-path</em> must be an absolute path, not a relative path, even when used with +.htaccess files or inside of <Directory> sections.<p> + +If no <em>status</em> argument is given, the redirect will be +"temporary" (HTTP status 302). This indicates to the client that the +resources is has moved temporarily. The <em>status</em> +argument can be used to return other HTTP status codes: +<dl> +<dt>permanent<dd>Returns a permanent redirect status (301) indicating that +the resource has moved permanently. +<dt>temp<dd>Returns a temporary redirect status (302). This is the +default. +<dt>seeother<dd>Returns a "See Other" status (303) indicating that +the resource has been replaced. +<dt>gone<dd>Returns a "Gone" status (410) indicating that the resource +has been permanently removed. When this status is used the <em>url</em> +argument should be omitted. +</dl> + +Other status codes can be returned by giving the numeric status code +as the value of <em>status</em>. If the status is between 300 and 399, +the <em>url</em> argument must be present, otherwise it must be +omitted. Note that the status must be known to the Apache code (see +the function <code>send_error_response</code> in http_protocol.c). + +<A name="redirecttemp"><h2>RedirectTemp</h2></A> +<!--%plaintext <?INDEX {\tt Redirect} directive> --> +<strong>Syntax:</strong> RedirectTemp <em>url-path url</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_alias<br> +<strong>Compatibility:</strong> This directive is only available in 1.2<P> + +This directive makes the client know that the Redirect is only +temporary. (Status 302). Exactly equivalent to <code>Redirect temporary </code><P> + +<A name="redirectperm"><h2>RedirectPermanent</h2></A> +<!--%plaintext <?INDEX {\tt Redirect} directive> --> +<strong>Syntax:</strong> RedirectPermanent <em>url-path url</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_alias<br> +<strong>Compatibility:</strong> This directive is only available in 1.2<P> + +This directive makes the client know that the Redirect is permanent. +(Status 301). Exactly equivalent to <code>Redirect permanent</code><P> + +<hr> +<A name="scriptalias"><h2>ScriptAlias</h2></A> +<!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> +<strong>Syntax:</strong> ScriptAlias <em>url-path directory-filename</em><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_alias<br> + +The ScriptAlias directive has the same behavior as the +<A HREF="#alias">Alias</A> directive, except that in addition it +marks the target directory as containing CGI scripts. +URLs with a (%-decoded) path beginning with <em>url-path</em> will be +mapped to scripts beginning with <em>directory-filename</em>. +Example: +<blockquote><code>ScriptAlias /cgi-bin/ /web/cgi-bin/</code></blockquote> +A request for http://myserver/cgi-bin/foo would cause the server to +run the script /web/cgi-bin/foo.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html b/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html new file mode 100644 index 00000000000..59a164c7b4b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_asis.html @@ -0,0 +1,81 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_asis</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Module mod_asis</h1> + +This module is contained in the <code>mod_asis.c</code> file, and +is compiled in by default. It provides for <code>.asis</code> files. Any +document with mime type <code>httpd/send-as-is</code> will be processed by +this module. +<!--%plaintext <?INDEX {\tt httpd/send-as-is} mime type> --> + +<h2>Purpose</h2> +To allow file types to be defined such that Apache sends them without +adding HTTP headers.<P> + +This can be used to send any kind of data from the server, including redirects +and other special HTTP responses, without requiring a cgi-script or an nph +script. +<h2>Usage</h2> +In the server configuration file, define a new mime type called +<code>httpd/send-as-is</code> e.g. +<blockquote><code>AddType httpd/send-as-is asis</code></blockquote> +this defines the <code>.asis</code> file extension as being of the new +<code>httpd/send-as-is</code> mime type. The contents of any file with a +<code>.asis</code> extension will then be sent by Apache to the client with +almost no changes. Clients will need HTTP headers to be attached, so do not +forget them. A Status: header is also required; the data should be the +3-digit HTTP response code, followed by a textual message.<p> + +Here's an example of a file whose contents are sent <em>as is</em> so as to +tell the client that a file has redirected. +<blockquote><code> +Status: 302 Now where did I leave that URL <br> +Location: http://xyz.abc.com/foo/bar.html <br> +Content-type: text/html <br> +<br> +<HTML> <br> +<HEAD> <br> +<TITLE>Lame excuses'R'us</TITLE> <br> +</HEAD> <br> +<BODY> <br> +<H1>Fred's exceptionally wonderful page has moved to <br> +<A HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> site. <br> +</H1> <br> +</BODY> <br> +</HTML> +</code></blockquote> +Notes: the server always adds a Date: and Server: header to the data returned +to the client, so these should not be included in the file. +The server does <em>not</em> add a Last-Modified header; it probably should. +<P> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html new file mode 100644 index 00000000000..9fa7c47159f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_auth.html @@ -0,0 +1,158 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_auth</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Module mod_auth</h1> + +This module is contained in the <code>mod_auth.c</code> file, and +is compiled in by default. It provides for user authentication using +textual files. + + +<menu> +<li><A HREF="#authgroupfile">AuthGroupFile</A> +<li><A HREF="#authuserfile">AuthUserFile</A> +<li><A HREF="#authauthoritative">AuthAuthoritative</A> +</menu> +<hr> + + +<A name="authgroupfile"><h2>AuthGroupFile</h2></A> +<!--%plaintext <?INDEX {\tt AuthGroupFile} directive> --> +<strong>Syntax:</strong> AuthGroupFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_auth<p> + +The AuthGroupFile directive sets the name of a textual file containing the list +of user groups for user authentication. <em>Filename</em> is the absolute path +to the group file.<p> +Each line of the group file contains a groupname followed by a colon, followed +by the member usernames separated by spaces. Example: +<blockquote><code>mygroup: bob joe anne</code></blockquote> +Note that searching large groups files is <em>very</em> inefficient; +<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> should +be used instead.<p> + +Security: make sure that the AuthGroupFile is stored outside the +document tree of the web-server; do <em>not</em> put it in the directory that +it protects. Otherwise, clients will be able to download the AuthGroupFile.<p> + +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authuserfile">AuthUserFile</A>.<p><hr> + +<A name="authuserfile"><h2>AuthUserFile</h2></A> +<!--%plaintext <?INDEX {\tt AuthUserFile} directive> --> +<strong>Syntax:</strong> AuthUserFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_auth<p> + +The AuthUserFile directive sets the name of a textual file containing +the list of users and passwords for user +authentication. <em>Filename</em> is the absolute path to the user +file.<p> Each line of the user file file contains a username followed +by a colon, followed by the crypt() encrypted password. The behavior +of multiple occurrences of the same user is undefined.<p> Note that +searching user groups files is inefficient; <A +HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> should be +used instead.<p> + +Security: make sure that the AuthUserFile is stored outside the +document tree of the web-server; do <em>not</em> put it in the directory that +it protects. Otherwise, clients will be able to download the AuthUserFile.<p> + +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authgroupfile">AuthGroupFile</A>.<p> +<hr> +<A name="authauthoritative"><h2>AuthAuthoritative</h2></A> +<!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> --> +<strong>Syntax:</strong> AuthAuthoritative < <strong> on</strong>(default) | off > <br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_auth<p> + +Setting the AuthAuthoritative directive explicitly to <b>'off'</b> +allows for both authentication and authorization to be passed on to +lower level modules (as defined in the <code>Configuration</code> and +<code>modules.c</code> files) if there is <b>no userID</b> or +<b>rule</b> matching the supplied userID. If there is a userID and/or +rule specified; the usual password and access checks will be applied +and a failure will give an Authorization Required reply. + +<p> + +So if a userID appears in the database of more than one module; or if +a valid require directive applies to more than one module; then the +first module will verify the credentials; and no access is passed on; +regardless of the AuthAuthoritative setting. + +<p> + +A common use for this is in conjunction with one of the database +modules; such as <a +href="mod_auth_db.html"><code>mod_auth_db.c</code></a>, <a +href="mod_auth_dbm.html"><code>mod_auth_dbm.c</code></a>, <a +href="mod_auth_msql.html"><code>mod_auth_msql.c</code></a> and <a +href="mod_auth_anon.html"><code>mod_auth_anon.c</code></a>. These modules +supply the bulk of the user credential checking; but a few +(administrator) related accesses fall through to a lower level with a +well protected AuthUserFile. + +<p> + +<b>Default:</b> By default; control is not passed on; and an unknown +userID or rule will result in an Authorization Required reply. Not +setting it thus keeps the system secure; and forces an NSCA compliant +behaviour. + +<p> + +Security: Do consider the implications of allowing a user to allow +fall-through in his .htaccess file; and verify that this is really +what you want; Generally it is easier to just secure a single +.htpasswd file, than it is to secure a database such as mSQL. Make +sure that the AuthUserFile is stored outside the document tree of the +web-server; do <em>not</em> put it in the directory that it +protects. Otherwise, clients will be able to download the +AuthUserFile. + +<p> +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authgroupfile">AuthGroupFile</A>.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth_anon.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_anon.html new file mode 100644 index 00000000000..b9ee13bcba6 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_anon.html @@ -0,0 +1,262 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_auth_anon.c</TITLE> +</HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_auth_anon</H1> + +This module is contained in the <code>mod_auth_anon.c</code> file and +is not compiled in by default. It is only available in Apache 1.1 and +later. It allows "anonymous" user access to authenticated areas. + +<h2>Summary</h2> + +It does access control in a manner similar to anonymous-ftp sites; i.e. +have a 'magic' user id 'anonymous' and the email address as a password. +These email addresses can be logged. +<p> +Combined with other (database) access control methods, this allows for +effective user tracking and customization according to a user profile +while still keeping the site open for 'unregistered' users. One advantage +of using Auth-based user tracking is that, unlike magic-cookies and +funny URL pre/postfixes, it is completely browser independent and it +allows users to share URLs. +<p> + +<a href="#Directives">Directives</a> / +<a href="#Example">Example</a> / +<a href="#CompileTimeOptions">Compile time options</a> / +<a href="#RevisionHistory">RevisionHistory</a> / +<a href="#Person">Person to blame</a> / +<a href="#Sourcecode">Sourcecode</a> +<p> + +<h2><a name="Directives">Directives</a></h2> +<ul> +<li><A HREF="#anonymous">Anonymous</A> +<li><A HREF="#Authoritative">Anonymous_Authoritative</A> +<li><A HREF="#LogEmail">Anonymous_LogEmail</A> +<li><A HREF="#MustGiveEmail">Anonymous_MustGiveEmail</A> +<li><A HREF="#NoUserID">Anonymous_NoUserID</A> +<li><A HREF="#VerifyEmail">Anonymous_VerifyEmail</A> +</ul> + +<hr> + +<A name="anonymous"><h2>Anonymous</h2></a> +<!--%plaintext <?INDEX {\tt Anonymous} directive> --> +<strong>Syntax:</strong> Anonymous <em>user user ...</em><br> +<strong>Default:</strong> none<br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_anon<p> + + A list of one or more 'magic' userIDs which are allowed access + without password verification. The userIDs are space separated. + It is possible to use the ' and " quotes to allow a space in + a userID as well as the \ escape character. + <p> + Please note that the comparison is <b>case-IN-sensitive</b>. + <br> + I strongly suggest that the magic username '<code>anonymous</code>' + is always one of the allowed userIDs. + <p> + Example:<br> + <code> + Anonymous: anonymous "Not Registered" 'I don\'t know' + </code><p> + This would allow the user to enter without password verification + by using the userId's 'anonymous', 'AnonyMous','Not Registered' and + 'I Don't Know'. +<HR> + +<A name="Authoritative"><h2>Anonymous_Authoritative</h2></A> +<strong>Syntax:</strong> Anonymous_Authoritative <em>on | off</em><br> +<strong>Default:</strong> <code>Anonymous_Authoritative off</code><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_anon<p> + + When set 'on', there is no + fall-through to other authorization methods. So if a + userID does not match the values specified in the + <code>Anonymous</code> directive, access is denied. + <p> + Be sure you know what you are doing when you decide to switch + it on. And remember that it is the linking order of the modules + (in the Configuration / Make file) which details the order + in which the Authorization modules are queried. +<hr> + +<A name="LogEmail"><h2>Anonymous_LogEmail</h2></A> +<strong>Syntax:</strong> Anonymous_LogEmail <em>on | off</em><br> +<strong>Default:</strong> <code>off</code><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_anon<p> + + When set 'on', the default, the 'password' entered (which hopefully + contains a sensible email address) is logged in the httpd-log file. +<hr> + +<A name="MustGiveEmail"><h2>Anonymous_MustGiveEmail</h2></a> +<!--%plaintext <?INDEX {\tt Anonymous_MustGiveEmail} directive> --> +<strong>Syntax:</strong> Anonymous_MustGiveEmail <em>on</em> | <em>off</em><br> +<strong>Default:</strong> off<br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_anon<p> + + Specifies whether the user must specify an email + address as the password. This prohibits blank passwords. +<HR> + +<A name="NoUserID"><h2>Anonymous_NoUserID</h2></A> +<strong>Syntax:</strong> Anonymous_NoUserID <em>on | off</em><br> +<strong>Default:</strong> <code>Anonymous_NoUserID off</code><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_anon<p> + + When set 'on', users can leave + the userID (and perhaps the password field) empty. This + can be very convenient for MS-Explorer users who can + just hit return or click directly on the OK button; which + seems a natural reaction. + +<hr> + +<A name="VerifyEmail"><h2>Anonymous_VerifyEmail</h2></A> +<strong>Syntax:</strong> Anonymous <em>on | off</em><br> +<strong>Default:</strong> <code>Anonymous_VerifyEmail off</code><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_anon<p> + + When set 'on' the 'password' entered is + checked for at least one '@' and a '.' to encourage users to enter + valid email addresses (see the above <code>Auth_LogEmail</code>). + +<hr><a name="Example"><h2>Example</h2></a> + +The example below (when combined with the Auth directives +of a htpasswd-file based (or GDM, mSQL etc) base access +control system allows users in as 'guests' with the +following properties: +<ul> +<li> +It insists that the user enters a userId. (<code>Anonymous_NoUserId</code>) +<li> +It insists that the user enters a password. (<code>Anonymous_MustGiveEmail</code>) +<li> +The password entered must be a valid email address, ie. contain at least one '@' and a '.'. +(<code>Anonymous_VerifyEmail</code>) +<li> +The userID must be one of <code>anonymous guest www test welcome</code> +and comparison is <b>not</b> case sensitive. +<code><directory /web/docs/public></code> +<li> +And the Email addresses entered in the passswd field are logged to +the httpd-log file +(<code>Anonymous_LogEmail</code>) +</ul> +<p> +Excerpt of access.conf: +<dl> +<dt><code> +Anonymous anonymous guest www test welcome<p> +Anonymous_MustGiveEmail on<br> +Anonymous_VerifyEmail on<br> +Anonymous_NoUserId off<br> +Anonymous_LogEmail on<br> +<p> +AuthName Use 'anonymous' & Email address for guest entry<br> +AuthType basic<p> + +</code></dt> +<dd> + Normal Apache/NCSA tokens for access control + <p> + <code><limit get post head></code><br> + <code>order deny,allow </code><br> + <code>allow from all </code><br> + <p> + <code>require valid-user </code><br> + <code><limit> </code><br> +</dd> +</dl> + + +<hr><h2><a name="CompileTimeOptions">Compile Time Options</a></h2> + +Currently there are no Compile options. + +<hr><h2><a name="RevisionHistory">Revision History</a></h2> + +This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. + +<dl> + +<dt>Version 0.4<br></dt> + <dd>First release + </dd> +<dt>Version 0.5<br></dt> + <dd>Added 'VerifyEmail' and 'LogEmail' options. Multiple + 'anonymous' tokens allowed. more docs. Added Authoritative + functionality. + </dd> +</dl> + + +<hr><h2><a name="Person">Contact/person to blame</a></h2> + +This module was written for the +<a href="http://ewse.ceo.org">European Wide Service Exchange</a> by +<<a href="mailto:Dirk.vanGulik@jrc.it"><code>Dirk.vanGulik@jrc.it</code></a>>. +Feel free to contact me if you have any problems, ice-creams or bugs. This +documentation, courtesy of Nick Himba, <a href="mailto:himba@cs.utwente.nl"> +<code><himba@cs.utwente.nl></code></a>. +<p> + + +<hr><h2><a NAME="Sourcecode">Sourcecode</a></h2> + +The source code can be found at <a href="http://www.apache.org"><code> +http://www.apache.org</code></a>. A snapshot of a development version +usually resides at <a href="http://me-www.jrc.it/~dirkx/mod_auth_anon.c"><code> +http://me-www.jrc.it/~dirkx/mod_auth_anon.c</code></a>. Please make sure +that you always quote the version you use when filing a bug report. +<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</body> +</html> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth_db.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_db.html new file mode 100644 index 00000000000..2140aa4bcc0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_db.html @@ -0,0 +1,173 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_auth_db</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_auth_db</h1> + +This module is contained in the <code>mod_auth_db.c</code> file, and +is not compiled in by default. It provides for user authentication using +Berkeley DB files. It is an alternative to <A HREF="mod_auth_dbm.html">DBM</A> +files for those systems which support DB and not DBM. It is only +available in Apache 1.1 and later. + + +<menu> +<li><A HREF="#authdbgroupfile">AuthDBGroupFile</A> +<li><A HREF="#authdbuserfile">AuthDBUserFile</A> +<li><A HREF="#authdbauthoritative">AuthDBAuthoritative</A> +</menu> +<hr> + + +<A name="authdbgroupfile"><h2>AuthDBGroupFile</h2></A> +<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> --> +<strong>Syntax:</strong> AuthDBGroupFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_db<p> + +The AuthDBGroupFile directive sets the name of a DB file containing the list +of user groups for user authentication. <em>Filename</em> is the absolute path +to the group file.<p> + +The group file is keyed on the username. The value for a user is a +comma-separated list of the groups to which the users belongs. There must +be no whitespace within the value, and it must never contain any colons.<p> + +Security: make sure that the AuthDBGroupFile is stored outside the +document tree of the web-server; do <em>not</em> put it in the directory that +it protects. Otherwise, clients will be able to download the +AuthDBGroupFile unless otherwise protected.<p> + +Combining Group and Password DB files: In some cases it is easier to +manage a single database which contains both the password and group +details for each user. This simplifies any support programs that need +to be written: they now only have to deal with writing to and locking +a single DBM file. This can be accomplished by first setting the group +and password files to point to the same DB file:<p> + +<blockquote><code> +AuthDBGroupFile /www/userbase<br> +AuthDBUserFile /www/userbase +</code></blockquote> + +The key for the single DB record is the username. The value consists of <p> + +<blockquote><code> +Unix Crypt-ed Password : List of Groups [ : (ignored) ] +</code></blockquote> + +The password section contains the Unix crypt() password as before. This is +followed by a colon and the comma separated list of groups. Other data may +optionally be left in the DB file after another colon; it is ignored by the +authentication module. <p> + +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authdbuserfile">AuthDBUserFile</A>.<p><hr> + +<A name="authdbuserfile"><h2>AuthDBUserFile</h2></A> +<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> --> +<strong>Syntax:</strong> AuthDBUserFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_db<p> + +The AuthDBUserFile directive sets the name of a DB file containing the list +of users and passwords for user authentication. <em>Filename</em> is the +absolute path to the user file.<p> + +The user file is keyed on the username. The value for a user is the +crypt() encrypted password, optionally followed by a colon and +arbitrary data. The colon and the data following it will be ignored +by the server.<p> + +Security: make sure that the AuthDBUserFile is stored outside the +document tree of the web-server; do <em>not</em> put it in the directory that +it protects. Otherwise, clients will be able to download the +AuthDBUserFile.<p> + +Important compatibility note: The implementation of "dbmopen" in the +apache modules reads the string length of the hashed values from the +DB data structures, rather than relying upon the string being +NULL-appended. Some applications, such as the Netscape web server, +rely upon the string being NULL-appended, so if you are having trouble +using DB files interchangeably between applications this may be a +part of the problem. <p> + +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p> +<hr> +<A name="authdbauthoritative"><h2>AuthDBAuthoritative</h2></A> +<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> --> +<strong>Syntax:</strong> AuthDBAuthoritative < <strong> on</strong>(default) | off > <br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_auth<p> + +Setting the AuthDBAuthoritative directive explicitly to <b>'off'</b> +allows for both authentication and authorization to be passed on +to lower level modules (as defined in the <code>Configuration</code> +and <code>modules.c</code> file if there is <b>no userID</b> or +<b>rule</b> matching the supplied userID. If there is a userID +and/or rule specified; the usual password and access checks will +be applied and a failure will give an Authorization Required reply. +<p> +So if a userID appears in the database of more than one module; or +if a valid require directive applies to more than one module; then +the first module will verify the credentials; and no access is +passed on; regardless of the AuthAuthoritative setting. <p> + +A common use for this is in conjunction with one of the basic auth +modules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>. +Whereas this DB module supplies the bulk of the user credential +checking; a few (administrator) related accesses fall through to +a lower level with a well protected .htpasswd file. <p> + +<b>Default:</b> By default; control is not passed on; and an unknown +userID or rule will result in an Authorization Required reply. Not +setting it thus keeps the system secure; and forces an NSCA compliant +behaviour. <p> +Security: Do consider the implications of allowing a user to allow +fall-through in his .htaccess file; and verify that this is really +what you want; Generally it is easier to just secure a single +.htpasswd file, than it is to secure a database which might have +more access interfaces. + +<p> +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth_dbm.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_dbm.html new file mode 100644 index 00000000000..7098d3ead3e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_dbm.html @@ -0,0 +1,175 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_auth_dbm</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Module mod_auth_dbm</h1> + +This module is contained in the <code>mod_auth_dbm.c</code> file, and +is not compiled in by default. It provides for user authentication using +DBM files. + + +<menu> +<li><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A> +<li><A HREF="#authdbmuserfile">AuthDBMUserFile</A> +<li><A HREF="#authdbmauthoritative">AuthDBMAuthoritative</A> +</menu> +<hr> + + +<A name="authdbmgroupfile"><h2>AuthDbmGroupFile</h2></A> +<!--%plaintext <?INDEX {\tt AuthDbmGroupFile} directive> --> +<strong>Syntax:</strong> AuthDBMGroupFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_dbm<p> + +The AuthDBMGroupFile directive sets the name of a DBM file containing the list +of user groups for user authentication. <em>Filename</em> is the absolute path +to the group file.<p> + +The group file is keyed on the username. The value for a user is a +comma-separated list of the groups to which the users belongs. There must +be no whitespace within the value, and it must never contain any colons.<p> + +Security: make sure that the AuthDBMGroupFile is stored outside the +document tree of the web-server; do <em>not</em> put it in the directory that +it protects. Otherwise, clients will be able to download the +AuthDBMGroupFile unless otherwise protected.<p> + +Combining Group and Password DBM files: In some cases it is easier to +manage a single database which contains both the password and group +details for each user. This simplifies any support programs that need +to be written: they now only have to deal with writing to and locking +a single DBM file. This can be accomplished by first setting the group +and password files to point to the same DBM:<p> + +<blockquote><code> +AuthDBMGroupFile /www/userbase<br> +AuthDBMUserFile /www/userbase +</code></blockquote> + +The key for the single DBM is the username. The value consists of <p> + +<blockquote><code> +Unix Crypt-ed Password : List of Groups [ : (ignored) ] +</code></blockquote> + +The password section contains the Unix crypt() password as before. This is +followed by a colon and the comma separated list of groups. Other data may +optionally be left in the DBM file after another colon; it is ignored by the +authentication module. This is what www.telescope.org uses for its combined +password and group database. <p> + +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authdbmuserfile">AuthDBMUserFile</A>.<p><hr> + +<A name="authdbmuserfile"><h2>AuthDBMUserFile</h2></A> +<!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> --> +<strong>Syntax:</strong> AuthDBMUserFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_auth_dbm<p> + +The AuthDBMUserFile directive sets the name of a DBM file containing the list +of users and passwords for user authentication. <em>Filename</em> is the +absolute path to the user file.<p> + +The user file is keyed on the username. The value for a user is the +crypt() encrypted password, optionally followed by a colon and +arbitrary data. The colon and the data following it will be ignored +by the server.<p> + +Security: make sure that the AuthDBMUserFile is stored outside the +document tree of the web-server; do <em>not</em> put it in the directory that +it protects. Otherwise, clients will be able to download the +AuthDBMUserFile.<p> + +Important compatibility note: The implementation of "dbmopen" in the +apache modules reads the string length of the hashed values from the +DBM data structures, rather than relying upon the string being +NULL-appended. Some applications, such as the Netscape web server, +rely upon the string being NULL-appended, so if you are having trouble +using DBM files interchangeably between applications this may be a +part of the problem. <p> + +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<p> + +<hr> +<A name="authdbmauthoritative"><h2>AuthDBMAuthoritative</h2></A> +<!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> --> +<strong>Syntax:</strong> AuthDBMAuthoritative < <strong> on</strong>(default) | off > <br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_auth<p> + +Setting the AuthDBMAuthoritative directive explicitly to <b>'off'</b> +allows for both authentication and authorization to be passed on +to lower level modules (as defined in the <code>Configuration</code> +and <code>modules.c</code> file if there is <b>no userID</b> or +<b>rule</b> matching the supplied userID. If there is a userID +and/or rule specified; the usual password and access checks will +be applied and a failure will give an Authorization Required reply. +<p> +So if a userID appears in the database of more than one module; or +if a valid require directive applies to more than one module; then +the first module will verify the credentials; and no access is +passed on; regardless of the AuthAuthoritative setting. <p> + +A common use for this is in conjunction with one of the basic auth +modules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>. +Whereas this DBM module supplies the bulk of the user credential +checking; a few (administrator) related accesses fall through to +a lower level with a well protected .htpasswd file. <p> + +<b>Default:</b> By default; control is not passed on; and an unknown +userID or rule will result in an Authorization Required reply. Not +setting it thus keeps the system secure; and forces an NSCA compliant +behaviour. <p> + +Security: Do consider the implications of allowing a user to allow +fall-through in his .htaccess file; and verify that this is really +what you want; Generally it is easier to just secure a single +.htpasswd file, than it is to secure a database which might have +more access interfaces. + +<p> +See also <A HREF="core.html#authname">AuthName</A>, +<A HREF="core.html#authtype">AuthType</A> and +<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_auth_msql.html b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_msql.html new file mode 100644 index 00000000000..9e85f5d2cdd --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_auth_msql.html @@ -0,0 +1,488 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Module mod_auth_msql</title> +</head> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_auth_msql</H1> + +This module is contained in the <code>mod_auth_msql.c</code> file and +is compiled in by default. It allows access control using the public +domain mSQL database <code><a +href="ftp://ftp.bond.edu.au/pub/Minerva/msql">ftp://ftp.bond.edu.au/pub/Minerva/msql</a></code>, +a fast but limited SQL engine which can be contacted over an internal +Unix domain protocol as well as over normal TCP/IP socket +communication. It is only available in Apache 1.1 and later. <p> + +<a href="#FullDescription">Full description</a> / +<a href="#Example">Example</a> / +<a href="#CompileTimeOptions">Compile time options</a> / +<a href="#RevisionHistory">RevisionHistory</a> / +<a href="#Person">Person to blame</a> / +<a href="#Sourcecode">Sourcecode</a> +<p> + +<hr><h2><a name="FullDescription">Full description of all tokens</a></h2> +<dl> + +<code><dt> +Auth_MSQLhost < FQHN | IP Address | localhost > +</dt></code><dd> + Hostname of the machine running the mSQL demon. The effective uid + of the server should be allowed access. If not given, or if it is + the magic name <code>localhost</code>, it is passed to the mSQL library as a null + pointer. This effectively forces it to use /dev/msql rather than the + (slower) socket communication. +</dd> + +<code><dt> +Auth_MSQLdatabase < mSQL database name > +</dt></code><dd> + Name of the database in which the following table(s) are contained (Quick check: use the + mSQL command <code>relshow [<hostname> dbase]</code> to verify the spelling of the + database name). +</dd> + +<code><dt> +Auth_MSQLpwd_table < mSQL table name > +</dt></code><dd> + Contains at least the fields with the username + and the (encrypted) password. Each uid should only occur once in this table and + for performance reasons should be a primary key. + Normally this table is compulsory, but it is + possible to use a fall-through to other methods + and use the mSQL module for group control only. + See the <a href="#Authoritative"><code>Auth_MSQL_Authoritative</code></a> + directive below. +</dd> + +<code><dt> +Auth_MSQLgrp_table < mSQL table name in the above database > +</dt></code><dd> + Contains at least the fields with the + username and the groupname. A user which + is in multiple groups has therefore + multiple entries. There might be some performance + problems associated with this and one + might consider to have separate tables for each + group (rather than all groups in one table) if + your directory structure allows for it. + One only need to specify this table when doing + group control. +</dd> + +<code><dt> +Auth_MSQLuid_field < mSQL field name > +</dt></code><dd> + Name of the field containing the username in the <code> + Auth_MSQLpwd_table</code> and optionally in the <code> + Auth_MSQLgrp_table</code> tables. +</dd> + +<code><dt> +Auth_MSQLpwd_field < mSQL field name > +</dt></code><dd> + Fieldname for the passwords in the <code> + Auth_MSQLpwd_table</code> table. +</dd> + +<code><dt> +Auth_MSQLgrp_field < mSQL field name > +</dt></code><dd> + Fieldname for the groupname<br> + Only the fields used need to be specified. When this + module is compiled with the + <a href="#VITEK"><code>BACKWARD_VITEK</code></a> option then + the uid and pwd field names default to 'user' and 'password'. + However you are strongly encouraged to always specify these values + explicitly given the security issues involved. +</dd> + +<code><dt> +Auth_MSQL_nopasswd < on | off > +</dt></code><dd> + Skip password comparison if passwd field is + empty, i.e. allow any password. This is 'off' + by default to ensure that an empty field + in the mSQL table does not allow people in by + default with a random password. +</dd> + +<code><dt> +<a name="Authoritative">Auth_MSQL_Authoritative < on | off ></a> +</dt></code><dd> + Default is 'on'. When set 'on', there is no + fall-through to other authorization methods. So if a + user is not in the mSQL dbase table (and perhaps + not in the right group) or has the password wrong, then + he or she is denied access. When this directive is set to + 'off', control is passed on to any other authorization + modules, such as the basic auth module with the htpasswd + file or the Unix-(g)dbm modules. The default is 'on' + to avoid nasty 'fall-through' surprises. Be sure you + know what you are doing when you decide to switch it off. +</dd> + +<code><dt> +Auth_MSQL_EncryptedPasswords < on | off > +</dt></code><dd> + Default is 'on'. When set on, the values in the + pwd_field are assumed to be crypt-ed using *your* + machines 'crypt()' function and the incoming password + is 'crypt'ed before comparison. When this function is + 'off', the comparison is done directly with the plaintext + entered password. (Yes, http-basic-auth does send the + password as plaintext over the wire :-( ). The default + is a sensible 'on', and I personally think that it is + a *very-bad-idea* to change this. However a multi + vendor or international environment (which sometimes + leads to different crypts functions) might force you to. +</dd> +</dl> + + +<hr><h2><a name="Example">Example</a></h2> + +An example mSQL table could be created with the following commands: +<pre> + % msqladmin create www <br> + % msql www <br> + -> create table user_records ( <br> + -> User_id char(32) primary key, <br> + -> Cpasswd char(32), <br> + -> Xgroup char(32) <br> + -> ) \g <br> + query OK <br> + -> \q <br> + % <br> +</pre><br> + +The <code>User_id</code> can be as long as desired. However some of the +popular web browsers truncate names at or stop the user from entering +names longer than 32 characters. Furthermore the 'crypt' function +on your platform might impose further limits. Also use of +the <code>require users uid [uid..]</code> directive in the +<code>access.conf</code> file where the uid's are separated by +spaces can possibly prohibit the use of spaces in your usernames. +Also, please note the <a href="#MAX_FIELD_LEN"><code>MAX_FIELD_LEN</code></a> +directive somewhere below. +<p> +To use the above, the following example could be in your +<code>access.conf</code> file. Also there is a more elaborate description +below this example. +<p> + +<code><directory /web/docs/private></code> +<p> + +<dl> +<dt><code> +Auth_MSQLhost localhost<br> +</code></dt> + <blockquote>or</blockquote> +<dt><code> +Auth_MSQLhost datab.machine.your.org +</code></dt><dd> + If this directive is omitted or set to <code>localhost</code>, + it is assumed that Apache and the mSQL + database run on the same (physical) machine and the faster + /dev/msql communication channel will be used. Otherwise, + it is the machine to contact by TCP/IP. Consult the mSQL + documentation for more information. +</dd> +<p> + +<dt><code> +Auth_MSQLdatabase www +</code></dt><dd> + The name of the database on the above machine, + which contains *both* the tables for group and + for user/passwords. Currently it is not possible + to have these split over two databases. Make + sure that the <code>msql.acl</code> (access control file) of + mSQL does indeed allow the effective uid of the + web server read access to this database. Check the + httpd.conf file for this uid. +</dd> + +<code><dt> +Auth_MSQLpwd_table user_records +</dt></code><dd> + This is the table which contain the uid/password combination + is specified. +</dd> + +<code><dt> +Auth_MSQLuid_field User_id <br> +Auth_MSQLpwd_field Cpasswd +</dt></code><dd> + These two directive specify the field names in the <code>user_record</code> + table. If this module is compiled with the <a href="#VITEK"><code>BACKWARD_VITEK</code></a> + compatibility switch, the defaults <code>user</code> and <code>password</code> are + assumed if you do not specify them. Currently the user_id field + *MUST* be a primary key or one must ensure that each user only + occurs <b>once</b> in the table. If a uid occurs twice access is + denied by default; but see the <code><a href="#ONLY_ONCE">ONLY_ONCE</a></code> + compiler directive for more information. +</dd> + +<code><dt> +Auth_MSQLgrp_table user_records <br> +Auth_MSQLgrp_field Xgroup <br> +</dt></code><dd> + Optionally one can also specify a table which contains the + user/group combinations. This can be the same table which + also contains the username/password combinations. However + if a user belongs to two or more groups, one will have to + use a different table with multiple entries. +</dd> + +<code><dt> +Auth_MSQL_nopasswd off <br> +Auth_MSQL_Authoritative on <br> +Auth_MSQL_EncryptedPasswords on <br> +</dt></code><dd> + These three optional fields (all set to the sensible defaults, + so you really do not have to enter them) are described in more + detail below. If you choose to set these to any other values then + the above, be very sure you understand the security implications and + do verify that Apache does what you expect it to do. +</dd> + +<code><dt> +AuthName example mSQL realm <br> +AuthType basic +</dt></code> +<dd> + Normal Apache/NCSA tokens for access control + <p> + <code><limit get post head></code><br> + <code>order deny,allow </code><br> + <code>allow from all </code><br> + <p> + <code>require valid-user </code><br> + <ul><li><code>valid-user</code>; allow in any user which has a valid uid/passwd + pair in the above pwd_table. + </ul> + or<br> + <code>require user smith jones </code><br> + <ul><li>Limit access to users who have a valid uid/passwd pair in the + above pwd_table *and* whose uid is 'smith' or 'jones'. Do note that + the uid's are separated by 'spaces' for historic (NCSA) reasons. + So allowing uids with spaces might cause problems. + </ul> + <code>require group has_paid</code><br> + <ul><li>Optionally also ensure that the uid has the value 'has_paid' in + the group field in the group table. + </ul> + <code><limit> </code><br> +</dd> +</dl> + + +<hr><h2><a name="CompileTimeOptions">Compile Time Options</a></h2> + +<dl> +<dt><code> +<a name="ONLY_ONCE">#define ONLY_ONCE 1</a> +</code></dt><dd> + If the mSQL table containing the uid/passwd combination does + not have the uid field as a primary key, it is possible for the + uid to occur more than once in the table with possibly different + passwords. When this module is compiled with the <code>ONLY_ONCE</code> + directive set, access is denied if the uid occurs more than once in the + uid/passwd table. If you choose not to set it, the software takes + the first pair returned and ignores any further pairs. The SQL + statement used for this is<br> + <p><code>"select password form pwd_table where user='UID'"</code><p> + this might lead to unpredictable results. For this reason as well + as for performance reasons you are strongly advised to make the + uid field a primary key. Use at your own peril :-) +</dd> + +<dt><code> +<a name="KEEP_MSQL_CONNECTION_OPEN">#define KEEP_MSQL_CONNECTION_OPEN</a> +</code></dt><dd> + Normally the (TCP/IP) connection with the database is opened and + closed for each SQL query. When the Apache web-server and the database + are on the same machine, and /dev/msql is used this does not + cause a serious overhead. However when your platform does not + support this (see the mSQL documentation) or when the web server + and the database are on different machines the overhead can be + considerable. When the above directive is set defined the server leaves + the connection open, i.e. no call to <code>msqlClose()</code>. + If an error occurs an attempt is made to reopen the connection for + the next http request. + <p> + This has a number of very serious drawbacks + <ul><li> It costs 2 already rare file-descriptors for each child. + <li> It costs msql-connections, typically one per child. The (compiled in) + number of connections mSQL can handle is low, typically 6 or 12. + which might prohibit access to the mSQL database for later + processes. + <li> When a child dies, it might not free that connection properly + or quick enough. + <li> When errors start to occur, connection/file-descriptor resources + might become exhausted very quickly. + </ul> + <p> + In short, use this at your own peril and only in a highly controlled and + monitored environment. +</dd> + +<dt><code> +<a name="VITEK"> +#define BACKWARD_VITEK<br></a> +#define VITEK_uid_name "user"<br> +#define VITEK_gid_name "passwd" +</code></dt><dd> + A second mSQL auth module for Apache has also been developed by Vivek Khera + <<a href="mailto:khera@kciLink.com"><code>khera@kciLink.com</code></a>> + and was subsequently distributed with some early versions of Apache. It + can be obtained from + <code><a href="ftp://ftp.kcilink.com/pub/">ftp://ftp.kcilink.com/pub/mod_auth_msql.c*</a></code>. + Older 'vitek' versions had the field/table names compiled in. Newer + versions, v.1.11 have more <code>access.conf</code> configuration + options. However these where chosen not to be in line the 'ewse' + version of this module. Also, the 'vitek' module does not give group + control or 'empty' password control. + <p> + To get things slightly more in line this version (0.9) should + be backward compatible with the 'vitek' module by: + <ul><li> Adding support for the <code>Auth_MSQL_EncryptedPasswords</code> on/off functionality + <li> Adding support for the different spelling of the 4 configuration + tokens for user-table-name, user/password-field-name and dbase-name. + <li> Setting some field names to a default which used to be hard + coded in in older 'vitek' modules. + </ul> + <p> + If this troubles you, remove the 'BACKWARD_VITEK' define. +</dd> + +<dt><code> +<a name="MAX_FIELD_LEN"> +#define MAX_FIELD_LEN (64)<br> +#define MAX_QUERY_LEN (32+24+MAX_FIELD_LEN*2+3*MSQL_FIELD_NAME_LEN+1*MSQL_TABLE_NAME_LEN)<br></a> +</code></dt><dd> + In order to avoid using the very large <code>HUGE_STRING_LENGTH</code>, the above two compile + time directives are supplies. The <code>MAX_FIELD_LEN</code> contains the maximum number of + characters in your user, password and group fields. The maximum query length is derived + from those values. + <p> + We only do the following two queries: + <ul><li>For the user/passwd combination + <p><code>"select PWDFIELD from PWDTABLE where USERFIELD='UID'"</code><br> + <li>Optionally for the user/group combination: + <p><code>"select GROUPFIELD from GROUPTABLE where USERFIELD='UID' and GROUPFIELD='GID'"</code><br> + </ul> + <p> + This leads to the above limit for the query string. We are ignoring escaping a wee bit here + assuming not more than 24 escapes.) +</dd> +</dl> + + +<hr><h2><a name="RevisionHistory">Revision History</a></h2> + +This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. + +<dl> + +<dt>Version 0.0<br></dt> + <dd>First release + </dd> +<dt>Version 0.1<br></dt> + <dd>Update to Apache 1.00 + </dd> +<dt>Version 0.2<br></dt> + <dd>Added lines which got missing God knows when + and which did the valid-user authentication no good at all ! + </dd> +<dt>Version 0.3<br></dt> + <dd>Added '<code>Auth_MSQL_nopasswd</code>' option + </dd> +<dt>Version 0.4<br></dt> + <dd>Cleaned out the error messages mess. + </dd> +<dt>Version 0.6<br></dt> + <dd>Inconsistency with gid/grp in comment/token/source + Make sure you really use '<code>Auth_MSQLgrp_field</code>' + as indicated above. + </dd> +<dt>Version 0.7<br></dt> + <dd><code>*host</code> to <code>host</code> fixed. Credits + go to Rob Stout, <stout@lava.et.tudelft.nl> for + spotting this one. + </dd> +<dt>Version 0.8<br></dt> + <dd>Authoritative directive added. See above. + </dd> +<dt>Version 0.9<br></dt> + <dd><code>palloc</code> return code check(s), should be + backward compatible with 1.11 version of Vivek Khera + <khera@kciLink.com> msql + module, fixed broken err msg in group control, changed + command table messages to make more sense when displayed + in that new module management tool. Added + <code>Auth_MSQL_EncryptedPasswords</code> on/off functionality. + msqlClose() statements added upon error. Support for + persistent connections with the mSQL database (riscy). + Escaping of ' and \. Replaced some + <code>MAX_STRING_LENGTH</code> claims. + </dd> +</dl> + + +<hr><h2><a name="Person">Contact/person to blame</a></h2> + +This module was written for the +<a href="http://ewse.ceo.org">European Wide Service Exchange</a> by +<<a href="mailto:Dirk.vanGulik@jrc.it"><code>Dirk.vanGulik@jrc.it</code></a>>. +Feel free to contact me if you have any problems, ice-creams or bugs. This +documentation, courtesy of Nick Himba, <a href="mailto:himba@cs.utwente.nl"> +<code><himba@cs.utwente.nl></code></a>. +<p> + + +<hr><h2><a NAME="Sourcecode">Sourcecode</a></h2> + +The source code can be found at <a href="http://www.apache.org"><code> +http://www.apache.org</code></a>. A snapshot of a development version +usually resides at <a href="http://me-www.jrc.it/~dirkx/mod_auth_msql.c"><code> +http://me-www.jrc.it/~dirkx/mod_auth_msql.c</code></a>. Please make sure +that you always quote the version you use when filing a bug report. +<p> +Furthermore a test/demonstration suite (which assumes that you have +both mSQL and Apache compiled and installed) is available at the contrib +section of <a href="ftp://ftp.apache.org/apache/dist/contrib"><code> +ftp://ftp.apache.org/apache/dist/contrib</code></a> or +<a href="http://me-www.jrc.it/~dirkx/apache-msql-demo.tar.gz"><code> +http://me-www.jrc.it/~dirkx/apache-msql-demo.tar.gz</code></a> and +its <a href="http://me-www.jrc.it/~dirkx/apache-msql-demo"><code> +README</code></a> file. + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</body> +</html> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_browser.html b/usr.sbin/httpd/htdocs/manual/mod/mod_browser.html new file mode 100644 index 00000000000..47ec81b760a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_browser.html @@ -0,0 +1,100 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_browser</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_browser</H1> + +This module is contained in the <code>mod_browser.c</code> file, and +is compiled in by default with Apache 1.2 and above. It provides for +setting environment variables based on the browser. + +<h2>Summary</h2> + +<p>This module allows you to set environment variables based on the name of +the browser accessing your document, based on the <code>User-Agent</code> +header field. This is especially useful when combined with a conditional +HTML language such as <a href="mod_include.html">XSSI</a> or PHP, and +can provide for simple browser-based negotiation of HTML features.</p> + +<h2>Directives</h2> +<ul> +<li><A HREF="#browsermatch">BrowserMatch</A> +<li><A HREF="#browsermatchnocase">BrowserMatchNoCase</A> +</ul> + +<hr> + +<h2><A name="browsermatch">BrowserMatch</A></h2> +<strong>Syntax:</strong> BrowserMatch <em>regex attr1 attr2...</em><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> base<br> +<strong>Module:</strong> mod_browser<br> +<strong>Compatibility:</strong> Apache 1.2 and above<p> + +The BrowserMatch directive defines environment variables based on the +User-Agent +header. The first argument should be a POSIX.2 extended regular +expression (similar to an egrep-style regex). The rest of the arguments +give names of variables to set. These take the form of either +"<code>varname</code>", "<code>!varname</code>" or +"<code>varname=value</code>". In the first form, the value will be set +to "1". The second will remove the given variable if already defined, +and the third will set the variable to the value given by <code>value</code>. If a User-Agent +string matches more than one entry, they will +be merged. Entries are processed in the order they appear, and later +entries can override earlier ones. + +<p>For example:</p> +<pre> + BrowserMatch ^Mozilla forms jpeg=yes browser=netscape + BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript + BrowserMatch MSIE !javascript +</pre> + +<p><h2><A name="browsermatchnocase">BrowserMatchNoCase</A></h2> +<strong>Syntax:</strong> BrowserMatchNoCase <em>regex attr1 attr2...</em><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> base<br> +<strong>Module:</strong> mod_browser<br> +<strong>Compatibility:</strong> Apache 1.2 and above + +<p>The <code>BrowserMatchNoCase</code> directive is semantically identical to + the <a href="#browsermatch"><code>BrowserMatch</code></a> + directive. However, it provides for case-insensitive matching. For + example:</p> +<pre> + BrowserMatchNoCase mac platform=macintosh + BrowserMatchNoCase win platform=windows +</pre> + + +<p> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_cern_meta.html b/usr.sbin/httpd/htdocs/manual/mod/mod_cern_meta.html new file mode 100644 index 00000000000..3eb508f9997 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_cern_meta.html @@ -0,0 +1,94 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Module mod_cern_meta</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_cern_meta</H1> + +This module is contained in the <code>mod_cern_meta.c</code> file, and +is not compiled in by default. It provides for CERN httpd metafile +semantics. It is only available in Apache 1.1 and later. + +<h2>Summary</h2> + +Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP +headers that can be output in addition to the normal range of headers +for each file accessed. They appear rather like the Apache +.asis files, and are able to provide a crude way of influencing +the Expires: header, as well as providing other curiosities. +There are many ways to manage meta information, this one was +chosen because there is already a large number of CERN users +who can exploit this module. + +<p>More information on the +<a href="http://www.w3.org/pub/WWW/Daemon/User/Config/General.html#MetaDir +">CERN metafile semantics</a> is available. + +<h2>Directives</h2> +<ul> +<li><A HREF="#metadir">MetaDir</A> +<li><A HREF="#metasuffix">MetaSuffix</A> +</ul> + +<hr> + +<h2><A name="metadir">MetaDir</A></h2> +<strong>Syntax:</strong> MetaDir <em>directory name</em><br> +<strong>Default:</strong> <code>MetaDir .web</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_cern_meta<br> +<strong>Compatibility:</strong> MetaDir is only available in Apache 1.1 +and later.<p> + +Specifies the name of the directory in which Apache can find +meta information files. The directory is usually a 'hidden' +subdirectory of the directory that contains the file being +accessed. Set to "<code>.</code>" to look in the same directory as the +file. + +<h2><A name="metasuffix">MetaSuffix</A></h2> +<strong>Syntax:</strong> MetaSuffix <em>suffix</em><br> +<strong>Default:</strong> <code>MetaSuffix .meta</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_cern_meta<br> +<strong>Compatibility:</strong> MetaSuffix is only available in Apache 1.1 +and later.<p> + +Specifies the file name suffix for the file containing the +meta information. For example, the default values for the two +directives will cause a request to <code> +DOCUMENT_ROOT/somedir/index.html</code> to look in +<code>DOCUMENT_ROOT/somedir/.web/index.html.meta</code> and will use +its contents to generate additional MIME header information. + +<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html new file mode 100644 index 00000000000..d1cfa745a5b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html @@ -0,0 +1,187 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache module mod_cgi</title> +</head> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<h1 ALIGN="CENTER">Module mod_cgi</h1> + +This module is contained in the <code>mod_cgi.c</code> file, and +is compiled in by default. It provides for execution of CGI scripts. +Any file with mime type <code>application/x-httpd-cgi</code> will be +processed by this module. +<!--%plaintext <?INDEX {\tt application/x-httpd-cgi} mime type> --> +<!--%plaintext <?INDEX CGI scripts> --> + +<h2>Summary</h2> +Any file that has the mime type <code>application/x-httpd-cgi</code> +or handler <code>cgi-script</code> (Apache 1.1 or later) +will be treated as a CGI script, and run by the server, with its output +being returned to the client. Files acquire this type either by +having a name ending in an extension defined by the +<A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in +a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <p> + +When the server invokes a CGI script, it will add a variable called +<code>DOCUMENT_ROOT</code> to the environment. This variable will contain the +value of the <A HREF="core.html#documentroot">DocumentRoot</A> +configuration variable. + +<h2>CGI Environment variables</h2> +The server will set the CGI environment variables as described in the CGI +specification, with the following provisions: +<dl> +<dt>REMOTE_HOST +<dd>This will only be set if the server has not been compiled with +<code>MINIMAL_DNS</code>. +<dt>REMOTE_IDENT +<dd>This will only be set if +<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <code>on</code>. +<dt>REMOTE_USER +<dd>This will only be set if the CGI script is subject to authentication. +</dl> +<P> + +<hr> + +<h2><a name="cgi_debug">CGI Debugging</a></h2> + +Debugging CGI scripts has traditionally been difficult, mainly because +it has +not +been possible to study the output (standard output and error) for +scripts +which are failing to run properly. These directives, included in +Apache 1.2 and later, provide +more detailed logging of errors when they occur. + +<hr> + +<h2>CGI Logfile Format</h2> + +When configured, the CGI error log logs any CGI which does not execute +properly. Each CGI script which fails to operate causes several lines +of information to be logged. The first two lines are always of the +format: + +<pre> + %% [<i>time</i>] <i>request-line</i> + %% <i>HTTP-status</i> <i>CGI-script-filename</i> +</pre> + +If the error is that CGI script cannot be run, the log file will +contain +an extra two lines: + +<pre> + %%error + <i>error-message</i> +</pre> + +Alternatively, if the error is the result of the script returning +incorrect header information (often due to a bug in the script), the +following information is logged: + +<pre> + %request + <i>All HTTP request headers received</i> + <i>POST or PUT entity (if any)</i> + %response + <i>All headers output by the CGI script</i> + %stdout + <i>CGI standard output</i> + %stderr + <i>CGI standard error</i> +</pre> + +(The %stdout and %stderr parts may be missing if the script did not +output +anything on standard output or standard error). + +<hr> + +<h2>Directives</h2> + +<h3><a name="scriptlog">ScriptLog</a></h3> + +<b>Syntax:</b> ScriptLog <i>filename</i><br> +<b>Default:</b> none<br> +<b>Context:</b> resource config<br> +<b>Status:</b> mod_cgi +<p> + +The <tt>ScriptLog</tt> directive sets the CGI script error logfile. +If no ScriptLog is given, no error log is created. If given, any +CGI errors are logged into the filename given as argument. If this +is a relative file or path it is taken relative to the server root. + +<P>This log will be opened as the user the child processes run as, +ie. the user specified in the main <A HREF="core.html#User">User</A> +directive. This means that either the directory the script log is +in needs to be writable by that user or the file needs to be manually +created and set to be writable by that user. If you place the +script log in your main logs directory, do <STRONG>NOT</STRONG> +change the directory permissions to make it writable by the user +the child processes run as.</P> + +<p>Note that script logging is meant to be a debugging feature when +writing CGI scripts, and is not meant to be activated continuously on +running servers. It is not optimized for speed or efficiency, and may +have security problems if used in a manner other than that for which +it was designed.</p> + +<h3><a name="scriptloglength">ScriptLogLength</a></h3> + +<b>Syntax:</b> ScriptLogLength <i>size</i><br> +<b>Default:</b> 10385760<br> +<b>Context:</b> resource config<br> +<b>Status:</b> mod_cgi +<p> + +<tt>ScriptLogLength</tt> can be used to limit the size of the CGI +script logfile. Since the logfile logs a lot of information per CGI +error (all request headers, all script output) it can grow to be a big +file. To prevent problems due to unbounded growth, this directive can +be used to set an maximum file-size for the CGI logfile. If the file +exceeds this size, no more information will be written to it. + +<h3><a name="scriptlogbuffer">ScriptLogBuffer</a></h3> + +<b>Syntax:</b> ScriptLogBuffer <i>size</i><br> +<b>Default:</b> 1024<br> +<b>Context:</b> resource config<br> +<b>Status:</b> mod_cgi +<p> + +The size of any PUT or POST entity body that is logged to the file is +limited, to prevent the log file growing too big too quickly if large +bodies are being received. By default, up to 1024 bytes are logged, +but this can be changed with this directive. + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_cookies.html b/usr.sbin/httpd/htdocs/manual/mod/mod_cookies.html new file mode 100644 index 00000000000..5f76d8f736f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_cookies.html @@ -0,0 +1,56 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_cookies</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_cookies</h1> + +This module is contained in the <code>mod_cookies.c</code> file, and +is not compiled in by default. It provides for Netscape(TM) cookies. +There is no documentation available for this module. + + +<menu> +<li><A HREF="#cookielog">CookieLog</A> +</menu> +<hr> + + +<h2><A name="cookielog">CookieLog</A></h2> +<!--%plaintext <?INDEX {\tt CookieLog} directive> --> +<strong>Syntax:</strong> CookieLog <em>filename</em><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Experimental<br> +<strong>Module:</strong> mod_cookies<p> + +The CookieLog directive sets the filename for logging of cookies. +The filename is relative to the <A HREF="core.html#serverroot">ServerRoot</A>. +<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_digest.html b/usr.sbin/httpd/htdocs/manual/mod/mod_digest.html new file mode 100644 index 00000000000..ff6c0a6e153 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_digest.html @@ -0,0 +1,78 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_digest</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_digest</h1> + +This module is contained in the <code>mod_digest.c</code> file, and is +not compiled in by default. It is only available in Apache 1.1 and +later. It provides for user authentication using MD5 Digest +Authentication. + + +<menu> +<li><A HREF="#authdigestfile">AuthDigestFile</A> +</menu> +<hr> + + +<h2><A name="authdigestfile">AuthDigestFile</A></h2> +<strong>Syntax:</strong> AuthDigestFile <em>filename</em><br> +<Strong>Context:</strong> directory, .htaccess<br> +<Strong>Override:</strong> AuthConfig<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_digest<p> + +<p>The AuthDigestFile directive sets the name of a textual file containing +the list +of users and encoded passwords for digest authentication. +<em>Filename</em> +is the absolute path to the user file.</p> +<p>The digest file uses a special format. Files in this format can be +created using the "htdigest" utility found in the support/ subdirectory of +the Apache distribution.</p> + +<hr> + +<h3>Using Digest Authentication</h3> + +<p>Using MD5 Digest authentication is very simple. Simply set up +authentication normally. However, use "AuthType Digest" and +"AuthDigestFile" instead of the normal "AuthType Basic" and +"AuthUserFile". Everything else should remain the same.</p> + +<p>MD5 authentication provides a more secure password system, but only +works with supporting browsers. As of this writing (July 1996), the +majority of browsers do not support digest authentication. Therefore, we +do not recommend using this feature on a large Internet site. However, for +personal and intra-net use, where browser users can be controlled, it is +ideal.</p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html b/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html new file mode 100644 index 00000000000..43beb8f145c --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_dir.html @@ -0,0 +1,380 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_dir</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_dir</H1> + +This module is contained in the <code>mod_dir.c</code> file, and +is compiled in by default. It provides for directory indexing. + +<h2>Summary</h2> +This module controls the directory indexing. The index of a directory +can come from one of two sources: +<ul> +<li>A file written by the user, typically called <code>index.html</code>. +The <A HREF="#directoryindex">DirectoryIndex</A> directive sets the name +of this file. +<li>Otherwise, a listing generated by the server. The other directives +control the format of this listing. The <A HREF="#addicon">AddIcon</A>, +<A HREF="#addiconbyencoding">AddIconByEncoding</A> and +<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of +icons to display for various file types; for each file listed, the +first icon listed that matches the file is displayed. +</ul> + + +<h2>Directives</h2> + +<menu> +<li><A HREF="#addalt">AddAlt</A> +<li><A HREF="#addaltbyencoding">AddAltByEncoding</A> +<li><A HREF="#addaltbytype">AddAltByType</A> +<li><A HREF="#adddescription">AddDescription</A> +<li><A HREF="#addicon">AddIcon</A> +<li><A HREF="#addiconbyencoding">AddIconByEncoding</A> +<li><A HREF="#addiconbytype">AddIconByType</A> +<li><A HREF="#defaulticon">DefaultIcon</A> +<li><A HREF="#directoryindex">DirectoryIndex</A> +<li><A HREF="#fancyindexing">FancyIndexing</A> +<li><A HREF="#headername">HeaderName</A> +<li><A HREF="#indexignore">IndexIgnore</A> +<li><A HREF="#indexoptions">IndexOptions</A> +<li><A HREF="#readmename">ReadmeName</A> +</menu> +<hr> + +<A name="addalt"><h2>AddAlt</h2></A> +<!--%plaintext <?INDEX {\tt AddAlt} directive> --> +<strong>Syntax:</strong> AddAlt <em>string file file...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the alternate text to display for a file, instead of an icon, for +<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file +extension, partial filename, wild-card expression or full filename for files +to describe. <em>String</em> is enclosed in double quotes +(<code>"</code>). This alternate text is displayed if the client is +image-incapable or has image loading disabled. + +<HR> +<A name="addaltbyencoding"><h2>AddAltByEncoding</h2></A> +<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> +<strong>Syntax:</strong> AddAltByEncoding <em>string MIME-encoding + MIME-encoding...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the alternate text to display for a file, instead of an icon, for +<A HREF="#fancyindexing">FancyIndexing</A>. <em>MIME-encoding</em> is a +valid content-encoding, such as <SAMP>x-compress</SAMP>. +<em>String</em> is enclosed in double quotes +(<code>"</code>). This alternate text is displayed if the client is +image-incapable or has image loading disabled. + +<HR> +<A name="addaltbytype"><h2>AddAltByType</h2></A> +<!--%plaintext <?INDEX {\tt AddAltByType} directive> --> +<strong>Syntax:</strong> AddAltByType <em>string MIME-type MIME-type...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the alternate text to display for a file, instead of an icon, for +<A HREF="#fancyindexing">FancyIndexing</A>. <em>MIME-type</em> is a +valid content-type, such as <SAMP>text/html</SAMP>. +<em>String</em> is enclosed in double quotes +(<code>"</code>). This alternate text is displayed if the client is +image-incapable or has image loading disabled. + +<HR> + +<A name="adddescription"><h2>AddDescription</h2></A> +<!--%plaintext <?INDEX {\tt AddDescription} directive> --> +<strong>Syntax:</strong> AddDescription <em>string file file...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the description to display for a file, for +<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file +extension, partial filename, wild-card expression or full filename for files +to describe. <em>String</em> is enclosed in double quotes +(<code>"</code>). Example: +<blockquote><code>AddDescription "The planet Mars" /web/pics/mars.gif +</code></blockquote><p><hr> + +<A name="addicon"><h2>AddIcon</h2></A> +<!--%plaintext <?INDEX {\tt AddIcon} directive> --> +<strong>Syntax:</strong> AddIcon <em>icon name name ...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the icon to display next to a file ending in <em>name</em> for +<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a +(%-escaped) relative URL to the icon, or of the format +(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given +for an icon for non-graphical browsers.<p> + +<em>Name</em> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for +blank lines (to format the list correctly), a file extension, a wildcard +expression, a partial filename or a complete filename. Examples: +<blockquote><code> +AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <br> +AddIcon /icons/dir.xbm ^^DIRECTORY^^ <br> +AddIcon /icons/backup.xbm *~ +</code></blockquote> +<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to +AddIcon, when possible.<p><hr> + +<A name="addiconbyencoding"><h2>AddIconByEncoding</h2></A> +<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> +<strong>Syntax:</strong> AddIconByEncoding <em>icon mime-encoding mime-encoding +...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the icon to display next to files with +<em>mime-encoding</em> for <A HREF="#fancyindexing">FancyIndexing</A>. +<em>Icon</em> is either a (%-escaped) relative URL to the icon, or of the +format (<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag +given for an icon for non-graphical browsers.<p> + +<em>Mime-encoding</em> is a wildcard expression matching required the +content-encoding. Examples: +<blockquote><code> +AddIconByEncoding /icons/compress.xbm x-compress +</code></blockquote><p><hr> + +<A name="addiconbytype"><h2>AddIconByType</h2></A> +<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> +<strong>Syntax:</strong> AddIconByType <em>icon mime-type mime-type ...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +This sets the icon to display next to files of type <em>mime-type</em> for +<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a +(%-escaped) relative URL to the icon, or of the format +(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given +for an icon for non-graphical browsers.<p> +<em>Mime-type</em> is a wildcard expression matching required the mime types. +Examples: +<blockquote><code> +AddIconByType (IMG,/icons/image.xbm) image/* +</code></blockquote><p><hr> + +<A name="defaulticon"><h2>DefaultIcon</h2></A> +<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> +<strong>Syntax:</strong> DefaultIcon <em>url</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The DefaultIcon directive sets the icon to display for files when no +specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. +<em>Url</em> is a (%-escaped) relative URL to the icon. Examples: +<blockquote><code> +DefaultIcon /icon/unknown.xbm +</code></blockquote><p><hr> + +<A name="directoryindex"><h2>DirectoryIndex</h2></A> +<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> +<strong>Syntax:</strong> DirectoryIndex <em>local-url local-url ...</em><br> +<strong>Default:</strong> <code>DirectoryIndex index.html</code><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The DirectoryIndex directive sets the list of resources to look for, +when the client requests an index of the directory by specifying a / +at the end of the a directory name. <em>Local-url</em> is the +(%-encoded) URL of a document on the server relative to the requested +directory; it is usually the name of a file in the directory. Several +URLs may be given, in which case the server will return the first one +that it finds. If none of the resources exist and the +<CODE>Indexes</CODE> option is set, the server will generate its own +listing of the directory. +<P> + +Example: +<blockquote><code> +DirectoryIndex index.html +</code></blockquote> +then a request for <code>http://myserver/docs/</code> would return +<code>http://myserver/docs/index.html</code> if it exists, or would list +the directory if it did not. <p> + +Note that the documents do not need to be relative to the directory; +<blockquote><code> +DirectoryIndex index.html index.txt /cgi-bin/index.pl</code></blockquote> +would cause the CGI script <code>/cgi-bin/index.pl</code> to be executed +if neither <code>index.html</code> or <code>index.txt</code> existed in +a directory.<p><hr> + +<A name="fancyindexing"><h2>FancyIndexing</h2></A> +<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> +<strong>Syntax:</strong> FancyIndexing <em>boolean</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The FancyIndexing directive sets the FancyIndexing option for a directory. +<em>Boolean</em> can be <code>on</code> or <code>off</code>. The +<A HREF="#indexoptions">IndexOptions</A> directive should be used in +preference.<p><hr> + +<A name="headername"><h2>HeaderName</h2></A> +<!--%plaintext <?INDEX {\tt HeaderName} directive> --> +<strong>Syntax:</strong> HeaderName <em>filename</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The HeaderName directive sets the name of the file that will be inserted +at the top of the index listing. <em>Filename</em> is the name of the file +to include, and is taken to be relative to the directory being indexed. +The server first attempts to include <em>filename</em><code>.html</code> +as an HTML document, otherwise it will include <em>filename</em> as plain +text. Example: +<blockquote><code>HeaderName HEADER</code></blockquote> +when indexing the directory <code>/web</code>, the server will first look for +the HTML file <code>/web/HEADER.html</code> and include it if found, otherwise +it will include the plain text file <code>/web/HEADER</code>, if it exists. + +<p>See also <A HREF="#readmename">ReadmeName</A>.<p><hr> + +<A name="indexignore"><h2>IndexIgnore</h2></A> +<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> +<strong>Syntax:</strong> IndexIgnore <em>file file ...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The IndexIgnore directive adds to the list of files to hide when listing +a directory. <em>File</em> is a file extension, partial filename, +wildcard expression or full filename for files to ignore. Multiple +IndexIgnore directives add to the list, rather than the replacing the list +of ignored files. By default, the list contains `<code>.</code>'. Example: +<blockquote><code> +IndexIgnore README .htaccess *~ +</code></blockquote><p><hr> + +<A name="indexoptions"><h2>IndexOptions</h2></A> +<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> +<strong>Syntax:</strong> IndexOptions <em>option option ...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The IndexOptions directive specifies the behavior of the directory indexing. +<em>Option</em> can be one of +<dl> +<dt>FancyIndexing +<dd><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> +This turns on fancy indexing of directories. +<dt>IconsAreLinks +<dd> +<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> +This makes the icons part of the anchor for the filename, for +fancy indexing. +<dt>ScanHTMLTitles +<dd><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> +This enables the extraction of the title from HTML documents for fancy +indexing. If the file does not have a description given by +<A HREF="#adddescription">AddDescription</A> then httpd will read the +document for the value of the TITLE tag. This is CPU and disk intensive. +<dt>SuppressLastModified +<dd> +<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> +This will suppress the display of the last modification date, in fancy +indexing listings. +<dt>SuppressSize +<dd> +<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> +This will suppress the file size in fancy indexing listings. +<dt>SuppressDescription +<dd> +<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> +This will suppress the file description in fancy indexing listings. +</dl> +This default is that no options are enabled. If multiple IndexOptions +could apply to a directory, then the most specific one is taken complete; +the options are not merged. For example: +<blockquote><code> +<Directory /web/docs> <br> +IndexOptions FancyIndexing <br> +</Directory><br> +<Directory /web/docs/spec> <br> +IndexOptions ScanHTMLTitles <br> +</Directory> +</code></blockquote> +then only <code>ScanHTMLTitles</code> will be set for the /web/docs/spec +directory.<p><hr> + +<A name="readmename"><h2>ReadmeName</h2></A> +<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> +<strong>Syntax:</strong> ReadmeName <em>filename</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_dir<p> + +The ReadmeName directive sets the name of the file that will be appended +to the end of the index listing. <em>Filename</em> is the name of the file +to include, and is taken to be relative to the directory being indexed. +The server first attempts to include <em>filename</em><code>.html</code> +as an HTML document, otherwise it will include <em>filename</em> as plain +text. Example: +<blockquote><code>ReadmeName README</code></blockquote> +when indexing the directory <code>/web</code>, the server will first look for +the HTML file <code>/web/README.html</code> and include it if found, otherwise +it will include the plain text file <code>/web/README</code>, if it exists. + +<p>See also <A HREF="#headername">HeaderName</A>.<p> + + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_dld.html b/usr.sbin/httpd/htdocs/manual/mod/mod_dld.html new file mode 100644 index 00000000000..55ee488f1f0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_dld.html @@ -0,0 +1,93 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_dld</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_dld</h1> + +This module is contained in the <code>mod_dld.c</code> file, and is not +compiled in by default. It provides for loading of executable code +and modules into the server at start-up time, using the GNU dld library. + +<h2>Summary</h2> + +The optional dld module is a proof-of-concept piece of code which +loads other modules into the server as it is configuring itself (the +first time only; for now, rereading the config files cannot affect the +state of loaded modules), using the GNU dynamic linking library, DLD. +It isn't compiled into the server by default, since not everyone has +DLD, but it works when I try it. (Famous last words.) <p> + +Note that for some reason, <code>LoadFile /lib/libc.a</code> seems to be +required for just about everything.<p> + +Note: that DLD needs to read the symbol table out of the server binary +when starting up; these commands will fail if the server can't find +its own binary when it starts up, or if that binary is stripped.<p> + + +<h2>Directives</h2> +<ul> +<li><A HREF="#loadfile">LoadFile</A> +<li><A HREF="#loadmodule">LoadModule</A> +</ul> +<hr> + + +<h2><A name="loadfile">LoadFile</A></h2> +<!--%plaintext <?INDEX {\tt LoadFile} directive> --> +<strong>Syntax:</strong> LoadFile <em>filename filename ...</em><br> +<Strong>Context:</strong> server config<br> +<strong>Status:</strong> Experimental<br> +<strong>Module:</strong> mod_dld<p> + +The LoadFile directive links in the named object files or libraries when +the server is started; this is used to load additional code which +may be required for some module to work. <em>Filename</em> is relative +to <A HREF="core.html#serverroot">ServerRoot</A>.<p><hr> + +<h2><A name="loadmodule">LoadModule</A></h2> +<!--%plaintext <?INDEX {\tt LoadModule} directive> --> +<strong>Syntax:</strong> LoadModule <em>module filename</em><br> +<Strong>Context:</strong> server config<br> +<strong>Status:</strong> Experimental<br> +<strong>Module:</strong> mod_dld<p> + +The LoadModule directive links in the object file or library <em>filename</em> +and adds the module structure named <em>module</em> to the list of active +modules. <em>Module</em> is the name of the external variable of type +<code>module</code> in the file. Example: +<blockquote><code> +LoadModule ai_backcompat_module modules/mod_ai_backcompat.o<br> +LoadFile /lib/libc.a +</code></blockquote> +loads the module in the modules subdirectory of the ServerRoot.<p> + + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_env.html b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html new file mode 100644 index 00000000000..f3b602fdd72 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html @@ -0,0 +1,105 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_env</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_env</H1> + +This module is contained in the <code>mod_env.c</code> file, and +is not compiled in by default. It provides for +passing environment variables to CGI/SSI scripts. Is is only available +in Apache 1.1 and later. + +<h2>Summary</h2> + +This module allows Apache's CGI and SSI environment to inherit +environment variables from the shell which invoked the httpd process. +CERN web-servers are able to do this, so this module is especially +useful to web-admins who wish to migrate from CERN to Apache without +rewriting all their scripts + +<h2>Directives</h2> +<ul> +<li><A HREF="#passenv">PassEnv</A> +<li><A HREF="#setenv">SetEnv</A> +<li><A HREF="#unsetenv">UnsetEnv</A> +</ul> + +<hr> + +<h2><A name="passenv">PassEnv</A></h2> +<strong>Syntax:</strong> PassEnv <em>variable variable ...</em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_env<br> +<strong>Compatibility:</strong> PassEnv is only available in +Apache 1.1 and later.<p> + +Specifies one or more environment variables to pass to CGI scripts +from the server's own environment. Example: +<pre> + PassEnv LD_LIBRARY_PATH +</pre> + +<HR> + +<h2><A name="setenv">SetEnv</A></h2> +<strong>Syntax:</strong> SetEnv <em>variable value</em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_env<br> +<strong>Compatibility:</strong> SetEnv is only available in +Apache 1.1 and later.<p> + +Sets an environment variable, which is then passed on to CGI +scripts. Example: +<pre> + SetEnv SPECIAL_PATH /foo/bin +</pre> + +<hr> + +<h2><A name="unsetenv">UnsetEnv</A></h2> +<strong>Syntax:</strong> UnsetEnv <em>variable variable ...</em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_env<br> +<strong>Compatibility:</strong> UnsetEnv is only available in +Apache 1.1 and later.<p> + +Removes one or more environment variables from those passed on to +CGI scripts. Example: +<pre> + UnsetEnv LD_LIBRARY_PATH +</pre> + + + +<p> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_example.html b/usr.sbin/httpd/htdocs/manual/mod/mod_example.html new file mode 100644 index 00000000000..013966e9f92 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_example.html @@ -0,0 +1,153 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache module mod_example</TITLE> + </HEAD> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > + <DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Module mod_example</h1> + <P> + This module is contained in the <CODE>modules/mod_example.c</CODE> file, and + <STRONG>is not</STRONG> compiled in by default. It illustrates many of + the aspects of the + <A + HREF="../misc/API.html" + REL="Help" + >Apache 1.2 API</A> + and, when used, demonstrates the manner in which module callbacks are + triggered by the server. + </P> + <H2>Summary</H2> + <P> + The files in the <CODE>src/modules/example directory</CODE> under the + Apache distribution directory tree are provided as an example to those + that wish to write modules that use the Apache API. + </P> + <P> + The main file is <CODE>mod_example.c</CODE>, which illustrates all + the different callback mechanisms and call syntaces. By no means does + an add-on module need to include routines for all of the callbacks - + quite the contrary! + </P> + <P> + The example module is an actual working module. If you link it into + your server, enable the "example-handler" handler for a location, and + then browse to that location, you will see a display of + some of the tracing the example module did as the various callbacks + were made. + </P> + <P> + To include the example module in your server, follow the steps below: + </P> + <OL> + <LI>Uncomment the "Module example_module" line near the bottom of + the <CODE>src/Configuration</CODE> file. If there isn't one, add + it; it should look like this: + <PRE> + Module example_module modules/example/mod_example.o + </PRE> + </LI> + <LI>Run the <CODE>src/Configure</CODE> script + ("<SAMP>cd src; ./Configure</SAMP>"). This will + build the Makefile for the server itself, and update the + <CODE>src/modules/Makefile</CODE> for any additional modules you + have requested from beneath that subdirectory. + </LI> + <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE> + directory). + </LI> + </OL> + <P> + To add another module of your own: + </P> + <OL TYPE="A"> + <LI><SAMP>mkdir src/modules/<EM>mymodule</EM></SAMP> + </LI> + <LI><SAMP>cp src/modules/example/* src/modules/<EM>mymodule</EM></SAMP> + </LI> + <LI>Modify the files in the new directory. + </LI> + <LI>Follow steps [1] through [3] above, with appropriate changes. + </LI> + </OL> + <H3> + Using the <SAMP>mod_example</SAMP> Module + </H3> + <P> + To activate the example module, include a block similar to the + following in your <SAMP>srm.conf</SAMP> file: + </P> + <PRE> + <Location /example-info> + SetHandler example-handler + </Location> + </PRE> + <P> + As an alternative, you can put the following into a + <A + HREF="core.html#accessfilename" + ><SAMP>.htaccess</SAMP></A> + file and then request the file "test.example" from that + location: + </P> + <PRE> + AddHandler example-handler .example + </PRE> + <P> + After reloading/restarting your server, you should be able to browse + to this location and see the brief display mentioned earlier. + </P> + <H2>Directives</H2> + <P> + <UL> + <LI><A HREF="#example">Example</A> + </LI> + </UL> + </P> + <HR> + <H2><A NAME="example"> + Example + </A></H2> + <P> + <STRONG>Syntax:</STRONG> Example + <BR> + <STRONG>Default:</STRONG> None + <BR> + <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess + <BR> + <STRONG>Override:</STRONG> Options + <BR> + <STRONG>Status:</STRONG> Extension + <BR> + <STRONG>Module:</STRONG> mod_example + </P> + <P> + The Example directive activates the example module's content handler + for a particular location or file type. It takes no arguments. If + you browse to an URL to which the example content-handler applies, you + will get a display of the routines within the module and how and in + what order they were called to service the document request. + </P> + <HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_expires.html b/usr.sbin/httpd/htdocs/manual/mod/mod_expires.html new file mode 100644 index 00000000000..af226b259fa --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_expires.html @@ -0,0 +1,198 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache module mod_expires</TITLE> + </HEAD> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > + <DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Module mod_expires</H1> + <P> + This module is contained in the <CODE>mod_expires.c</CODE> file, and + is <STRONG>not</STRONG> compiled in by default. It provides for the + generation of <CODE>Expires</CODE> headers according to user-specified + criteria. + </P> + <H2>Summary</H2> + <P> + This module controls the setting of the <CODE>Expires</CODE> HTTP + header in server responses. The expiration date can set to be + relative to either the time the source file was last modified, or to + the time of the client access. + </P> + <P> + The <CODE>Expires</CODE> HTTP header is an instruction to the client + about the document's validity and persistence. If cached, the document + may be fetched from the cache rather than from the source until this + time has passed. After that, the cache copy is considered + "expired" and invalid, and a new copy must be obtained from + the source. + </P> + <H2>Directives</H2> + <P> + <MENU> + <LI><A + HREF="#expiresactive" + >ExpiresActive</A> + </LI> + <LI><A + HREF="#expiresbytype" + >ExpiresByType</A> + </LI> + <LI><A + HREF="#expiresdefault" + >ExpiresDefault</A> + </LI> + </MENU> + <HR> + <H2><A NAME="expiresactive"> + ExpiresActive directive + </A></H2> + <!--%plaintext <?INDEX {\tt ExpiresActive} directive> --> + <P> + <STRONG>Syntax:</STRONG> ExpiresActive <EM>boolean</EM> + <BR> + <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess + <br> + <STRONG>Override:</STRONG> Indexes + <br> + <STRONG>Status:</STRONG> Extension + <br> + <STRONG>Module:</STRONG> mod_expires + </P> + <P> + This directive enables or disables the generation of the + <CODE>Expires</CODE> header for the document realm in question. (That + is, if found in an <CODE>.htaccess</CODE> file, for instance, it + applies only to documents generated from that directory.) If set to + <EM><CODE>Off</CODE></EM>, no <CODE>Expires</CODE> header will be + generated for any document in the realm (unless overridden at a lower + level, such as an <CODE>.htaccess</CODE> file overriding a server + config file). If set to <EM><CODE>On</CODE></EM>, the header will be + added to served documents according to the criteria defined by the + <A + HREF="#expiresbytype" + >ExpiresByType</A> + and + <A + HREF="#expiresdefault" + >ExpiresDefault</A> + directives (<EM>q.v.</EM>). + </P> + <P> + Note that this directive does not guarantee that an + <CODE>Expires</CODE> header will be generated. If the criteria aren't + met, no header will be sent, and the effect will be as though this + directive wasn't even specified. + </P> + <HR> + <H2><A NAME="expiresbytype"> + ExpiresByType directive + </A></H2> + <!--%plaintext <?INDEX {\tt ExpiresByType} directive> --> + <P> + <STRONG>Syntax:</STRONG> ExpiresByType <EM>mime-type <code>seconds</EM> + <BR> + <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess + <br> + <STRONG>Override:</STRONG> Indexes + <br> + <STRONG>Status:</STRONG> Extension + <br> + <STRONG>Module:</STRONG> mod_expires + </P> + <P> + This directive defines the value of the <CODE>Expires</CODE> header + generated for documents of the specified type (<EM>e.g.</EM>, + <CODE>text/html</CODE>). The second argument sets the number of + seconds that will be added to a base time to construct the expiration + date. + </P> + <P> + The base time is either the last modification time of the file, or the + time of the client's access to the document. Which should be used is + specified by the <CODE><EM><code></EM></CODE> field; + <STRONG>M</STRONG> means that the file's last modification time should + be used as the base time, and <STRONG>A</STRONG> means the client's + access time should be used. + </P> + <P> + The difference in effect is subtle. If <EM>M</EM> is used, all current + copies of the document in all caches will expire at the same time, + which can be good for something like a weekly notice that's always + found at the same URL. If <EM>A</EM> is used, the date of expiration + is different for each client; this can be good for image files that + don't change very often, particularly for a set of related documents + that all refer to the same images (<EM>i.e.</EM>, the images will be + accessed repeatedly within a relatively short timespan). + </P> + <P> + <STRONG>Example:</STRONG> + </P> + <P> + <PRE> + ExpiresActive On # enable expirations + ExpiresByType image/gif A2592000 # expire GIF images after a month + # in the client's cache + ExpiresByType text/html M604800 # HTML documents are good for a + # week from the time they were + # changed, period + </PRE> + </P> + <P> + Note that this directive only has effect if <CODE>ExpiresActive + On</CODE> has been specified. It overrides, for the specified MIME + type <EM>only</EM>, any expiration date set by the + <A + HREF="#expiresdefault" + >ExpiresDefault</A> + directive. + </P> + <HR> + <H2><A NAME="expiresdefault"> + ExpiresDefault directive + </A></H2> + <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> --> + <P> + <STRONG>Syntax:</STRONG> ExpiresDefault <EM><code>seconds</EM> + <BR> + <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess + <br> + <STRONG>Override:</STRONG> Indexes + <br> + <STRONG>Status:</STRONG> Extension + <br> + <STRONG>Module:</STRONG> mod_expires + </P> + <P> + This directive sets the default algorithm for calculating the + expiration time for all documents in the affected realm. It can be + overridden on a type-by-type basis by the + <A + HREF="#expiresbytype" + >ExpiresByType</A> + directive. See the description of that directive for details about + the syntax of the argument. + </P> + <HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_headers.html b/usr.sbin/httpd/htdocs/manual/mod/mod_headers.html new file mode 100644 index 00000000000..212c519bf7e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_headers.html @@ -0,0 +1,117 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_headers</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<h1 ALIGN="CENTER">Module mod_headers</h1> + +The optional headers module allows for the customization of HTTP +response headers. Headers can be merged, replaced or removed. The +directives described in this document are only available if Apache is +compiled with <b>mod_headers.c</b>. + +<hr> + +<h2>Directive</h2> +<ul> +<li><A HREF="#header">Header</A> +</ul> + +<hr> + +<h2><A name="header">Header</A></h2> +<strong>Syntax:</strong> Header [ set | append | add ] <em>header</em> <em>value</em><br> +<strong>Syntax:</strong> Header unset <em>header</em><br> +<strong>Context:</strong> server config, virtual host, access.conf, .htaccess<br> +<strong>Status:</strong> optional<br> +<strong>Module:</strong> mod_header<p> + +This directive can replace, merge or remove HTTP response headers. The +action it performs is determined by the first argument. This can be one +of the following values: + +<ul> +<li><b>set</b><br> + The response header is set, replacing any previous header with this name + +<li><b>append</b><br> + The response header is appended to any existing header of the same + name. When a new value is merged onto an existing header it is + separated from the existing header with a comma. This is the HTTP standard + way of giving a header multiple values. + +<li><b>add</b><br> + The response header is added to the existing set of headers, even if + this header already exists. This can result in two (or more) headers + having the same name. This can lead to unforeseen consequences, and in + general "append" should be used instead. + +<li><b>unset</b><br> + The response header of this name is removed, if it exists. If there are + multiple headers of the same name, only the first one set will be removed. +</ul> + +This argument is followed by a header name, which can include the +final colon, but it is not required. Case is ignored. For +add, append and set a value is given as the third argument. If this +value contains spaces, it should be surrounded by double quotes. +For unset, no value should be given. + +<h3>Order of Processing</h3> + +The Header directive can occur almost anywhere within the server +configuration. It is valid in the main server config and virtual host +sections, inside <Directory>, <Location> and <Files> +sections, and within .htaccess files. +<p> +The Header directives are processed in the following order: +<ol> +<li>main server +<li>virtual host +<li><Directory> sections and .htaccess +<li><Location> +<li><Files> +</ol> + +Order is important. These two headers have a different effect if reversed: +<pre> +Header append Author "John P. Doe" +Header unset Author +</pre> + +This way round, the Author header is not set. If reversed, the Author +header is set to "John P. Doe". +<p> + +The Header directives are processed just before the response is sent +by its handler. These means that some headers that are added just +before the response is sent cannot be unset or overridden. This +includes headers such as "Date" and "Server". +<P> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_imap.html b/usr.sbin/httpd/htdocs/manual/mod/mod_imap.html new file mode 100644 index 00000000000..25875b86002 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_imap.html @@ -0,0 +1,297 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache module mod_imap</title> +</head> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<h1 ALIGN="CENTER">Module mod_imap</h1> + +This module is contained in the <code>mod_imap.c</code> file, and is +compiled in by default. It provides for <code>.map</code> files, +replacing the functionality of the <code>imagemap</code> CGI +program. Any directory or document type configured to use the handler +<code>imap-file</code> (using either <code><A +HREF="mod_mime.html#addhandler">AddHandler</A> </code> or <code><A +HREF="mod_mime.html#sethandler">SetHandler</A></code>) will be +processed by this module. + +<h2>Summary</h2> + +This module is in the default Apache distribution. The following directive will +activate files ending with <code>.map</code> as imagemap files: + +<blockquote><code>AddHandler imap-file map</code></blockquote> + +Note that the following is still supported: + + <blockquote><code>AddType application/x-httpd-imap map</code></blockquote> + +However, we are trying to phase out "magic MIME types" so we are deprecating +this method. + +<H2>New Features</H2> +The imagemap module adds some new features that were not +possible with previously distributed imagemap programs.<P> + +<ul> +<LI>URL references relative to the Referer: information. +<LI>Default <BASE> assignment through a new map directive +<code>base</code>. +<LI>No need for <code>imagemap.conf</code> file. +<LI>Point references. +<LI>Configurable generation of imagemap menus. +</ul> +<P> + +<h2>Configuration Directives</h2> +<ul> +<li><A HREF="#imapmenu">ImapMenu</A> +<li><A HREF="#imapdefault">ImapDefault</A> +<li><A HREF="#imapbase">ImapBase</A> +</ul> + + +<p> + +<h3><A name="imapmenu">ImapMenu</A></h3> +<strong>Syntax:</strong> ImapMenu <code>{none, formatted, semi-formatted, + unformatted}</code><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Module:</strong> mod_imap.c<br> +<strong>Compatibility:</strong> ImapMenu is only available in Apache +1.1 and later.<p> + +The ImapMenu directive determines the action taken if an imagemap file +is called without valid coordinates. +<dl> + <dt><code>none</code> + <dd>If ImapMenu is + <code>none</code>, no menu is generated, and the <code>default</code> + action is performed. + <dt><code>formatted</code> + <dd>A <code>formatted</code> menu is the simplest menu. Comments + in the imagemap file are ignored. A level one header is + printed, then an hrule, then the links each on a separate line. + The menu has a consistent, plain look close to that of + a directory listing. + <dt><code>semiformatted</code> + <dd>In the <code>semiformatted</code> menu, comments are printed + where they occur in the imagemap file. Blank lines are turned + into HTML breaks. No header or hrule is printed, but otherwise + the menu is the same as a <code>formatted</code> menu. + <dt><code>unformatted</code> + <dd>Comments are printed, blank lines are ignored. Nothing is + printed that does not appear in the imagemap file. All breaks + and headers must be included as comments in the imagemap file. + This gives you the most flexibility over the appearance of your + menus, but requires you to treat your map files as HTML instead + of plaintext. +</dl> + +<p> + +<h3><A name="imapdefault">ImapDefault</A></h3> +<strong>Syntax:</strong> ImapDefault <code>{error, nocontent, + map, referer, URL}</code><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Module:</strong> mod_imap.c<br> +<strong>Compatibility:</strong> ImapDefault is only available in Apache +1.1 and later.<p> + + +The ImapDefault directive sets the default <code>default</code> used in +the imagemap files. It's value is overridden by a <code>default</code> +directive within the imagemap file. If not present, the +<code>default</code> action is <code>nocontent</code>, which means +that a <code>204 No Content</code> is sent to the client. In this +case, the client should continue to display the original page. + +<p> + +<h3><A name="imapbase">ImapBase</A></h3> +<strong>Syntax:</strong> ImapBase <code>{map, referer, URL}</code><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Indexes<br> +<strong>Module:</strong> mod_imap.c<br> +<strong>Compatibility:</strong> ImapBase is only available in Apache +1.1 and later.<p> + +The ImapBase directive sets the default <code>base</code> used in +the imagemap files. It's value is overridden by a <code>base</code> +directive within the imagemap file. If not present, the +<code>base</code> defaults to <code>http://servername/</code>. + +<hr> +<p> + +<h2>Imagemap File</h2> +The lines in the imagemap files can have one of several formats: +<blockquote> +<code>directive value [x,y ...]</code><br> +<code>directive value "Menu text" [x,y ...]</code><br> +<code>directive value x,y ... "Menu text"</code><br> +</blockquote> +The directive is one of <code>base</code>, <code>default</code>, +<code>poly</code>, <code>circle</code>, <code>rect</code>, or +<code>point</code>. The value is an absolute or relative URL, or one +of the special values listed below. The coordinates are +<code>x,y</code> pairs separated by whitespace. The quoted text is +used as the text of the link if a imagemap menu is generated. Lines +beginning with '#' are comments. + +<h3>Imagemap File Directives</h3> +There are six directives allowed in the imagemap file. The directives +can come in any order, but are processed in the order they are found +in the imagemap file. +<dl> +<dt><code>base</code> Directive +<dd>Has the effect of <code><BASE href="value"></code>. The + non-absolute URLs of the map-file are taken relative to this value. + The <code>base</code> directive overrides ImapBase as set in a + .htaccess file or in the server configuration files. In the absence + of an ImapBase configuration directive, <code>base</code> defaults to + <code>http://server_name/</code>. <br> + <code>base_uri</code> is synonymous with <code>base</code>. Note that + a trailing slash on the URL is significant. +<p> +<dt><code>default</code> Directive +<dd>The action taken if the coordinates given do not fit any of the + <code>poly</code>, <code>circle</code> or <code>rect</code> + directives, and there are no <code>point</code> directives. Defaults + to <code>nocontent</code> in the absence of an ImapDefault + configuration setting, causing a status code of <code>204 No + Content</code> to be returned. The client should keep the same + page displayed. +<p> +<dt><code>poly</code> Directive +<dd>Takes three to one-hundred points, and is obeyed if the user selected + coordinates fall within the polygon defined by these points. +<p> +<dt><code>circle</code> +<dd>Takes the center coordinates of a circle and a point on the circle. Is + obeyed if the user selected point is with the circle. +<p> +<dt><code>rect</code> Directive +<dd>Takes the coordinates of two opposing corners of a rectangle. Obeyed + if the point selected is within this rectangle. +<p> +<dt><code>point</code> Directive +<dd>Takes a single point. The point directive closest to the user + selected point is obeyed if no other directives are satisfied. + Note that <code>default</code> will not be followed if a + <code>point</code> directive is present and valid coordinates are + given. +</dl> + + + +<h3>Values</h3> +The values for each of the directives can any of the following: +<dl> + <dt>a URL + <dd>The URL can be relative or absolute URL. Relative URLs can + contain '..' syntax and will be resolved relative to the + <code>base</code> value. <br> + <code>base</code> itself will not resolved according to the current + value. A statement <code>base mailto:</code> will work properly, though. +<p> + <dt><code>map</code> + <dd>Equivalent to the URL of the imagemap file itself. No + coordinates are sent with this, so a menu will be generated + unless ImapMenu is set to 'none'. +<p> + <dt><code>menu</code> + <dd>Synonymous with <code>map</code>. +<p> + <dt><code>referer</code> + <dd>Equivalent to the URL of the referring document. + Defaults to <code>http://servername/</code> if no Referer: + header was present. +<p> + <dt><code>nocontent</code> + <dd>Sends a status code of <code>204 No Content</code>, + telling the client to keep the same page displayed. Valid for + all but <code>base</code>. +<p> + <dt><code>error</code> + <dd>Fails with a <code>500 Server Error</code>. Valid for all but + <code>base</code>, but sort of silly for anything but + <code>default</code>. +</dl> + +<h3>Coordinates</h3> +<dl> + <dt><code>0,0 200,200</code> + <dd>A coordinate consists of an <tt>x</tt> and a <tt>y</tt> value + separated by a comma. The coordinates are separated from each other + by whitespace. To accommodate the way Lynx handles imagemaps, should a + user select the coordinate <code>0,0</code>, it is as if + no coordinate had been selected. +</dl> + +<h3>Quoted Text</h3> +<dl> + <dt><code>"Menu Text"</code> + <dd>After the value or after the coordinates, the line optionally may + contain text within double quotes. This string is used as the + text for the link if a menu is generated:<br> + <code><a href="http://foo.com/">Menu text</a></code><br> + If no quoted text is present, the name of the link will be used + as the text:<br> + <code><a href="http://foo.com/">http://foo.com</a></code><br> + It is impossible to escape double quotes within this text. +</dl> + +<hr> + +<h2>Example Mapfile</h2> +<blockquote><code> +#Comments are printed in a 'formatted' or 'semiformatted' menu. <br> +#And can contain html tags. <hr> <br> +base referer <br> +poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0 <br> +rect .. 0,0 77,27 "the directory of the referer"<br> +circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27 <br> +rect another_file "in same directory as referer" 306,0 419,27 <br> +point http://www.zyzzyva.com/ 100,100 <br> +point http://www.tripod.com/ 200,200 <br> +rect mailto:nate@tripod.com 100,150 200,0 "Bugs?" <br> +</code></blockquote> +<P> + +<h2>Referencing your mapfile</h2> +<blockquote><code> +<A HREF="/maps/imagmap1.map"> <br> +<IMG ISMAP SRC="/images/imagemap1.gif"> <br> +</A> +</code></blockquote><p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_include.html b/usr.sbin/httpd/htdocs/manual/mod/mod_include.html new file mode 100644 index 00000000000..3ce515b26d8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_include.html @@ -0,0 +1,398 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_include</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_include</H1> + +This module is contained in the <code>mod_include.c</code> file, and +is compiled in by default. It provides for server-parsed html +documents. Several directives beyond the original NCSA definition have been +included in Apache 1.2 - these are flagged below with the phrase +"Apache 1.2 and above". Of particular significance are the new flow +control directives documented at the bottom. + +<H2>Enabling Server-Side Includes</H2> + +Any document with handler of "server-parsed" will be parsed by this +module, if the <CODE>Includes</CODE> option is set. If documents +containing server-side include directives are given the extension +.shtml, the following directives will make Apache parse them and +assign the resulting document the mime type of <CODE>text/html</CODE>: + +<PRE> +AddType text/html .shtml +AddHandler server-parsed .shtml +</PRE> + +The following directive must be given for the directories containing +the shtml files (typically in a <CODE><Directory></CODE> section, +but this directive is also valid .htaccess files if <CODE>AllowOverride +Options</CODE> is set): + +<PRE> +Options +Includes +</PRE> + +Alternatively the <A HREF="#xbithack"><CODE>XBitHack</CODE></A> +directive can be used to parse normal (<CODE>text/html</CODE>) files, +based on file permissions. <P> + +For backwards compatibility, documents with mime type +<code>text/x-server-parsed-html</code> or +<code>text/x-server-parsed-html3</code> will also be parsed +(and the resulting output given the mime type <code>text/html</code>). + +<h2>Basic Elements</h2> + +The document is parsed as an HTML document, with special commands embedded +as SGML comments. A command has the syntax: + +<blockquote><code> +<!--#</code><em>element attribute=value attribute=value ...</em> +<code> --> +</code></blockquote> + +The value will often be enclosed in double quotes; many commands only allow +a single attribute-value pair. Note that the comment terminator +(<SAMP>--></SAMP>) should be preceded by whitespace to ensure that it +isn't considered part of an SSI token. +<p> +The allowed elements are:<p> + +<dl> + +<dt><strong>config</strong> +<dd> +This command controls various aspects of the parsing. The valid attributes +are: +<dl> +<dt>errmsg +<dd>The value is a message that is sent back to the client if an error occurs +whilst parsing the document. +<dt>sizefmt +<dd>The value sets the format to be used which displaying the size of a file. +Valid values are <code>bytes</code> for a count in bytes, or +<code>abbrev</code> for a count in Kb or Mb as appropriate. +<dt>timefmt +<dd>The value is a string to be used by the <code>strftime(3)</code> library +routine when printing dates. +</dl> + +<dt><strong>echo</strong> +<dd> +This command prints one of the include variables, defined below. +If the variable is unset, it is printed as <code>(none)</code>. +Any dates printed are subject to the currently configured <code>timefmt</code>. +Attributes: +<dl> +<dt>var +<dd>The value is the name of the variable to print. +</dl> + +<dt><strong>exec</strong> +<dd> +The exec command executes a given shell command or CGI script. +The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command +completely. The valid attributes are: +<dl> +<dt>cgi +<dd> +The value specifies a (%-encoded) URL relative path to the CGI script. +If the path does not begin with a (/), then it is taken to be relative to +the current document. The document referenced by this path is invoked +as a CGI script, even if the server would not normally recognize it as +such. However, the directory containing the script must be enabled for +CGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> +or the ExecCGI <A HREF="core.html#options">Option</A>).<p> +The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the +original request from the client; these cannot be specified in the URL path. +The include variables will be available to the script in addition to the +standard <A HREF="mod_cgi.html">CGI</A> environment.<p> +If the script returns a Location: header instead of output, then this +will be translated into an HTML anchor.<p> +The <code>include virtual</code> element should be used in preference to +<code>exec cgi</code>. +<dt>cmd +<dd>The server will execute the given string using <code>/bin/sh</code>. +The include variables are available to the command. +</dl> + +<dt><strong>fsize</strong> +<dd> +This command prints the size of the specified file, subject to the +<code>sizefmt</code> format specification. Attributes: +<dl> +<dt>file +<dd>The value is a path relative to the directory containing the current +document being parsed. +<dt>virtual +<dd>The value is a (%-encoded) URL-path relative to the current document being +parsed. If it does not begin with a slash (/) then it is taken to be relative +to the current document. +</dl> + +<dt><strong>flastmod</strong> +<dd> +This command prints the last modification date of the specified file, +subject to the <code>timefmt</code> format specification. The attributes are +the same as for the <code>fsize</code> command. + +<dt><strong>include</strong> +<dd> +This command inserts the text of another document or file into the parsed +file. Any included file is subject to the usual access control. If the +directory containing the parsed file has the +<A HREF="core.html#options">Option</A> +IncludesNOEXEC set, and the including the document would cause a program +to be executed, then it will not be included; this prevents the execution of +CGI scripts. Otherwise CGI scripts are invoked as normal using the complete +URL given in the command, including any query string. +<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> +<p> + +An attribute defines the location of the document; the inclusion is done for +each attribute given to the include command. The valid attributes are: +<dl> +<dt>file +<dd>The value is a path relative to the directory containing the current +document being parsed. It cannot contain <code>../</code>, nor can it be an +absolute path. The <code>virtual</code> attribute should always be used +in preference to this one. +<dt>virtual +<dd>The value is a (%-encoded) URL relative to the current document being +parsed. The URL cannot contain a scheme or hostname, only a path and +an optional query string. If it does not begin with a slash (/) then it +is taken to be relative to the current document. +</dl> +A URL is constructed from the attribute, and the output the server +would return if the URL were accessed by the client is included in the parsed +output. Thus included files can be nested. + +<dt><strong>printenv</strong> +<dd>This prints out a listing of all existing variables and their values. + No attributes. +<dd>For example: <code><!--#printenv --></code> +<dd>Apache 1.2 and above. + +<dt><strong>set</strong> +<dd>This sets the value of a variable. Attributes: +<dl> +<dt>var +<dd>The name of the variable to set. +<dt>value +<dd>The value to give a variable. +</dl> +For example: + <CODE><!--#set var="category" value="help" --></CODE> +<dd>Apache 1.2 and above. + +</dl> + +<h2>Include Variables</h2> + +In addition to the variables in the standard CGI environment, these are +available for the <code>echo</code> command, for <code>if</code> and +<code>elif</code>, and to any program invoked by the document. + +<dl> +<dt>DATE_GMT +<dd>The current date in Greenwich Mean Time. +<dt>DATE_LOCAL +<dd>The current date in the local time zone. +<dt>DOCUMENT_NAME +<dd>The filename (excluding directories) of the document requested by the +user. +<dt>DOCUMENT_URI +<dd>The (%-decoded) URL path of the document requested by the user. Note that +in the case of nested include files, this is <em>not</em> then URL for the +current document. +<dt>LAST_MODIFIED +<dd>The last modification date of the document requested by the user. +</dl> +<p> + +<H2>Variable Substitution</H2> +<P> Variable substitution is done within quoted strings in most cases + where they may reasonably occur as an argument to an SSI directive. + This includes the + <SAMP>config</SAMP>, + <SAMP>exec</SAMP>, + <SAMP>flastmod</SAMP>, + <SAMP>fsize</SAMP>, + <SAMP>include</SAMP>, and + <SAMP>set</SAMP> + directives, as well as the arguments to conditional operators. + You can insert a literal dollar sign into the string using backslash + quoting: + +<PRE> + <!--#if expr="$a = \$test" --> +</PRE> + +<P> If a variable reference needs to be substituted in the middle of a + character sequence that might otherwise be considered a valid + identifier in its own right, it can be disambiguated by enclosing + the reference in braces, <EM>à la</EM> shell substitution: + +<PRE> + <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> +</PRE> + +<P> This will result in the <SAMP>Zed</SAMP> variable being set to + "<SAMP>X_Y</SAMP>" if <SAMP>REMOTE_HOST</SAMP> is + "<SAMP>X</SAMP>" and <SAMP>REQUEST_METHOD</SAMP> is + "<SAMP>Y</SAMP>". + +<P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is +/foo/file.html, "in bar" if it is /bar/file.html and "in neither" +otherwise: +<PRE> + <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> + in foo + <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> + in bar + <!--#else --> + in neither + <!--#endif --> +</PRE> + +<H2>Flow Control Elements</H2> + +These are available in Apache 1.2 and above. The basic flow control +elements are: + +<PRE> + <!--#if expr="<I>test_condition</I>" --> + <!--#elif expr="<I>test_condition</I>" --> + <!--#else --> + <!--#endif --> +</PRE> + +<P> The <B><CODE>if</CODE></B> element works like an + if statement in a programming language. The test condition + is evaluated and if the result is true, then the text until + the next <B><CODE>elif</CODE></B>, <B><CODE>else</CODE></B>. + or <B><CODE>endif</CODE></B> element is included in the + output stream. + +<P> The <B><CODE>elif</CODE></B> or <B><CODE>else</CODE></B> + statements are be used the put text into the output stream + if the original test_condition was false. These elements + are optional. + +<P> The <B><CODE>endif</CODE></B> element ends the + <B><CODE>if</CODE></B> element and is required. + +<P> <I>test_condition</I> is one of the following: + +<DL> + +<DT><I>string</I><DD>true if <I>string</I> is not empty + +<DT><I>string1</I> = <I>string2</I><BR> + <I>string1</I> != <I>string2</I> + +<DD>Compare string1 with string 2. If string2 has the form <I>/string/</I> + than it is compared as a regular expression. + Regular expressions have the same syntax as those found in the + Unix egrep command. + +<DT>( <I>test_condition</I> ) + <DD>true if <I>test_condition</I> is true +<DT>! <I>test_condition</I> + <DD>true if <I>test_condition</I> is false +<DT><I>test_condition1</I> && <I>test_condition2</I> + <DD>true if both <I>test_condition1</I> and + <I>test_condition2</I> are true +<DT><I>test_condition1</I> || <I>test_condition2</I> + <DD>true if either <I>test_condition1</I> or + <I>test_condition2</I> is true +</DL> + +<P> "<I>=</I>" and "<I>!=</I>" bind more tightly than "<I>&&</I>" and + "<I>||</I>". + "<I>!</I>" binds most tightly. Thus, the following are equivalent: + +<PRE> + <!--#if expr="$a = test1 && $b = test2" --> + <!--#if expr="($a = test1) && ($b = test2)" --> +</PRE> + +<P> Anything that's not recognized as a variable or an operator is + treated as a string. Strings can also be quoted: <I>'string'</I>. + Unquoted strings can't contain whitespace (blanks and tabs) + because it is used to separate tokens such as variables. If + multiple strings are found in a row, they are concatenated using + blanks. So, + +<PRE> + <I>string1 string2</I> results in <I>string1 string2</I> + <I>'string1 string2'</I> results in <I>string1 string2</I> +</PRE> + +<hr> +<h2>Directives</h2> +<ul> +<li><A HREF="#xbithack">XBitHack</A> +</ul> +<hr> + + +<h2><A name="xbithack">XBitHack</A></h2> +<!--%plaintext <?INDEX {\tt XBitHack} directive> --> +<strong>Syntax:</strong> XBitHack <em>status</em><br> +<strong>Default:</strong> <code>XBitHack off</code><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> Options<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_include<p> + +The XBitHack directives controls the parsing of ordinary html documents. +This directive only affects files associated with the MIME type +<CODE>text/html</CODE>. +<em>Status</em> can have the following values: +<dl> +<dt>off +<dd>No special treatment of executable files. +<dt>on +<dd>Any file that has the user-execute bit set will be treated as a +server-parsed html document. +<dt>full +<dd>As for <code>on</code> but also test the group-execute bit. If it +is set, then set the Last-modified date of the returned file to be the +last modified time of the file. If it is not set, then no last-modified date +is sent. Setting this bit allows clients and proxies to cache the result of +the request. +<p><b>Note:</b> you would not want to use this, for example, when you +<code>#include</code> a CGI that produces different output on each hit +(or potentially depends on the hit). +</dl> +<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_info.html b/usr.sbin/httpd/htdocs/manual/mod/mod_info.html new file mode 100644 index 00000000000..8bb49e28983 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_info.html @@ -0,0 +1,86 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache module mod_info</title> +</head> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<h1 ALIGN="CENTER">Module mod_info</h1> + +This module is contained in the <code>mod_info.c</code> file. It +provides a comprehensive overview of the server configuration +including all installed modules and directives in the configuration +files. This module is not compiled into the +server by default. It is only available in Apache 1.1 and later. To +enable it, add the following line to the server build Configuration +file, and rebuild the server: + +<PRE> +Module info_module mod_info.o +</PRE> + +<HR> +<P> +To configure it, add the following to your <code>access.conf</code> file. + +<PRE> +<Location /server-info> +SetHandler server-info +</Location> +</PRE> + +You may wish to add a +<A + HREF="core.html#limit" +><Limit></A> +clause inside the +<A + HREF="core.html#location" +>location</A> +directive to limit access to your server configuration information.<p> +Once configured, the server information is obtained by accessing +<tt>http://your.host.dom/server-info</tt><p> +<BLOCKQUOTE> + <STRONG> + Note that the configuration files are read by the module at run-time, + and therefore the display may <EM>not</EM> reflect the running + server's active configuration if the files have been changed since the + server was last reloaded. Also, the configuration files must be + readable by the user as which the server is running (see the + <A + HREF="core.html#user" + ><SAMP>User</SAMP></A> + directive), or else the directive settings will not be listed. + <P> + It should also be noted that if <SAMP>mod_info</SAMP> is compiled into + the server, its handler capability is available in <EM>all</EM> + configuration files, including <EM>per</EM>-directory files + (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>). This may have + security-related ramifications for your site. + </P> + </STRONG> +</BLOCKQUOTE> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_agent.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_agent.html new file mode 100644 index 00000000000..a0913517dc0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_log_agent.html @@ -0,0 +1,74 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Module mod_log_agent</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_log_agent</h1> + +This module is contained in the <code>mod_log_agent.c</code> file, and is not +compiled in by default. It provides for logging of the client user agents. + + +<ul> +<li><A HREF="#agentlog">AgentLog</A> +</ul> +<hr> + + +<h2><A name="agentlog">AgentLog</A></h2> +<!--%plaintext <?INDEX {\tt AgentLog} directive> --> +<strong>Syntax:</strong> AgentLog <em>file-pipe</em><br> +<strong>Default:</strong> <code>AgentLog logs/agent_log</code><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_log_agent<p> + +The AgentLog directive sets the name of the file to which the server will +log the UserAgent header of incoming requests. <em>File-pipe</em> is one +of +<dl><dt>A filename +<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. +<dt> `|' followed by a command +<dd>A program to receive the agent log information on its standard input. +Note the a new program will not be started for a VirtualHost if it inherits +the AgentLog from the main server. +</dl> +<strong>Security:</strong> if a program is used, then it will be +run under the user who started httpd. This will be root if the server +was started by root; be sure that the program is secure.<p> + +<strong>Security:</strong> See the <A +HREF="../misc/security_tips.html">security tips</A> document for +details on why your security could be compromised if the directory +where logfiles are stored is writable by anyone other than the user +that starts the server.<P> + +This directive is provided for compatibility with NCSA 1.4.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_common.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_common.html new file mode 100644 index 00000000000..d4d4e5deec4 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_log_common.html @@ -0,0 +1,114 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_log_common</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_log_common</h1> + +This module is contained in the <code>mod_log_common.c</code> file, +and is compiled in by default. It provides for logging of the requests +made to the server using the Common Logfile Format. This module has +been replaced by mod_log_config in Apache 1.2 + +<h2>Log file format</h2> +The log file contains a separate line for each request. A line is composed +of several tokens separated by spaces: +<blockquote> +host ident authuser date request status bytes +</blockquote> +If a token does not have a value then it is represented by a hyphen (-). +The meanings and values of these tokens are as follows: +<dl> +<dt>host +<dd>The fully-qualified domain name of the client, or its IP number if the +name is not available. +<dt>ident +<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the +client machine runs identd, then this is the identity information reported +by the client. +<dt>authuser +<dd>If the request was for an password protected document, then this is +the userid used in the request. +<dt>date +<dd>The date and time of the request, in the following format: +<dl><dd><blockquote><code> date = [day/month/year:hour:minute:second zone] <br> +day = 2*digit<br> +month = 3*letter<br> +year = 4*digit<br> +hour = 2*digit<br> +minute = 2*digit<br> +second = 2*digit<br> +zone = (`+' | `-') 4*digit</code></blockquote></dl> +<dt>request +<dd>The request line from the client, enclosed in double quotes +(<code>"</code>). +<dt>status +<dd>The three digit status code returned to the client. +<dt>bytes +<dd>The number of bytes in the object returned to the client, not including +any headers. +</dl> + + +<h2>Directives</h2> +<ul> +<li><A HREF="#transferlog">TransferLog</A> +</ul> +<hr> + + +<h2><A name="transferlog">TransferLog</A></h2> +<!--%plaintext <?INDEX {\tt TransferLog} directive> --> +<strong>Syntax:</strong> TransferLog <em>file-pipe</em><br> +<strong>Default:</strong> <code>TransferLog logs/transfer_log</code><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_log_common<p> + +The TransferLog directive sets the name of the file to which the server will +log the incoming requests. <em>File-pipe</em> is one +of +<dl><dt>A filename +<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. +<dt> `|' followed by a command +<dd>A program to receive the agent log information on its standard input. +Note the a new program will not be started for a VirtualHost if it inherits +the TransferLog from the main server. +</dl> +<strong>Security:</strong> if a program is used, then it will be +run under the user who started httpd. This will be root if the server +was started by root; be sure that the program is secure.<p> + +<strong>Security:</strong> See the <A +HREF="../misc/security_tips.html">security tips</A> document for +details on why your security could be compromised if the directory +where logfiles are stored is writable by anyone other than the user +that starts the server.<P> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html new file mode 100644 index 00000000000..a670e824458 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html @@ -0,0 +1,276 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_log_config</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_log_config</h1> + +This module is contained in the <code>mod_log_config.c</code> file, +and is compiled in by default in Apache 1.2. mod_log_config replaces +mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was +an optional module. It provides for logging of the requests made to +the server, using the Common Log Format or a user-specified format. + +<h2>Summary</h2> + +Three directives are provided by this module: <code>TransferLog</code> +to create a log file, <code>LogFormat</code> to set a custom format, +and <code>CustomLog</code> to define a log file and format in one go. +The <code>TransferLog</code> and <code>CustomLog</code> directives can +be used multiple times in each server to cause each request to be +logged to multiple files. +<P> + +<h3>Compatibility notes</h3> + +<ul> +<li>This module is based on mod_log_config distributed with +previous Apache releases, now updated to handle multiple logs. +There is now no need to re-configure Apache to use configuration log +formats. + +<li>The module also implements the <code>CookieLog</code> directive, +used to log user-tracking information created by <a +href="mod_usertrack.html">mod_usertrack</a>. The use of +<code>CookieLog</code> is deprecated, and a <code>CustomLog</code> +should be defined to log user-tracking information instead. + +</ul> + +<h2>Log File Formats</h2> + +Unless told otherwise with <tt>LogFormat</tt> the log files created by +<tt>TransferLog</tt> will be in standard "Common Log Format" +(CLF). The contents of each line in a CLF file are explained +below. Alternatively, the log file can be customized (and if multiple +log files are used, each can have a different format). Custom formats +are set with <code>LogFormat</code> and <code>CustomLog</code>. + +<h3>Common Log Format</h3> + +The Common Log Format (CLF) file contains a separate line for each +request. A line is composed of several tokens separated by spaces: + +<blockquote> +host ident authuser date request status bytes +</blockquote> +If a token does not have a value then it is represented by a hyphen (-). +The meanings and values of these tokens are as follows: +<dl> +<dt>host +<dd>The fully-qualified domain name of the client, or its IP number if the +name is not available. +<dt>ident +<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the +client machine runs identd, then this is the identity information reported +by the client. +<dt>authuser +<dd>If the request was for an password protected document, then this is +the userid used in the request. +<dt>date +<dd>The date and time of the request, in the following format: +<dl><dd><blockquote><code> date = [day/month/year:hour:minute:second zone] <br> +day = 2*digit<br> +month = 3*letter<br> +year = 4*digit<br> +hour = 2*digit<br> +minute = 2*digit<br> +second = 2*digit<br> +zone = (`+' | `-') 4*digit</code></blockquote></dl> +<dt>request +<dd>The request line from the client, enclosed in double quotes +(<code>"</code>). +<dt>status +<dd>The three digit status code returned to the client. +<dt>bytes +<dd>The number of bytes in the object returned to the client, not including +any headers. +</dl> + +<h3><A NAME="formats">Custom Log Formats</A></h3> + +The format argument to the <code>LogFormat</code> and +<code>CustomLog</code> is a string. This string is logged to the log +file for each request. It can contain literal characters copied into +the log files, and `%' directives which are replaced in the log file +by the values as follows: + +<PRE> +%...b: Bytes sent, excluding HTTP headers. +%...f: Filename +%...{FOOBAR}e: The contents of the environment variable FOOBAR +%...h: Remote host +%...{Foobar}i: The contents of Foobar: header line(s) in the request + sent to the server. +%...l: Remote logname (from identd, if supplied) +%...{Foobar}n: The contents of note "Foobar" from another module. +%...{Foobar}o: The contents of Foobar: header line(s) in the reply. +%...p: The port the request was served to +%...P: The process ID of the child that serviced the request. +%...r: First line of request +%...s: Status. For requests that got internally redirected, this + is status of the *original* request --- %...>s for the last. +%...t: Time, in common log format time format +%...{format}t: The time, in the form given by format, which should + be in strftime(3) format. +%...T: The time taken to serve the request, in seconds. +%...u: Remote user (from auth; may be bogus if return status (%s) is 401) +%...U: The URL path requested. +%...v: The name of the server (i.e. which virtual host?) +</PRE> + +The `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can +indicate conditions for inclusion of the item (which will cause it +to be replaced with `-' if the condition is not met). Note that +there is no escaping performed on the strings from %r, %...i and +%...o; some with long memories may remember that I thought this was +a bad idea, once upon a time, and I'm still not comfortable with +it, but it is difficult to see how to `do the right thing' with all +of `%..i', unless we URL-escape everything and break with CLF. + +<P> + +The forms of condition are a list of HTTP status codes, which may +or may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs +User-agent: on 400 errors and 501 errors (Bad Request, Not +Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all +requests which did <b>not</b> return some sort of normal status. + +<P> + +Note that the common log format is defined by the string <code>"%h %l +%u %t \"%r\" %s %b"</code>, which can be used as the basis for +extending for format if desired (e.g. to add extra fields at the end). +NCSA's extended/combined log format would be <code>"%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""</code>. + +<h2>Using Multiple Log Files</h2> + +The <code>TransferLog</code> and <code>CustomLog</code> directives can +be given more than once to log requests to multiple log files. Each +request will be logged to all the log files defined by either of these +directives. + +<h3>Use with Virtual Hosts</h3> + +If a <VirtualHost> section does not contain any +<tt>TransferLog</tt> or <tt>CustomLog</tt> directives, the +logs defined for the main server will be used. If it does +contain one or more of these directives, requests serviced by +this virtual host will only be logged in the log files defined +within its definition, not in any of the main server's log files. +See the examples below. +<p> + +<h2>Security Considerations</h2> + +See the <A HREF="../misc/security_tips.html">security tips</A> document +for details on why your security could be compromised if the directory +where logfiles are stored is writable by anyone other than the user +that starts the server. +<p> +<h2>Directives</h2> + +<ul> +<li><A HREF="#cookielog">CookieLog</A> +<LI><A HREF="#customlog">CustomLog</A> +<li><A HREF="#logformat">LogFormat</A> +<li><A HREF="#transferlog">TransferLog</A> +</ul> +<hr> + + +<h2><A name="cookielog">CookieLog</A></h2> +<!--%plaintext <?INDEX {\tt CookieLog} directive> --> +<strong>Syntax:</strong> CookieLog <em>filename</em><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Module:</strong> mod_cookies<br> +<strong>Compatibility:</strong> Only available in Apache 1.2 and above<p> + +The CookieLog directive sets the filename for logging of cookies. +The filename is relative to the <A +HREF="core.html#serverroot">ServerRoot</A>. This directive is included +only for compatibility with <a +href="mod_cookies.html">mod_cookies</a>, and is deprecated. +<p> + +<H2><A NAME="customlog">CustomLog</A></H2> +<STRONG>Syntax:</STRONG> CustomLog <em>file-pipe</em> <em>format</em><BR> +<STRONG>Context:</STRONG> server config, virtual host<BR> +<STRONG>Status:</STRONG> Base<BR> +<STRONG>Module:</STRONG> mod_log_config<P> + +The first argument is the filename to log to. This is used +exactly like the argument to <tt>TransferLog</tt>, that is, +it is either a full path, or relative to the current +server root. <p> + +The format argument specifies a format for each line of the log file. +The options available for the format are exactly the same as for +the argument of the <tt>LogFormat</tt> directive. If the format +includes any spaces (which it will do in almost all cases) it +should be enclosed in double quotes. + +<h2><A name="logformat">LogFormat</A></h2> +<!--%plaintext <?INDEX {\tt LogFormat} directive> --> +<strong>Syntax:</strong> LogFormat <em>string</em><br> +<strong>Default:</strong> <code>LogFormat "%h %l %u %t \"%r\" +%s %b"</code><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_log_config<p> + +This sets the format of the logfile. See <A HREF="#formats"> +Custom Log Formats</A> for details on the format arguments.<p><hr> + + +<h2><A name="transferlog">TransferLog</A></h2> +<!--%plaintext <?INDEX {\tt TransferLog} directive> --> +<strong>Syntax:</strong> TransferLog <em>file-pipe</em><br> +<strong>Default:</strong> none<br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_log_config<p> + +The TransferLog directive adds a log file in Common Log Format. +<em>File-pipe</em> is one +of +<dl><dt>A filename +<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. +<dt> `|' followed by a command +<dd>A program to receive the agent log information on its standard input. +Note the a new program will not be started for a VirtualHost if it inherits +the TransferLog from the main server. +</dl> +<strong>Security:</strong> if a program is used, then it will be +run under the user who started httpd. This will be root if the server +was started by root; be sure that the program is secure.<p> + + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_referer.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_referer.html new file mode 100644 index 00000000000..ab86f2967a8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_log_referer.html @@ -0,0 +1,101 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_log_referer</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_log_referer</h1> + +This module is contained in the <code>mod_log_referer.c</code> file, and is not +compiled in by default. It provides for logging of the documents which +reference documents on the server. + +<h2>Log file format</h2> +The log file contains a separate line for each refer. Each line has the +format +<blockquote><em>uri</em> <code>-></code> <em>document</em></blockquote> +where <em>uri</em> is the (%-escaped) URI for the document that references +the one requested by the client, and <em>document</em> is the (%-decoded) +local URL to the document being referred to. + + +<h2>Directives</h2> +<ul> +<li><A HREF="#refererignore">RefererIgnore</A> +<li><A HREF="#refererlog">RefererLog</A> +</ul> +<hr> + + +<h2><A name="refererignore">RefererIgnore</A></h2> +<!--%plaintext <?INDEX {\tt RefererIgnore} directive> --> +<strong>Syntax:</strong> RefererIgnore <em>string string ...</em><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_log_referer<p> + +The RefererIgnore directive adds to the list of strings to ignore in +Referer headers. If any of the strings in the list is contained in +the Referer header, then no referrer information will be logged for the +request. Example: +<blockquote><code>RefererIgnore www.ncsa.uiuc.edu</code></blockquote> +This avoids logging references from www.ncsa.uiuc.edu. +<p><hr> + + +<h2><A name="refererlog">RefererLog</A></h2> +<!--%plaintext <?INDEX {\tt RefererLog} directive> --> +<strong>Syntax:</strong> RefererLog <em>file-pipe</em><br> +<strong>Default:</strong> <code>RefererLog logs/referer_log</code><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Extension<br> +<strong>Module:</strong> mod_log_referer<p> + +The RefererLog directive sets the name of the file to which the server will +log the Referer header of incoming requests. <em>File-pipe</em> is one +of +<dl><dt>A filename +<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. +<dt> `|' followed by a command +<dd>A program to receive the referrer log information on its standard input. +Note the a new program will not be started for a VirtualHost if it inherits +the RefererLog from the main server. +</dl> +<strong>Security:</strong> if a program is used, then it will be +run under the user who started httpd. This will be root if the server +was started by root; be sure that the program is secure.<p> + +<strong>Security:</strong> See the <A +HREF="../misc/security_tips.html">security tips</A> document for +details on why your security could be compromised if the directory +where logfiles are stored is writable by anyone other than the user +that starts the server.<P> + +This directive is provided for compatibility with NCSA 1.4.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html new file mode 100644 index 00000000000..aaf392a3e4a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html @@ -0,0 +1,247 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_mime</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_mime</h1> + +This module is contained in the <code>mod_mime.c</code> file, and is +compiled in by default. It provides for determining the types of files +from the filename. + +<h2>Summary</h2> + +This module is used to determine various bits of "meta information" +about documents. This information relates to the content of the +document and is returned to the browser or used in content-negotiation +within the server. In addition, a "handler" can be set for a document, +which determines how the document will be processed within the server. + +<P> + +The directives <A HREF="#addencoding">AddEncoding</A>, <A +HREF="#addhandler">AddHandler</A>, <A +HREF="#addlanguage">AddLanguage</A> and <A HREF="#addtype">AddType</A> +are all used to map file extensions onto the meta-information for that +file. Respectively they set the content-encoding, handler, +content-language and mime-type (content-type) of documents. The +directive <A HREF="#typesconfig">TypesConfig</A> is used to specify a +file which also maps extensions onto mime types. The directives <A +HREF="#forcetype">ForceType</A> and <A +HREF="#sethandler">SetHandler</A> are used to associated all the files +in a given location (e.g. a particular directory) onto a particular +mime type or handler. + +<P> + +Files can have more than one extension, and the order of the +extensions is normally irrelevant. For example, if the file +<CODE>welcome.html.fr</CODE> maps onto content type text/html and +language French then the file <CODE>welcome.fr.html</CODE> will map +onto exactly the same information. The only exception to this is if an +extension is given which Apache does not know how to handle. In this +case it will "forget" about any information it obtained from +extensions to the left of the unknown extension. So, for example, if +the extensions fr and html are mapped to the appropriate language and +type but extension xxx is not assigned to anything, then the file +<CODE>welcome.fr.xxx.html</CODE> will be associated with content-type +text/html but <i>no</i> language. + +<P> + +<h2> Directives</h2> +<ul> +<li><A HREF="#addencoding">AddEncoding</A> +<li><A HREF="#addhandler">AddHandler</A> +<li><A HREF="#addlanguage">AddLanguage</A> +<li><A HREF="#addtype">AddType</A> +<li><A HREF="#forcetype">ForceType</A> +<li><A HREF="#sethandler">SetHandler</A> +<li><A HREF="#typesconfig">TypesConfig</A> +</ul> +<hr> + + +<h2><A name="addencoding">AddEncoding</A></h2> +<!--%plaintext <?INDEX {\tt AddEncoding} directive> --> +<strong>Syntax:</strong> AddEncoding <em>mime-enc extension extension...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<p> + +The AddEncoding directive adds to the list of filename extensions which +filenames may end in for the specified encoding type. <em>Mime-enc</em> +is the mime encoding to use for documents ending in <em>extension</em>. +Example: +<blockquote><code> +AddEncoding x-gzip gz<br> +AddEncoding x-compress Z +</code></blockquote> + +This will cause files ending in .gz to be marked as encoded using the x-gzip +encoding, and .Z files to be marked as encoded with x-compress.<p><hr> + +<h2><a name="addhandler">AddHandler</a></h2> + +<strong>Syntax:</strong> AddHandler <em>handler-name extension extension...</em><br> +<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<br> +<strong>Compatibility:</strong> AddHandler is only available in Apache +1.1 and later<p> + +<p>AddHandler maps the filename extensions <em>extension</em> to the +<a href="../handler.html">handler</a> +<em>handler-name</em>. For example, to activate CGI scripts +with the file extension "<code>.cgi</code>", you might use: +<pre> + AddHandler cgi-script cgi +</pre> + +<p>Once that has been put into your srm.conf or httpd.conf file, any +file ending with "<code>.cgi</code>" will be treated as a CGI +program.</p> +<HR> + +<h2><A name="addlanguage">AddLanguage</A></h2> +<!--%plaintext <?INDEX {\tt AddLanguage} directive> --> +<strong>Syntax:</strong> AddLanguage <em>mime-lang extension extension...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<p> + +The AddLanguage directive adds to the list of filename extensions which +filenames may end in for the specified content language. <em>Mime-lang</em> +is the mime language of files with names ending <em>extension</em>, +after any content encoding extensions have been removed. Example: +<blockquote><code> +AddEncoding x-compress Z<br> +AddLanguage en .en<br> +AddLanguage fr .fr<br> +</code></blockquote> + +Then the document <code>xxxx.en.Z</code> will be treated as being a compressed +English document. Although the content language is reported to the client, +the browser is unlikely to use this information. The AddLanguage directive +is more useful for content negotiation, where the server returns one +from several documents based on the client's language preference.<p><hr> + +<h2><A name="addtype">AddType</A></h2> +<!--%plaintext <?INDEX {\tt AddType} directive> --> +<strong>Syntax:</strong> AddType <em>mime-type extension extension...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<p> + +The AddType directive adds to the list of filename extensions which +filenames may end in for the specified content type. <em>Mime-enc</em> +is the mime type to use for documents ending in <em>extension</em>. +after content-encoding and language extensions have been removed. Example: +<blockquote><code> +AddType image/gif GIF +</code></blockquote> +It is recommended that new mime types be added using the AddType directive +rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<p> +Note that, unlike the NCSA httpd, this directive cannot be used to set the +type of particular files.<p><hr> + +<h2><a name="forcetype">ForceType</a></h2> + +<strong>Syntax:</strong> ForceType <em>media type</em><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<br> +<strong>Compatibility:</strong> ForceType is only available in Apache +1.1 and later.<p> + +<p>When placed into an <code>.htaccess</code> file or a +<code><Directory></code> or <code><Location></code> section, +this directive forces all matching files to be served +as the content type given by <em>media type</em>. For example, if you +had a directory full of GIF files, but did not want to label them all with +".gif", you might want to use: +<pre> + ForceType image/gif +</pre> +<p>Note that this will override any filename extensions that might +media type.</p> + +<h2><a name="sethandler">SetHandler</a></h2> + +<strong>Syntax:</strong> SetHandler <em>handler-name</em><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<br> +<strong>Compatibility:</strong> SetHandler is only available in Apache +1.1 and later.<p> + +<p>When placed into an <code>.htaccess</code> file or a +<code><Directory></code> or <code><Location></code> section, +this directive forces all matching files to be parsed through the +<a href="../handler.html">handler</a> +given by <em>handler-name</em>. For example, if you had a +directory you wanted to be parsed entirely as imagemap rule files, +regardless of extension, you might put the following into an +<code>.htaccess</code> file in that directory: +<pre> + SetHandler imap-file +</pre> + +<p>Another example: if you wanted to have the server display a status +report whenever a URL of <code>http://servername/status</code> was +called, you might put the following into access.conf: +<pre> + <Location /status> + SetHandler server-status + </Location> +</pre> +<HR> + +<h2><A name="typesconfig">TypesConfig</A></h2> +<!--%plaintext <?INDEX {\tt TypesConfig} directive> --> +<strong>Syntax:</strong> TypesConfig <em>filename</em><br> +<strong>Default:</strong> <code>TypesConfig conf/mime.types</code><br> +<Strong>Context:</strong> server config<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime<p> + +The TypesConfig directive sets the location of the mime types configuration +file. <em>Filename</em> is relative to the +<A HREF="core.html#serverroot">ServerRoot</A>. This file sets the default list of +mappings from filename extensions to content types; changing this file is not +recommended. Use the <A HREF="#addtype">AddType</A> directive instead. The +file contains lines in the format of the arguments to an AddType command: +<blockquote><em>mime-type extension extension ...</em></blockquote> +The extensions are lower-cased. Blank lines, and lines beginning with a hash +character (`#') are ignored.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html new file mode 100644 index 00000000000..94cef4e5ac3 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html @@ -0,0 +1,160 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_negotiation</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_negotiation</h1> + +This module is contained in the <code>mod_negotiation.c</code> file, +and is compiled in by default. It provides for <A +HREF="../content-negotiation.html">content negotiation</A>. + +<h2>Summary</h2> +Content negotiation, or more accurately content selection, is the +selection of the document that best matches the clients +capabilities, from one of several available documents. +There are two implementations of this. +<ul> +<li> A type map (a file with the handler <code>type-map</code>) +which explicitly lists the files containing the variants. +<li> A MultiViews search (enabled by the MultiViews +<A HREF="core.html#options">Option</A>, where the server does an implicit +filename pattern match, and choose from amongst the results. +</ul> + +<h3>Type maps</h3> +A type map has the same format as RFC822 mail headers. It contains document +descriptions separated by blank lines, with lines beginning with a hash +character ('#') treated as comments. A document description consists of +several header records; records may be continued on multiple lines if the +continuation lines start with spaces. The leading space will be deleted +and the lines concatenated. A header record consists of a keyword +name, which always ends in a colon, followed by a value. Whitespace is allowed +between the header name and value, and between the tokens of value. + +The headers allowed are: + +<dl> +<dt>Content-Encoding: +<dd>The encoding of the file. Currently only two encodings are recognized +by http; <code>x-compress</code> for compressed files, and <code>x-gzip</code> +for gzipped files. +<dt>Content-Language: +<dd>The language of the variant, as an Internet standard language code, such +as <code>en</code>. +<dt>Content-Length: +<dd>The length of the file, in bytes. If this header is not present, then +the actual length of the file is used. +<dt>Content-Type: +<dd>The MIME media type of the document, with optional parameters. +parameters are separated from the media type and from one another by +semi-colons. Parameter syntax is name=value; allowed parameters are: +<dl> +<dt>level +<dd>the value is an integer, which specifies the version of the media type. +For <code>text/html</code> this defaults to 2, otherwise 0. +<dt>qs +<dd>the value is a floating-point number with value between 0. and 1. +It indications the 'quality' of this variant. +</dl> +Example: +<blockquote><code>Content-Type: image/jpeg; qs=0.8</code></blockquote> +<dt>URI: +<dd>The path to the file containing this variant, relative to the map file. +</dl> + +<h3>MultiViews</h3> +A MultiViews search is enabled by the MultiViews +<A HREF="core.html#options">Option</A>. +If the server receives a request for <code>/some/dir/foo</code> and +<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the +directory looking for all files named <code>foo.*</code>, and effectively +fakes up a type map which names all those files, assigning them the same media +types and content-encodings it would have if the client had asked for +one of them by name. It then chooses the best match to the client's +requirements, and returns that document.<p> + + + +<h2>Directives</h2> +<ul> +<li><A href="#cachenegotiateddocs">CacheNegotiatedDocs</a> +<li><A HREF="#languagepriority">LanguagePriority</A> +</ul> +<hr> + + +<h2><A name="cachenegotiateddocs">CacheNegotiatedDocs</A></h2> +<strong>Syntax:</strong> CacheNegotiatedDocs<br> +<Strong>Context:</strong> server config<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_negotiation<br> +<strong>Compatibility:</strong> CacheNegotiatedDocs is only available +in Apache 1.1 and later.<p> + +<p>If set, this directive allows content-negotiated documents to be +cached by proxy servers. This could mean that clients behind those +proxys could retrieve versions of the documents that are not the best +match for their abilities, but it will make caching more +efficient. +<p> + +This directive only applies to requests which come from HTTP/1.0 browsers. +HTTP/1.1 provides much better control over the caching of negotiated +documents, and this directive has no effect in responses to +HTTP/1.1 requests. + + + +<h2><A name="languagepriority">LanguagePriority</A></h2> +<!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> +<strong>Syntax:</strong> LanguagePriority <em>mime-lang mime-lang...</em><br> +<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<Strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_negotiation<p> + +The LanguagePriority sets the precedence of language variants for the case +where the client does not express a preference, when handling a +MultiViews request. The list of <em>mime-lang</em> are in order of decreasing +preference. Example: + +<blockquote><code>LanguagePriority en fr de</code></blockquote> + +For a request for <code>foo.html</code>, where <code>foo.html.fr</code> +and <code>foo.html.de</code> both existed, but the browser did not express +a language preference, then <code>foo.html.fr</code> would be returned.<p> + +<P> + +Note that this directive only has an effect if a 'best' language +cannot be determined by other any other means. Correctly implemented +HTTP/1.1 requests will mean this directive has no effect. + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_proxy.html b/usr.sbin/httpd/htdocs/manual/mod/mod_proxy.html new file mode 100644 index 00000000000..baf4c4ff65f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_proxy.html @@ -0,0 +1,379 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_proxy</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_proxy</H1> + +This module is contained in the <code>mod_proxy.c</code> file for Apache 1.1.x, +or the <code>modules/proxy</code> subdirectory for Apache 1.2, and +is not compiled in by default. It provides for an <b>HTTP 1.0</b> caching proxy +server. It is only available in Apache 1.1 and later. Common configuration +questions are addressed <a href="#configs">here</a>. + +<h3>Note:</h3> +<p>This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy +stability is <i>greatly</i> improved.<p> + +<h2>Summary</h2> + +This module implements a proxy/cache for Apache. It implements +proxying capability for +<code>FTP</code>, +<code>CONNECT</code> (for SSL), +<code>HTTP/0.9</code>, and +<code>HTTP/1.0</code>. +The module can be configured to connect to other proxy modules for these +and other protocols. + +<h2>Directives</h2> +<ul> +<li><a href="#proxyrequests">ProxyRequests</a> +<li><a href="#proxyremote">ProxyRemote</a> +<li><a href="#proxypass">ProxyPass</a> +<li><a href="#proxyblock">ProxyBlock</a> +<li><a href="#cacheroot">CacheRoot</a> +<li><a href="#cachesize">CacheSize</a> +<li><a href="#cachemaxexpire">CacheMaxExpire</a> +<li><a href="#cachedefaultexpire">CacheDefaultExpire</a> +<li><a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a> +<li><a href="#cachegcinterval">CacheGcInterval</a> +<li><a href="#cachedirlevels">CacheDirLevels</a> +<li><a href="#cachedirlength">CacheDirLength</a> +<li><a href="#nocache">NoCache</a> +</ul> + +<hr> + +<A name="proxyrequests"><h2>ProxyRequests</h2></A> +<strong>Syntax:</strong> ProxyRequests <em>on/off</em><br> +<strong>Default:</strong> <code>ProxyRequests Off</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> ProxyRequest is only available in +Apache 1.1 and later.<p> + +This allows or prevents Apache from functioning as a proxy +server. Setting ProxyRequests to 'off' does not disable use of the <a +href="#proxypass">ProxyPass</a> directive. + +<A name="proxyremote"><h2>ProxyRemote</h2></A> +<strong>Syntax:</strong> ProxyRemote <em><match> <remote-server></em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> ProxyRemote is only available in +Apache 1.1 and later.<p> + +This defines remote proxies to this proxy. <match> is either the +name of a URL-scheme that the remote server supports, or a partial URL +for which the remote server should be used, or '*' to indicate the +server should be contacted for all requests. <remote-server> is a +partial URL for the remote server. Syntax: + +<pre> + <remote-server> = <protocol>://<hostname>[:port] +</pre> + +<protocol> is the protocol that should be used to communicate +with the remote server; only "http" is supported by this module. + +Example: +<pre> + ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000 + ProxyRemote * http://cleversite.com + ProxyRemote ftp http://ftpproxy.mydomain.com:8080 +</pre> + +In the last example, the proxy will forward FTP requests, encapsulated +as yet another HTTP proxy request, to another proxy which can handle +them. + +<A name="proxypass"><h2>ProxyPass</h2></A> +<strong>Syntax:</strong> ProxyPass <em><path> <url></em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> ProxyPass is only available in +Apache 1.1 and later.<p> + +This directive allows remote servers to be mapped into the space of the local +server; the local server does not act as a proxy in the conventional sense, +but appears to be a mirror of the remote server. <path> is the name of +a local virtual path; <url> is a partial URL for the remote server. + +Suppose the local server has address http://wibble.org; then +<pre> + ProxyPass /mirror/foo http://foo.com +</pre> +Will cause a local request for the http://wibble.org/mirror/foo/bar to be +internally converted into a proxy request to http://foo.com/bar + +<A name="proxyblock"><h2>ProxyBlock</h2></A> +<strong>Syntax:</strong> ProxyBlock <em><word/host/domain list></em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> ProxyBlock is only available in +Apache 1.2 and later.<p> + +The ProxyBlock directive specifies a list of words, hosts and/or domains, +separated by spaces. HTTP, HTTPS, and FTP document requests to matched words, +hosts or domains are <em>blocked</em> by the proxy server. The proxy module +will also attempt to determine IP addresses of list items which may be +hostnames during startup, and cache them for match test as well. Example: + +<pre> + ProxyBlock joes_garage.com some_host.co.uk rocky.wotsamattau.edu +</pre> + +'rocky.wotsamattau.edu' would also be matched if referenced by IP address.<p> + +Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p> + +Note also that + +<pre> +ProxyBlock * +</pre> + +blocks connections to all sites. + +<A name="cacheroot"><h2>CacheRoot</h2></A> +<strong>Syntax:</strong> CacheRoot <em><directory></em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheRoot is only available in +Apache 1.1 and later.<p> + +Sets the name of the directory to contain cache files; this must be +writable +by the httpd server. + +<A name="cachesize"><h2>CacheSize</h2></A> +<strong>Syntax:</strong> CacheSize <em><size></em><br> +<strong>Default:</strong> <code>CacheSize 5</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheSize is only available in +Apache 1.1 and later.<p> + +Sets the desired space usage of the cache, in Kb (1024 byte units). Although +usage may grow above this setting, the garbage collection will delete files +until the usage is at or below this setting. + +<A name="cachegcinterval"><h2>CacheGcInterval</h2></A> +<strong>Syntax:</strong> CacheGcInterval <em><time></em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheGcinterval is only available in +Apache 1.1 and later.<p> + +Check the cache every <time> hours, and delete files if the space +usage is greater than that set by CacheSize. + +<A name="cachemaxexpire"><h2>CacheMaxExpire</h2></A> +<strong>Syntax:</strong> CacheMaxExpire <em><time></em><br> +<strong>Default:</strong> <code>CacheMaxExpire 24</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheMaxExpire is only available in +Apache 1.1 and later.<p> + +Cachable HTTP documents will be retained for at most <time> hours without +checking the origin server. Thus documents can be at most <time> +hours out of date. This restriction is enforced even if an expiry date +was supplied with the document. + +<A name="cachelastmodifiedfactor"><h2>CacheLastModifiedFactor</h2></A> +<strong>Syntax:</strong> CacheLastModifiedFactor <em><factor></em><br> +<strong>Default:</strong> <code>CacheLastModifiedFactor 0.1</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheLastModifiedFactor is only available in +Apache 1.1 and later.<p> + +If the origin HTTP server did not supply an expiry date for the +document, then estimate one using the formula +<pre> + expiry-period = time-since-last-modification * <factor> +</pre> +For example, if the document was last modified 10 hours ago, and +<factor> is 0.1, then the expiry period will be set to 10*0.1 = 1 hour. + +<p>If the expiry-period would be longer than that set by CacheMaxExpire, +then the latter takes precedence. + +<A name="cachedirlevels"><h2>CacheDirLevels</h2></A> +<strong>Syntax:</strong> CacheDirLevels <em><levels></em><br> +<strong>Default:</strong> <code>CacheDirLevels 3</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheDirLevels is only available in +Apache 1.1 and later.<p> + +CacheDirLevels sets the number of levels of subdirectories in the cache. +Cached data will be saved this many directory levels below CacheRoot. + +<A name="cachedirlength"><h2>CacheDirLength</h2></A> +<strong>Syntax:</strong> CacheDirLength <em><length></em><br> +<strong>Default:</strong> <code>CacheDirLength 1</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheDirLength is only available in +Apache 1.1 and later.<p> + +CacheDirLength sets the number of characters in proxy cache subdirectory names. + +<A name="cachedefaultexpire"><h2>CacheDefaultExpire</h2></A> +<strong>Syntax:</strong> CacheDefaultExpire <em><time></em><br> +<strong>Default:</strong> <code>CacheDefaultExpire 1</code><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> CacheDefaultExpire is only available in +Apache 1.1 and later.<p> + +If the document is fetched via a protocol that does not support expiry times, +then use <time> hours as the expiry time. +<a href="#cachemaxexpire">CacheMaxExpire</a> does <strong>not</strong> +override. + +<A name="nocache"><h2>NoCache</h2></A> +<strong>Syntax:</strong> NoCache <em><word/host/domain list></em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_proxy<br> +<strong>Compatibility:</strong> NoCache is only available in +Apache 1.1 and later.<p> + +The NoCache directive specifies a list of words, hosts and/or domains, separated +by spaces. HTTP and non-passworded FTP documents from matched words, hosts or +domains are <em>not</em> cached by the proxy server. The proxy module will +also attempt to determine IP addresses of list items which may be hostnames +during startup, and cache them for match test as well. Example: + +<pre> + NoCache joes_garage.com some_host.co.uk bullwinkle.wotsamattau.edu +</pre> + +'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP +address.<p> + +Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.<p> + +Note also that + +<pre> +NoCache * +</pre> + +disables caching completely.<p> + +<hr> + +<a name="configs"><h2>Common configuration topics</h2></a> + +<ul> +<li><a href="#access">Controlling access to your proxy</a> +<li><a href="#shortname">Using Netscape hostname shortcuts</a> +<li><a href="#mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a> +<li><a href="#startup">Why does Apache start more slowly when using the + proxy module?</a> +<li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a> +</ul> + +<h2><a name="access">Controlling access to your proxy</a></h2> + +You can control who can access your proxy via the normal <Directory> +control block using the following example:<p> + +<pre> +<Directory proxy:*> +<Limit GET PUT POST DELETE CONNECT OPTIONS> +order deny,allow +deny from [machines you'd like *not* to allow by IP address or name] +allow from [machines you'd like to allow by IP address or name] +</Limit> +</Directory> +</pre><p> + +A <Files> block will also work, and is the only method known to work +for all possible URLs in Apache versions earlier than 1.2b10.<p> + +<h2><a name="shortname">Using Netscape hostname shortcuts</a></h2> + +There is an optional patch to the proxy module to allow Netscape-like +hostname shortcuts to be used. It's available +<a href="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch"> +here</a>.<p> + +<h2><a name="mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a></h2> + +You probably don't have that particular file type defined as +<i>application/octet-stream</i> in your proxy's mime.types configuration +file. A useful line can be<p> + +<pre> +application/octet-stream bin dms lha lzh exe class tgz taz +</pre> + +<h2><a name="startup">Why does Apache start more slowly when using the + proxy module?</a></h2> + +If you're using the <code>ProxyBlock</code> or <code>NoCache</code> +directives, hostnames' IP addresses are looked up and cached during +startup for later match test. This may take a few seconds (or more) +depending on the speed with which the hostname lookups occur.<p> + +<h2><a name="socks">Can I use the Apache proxy module with my SOCKS proxy?</a></h2> + +Yes. Just build Apache with the rule <code>SOCKS4=yes</code> in your +<i>Configuration</i> file, and follow the instructions there. SOCKS5 +capability can be added in a similar way (there's no <code>SOCKS5</code> +rule yet), so use the <code>EXTRA_LFLAGS</code> definition, or build Apache +normally and run it with the <i>runsocks</i> wrapper provided with SOCKS5, +if your OS supports dynamically linked libraries.<p> + +Some users have reported problems when using SOCKS version 4.2 on Solaris. +The problem was solved by upgrading to SOCKS 4.3.<p> + +Remember that you'll also have to grant access to your Apache proxy machine by +permitting connections on the appropriate ports in your SOCKS daemon's +configuration.<p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html new file mode 100644 index 00000000000..44ed3239cf2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html @@ -0,0 +1,1231 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<!--%hypertext --> +<!-- mod_rewrite.html --> +<!-- Documentation for the mod_rewrite Apache module --> +<html> +<head> +<title>Apache module mod_rewrite</title> +</head> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<h1 ALIGN="CENTER">Module mod_rewrite</h1> + +This module is contained in the <code>mod_rewrite.c</code> file, with Apache +1.2 and later. It provides a rule-based rewriting engine to rewrite requested +URLs on the fly. <code>mod_rewrite</code> is not compiled into the server by +default. To use <code>mod_rewrite</code> you have to enable the following line +in the server build Configuration file: +<pre> + Module rewrite_module mod_rewrite.o +</pre> + +<h2>Summary</h2> + +This module uses a rule-based rewriting engine (based on a +regular-expression parser) to rewrite requested URLs on the fly. + +<p> +It supports an unlimited number of additional rule conditions (which can +operate on a lot of variables, including HTTP headers) for granular +matching and external database lookups (either via plain text +tables, DBM hash files or external processes) for advanced URL +substitution. + +<p> +It operates on the full URLs (including the PATH_INFO part) both in per-server +context (httpd.conf) and per-dir context (.htaccess) and even can generate +QUERY_STRING parts on result. The rewritten result can lead to internal +sub-processing, external request redirection or to internal proxy throughput. + +<p> +This module was originally written in April 1996 and +gifted exclusively to the The Apache Group in July 1997 by +<p> +<blockquote> + <i>Ralf S. Engelschall</i><br> + <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br> + <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a> +</blockquote> + +<!--%hypertext --> +<HR> +<!--/%hypertext --> + +<p> +<h2>Directives</h2> + +<ul> + <li><a href="#RewriteEngine">RewriteEngine</a> + <li><a href="#RewriteOptions">RewriteOptions</a> + <li><a href="#RewriteLog">RewriteLog</a> + <li><a href="#RewriteLogLevel">RewriteLogLevel</a> + <li><a href="#RewriteMap">RewriteMap</a> + <li><a href="#RewriteBase">RewriteBase</a> + <li><a href="#RewriteCond">RewriteCond</a> + <li><a href="#RewriteRule">RewriteRule</a> +</ul> + +<!--%hypertext --> +<hr> +<!--/%hypertext --> + + +<center> +<a name="Configuration"> +<h1>Configuration Directives</h1> +</a> +</center> + +<a name="RewriteEngine"><h3>RewriteEngine</h3></a> +<strong>Syntax:</strong> <code>RewriteEngine</code> {<code>on,off</code>}<br> +<strong>Default:</strong> <strong><code>RewriteEngine off</code></strong><br> +<strong>Context:</strong> server config, virtual host, per-directory config<br> +<p> + +The <tt>RewriteEngine</tt> directive enables or disables the +runtime rewriting engine. If it is set to <code>off</code> this module does +no runtime processing at all. It does not even update the <tt>SCRIPT_URx</tt> +environment variables. + +<p> +Use this directive to disable the module instead of commenting out +all <tt>RewriteRule</tt> directives! + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteOptions"><h3>RewriteOptions</h3></a> +<strong>Syntax:</strong> <code>RewriteOptions</code> <em>Option</em> ...<br> +<strong>Default:</strong> -<em>None</em>-<br> +<strong>Context:</strong> server config, virtual host, per-directory config<br> +<p> + +The <tt>RewriteOption</tt> directive sets some special options for the +current per-server or per-directory configuration. The <em>Option</em> +strings can be one of the following: + +<ul> +<li>'<strong><code>inherit</code></strong>'<br> + This forces the current configuration to inherit the configuration of the + parent. In per-virtual-server context this means that the maps, + conditions and rules of the main server gets inherited. In per-directory + context this means that conditions and rules of the parent directory's + <tt>.htaccess</tt> configuration gets inherited. +</ul> + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteLog"><h3>RewriteLog</h3></a> +<strong>Syntax:</strong> <code>RewriteLog</code> <em>Filename</em><br> +<strong>Default:</strong> -<em>None</em>-<br> +<strong>Context:</strong> server config, virtual host<br> +<p> + +The <tt>RewriteLog</tt> directive sets the name of the file to which the +server logs any rewriting actions it performs. If the name does not begin +with a slash ('<tt>/</tt>') then it is assumed to be relative to the +<em>Server Root</em>. The directive should occur only once per server +config. + +<p> +<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> +<tr><td> +To disable the logging of rewriting actions it is not recommended +to set <em>Filename</em> +to <code>/dev/null</code>, because although the rewriting engine does +not create output to a logfile it still creates the logfile +output internally. <b>This will slow down the server with no advantage to the +administrator!</b> +To disable logging either remove or comment out the +<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>! +</td></tr> +</table> + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +SECURITY: See the <a +href="../misc/security_tips.html">Apache Security +Tips</a> document for details on why your security could be compromised if the +directory where logfiles are stored is writable by anyone other than the user +that starts the server. +</td></tr> +</table> + +<p> +<b>Example:</b> +<blockquote> +<pre> +RewriteLog "/usr/local/var/apache/logs/rewrite.log" +</pre> +</blockquote> + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteLogLevel"><h3>RewriteLogLevel</h3></a> +<strong>Syntax:</strong> <code>RewriteLogLevel</code> <em>Level</em><br> +<strong>Default:</strong> <strong><code>RewriteLogLevel 0</code></strong><br> +<strong>Context:</strong> server config, virtual host<br> +<p> + +The <tt>RewriteLogLevel</tt> directive set the verbosity level of the rewriting +logfile. The default level 0 means no logging, while 9 or more means +that practically all actions are logged. + +<p> +To disable the logging of rewriting actions simply set <em>Level</em> to 0. +This disables all rewrite action logs. + +<p> +<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> +<tr><td> +<b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache +server dramatically! Use the rewriting logfile only for debugging or at least +at <em>Level</em> not greater than 2! +</td></tr> +</table> + + +<p> +<b>Example:</b> +<blockquote> +<pre> +RewriteLogLevel 3 +</pre> +</blockquote> + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteMap"><h3>RewriteMap</h3></a> +<strong>Syntax:</strong> <code>RewriteMap</code> <em>Mapname</em> <code>{txt,dbm,prg}:</code><em>Filename</em><br> +<strong>Default:</strong> not used per default<br> +<strong>Context:</strong> server config, virtual host<br> +<p> + +The <tt>RewriteMap</tt> directive defines an external <em>Rewriting Map</em> +which can be used inside rule substitution strings by the mapping-functions +to insert/substitute fields through a key lookup. +<p> + +The <a name="mapfunc"><em>Mapname</em></a> is the name of the map and will +be used to specify a mapping-function for the substitution strings of a +rewriting rule via + +<blockquote><strong> +<code>${</code> <em>Mapname</em> <code>:</code> <em>LookupKey</em> +<code>|</code> <em>DefaultValue</em> <code>}</code> +</strong></blockquote> + +When such a directive occurs the map <em>Mapname</em> +is consulted and the key <em>LookupKey</em> is looked-up. If the key is +found, the map-function directive is substituted by <em>SubstValue</em>. If +the key is not found then it is substituted by <em>DefaultValue</em>. + +<p> +The <em>Filename</em> must be a valid Unix filepath, containing one +of the following formats: + +<ol> +<li><b>Plain Text Format</b> + <p> + This is a ASCII file which contains either blank lines, comment lines + (starting with a '#' character) or + + <blockquote><strong> + <em>MatchingKey</em> <em>SubstValue</em> + </strong></blockquote> + + pairs - one per line. You can create such files either manually, + using your favorite editor, or by using the programs + <tt>mapcollect</tt> and <tt>mapmerge</tt> from the <tt>support</tt> + directory of the <b>mod_rewrite</b> distribution. + <p> + To declare such a map prefix, <em>Filename</em> with a <code>txt:</code> + string as in the following example: + +<p> +<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> +<tr><td><pre> +# +# map.real-to-user -- maps realnames to usernames +# + +Ralf.S.Engelschall rse # Bastard Operator From Hell +Dr.Fred.Klabuster fred # Mr. DAU +</pre></td></tr> +</table> + +<p> +<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> +<tr><td><pre> +RewriteMap real-to-host txt:/path/to/file/map.real-to-user +</pre></td></tr> +</table> + +<p> +<li><b>DBM Hashfile Format</b> + <p> + This is a binary NDBM format file containing the + same contents as the <em>Plain Text Format</em> files. You can create + such a file with any NDBM tool or with the <tt>dbmmanage</tt> program + from the <tt>support</tt> directory of the Apache distribution. + <p> + To declare such a map prefix <em>Filename</em> with a <code>dbm:</code> + string. +<p> +<li><b>Program Format</b> + <p> + This is a Unix executable, not a lookup file. To create it you can use + the language of your choice, but the result has to be a run-able Unix + binary (i.e. either object-code or a script with the + magic cookie trick '<tt>#!/path/to/interpreter</tt>' as the first line). + <p> + This program gets started once at startup of the Apache servers and then + communicates with the rewriting engine over its <tt>stdin</tt> and + <tt>stdout</tt> file-handles. For each map-function lookup it will + receive the key to lookup as a newline-terminated string on + <tt>stdin</tt>. It then has to give back the looked-up value as a + newline-terminated string on <tt>stdout</tt> or the four-character string + ``<tt>NULL</tt>'' if it fails (i.e. there is no corresponding value + for the given key). A trivial program which will implement a 1:1 map + (i.e. key == value) could be: + <p> +<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> +<tr><td><pre> +#!/usr/bin/perl +$| = 1; +while (<STDIN>) { + # ...here any transformations + # or lookups should occur... + print $_; +} +</pre></td></tr> +</table> + <p> + <b>But be very careful:</b><br> + <ol> + <li>``<i>Keep the program simple, stupid</i>'' (KISS), because + if this program hangs it will lead to a hang of the Apache server + when the rule occurs. + <li>Avoid one common mistake: never do buffered I/O on <tt>stdout</tt>! + This will cause a deadloop! Hence the ``<tt>$|=1</tt>'' in the above + example... + </ol> + <p> + To declare such a map prefix <em>Filename</em> with a <code>prg:</code> + string. +</ol> + +The <tt>RewriteMap</tt> directive can occur more than once. For each +mapping-function use one <tt>RewriteMap</tt> directive to declare its +rewriting mapfile. While you cannot <b>declare</b> a map in per-directory +context it is of course possible to <b>use</b> this map in per-directory +context. + +<p> +<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> +<tr><td> +For plain text and DBM format files the looked-up keys are cached in-core +until the <tt>mtime</tt> of the mapfile changes or the server does a +restart. This way you can have map-functions in rules which are used +for <b>every</b> request. This is no problem, because the external lookup +only happens once! +</td></tr> +</table> + + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteBase"><h3>RewriteBase</h3></a> +<strong>Syntax:</strong> <code>RewriteBase</code> <em>BaseURL</em><br> +<strong>Default:</strong> <em>default is the physical directory path</em><br> +<strong>Context:</strong> per-directory config<br> +<p> + +The <tt>RewriteBase</tt> directive explicitly sets the base URL for +per-directory rewrites. As you will see below, <tt>RewriteRule</tt> can be +used in per-directory config files (<tt>.htaccess</tt>). There it will act +locally, i.e. the local directory prefix is stripped at this stage of +processing and your rewriting rules act only on the remainder. At the end +it is automatically added. + +<p> +When a substitution occurs for a new URL, this module has to +re-inject the URL into the server processing. To be able to do this it needs +to know what the corresponding URL-prefix or URL-base is. By default this +prefix is the corresponding filepath itself. <b>But at most websites URLs are +<b>NOT</b> directly related to physical filename paths, so this assumption +will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt> +directive to specify the correct URL-prefix. + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +So, if your webserver's URLs are <b>not</b> directly +related to physical file paths, you have to use <tt>RewriteBase</tt> in every +<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt> +directives. +</td></tr> +</table> + +<p> +<b>Example:</b> + +<blockquote> + Assume the following per-directory config file: + +<p> +<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> +<tr><td><pre> +# +# /abc/def/.htaccess -- per-dir config file for directory /abc/def +# Remember: /abc/def is the physical path of /xyz, i.e. the server +# has a 'Alias /xyz /abc/def' directive e.g. +# + +RewriteEngine On + +# let the server know that we are reached via /xyz and not +# via the physical path prefix /abc/def +RewriteBase /xyz + +# now the rewriting rules +RewriteRule ^oldstuff\.html$ newstuff.html +</pre></td></tr> +</table> + +<p> +In the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly +rewritten to the physical file <tt>/abc/def/newstuff.html</tt>. + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +<font size=-1> +<b>For the Apache hackers:</b><br> +The following list gives detailed information about the internal +processing steps: + +<p> +<pre> +Request: + /xyz/oldstuff.html + +Internal Processing: + /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) + /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) + /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) + /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) + +Result: + /abc/def/newstuff.html +</pre> + +This seems very complicated but is the correct Apache internal processing, +because the per-directory rewriting comes too late in the process. So, +when it occurs the (rewritten) request has to be re-injected into the Apache +kernel! BUT: While this seems like a serious overhead, it really isn't, because +this re-injection happens fully internal to the Apache server and the same +procedure is used by many other operations inside Apache. So, you can be +sure the design and implementation is correct. +</font> +</td></tr> +</table> + +</blockquote> + + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteCond"><h3>RewriteCond</h3></a> +<strong>Syntax:</strong> <code>RewriteCond</code> <em>TestString</em> <em>CondPattern</em><br> +<strong>Default:</strong> -<em>None</em>-<br> +<strong>Context:</strong> server config, virtual host, per-directory config<br> +<p> + +The <tt>RewriteCond</tt> directive defines a rule condition. Precede a +<tt>RewriteRule</tt> directive with one or more <tt>RewriteCond</tt> +directives. + +The following rewriting rule is only used if its pattern matches the current +state of the URI <b>AND</b> if these additional conditions apply, too. + +<p> +<em>TestString</em> is a string which contains server-variables of the form + +<blockquote><strong> +<tt>%{</tt> <em>NAME_OF_VARIABLE</em> <tt>}</tt> +</strong></blockquote> + +where <em>NAME_OF_VARIABLE</em> can be a string +of the following list: + +<p> +<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> +<tr> +<td valign=top> +<b>HTTP headers:</b><p> +<font size=-1> +HTTP_USER_AGENT<br> +HTTP_REFERER<br> +HTTP_COOKIE<br> +HTTP_FORWARDED<br> +HTTP_HOST<br> +HTTP_PROXY_CONNECTION<br> +HTTP_ACCEPT<br> +</font> +</td> + +<td valign=top> +<b>connection & request:</b><p> +<font size=-1> +REMOTE_ADDR<br> +REMOTE_HOST<br> +REMOTE_USER<br> +REMOTE_IDENT<br> +REQUEST_METHOD<br> +SCRIPT_FILENAME<br> +PATH_INFO<br> +QUERY_STRING<br> +AUTH_TYPE<br> +</font> +</td> + +</tr> +<tr> + +<td valign=top> +<b>server internals:</b><p> +<font size=-1> +DOCUMENT_ROOT<br> +SERVER_ADMIN<br> +SERVER_NAME<br> +SERVER_PORT<br> +SERVER_PROTOCOL<br> +SERVER_SOFTWARE<br> +SERVER_VERSION<br> +</font> +</td> + +<td valign=top> +<b>system stuff:</b><p> +<font size=-1> +TIME_YEAR<br> +TIME_MON<br> +TIME_DAY<br> +TIME_HOUR<br> +TIME_MIN<br> +TIME_SEC<br> +TIME_WDAY<br> +TIME<br> +</font> +</td> + +<td valign=top> +<b>specials:</b><p> +<font size=-1> +API_VERSION<br> +THE_REQUEST<br> +REQUEST_URI<br> +REQUEST_FILENAME<br> +IS_SUBREQ<br> +</font> +</td> +</tr> +</table> + + +<p> +<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> +<tr><td> +These variables all correspond to the similar named HTTP MIME-headers, C +variables of the Apache server or <tt>struct tm</tt> fields of the Unix +system. +</td></tr> +</table> + +<p> +Special Notes: +<ol> +<li>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same +value, i.e. the value of the <tt>filename</tt> field of the internal +<tt>request_rec</tt> structure of the Apache server. The first name is just the +commonly known CGI variable name while the second is the consistent +counterpart to REQUEST_URI (which contains the value of the <tt>uri</tt> +field of <tt>request_rec</tt>). + +<p> +<li>There is the special format: <tt>%{ENV:variable}</tt> where +<i>variable</i> can be any environment variable. This is looked-up via +internal Apache structures and (if not found there) via <tt>getenv()</tt> from +the Apache server process. + +<p> +<li>There is the special format: <tt>%{HTTP:header}</tt> where +<i>header</i> can be any HTTP MIME-header name. This is looked-up +from the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt> +is the value of the HTTP header ``<tt>Proxy-Connection:</tt>''. + +<p> +<li>There is the special format: <tt>%{LA-U:url}</tt> +for look-aheads like <tt>-U</tt>. This performs a internal sub-request to +look-ahead for the final value of <i>url</i>. + +<p> +<li>There is the special format: <tt>%{LA-F:file}</tt> +for look-aheads like <tt>-F</tt>. This performs a internal sub-request to +look-ahead for the final value of <i>file</i>. +</ol> + +<p> +<em>CondPattern</em> is the condition pattern, i.e. a regular expression +which gets applied to the current instance of the <em>TestString</em>, i.e. +<em>TestString</em> gets evaluated and then matched against +<em>CondPattern</em>. + +<p> +<b>Remember:</b> <em>CondPattern</em> is a standard +<em>Extended Regular Expression</em> with some additions: + +<ol> +<li>You can precede the pattern string with a '<tt>!</tt>' character +(exclamation mark) to specify a <b>non</b>-matching pattern. + +<p> +<li> +There are some special variants of <em>CondPatterns</em>. Instead of real +regular expression strings you can also use one of the following: +<p> +<ul> +<li>'<b><CondPattern</b>' (is lexicographically lower)<br> +Treats the <i>CondPattern</i> as a plain string and compares it +lexicographically to <i>TestString</i> and results in a true expression if +<i>TestString</i> is lexicographically lower then <i>CondPattern</i>. +<p> +<li>'<b>>CondPattern</b>' (is lexicographically greater)<br> +Treats the <i>CondPattern</i> as a plain string and compares it +lexicographically to <i>TestString</i> and results in a true expression if +<i>TestString</i> is lexicographically greater then <i>CondPattern</i>. +<p> +<li>'<b>=CondPattern</b>' (is lexicographically equal)<br> +Treats the <i>CondPattern</i> as a plain string and compares it +lexicographically to <i>TestString</i> and results in a true expression if +<i>TestString</i> is lexicographically equal to <i>CondPattern</i>, i.e the +two strings are exactly equal (character by character). +<p> +<li>'<b>-d</b>' (is <b>d</b>irectory)<br> +Treats the <i>TestString</i> as a pathname and +tests if it exists and is a directory. +<p> +<li>'<b>-f</b>' (is regular <b>f</b>ile)<br> +Treats the <i>TestString</i> as a pathname and +tests if it exists and is a regular file. +<p> +<li>'<b>-s</b>' (is regular file with <b>s</b>ize)<br> +Treats the <i>TestString</i> as a pathname and +tests if it exists and is a regular file with size greater then zero. +<p> +<li>'<b>-l</b>' (is symbolic <b>l</b>ink)<br> +Treats the <i>TestString</i> as a pathname and +tests if it exists and is a symbolic link. +<p> +<li>'<b>-F</b>' (is existing file via subrequest)<br> +Checks if <i>TestString</i> is a valid file and accessible via all the +server's currently-configured access controls for that path. This uses an +internal subrequest to determine the check, so use it with care because it +decreases your servers performance! +<p> +<li>'<b>-U</b>' (is existing URL via subrequest)<br> +Checks if <i>TestString</i> is a valid URL and accessible via all the server's +currently-configured access controls for that path. This uses an internal +subrequest to determine the check, so use it with care because it decreases +your servers performance! +</ul> +<p> +Notice: All of these tests can also be prefixed by a not ('!') character +to negate their meaning. +</ol> + +<p> +Additionally you can set special flags for <em>CondPattern</em> by appending + +<blockquote><strong> +<code>[</code><em>flags</em><code>]</code> +</strong></blockquote> + +as the third argument to the <tt>RewriteCond</tt> directive. <em>Flags</em> +is a comma-separated list of the following flags: + +<ul> +<li>'<strong><code>nocase|NC</code></strong>' (<b>n</b>o <b>c</b>ase)<br> + This makes the condition test case-insensitive, i.e. there is + no difference between 'A-Z' and 'a-z' both in the expanded + <em>TestString</em> and the <em>CondPattern</em>. +<p> +<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br> + Use this to combine rule conditions with a local OR instead of the + implicit AND. Typical example: + <p> +<blockquote><pre> +RewriteCond %{REMOTE_HOST} ^host1.* [OR] +RewriteCond %{REMOTE_HOST} ^host2.* [OR] +RewriteCond %{REMOTE_HOST} ^host3.* +RewriteRule ...some special stuff for any of these hosts... +</pre></blockquote> + Without this flag you had to write down the cond/rule three times. +</ul> + +<p> +<b>Example:</b> +<blockquote> + +To rewrite the Homepage of a site according to the ``<tt>User-Agent:</tt>'' +header of the request, you can use the following: + +<blockquote><pre> +RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* +RewriteRule ^/$ /homepage.max.html [L] + +RewriteCond %{HTTP_USER_AGENT} ^Lynx.* +RewriteRule ^/$ /homepage.min.html [L] + +RewriteRule ^/$ /homepage.std.html [L] +</pre></blockquote> + +Interpretation: If you use Netscape Navigator as your browser (which identifies +itself as 'Mozilla'), then you get the max homepage, which includes +Frames, etc. If you use the Lynx browser (which is Terminal-based), then you +get the min homepage, which contains no images, no tables, etc. If you +use any other browser you get the standard homepage. +</blockquote> + +<p> +<hr noshade size=1> +<p> + +<a name="RewriteRule"><h3>RewriteRule</h3></a> +<strong>Syntax:</strong> <code>RewriteRule</code> <em>Pattern</em> <em>Substitution</em><br> +<strong>Default:</strong> -<em>None</em>-<br> +<strong>Context:</strong> server config, virtual host, per-directory config<br> + +<p> +The <tt>RewriteRule</tt> directive is the real rewriting workhorse. The +directive can occur more than once. Each directive then defines one single +rewriting rule. The <b>definition order</b> of these rules is +<b>important</b>, because this order is used when applying the rules at +run-time. + +<p> +<a name="patterns"><em>Pattern</em></a> can be (for Apache 1.1.x a System +V8 and for Apache 1.2.x a POSIX) <a name="regexp">regular expression</a> +which gets applied to the current URL. Here ``current'' means the value of the +URL when this rule gets applied. This may not be the original requested +URL, because there could be any number of rules before which already matched +and made alterations to it. + +<p> +Some hints about the syntax of regular expressions: + +<p> +<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> +<tr> +<td valign=top> +<pre> +<strong><code>^</code></strong> Start of line +<strong><code>$</code></strong> End of line +<strong><code>.</code></strong> Any single character +<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars +<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars + +<strong><code>?</code></strong> 0 or 1 of the preceding char +<strong><code>*</code></strong> 0 or N of the preceding char +<strong><code>+</code></strong> 1 or N of the preceding char + +<strong><code>\</code></strong>char escape that specific char + (e.g. for specifying the chars "<code>.[]()</code>" etc.) + +<strong><code>(</code></strong>string<strong><code>)</code></strong> Grouping of chars (the <b>N</b>th group can be used on the RHS with <code>$</code><b>N</b>) +</pre> +</td> +</tr> +</table> + +<p> +Additionally the NOT character ('<tt>!</tt>') is a possible pattern +prefix. This gives you the ability to negate a pattern; to say, for instance: ``<i>if +the current URL does <b>NOT</b> match to this pattern</i>''. This can be used +for special cases where it is better to match the negative pattern or as a +last default rule. + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +<b>Notice!</b> When using the NOT character to negate a pattern you cannot +have grouped wildcard parts in the pattern. This is impossible because when +the pattern does NOT match, there are no contents for the groups. In +consequence, if negated patterns are used, you cannot use <tt>$N</tt> in the +substitution string! +</td></tr> +</table> + +<p> +<a name="rhs"><em>Substitution</em></a> of a rewriting rule is the string +which is substituted for (or replaces) the original URL for which +<em>Pattern</em> matched. Beside plain text you can use + +<ol> +<li>pattern-group back-references (<code>$N</code>) +<li>server-variables as in rule condition test-strings (<code>%{VARNAME}</code>) +<li><a href="#mapfunc">mapping-function</a> calls (<code>${mapname:key|default}</code>) +</ol> + +Back-references are <code>$</code><b>N</b> (<b>N</b>=1..9) identifiers which +will be replaced by the contents of the <b>N</b>th group of the matched +<em>Pattern</em>. The server-variables are the same as for the +<em>TestString</em> of a <tt>RewriteCond</tt> directive. The +mapping-functions come from the <tt>RewriteMap</tt> directive and are +explained there. These three types of variables are expanded in the order of +the above list. + +<p> +As already mentioned above, all the rewriting rules are applied to the +<em>Substitution</em> (in the order of definition in the config file). The +URL is <b>completely replaced</b> by the <em>Substitution</em> and the +rewriting process goes on until there are no more rules (unless explicitly +terminated by a <code><b>L</b></code> flag - see below). + +<p> +There is a special substitution string named '<tt>-</tt>' which means: +<b>NO substitution</b>! Sounds silly? No, it is useful to provide rewriting +rules which <b>only</b> match some URLs but do no substitution, e.g. in +conjunction with the <b>C</b> (chain) flag to be able to have more than one +pattern to be applied before a substitution occurs. + +<p> +One more note: You can even create URLs in the substitution string containing +a query string part. Just use a question mark inside the substitution string +to indicate that the following stuff should be re-injected into the +QUERY_STRING. When you want to erase an existing query string, end the +substitution string with just the question mark. + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +<b>Notice</b>: There is a special feature. When you prefix a substitution +field with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then +<b>mod_rewrite</b> automatically strips it out. This auto-reduction on +implicit external redirect URLs is a useful and important feature when +used in combination with a mapping-function which generates the hostname +part. Have a look at the first example in the example section below to +understand this. +<p> +<b>Remember:</b> An unconditional external redirect to your own server will +not work with the prefix <tt>http://thishost</tt> because of this feature. +To achieve such a self-redirect, you have to use the <b>R</b>-flag (see +below). +</td></tr> +</table> + +<p> +Additionally you can set special flags for <em>Substitution</em> by appending + +<blockquote><strong> +<code>[</code><em>flags</em><code>]</code> +</strong></blockquote> + +as the third argument to the <tt>RewriteRule</tt> directive. <em>Flags</em> is a +comma-separated list of the following flags: + +<ul> +<li>'<strong><code>redirect|R</code>[=<i>code</i>]</strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br> + Prefix <em>Substitution</em> + with <code>http://thishost[:thisport]/</code> (which makes the new URL a URI) to + force a external redirection. If no <i>code</i> is given a HTTP response + of 302 (MOVED TEMPORARILY) is used. If you want to use other response + codes in the range 300-400 just specify them as a number or use + one of the following symbolic names: <tt>temp</tt> (default), <tt>permanent</tt>, + <tt>seeother</tt>. + Use it for rules which should + canonicalize the URL and gives it back to the client, e.g. translate + ``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to + <code>/u/</code><em>user</em>, etc.<br> + <p> + <b>Notice:</b> When you use this flag, make sure that the + substitution field is a valid URL! If not, you are redirecting to an + invalid location! And remember that this flag itself only prefixes the + URL with <code>http://thishost[:thisport]/</code>, but rewriting goes on. + Usually you also want to stop and do the redirection immediately. To stop + the rewriting you also have to provide the 'L' flag. +<p> +<li>'<strong><code>forbidden|F</code></strong>' (force URL to be <b>f</b>orbidden)<br> + This forces the current URL to be forbidden, i.e. it immediately sends + back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with + appropriate RewriteConds to conditionally block some URLs. +<p> +<li>'<strong><code>gone|G</code></strong>' (force URL to be <b>g</b>one)<br> + This forces the current URL to be gone, i.e. it immediately sends back a + HTTP response of 410 (GONE). Use this flag to mark no longer existing + pages as gone. +<p> +<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br> + This flag forces the substitution part to be internally forced as a proxy + request and immediately (i.e. rewriting rule processing stops here) put + through the proxy module. You have to make sure that the substitution + string is a valid URI (e.g. typically <tt>http://</tt>) which can + be handled by the Apache proxy module. If not you get an error from + the proxy module. Use this flag to achieve a more powerful implementation + of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map + some remote stuff into the namespace of the local server. + <p> + Notice: <b>You really have to put <tt>ProxyRequests On</tt> into your + server configuration to prevent proxy requests from leading to core-dumps + inside the Apache kernel. If you have not compiled in the proxy module, + then there is no core-dump problem, because mod_rewrite checks for + existence of the proxy module and if lost forbids proxy URLs. </b> +<p> +<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br> + Stop the rewriting process here and + don't apply any more rewriting rules. This corresponds to the Perl + <code>last</code> command or the <code>break</code> command from the C + language. Use this flag to prevent the currently rewritten URL from being + rewritten further by following rules which may be wrong. For + example, use it to rewrite the root-path URL ('<code>/</code>') to a real + one, e.g. '<code>/e/www/</code>'. +<p> +<li>'<strong><code>next|N</code></strong>' (<b>n</b>ext round)<br> + Re-run the rewriting process (starting again with the first rewriting + rule). Here the URL to match is again not the original URL but the URL + from the last rewriting rule. This corresponds to the Perl + <code>next</code> command or the <code>continue</code> command from the C + language. Use this flag to restart the rewriting process, i.e. to + immediately go to the top of the loop. <br> + <b>But be careful not to create a deadloop!</b> +<p> +<li>'<strong><code>chain|C</code></strong>' (<b>c</b>hained with next rule)<br> + This flag chains the current rule with the next rule (which itself can + also be chained with its following rule, etc.). This has the following + effect: if a rule matches, then processing continues as usual, i.e. the + flag has no effect. If the rule does <b>not</b> match, then all following + chained rules are skipped. For instance, use it to remove the + ``<tt>.www</tt>'' part inside a per-directory rule set when you let an + external redirect happen (where the ``<tt>.www</tt>'' part should not to + occur!). +<p> +<li>'<strong><code>type|T</code></strong>=<em>mime-type</em>' (force MIME <b>t</b>ype)<br> + Force the MIME-type of the target file to be <em>mime-type</em>. For + instance, this can be used to simulate the old <tt>mod_alias</tt> + directive <tt>ScriptAlias</tt> which internally forces all files inside + the mapped directory to have a MIME type of + ``<tt>application/x-httpd-cgi</tt>''. +<p> +<li>'<strong><code>nosubreq|NS</code></strong>' (used only if <b>n</b>o internal <b>s</b>ub-request)<br> + This flag forces the rewriting engine to skip a rewriting rule if the + current request is an internal sub-request. For instance, sub-requests + occur internally in Apache when <tt>mod_include</tt> tries to find out + information about possible directory default files (<tt>index.xxx</tt>). + On sub-requests it is not always useful and even sometimes causes a failure to + if the complete set of rules are applied. Use this flag to exclude some rules.<br> + <p> + Use the following rule for your decision: whenever you prefix some URLs + with CGI-scripts to force them to be processed by the CGI-script, the + chance is high that you will run into problems (or even overhead) on sub-requests. + In these cases, use this flag. +<p> +<li>'<strong><code>qsappend|QSA</code></strong>' (<b>q</b>uery <b>s</b>tring + <b>a</b>ppend)<br> + This flag forces the rewriting engine to append a query + string part in the substitution string to the existing one instead of + replacing it. Use this when you want to add more data to the query string + via a rewrite rule. +<p> +<li>'<strong><code>passthrough|PT</code></strong>' (<b>p</b>ass <b>t</b>hrough to next handler)<br> + This flag forces the rewriting engine to set the <code>uri</code> field + of the internal <code>request_rec</code> structure to the value + of the <code>filename</code> field. This flag is just a hack to be able + to post-process the output of <tt>RewriteRule</tt> directives by + <tt>Alias</tt>, <tt>ScriptAlias</tt>, <tt>Redirect</tt>, etc. directives + from other URI-to-filename translators. A trivial example to show the + semantics: + If you want to rewrite <tt>/abc</tt> to <tt>/def</tt> via the rewriting + engine of <tt>mod_rewrite</tt> and then <tt>/def</tt> to <tt>/ghi</tt> + with <tt>mod_alias</tt>: + <pre> + RewriteRule ^/abc(.*) /def$1 [PT] + Alias /def /ghi + </pre> + If you omit the <tt>PT</tt> flag then <tt>mod_rewrite</tt> + will do its job fine, i.e. it rewrites <tt>uri=/abc/...</tt> to + <tt>filename=/def/...</tt> as a full API-compliant URI-to-filename + translator should do. Then <tt>mod_alias</tt> comes and tries to do a + URI-to-filename transition which will not work. + <p> + Notice: <b>You have to use this flag if you want to intermix directives + of different modules which contain URL-to-filename translators</b>. The + typical example is the use of <tt>mod_alias</tt> and + <tt>mod_rewrite</tt>.. +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +<font size=-1> + <b>For the Apache hackers:</b><br> + If the current Apache API had a + filename-to-filename hook additionally to the URI-to-filename hook then + we wouldn't need this flag! But without such a hook this flag is the + only solution. The Apache Group has discussed this problem and will + add such hooks into Apache version 2.0. +</font> +</td></tr> +</table> +<p> +<li>'<strong><code>skip|S</code></strong>=<em>num</em>' (<b>s</b>kip next rule(s))<br> + This flag forces the rewriting engine to skip the next <em>num</em> rules + in sequence when the current rule matches. Use this to make pseudo + if-then-else constructs: The last rule of the then-clause becomes + a <tt>skip=N</tt> where N is the number of rules in the else-clause. + (This is <b>not</b> the same as the 'chain|C' flag!) +<p> +<li>'<strong><code>env|E=</code></strong><i>VAR</i>:<i>VAL</i>' (set <b>e</b>nvironment variable)<br> + This forces an environment variable named <i>VAR</i> to be set to the value + <i>VAL</i>, where <i>VAL</i> can contain regexp backreferences <tt>$N</tt> + which will be expanded. You can use this flag more than once to set more + than one variable. The variables can be later dereferenced at a lot of + situations, but the usual location will be from within XSSI (via + <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>). + But additionally you can also dereference it in a following RewriteCond + pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember + information from URLs. +</ul> + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +Remember: Never forget that <em>Pattern</em> gets applied to a complete URL +in per-server configuration files. <b>But in per-directory configuration +files, the per-directory prefix (which always is the same for a specific +directory!) gets automatically <em>removed</em> for the pattern matching and +automatically <em>added</em> after the substitution has been done.</b> This feature is +essential for many sorts of rewriting, because without this prefix stripping +you have to match the parent directory which is not always possible. +<p> +There is one exception: If a substitution string starts with +``<tt>http://</tt>'' then the directory prefix will be <b>not</b> added and a +external redirect or proxy throughput (if flag <b>P</b> is used!) is forced! +</td></tr> +</table> + +<p> +<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> +<tr><td> +Notice! To enable the rewriting engine for per-directory configuration files +you need to set ``<tt>RewriteEngine On</tt>'' in these files <b>and</b> +``<tt>Option FollowSymLinks</tt>'' enabled. If your administrator has +disabled override of <tt>FollowSymLinks</tt> for a user's directory, then +you cannot use the rewriting engine. This restriction is needed for +security reasons. +</td></tr> +</table> + +<p> +Here are all possible substitution combinations and their meanings: + +<p> +<b>Inside per-server configuration (<tt>httpd.conf</tt>)<br> +for request ``<tt>GET /somepath/pathinfo</tt>'':</b><br> + +<p> +<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> +<tr> +<td> +<pre> +<b>Given Rule</b> <b>Resulting Substitution</b> +---------------------------------------------- ---------------------------------- +^/somepath(.*) otherpath$1 not supported, because invalid! + +^/somepath(.*) otherpath$1 [R] not supported, because invalid! + +^/somepath(.*) otherpath$1 [P] not supported, because invalid! +---------------------------------------------- ---------------------------------- +^/somepath(.*) /otherpath$1 /otherpath/pathinfo + +^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^/somepath(.*) /otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo + +^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo + via external redirection + +^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo + via external redirection + (the [R] flag is redundant) + +^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo + via internal proxy +</pre> +</td> +</tr> +</table> + +<p> +<b>Inside per-directory configuration for <tt>/somepath</tt><br> +(i.e. file <tt>.htaccess</tt> in dir <tt>/physical/path/to/somepath</tt> containing +<tt>RewriteBase /somepath</tt>)<br> for +request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br> + +<p> +<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> +<tr> +<td> +<pre> +<b>Given Rule</b> <b>Resulting Substitution</b> +---------------------------------------------- ---------------------------------- +^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo + +^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo + via external redirection + +^localpath(.*) otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^localpath(.*) /otherpath$1 /otherpath/pathinfo + +^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^localpath(.*) /otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo + +^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo + via external redirection + +^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo + via external redirection + (the [R] flag is redundant) + +^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo + via internal proxy +</pre> +</td> +</tr> +</table> + + +<p> +<b>Example:</b> +<p> +<blockquote> +We want to rewrite URLs of the form +<blockquote> +<code>/</code> <em>Language</em> +<code>/~</code> <em>Realname</em> +<code>/.../</code> <em>File</em> +</blockquote> +into +<blockquote> +<code>/u/</code> <em>Username</em> +<code>/.../</code> <em>File</em> +<code>.</code> <em>Language</em> +</blockquote> +<p> +We take the rewrite mapfile from above and save it under +<code>/anywhere/map.real-to-user</code>. Then we only have to add the +following lines to the Apache server configuration file: + +<blockquote> +<pre> +RewriteLog /anywhere/rewrite.log +RewriteMap real-to-user txt:/anywhere/map.real-to-host +RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 +</pre> +</blockquote> +</blockquote> + + +<!--%hypertext --> +<hr> +<!--/%hypertext --> + +<center> +<a name="Additional"> +<h1>Additional Features</h1> +</a> +</center> + +<a name="EnvVar"> +<h2>Environment Variables</h2> +</a> + +This module keeps track of two additional (non-standard) CGI/SSI environment +variables named <tt>SCRIPT_URL</tt> and <tt>SCRIPT_URI</tt>. These contain +the <em>logical</em> Web-view to the current resource, while the standard CGI/SSI +variables <tt>SCRIPT_NAME</tt> and <tt>SCRIPT_FILENAME</tt> contain the +<em>physical</em> System-view. + +<p> +Notice: These variables hold the URI/URL <em>as they were initially +requested</em>, i.e. in a state <em>before</em> any rewriting. This is +important because the rewriting process is primarily used to rewrite logical +URLs to physical pathnames. + +<p> +<b>Example:</b> + +<blockquote> +<pre> +SCRIPT_NAME=/v/sw/free/lib/apache/global/u/rse/.www/index.html +SCRIPT_FILENAME=/u/rse/.www/index.html +SCRIPT_URL=/u/rse/ +SCRIPT_URI=http://en2.en.sdm.de/u/rse/ +</pre> +</blockquote> + + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> +<!--/%hypertext --> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_status.html b/usr.sbin/httpd/htdocs/manual/mod/mod_status.html new file mode 100644 index 00000000000..f88c38c00b8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_status.html @@ -0,0 +1,120 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html><head> +<title>Apache module mod_status</title> +</head><!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> + +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<h1 ALIGN="CENTER">Module mod_status</h1> + +The Status Module is only available in Apache 1.1 and later.<p> + +<h2>Function</h2> + +The Status module allows a server administrator to find out how well +their server is performing. A HTML page is presented that gives +the current server statistics in an easily readable form. If required +this page can be made to automatically refresh (given a compatible +browser). Another page gives a simple machine-readable list of the current +server state. +<p> +The details given are: +<ul> +<li>The number of children serving requests +<li>The number of idle children +<li>The status of each child, the number of requests that child has +performed and the total number of bytes served by the child (*) +<li>A total number of accesses and byte count served (*) +<li>The time the server was started/restarted and the +time it has been running for +<li>Averages giving the number of requests per second, +the number of bytes served per second and the average number +of bytes per request (*) +<li>The current percentage CPU used by each child and in total by +Apache (*) +<li>The current hosts and requests being processed (*) +</ul> + +A compile-time option must be used to display the details marked "(*)" as +the instrumentation required for obtaining these statistics does not +exist within standard Apache. + +<h2>Enabling Status Support</h2> + +To enable status reports only for browsers from the foo.com +domain add this code to your <code>access.conf</code> configuration file +<pre> + <Location /server-status> + SetHandler server-status + + order deny,allow + deny from all + allow from .foo.com + </Location> +</pre> +<p> +You can now access server statistics by using a Web browser to access the +page <code>http://your.server.name/server-status</code> +<p> +Note that mod_status will only work when you are running Apache in +<A HREF="core.html#servertype">standalone</A> mode and not +<A HREF="core.html#servertype">inetd</A> mode. + +<h3>Automatic Updates</h3> +You can get the status page to update itself automatically if you have +a browser that supports "refresh". Access the page +<code>http://your.server.name/server-status?refresh=N</code> to refresh the page +every N seconds. +<h3>Machine Readable Status File</h3> +A machine-readable version of the status file is available by accessing the +page <code>http://your.server.name/server-status?auto</code>. This is useful +when automatically run, see the Perl program in the <code>/support</code> +directory of Apache, <code>log_server_status</code>. + +<h2>Full Instrumentation</h2> + +To obtain full statistics you must compile Apache with a special +directive. On some machines there may be a small performance loss +if you do this. Try full statistics and see if you notice any +difference. If you do please contact <a href="mailto:mark@ukweb.com"> +mark@ukweb.com</a> and tell me your configuration. + +<p> + +Do this by adding the following to the AUX_CFLAGS line in the +"Configuration" file and then recompiling as usual. +<pre> + AUX_CFLAGS= (something) -DSTATUS +</pre> + +<BLOCKQUOTE> + <STRONG> + It should be noted that if <SAMP>mod_status</SAMP> is compiled into + the server, its handler capability is available in <EM>all</EM> + configuration files, including <EM>per</EM>-directory files + (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>). This may have + security-related ramifications for your site. + </STRONG> +</BLOCKQUOTE> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html b/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html new file mode 100644 index 00000000000..946f8da6db2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_userdir.html @@ -0,0 +1,89 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_userdir</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_userdir</h1> + +This module is contained in the <code>mod_userdir.c</code> file, and +is compiled in by default. It provides for user-specific directories. + + +<ul> +<li><A HREF="#userdir">UserDir</A> +</ul> +<hr> + + +<h2><A name="userdir">UserDir</A></h2> +<!--%plaintext <?INDEX {\tt UserDir} directive> --> +<strong>Syntax:</strong> UserDir <em>directory/filename</em><br> +<strong>Default:</strong> <code>UserDir public_html</code><br> +<Strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_userdir<br> +<strong>Compatibility:</strong> All forms except the <code>UserDir +public_html</code> form are only available in Apache 1.1 or above.<p> + +The UserDir directive sets the real directory in a user's home directory +to use when a request for a document for a user is received. +<em>Directory</em> is either <code>disabled</code>, to disable this feature, + or the name of a directory, following one of the following +patterns. If not disabled, then a request for +<code>http://www.foo.com/~bob/one/two.html</code> will be translated to: +<pre> +UserDir public_html -> ~bob/public_html/one/two.html +UserDir /usr/web -> /usr/web/bob/one/two.html +UserDir /home/*/www -> /home/bob/www/one/two.html +</pre> +The following directives will send redirects to the client: +<pre> +UserDir http://www.foo.com/users -> http//www.foo.com/users/bob/one/two.html +UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html +UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html +</pre> + +<P> +<STRONG> +Be careful when using this directive; for instance, <SAMP>"UserDir +./"</SAMP> would map <SAMP>"/~root"</SAMP> to +<SAMP>"/"</SAMP> - which is probably undesirable. See also +the +<A + HREF="core.html#directory" +><Directory></A> +directive and the +<A + HREF="../misc/security_tips.html" +>Security Tips</A> +page for more information. +</STRONG> +</P> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_usertrack.html b/usr.sbin/httpd/htdocs/manual/mod/mod_usertrack.html new file mode 100644 index 00000000000..5dc90165e3f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_usertrack.html @@ -0,0 +1,100 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_usertrack</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_usertrack</h1> + +Previous releases of Apache have included a module which generates a +'clickstream' log of user activity on a site using cookies. This was +called the "cookies" module, mod_cookies. In Apache 1.2 and later this +module has been renamed the "user tracking" module, +mod_usertrack. This module has been simplified and new directives +added. + +<hr> + +<h2>Logging</h2> + +Previously, the cookies module (now the user tracking module) did its +own logging, using the <tt>CookieLog</tt> directive. In this release, +this module does no logging at all. Instead, a configurable log +format file should be used to log user click-streams. This is possible +because the logging module now allows <a +href="../multilogs.html">multiple log files</a>. The cookie itself is +logged by using the text <tt>%{cookie}n </tt> + +in the log file format. For example: +<pre> +CustomLog logs/clickstream "%{cookie}n %r %t" +</pre> + +For backward compatibility the configurable log module implements the +old <tt>CookieLog</tt> directive, but this should be upgraded to the +above <tt>CustomLog</tt> directive. + +<h2>Directives</h2> + +<ul> +<li><a href="#cookieexpires">CookieExpires</a> +<li><a href="#cookietracking">CookieTracking</a> +</ul> + +<hr> + +<h2><a name="cookieexpires">CookieExpires</A></h2> +<strong>Syntax:</strong> CookieExpires <em>expiry-period</em><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> optional<br> +<strong>Module:</strong> mod_usertrack<p> + +When used, this directive sets an expiry time on the cookie generated +by the usertrack module. The <i>expiry-period</i> can be given either +as a number of seconds, or in the format such as "2 weeks 3 days 7 +hours". Valid denominations are: years, months, weeks, hours, minutes +and seconds. + +<p>If this directive is not used, cookies last only for the current +browser session.</p> + +<h2><a name="cookietracking">CookieTracking</A></h2> +<strong>Syntax:</strong> CookieTracking <em>on | off</em><br> +<strong>Context:</strong> server config, virtual host, directory, +.htaccess<br> +<strong>Override:</strong> FileInfo<br> +<strong>Status:</strong> optional<br> +<strong>Module:</strong> mod_usertrack<p> + +When the user track module is compiled in, and "CookieTracking on" is +set, Apache will start sending a user-tracking cookie for all new +requests. This directive can be used to turn this behavior on or off +on a per-server or per-directory basis. By default, compiling +mod_usertrack will not activate cookies. + + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> |