diff options
| author | Rich Bowen <rbowen@apache.org> | 2001-09-22 19:39:26 +0000 |
|---|---|---|
| committer | Rich Bowen <rbowen@apache.org> | 2001-09-22 19:39:26 +0000 |
| commit | f88b50dec40878abeccce0e1b9cfc6780a4b1465 (patch) | |
| tree | 84e6a7b926e102d9f322b96351f2346be29c2db5 /docs/manual/mod | |
| parent | 651abc3a73acadb00f390b58ed4e5b7ebb14d2b0 (diff) | |
| download | httpd-f88b50dec40878abeccce0e1b9cfc6780a4b1465.tar.gz | |
w3c tidy to convert to xhtml
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91116 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs/manual/mod')
53 files changed, 13343 insertions, 13866 deletions
diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html index f9d49da12f..81e719ecb9 100644 --- a/docs/manual/mod/directives.html +++ b/docs/manual/mod/directives.html @@ -57,7 +57,8 @@ <li><a href="mod_autoindex.html#addiconbytype">AddIconByType</a></li> - <li><a href="mod_mime.html#addinputfilter">AddInputFilter</a></li> + <li><a + href="mod_mime.html#addinputfilter">AddInputFilter</a></li> <li><a href="mod_mime.html#addlanguage">AddLanguage</a></li> @@ -66,7 +67,8 @@ <li><a href="mod_info.html#addmoduleinfo">AddModuleInfo</a></li> - <li><a href="mod_mime.html#addoutputfilter">AddOutputFilter</a></li> + <li><a + href="mod_mime.html#addoutputfilter">AddOutputFilter</a></li> <li><a href="mod_mime.html#addtype">AddType</a></li> diff --git a/docs/manual/mod/footer.html b/docs/manual/mod/footer.html index 4a0991e6fa..edcc022ccc 100644 --- a/docs/manual/mod/footer.html +++ b/docs/manual/mod/footer.html @@ -1,8 +1,19 @@ -<HR> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 2.0 -</H3> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title></title> + </head> + + <body> + <hr /> + + <h3 align="CENTER">Apache HTTP Server Version 2.0</h3> + <a href="./"><img src="../images/index.gif" alt="Index" /></a> + <a href="../"><img src="../images/home.gif" alt="Home" /></a> + </body> +</html> -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/docs/manual/mod/header.html b/docs/manual/mod/header.html index 9bc11593a3..6c4764044e 100644 --- a/docs/manual/mod/header.html +++ b/docs/manual/mod/header.html @@ -1,6 +1,19 @@ -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 2.0 - </H3> -</DIV> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title></title> + </head> + + <body> + <div align="CENTER"> + <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> + + <h3>Apache HTTP Server Version 2.0</h3> + </div> + </body> +</html> + diff --git a/docs/manual/mod/index-bytype.html b/docs/manual/mod/index-bytype.html index 986580650c..718252ae8f 100644 --- a/docs/manual/mod/index-bytype.html +++ b/docs/manual/mod/index-bytype.html @@ -1,190 +1,280 @@ -<!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" -> -<!--#include virtual="header.html" --> -<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 list of modules <A -HREF="index.html">sorted alphabetically</A> and the complete -alphabetical list of <A HREF="directives.html" >all Apache -directives</A>. -</P> - -<H2>Core and Mutli-Processing Modules</H2> - -<DL> -<DT><A HREF="core.html">Core</A> -<DD>Core Apache features. -<DT><A HREF="threaded.html">threaded</A> -<DD>Multi-Processing Module with Threading via Pthreads; Variable number -of processes, constant number of threads/child -<DT><a href="mpm_winnt.html">mpm_winnt</a> -<DD>Multi-Processing Module with a single control process and a single -server process with multiple threads for Windows NT -<DT><a href="perchild.html">perchild</a> -<DD>Multi-Processing Module with the ability to server different -virtual hosts under different userids. -<DT><a href="prefork.html">prefork</a> -<DD>Non-threaded preforking processes model similar to Apache 1.3 -</DL> - -<H2>Environment Creation</H2> - -<DL> -<DT><A HREF="mod_env.html">mod_env</A> -<DD>Passing of environments to CGI scripts -<DT><A HREF="mod_setenvif.html">mod_setenvif</A> -<DD>Set environment variables based on client information -<DT><A HREF="mod_unique_id.html">mod_unique_id</A> -<DD>Generate unique request identifier for every request -</DL> - -<H2>Content Type Decisions</H2> - -<DL> -<DT><A HREF="mod_mime.html">mod_mime</A> -<DD>Determining document types using file extensions. -<DT><A HREF="mod_mime_magic.html">mod_mime_magic</A> -<DD>Determining document types using "magic numbers". -<DT><A HREF="mod_negotiation.html">mod_negotiation</A> -<DD>Content negotiation. -<DT><A HREF="mod_charset_lite.html">mod_charset_lite</A> -<DD>Configuring character set translation. -</DL> - -<H2>URL Mapping</H2> - -<DL> -<DT><A HREF="mod_alias.html">mod_alias</A> -<DD>Mapping different parts of the host filesystem in the document tree, - and URL redirection. -<DT><A HREF="mod_rewrite.html">mod_rewrite</A> -<DD>Powerful URI-to-filename mapping using regular expressions -<DT><A HREF="mod_userdir.html">mod_userdir</A> -<DD>User home directories. -<DT><A HREF="mod_speling.html">mod_speling</A> -<DD>Automatically correct minor typos in URLs -<DT><A HREF="mod_vhost_alias.html">mod_vhost_alias</A> -<DD>Support for dynamically configured mass virtual hosting -</DL> - -<H2>Directory Handling</H2> - -<DL> -<DT><A HREF="mod_dir.html">mod_dir</A> -<DD>Basic directory handling. -<DT><A HREF="mod_autoindex.html">mod_autoindex</A> -<DD>Automatic directory listings. -</DL> - -<H2>Access Control</H2> - -<DL> -<DT><A HREF="mod_access.html">mod_access</A> -<DD>Access control based on client hostname or IP address. -<DT><A HREF="mod_auth.html">mod_auth</A> -<DD>User authentication using text files. -<DT><A HREF="mod_auth_dbm.html">mod_auth_dbm</A> -<DD>User authentication using DBM files. -<DT><A HREF="mod_auth_db.html">mod_auth_db</A> -<DD>User authentication using Berkeley DB files. -<DT><A HREF="mod_auth_anon.html">mod_auth_anon</A> -<DD>Anonymous user access to authenticated areas. -<DT><A HREF="mod_auth_digest.html">mod_auth_digest</A> -<DD>MD5 authentication -<DT><A HREF="mod_auth_ldap.html">mod_auth_ldap</A> -<DD>User authentication using LDAP. - -</DL> - -<H2>HTTP Response</H2> - -<DL> -<DT><A HREF="mod_headers.html">mod_headers</A> -<DD>Add arbitrary HTTP headers to resources -<DT><A HREF="mod_cern_meta.html">mod_cern_meta</A> -<DD>Support for HTTP header metafiles. -<DT><A HREF="mod_expires.html">mod_expires</A> -<DD>Apply Expires: headers to resources -<DT><A HREF="mod_asis.html">mod_asis</A> -<DD>Sending files which contain their own HTTP headers. -</DL> - -<H2>Dynamic Content</H2> - -<DL> -<DT><A HREF="mod_include.html">mod_include</A> -<DD>Server-parsed documents. -<DT><A HREF="mod_cgi.html">mod_cgi</A> -<DD>Invoking CGI scripts. -<DT><A HREF="mod_cgid.html">mod_cgid</A> -<DD>Invoking CGI scripts using an external daemon. -<DT><A HREF="mod_actions.html">mod_actions</A> -<DD>Executing CGI scripts based on media type or request method. -<DT><A HREF="mod_isapi.html">mod_isapi</A> -<DD>Windows ISAPI Extension support -<DT><A HREF="mod_ext_filter.html">mod_ext_filter</A> -<DD>Filtering content with external programs. -<DT><A HREF="mod_suexec.html">mod_suexec</A> -<DD>Run CGI requests as a specified user and group. -</DL> - -<H2>Internal Content Handlers</H2> - -<DL> -<DT><A HREF="mod_status.html">mod_status</A> -<DD>Server status display -<DT><A HREF="mod_info.html">mod_info</A> -<DD>Server configuration information -</DL> - -<H2>Logging</H2> - -<DL> -<DT><A HREF="mod_log_config.html">mod_log_config</A> -<DD>User-configurable logging replacement for mod_log_common. -<DT><A HREF="mod_usertrack.html">mod_usertrack</A> -<DD>User tracking using Cookies -</DL> - -<H2>Miscellaneous</H2> - -<DL> -<DT><A HREF="mod_imap.html">mod_imap</A> -<DD>The imagemap file handler. -<DT><A HREF="mod_proxy.html">mod_proxy</A> -<DD>Caching proxy abilities -<DT><A HREF="mod_so.html">mod_so</A> -<DD>Support for loading modules at runtime -<DT><A HREF="mod_file_cache.html">mod_file_cache</A> -<DD>Caching files in memory for faster serving. -<DT><A HREF="mod_dav.html">mod_dav</A> -<DD>Class 1,2 <A HREF="http://www.webdav.org">WebDAV</A> HTTP extensions -<DT><A HREF="mod_ldap.html">mod_ldap</A> -<DD>LDAP connection pool and shared memory cache. -</DL> - - -<H2>Development</H2> - -<DL> -<DT><A HREF="mod_example.html">mod_example</A> -<DD>Demonstrates Apache API -</DL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <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 list of modules <a + href="index.html">sorted alphabetically</a> and the complete + alphabetical list of <a href="directives.html">all Apache + directives</a>.</p> + + <h2>Core and Mutli-Processing Modules</h2> + + <dl> + <dt><a href="core.html">Core</a></dt> + + <dd>Core Apache features.</dd> + + <dt><a href="threaded.html">threaded</a></dt> + + <dd>Multi-Processing Module with Threading via Pthreads; + Variable number of processes, constant number of + threads/child</dd> + + <dt><a href="mpm_winnt.html">mpm_winnt</a></dt> + + <dd>Multi-Processing Module with a single control process and + a single server process with multiple threads for Windows + NT</dd> + + <dt><a href="perchild.html">perchild</a></dt> + + <dd>Multi-Processing Module with the ability to server + different virtual hosts under different userids.</dd> + + <dt><a href="prefork.html">prefork</a></dt> + + <dd>Non-threaded preforking processes model similar to Apache + 1.3</dd> + </dl> + + <h2>Environment Creation</h2> + + <dl> + <dt><a href="mod_env.html">mod_env</a></dt> + + <dd>Passing of environments to CGI scripts</dd> + + <dt><a href="mod_setenvif.html">mod_setenvif</a></dt> + + <dd>Set environment variables based on client + information</dd> + + <dt><a href="mod_unique_id.html">mod_unique_id</a></dt> + + <dd>Generate unique request identifier for every request</dd> + </dl> + + <h2>Content Type Decisions</h2> + + <dl> + <dt><a href="mod_mime.html">mod_mime</a></dt> + + <dd>Determining document types using file extensions.</dd> + + <dt><a href="mod_mime_magic.html">mod_mime_magic</a></dt> + + <dd>Determining document types using "magic numbers".</dd> + + <dt><a href="mod_negotiation.html">mod_negotiation</a></dt> + + <dd>Content negotiation.</dd> + + <dt><a href="mod_charset_lite.html">mod_charset_lite</a></dt> + + <dd>Configuring character set translation.</dd> + </dl> + + <h2>URL Mapping</h2> + + <dl> + <dt><a href="mod_alias.html">mod_alias</a></dt> + + <dd>Mapping different parts of the host filesystem in the + document tree, and URL redirection.</dd> + + <dt><a href="mod_rewrite.html">mod_rewrite</a></dt> + + <dd>Powerful URI-to-filename mapping using regular + expressions</dd> + + <dt><a href="mod_userdir.html">mod_userdir</a></dt> + + <dd>User home directories.</dd> + + <dt><a href="mod_speling.html">mod_speling</a></dt> + + <dd>Automatically correct minor typos in URLs</dd> + + <dt><a href="mod_vhost_alias.html">mod_vhost_alias</a></dt> + + <dd>Support for dynamically configured mass virtual + hosting</dd> + </dl> + + <h2>Directory Handling</h2> + + <dl> + <dt><a href="mod_dir.html">mod_dir</a></dt> + + <dd>Basic directory handling.</dd> + + <dt><a href="mod_autoindex.html">mod_autoindex</a></dt> + + <dd>Automatic directory listings.</dd> + </dl> + + <h2>Access Control</h2> + + <dl> + <dt><a href="mod_access.html">mod_access</a></dt> + + <dd>Access control based on client hostname or IP + address.</dd> + + <dt><a href="mod_auth.html">mod_auth</a></dt> + + <dd>User authentication using text files.</dd> + + <dt><a href="mod_auth_dbm.html">mod_auth_dbm</a></dt> + + <dd>User authentication using DBM files.</dd> + + <dt><a href="mod_auth_db.html">mod_auth_db</a></dt> + + <dd>User authentication using Berkeley DB files.</dd> + + <dt><a href="mod_auth_anon.html">mod_auth_anon</a></dt> + + <dd>Anonymous user access to authenticated areas.</dd> + + <dt><a href="mod_auth_digest.html">mod_auth_digest</a></dt> + + <dd>MD5 authentication</dd> + + <dt><a href="mod_auth_ldap.html">mod_auth_ldap</a></dt> + + <dd>User authentication using LDAP.</dd> + </dl> + + <h2>HTTP Response</h2> + + <dl> + <dt><a href="mod_headers.html">mod_headers</a></dt> + + <dd>Add arbitrary HTTP headers to resources</dd> + + <dt><a href="mod_cern_meta.html">mod_cern_meta</a></dt> + + <dd>Support for HTTP header metafiles.</dd> + + <dt><a href="mod_expires.html">mod_expires</a></dt> + + <dd>Apply Expires: headers to resources</dd> + + <dt><a href="mod_asis.html">mod_asis</a></dt> + + <dd>Sending files which contain their own HTTP headers.</dd> + </dl> + + <h2>Dynamic Content</h2> + + <dl> + <dt><a href="mod_include.html">mod_include</a></dt> + + <dd>Server-parsed documents.</dd> + + <dt><a href="mod_cgi.html">mod_cgi</a></dt> + + <dd>Invoking CGI scripts.</dd> + + <dt><a href="mod_cgid.html">mod_cgid</a></dt> + + <dd>Invoking CGI scripts using an external daemon.</dd> + + <dt><a href="mod_actions.html">mod_actions</a></dt> + + <dd>Executing CGI scripts based on media type or request + method.</dd> + + <dt><a href="mod_isapi.html">mod_isapi</a></dt> + + <dd>Windows ISAPI Extension support</dd> + + <dt><a href="mod_ext_filter.html">mod_ext_filter</a></dt> + + <dd>Filtering content with external programs.</dd> + + <dt><a href="mod_suexec.html">mod_suexec</a></dt> + + <dd>Run CGI requests as a specified user and group.</dd> + </dl> + + <h2>Internal Content Handlers</h2> + + <dl> + <dt><a href="mod_status.html">mod_status</a></dt> + + <dd>Server status display</dd> + + <dt><a href="mod_info.html">mod_info</a></dt> + + <dd>Server configuration information</dd> + </dl> + + <h2>Logging</h2> + + <dl> + <dt><a href="mod_log_config.html">mod_log_config</a></dt> + + <dd>User-configurable logging replacement for + mod_log_common.</dd> + + <dt><a href="mod_usertrack.html">mod_usertrack</a></dt> + + <dd>User tracking using Cookies</dd> + </dl> + + <h2>Miscellaneous</h2> + + <dl> + <dt><a href="mod_imap.html">mod_imap</a></dt> + + <dd>The imagemap file handler.</dd> + + <dt><a href="mod_proxy.html">mod_proxy</a></dt> + + <dd>Caching proxy abilities</dd> + + <dt><a href="mod_so.html">mod_so</a></dt> + + <dd>Support for loading modules at runtime</dd> + + <dt><a href="mod_file_cache.html">mod_file_cache</a></dt> + + <dd>Caching files in memory for faster serving.</dd> + + <dt><a href="mod_dav.html">mod_dav</a></dt> + + <dd>Class 1,2 <a href="http://www.webdav.org">WebDAV</a> HTTP + extensions</dd> + + <dt><a href="mod_ldap.html">mod_ldap</a></dt> + + <dd>LDAP connection pool and shared memory cache.</dd> + </dl> + + <h2>Development</h2> + + <dl> + <dt><a href="mod_example.html">mod_example</a></dt> + + <dd>Demonstrates Apache API</dd> + </dl> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html index bf6b81eece..e493a49eaf 100644 --- a/docs/manual/mod/index.html +++ b/docs/manual/mod/index.html @@ -1,139 +1,241 @@ -<!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" -> -<!--#include virtual="header.html" --> -<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 list of modules <A -HREF="index-bytype.html">sorted by type</A> and the complete -alphabetical list of <A HREF="directives.html">all Apache -directives</A>. - -</P> - -<h2>Core Features and Multi-Processing Modules</h2> - -<DL> -<DT><A HREF="core.html">Core</A> -<DD>Core Apache features. -<DT><A HREF="threaded.html">threaded</A> -<DD>Multi-Processing Module with Threading via Pthreads; Variable number -of processes, constant number of threads/child -<DT><a href="mpm_winnt.html">mpm_winnt</a> -<DD>Multi-Processing Module with a single control process and a single -server process with multiple threads for Windows NT -<DT><a href="perchild.html">perchild</a> -<DD>Multi-Processing Module with the ability to server different -virtual hosts under different userids. -<DT><a href="prefork.html">prefork</a> -<DD>Non-threaded preforking processes model similar to Apache 1.3 -</DL> - -<h2>Other Modules</h2> - -<DL> -<DT><A HREF="mod_access.html">mod_access</A> -<DD>Access control based on client hostname or IP address. -<DT><A HREF="mod_actions.html">mod_actions</A> -<DD>Executing CGI scripts based on media type or request method. -<DT><A HREF="mod_alias.html">mod_alias</A> -<DD>Mapping different parts of the host filesystem in the document tree, - and URL redirection. -<DT><A HREF="mod_asis.html">mod_asis</A> -<DD>Sending files which contain their own HTTP headers. -<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 access to authenticated areas. -<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_digest.html">mod_auth_digest</A> -<DD>MD5 authentication -<DT><A HREF="mod_auth_ldap.html">mod_auth_ldap</A> -<DD>User authentication using LDAP. -<DT><A HREF="mod_autoindex.html">mod_autoindex</A> -<DD>Automatic directory listings. -<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_cgid.html">mod_cgid</A> -<DD>Invoking CGI scripts using an external daemon. -<DT><A HREF="mod_charset_lite.html">mod_charset_lite</A> -<DD>Configuring character set translation. -<DT><A HREF="mod_dav.html">mod_dav</A> -<DD>Class 1,2 <A HREF="http://www.webdav.org">WebDAV</A> HTTP extensions -<DT><A HREF="mod_dir.html">mod_dir</A> -<DD>Basic directory handling. -<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> -<DD>Demonstrates Apache API -<DT><A HREF="mod_expires.html">mod_expires</A> -<DD>Apply Expires: headers to resources -<DT><A HREF="mod_ext_filter.html">mod_ext_filter</A> -<DD>Filtering output with external programs. -<DT><A HREF="mod_file_cache.html">mod_file_cache</A> -<DD>Caching files in memory for faster serving. -<DT><A HREF="mod_headers.html">mod_headers</A> -<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_isapi.html">mod_isapi</A> -<DD>Windows ISAPI Extension support -<DT><A HREF="mod_ldap.html">mod_ldap</A> -<DD>LDAP connection pool and shared memory cache. -<DT><A HREF="mod_log_config.html">mod_log_config</A> -<DD>User-configurable logging replacement for mod_log_common. -<DT><A HREF="mod_mime.html">mod_mime</A> -<DD>Determining document types using file extensions. -<DT><A HREF="mod_mime_magic.html">mod_mime_magic</A> -<DD>Determining document types using "magic numbers". -<DT><A HREF="mod_negotiation.html">mod_negotiation</A> -<DD>Content negotiation. -<DT><A HREF="mod_proxy.html">mod_proxy</A> -<DD>Caching proxy abilities -<DT><A HREF="mod_rewrite.html">mod_rewrite</A> -<DD>Powerful URI-to-filename mapping using regular expressions -<DT><A HREF="mod_setenvif.html">mod_setenvif</A> -<DD>Set environment variables based on client information -<DT><A HREF="mod_so.html">mod_so</A> -<DD>Support for loading modules at runtime -<DT><A HREF="mod_speling.html">mod_speling</A> -<DD>Automatically correct minor typos in URLs -<DT><A HREF="mod_status.html">mod_status</A> -<DD>Server status display -<DT><A HREF="mod_suexec.html">mod_suexec</A> -<DD>Run CGI requests as a specified user and group. -<DT><A HREF="mod_userdir.html">mod_userdir</A> -<DD>User home directories. -<DT><A HREF="mod_unique_id.html">mod_unique_id</A> -<DD>Generate unique request identifier for every request -<DT><A HREF="mod_usertrack.html">mod_usertrack</A> -<DD>User tracking using Cookies (replacement for mod_cookies.c) -<DT><A HREF="mod_vhost_alias.html">mod_vhost_alias</A> -<DD>Support for dynamically configured mass virtual hosting -</DL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <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 list of modules <a + href="index-bytype.html">sorted by type</a> and the complete + alphabetical list of <a href="directives.html">all Apache + directives</a>.</p> + + <h2>Core Features and Multi-Processing Modules</h2> + + <dl> + <dt><a href="core.html">Core</a></dt> + + <dd>Core Apache features.</dd> + + <dt><a href="threaded.html">threaded</a></dt> + + <dd>Multi-Processing Module with Threading via Pthreads; + Variable number of processes, constant number of + threads/child</dd> + + <dt><a href="mpm_winnt.html">mpm_winnt</a></dt> + + <dd>Multi-Processing Module with a single control process and + a single server process with multiple threads for Windows + NT</dd> + + <dt><a href="perchild.html">perchild</a></dt> + + <dd>Multi-Processing Module with the ability to server + different virtual hosts under different userids.</dd> + + <dt><a href="prefork.html">prefork</a></dt> + + <dd>Non-threaded preforking processes model similar to Apache + 1.3</dd> + </dl> + + <h2>Other Modules</h2> + + <dl> + <dt><a href="mod_access.html">mod_access</a></dt> + + <dd>Access control based on client hostname or IP + address.</dd> + + <dt><a href="mod_actions.html">mod_actions</a></dt> + + <dd>Executing CGI scripts based on media type or request + method.</dd> + + <dt><a href="mod_alias.html">mod_alias</a></dt> + + <dd>Mapping different parts of the host filesystem in the + document tree, and URL redirection.</dd> + + <dt><a href="mod_asis.html">mod_asis</a></dt> + + <dd>Sending files which contain their own HTTP headers.</dd> + + <dt><a href="mod_auth.html">mod_auth</a></dt> + + <dd>User authentication using text files.</dd> + + <dt><a href="mod_auth_anon.html">mod_auth_anon</a></dt> + + <dd>Anonymous user access to authenticated areas.</dd> + + <dt><a href="mod_auth_db.html">mod_auth_db</a></dt> + + <dd>User authentication using Berkeley DB files.</dd> + + <dt><a href="mod_auth_dbm.html">mod_auth_dbm</a></dt> + + <dd>User authentication using DBM files.</dd> + + <dt><a href="mod_auth_digest.html">mod_auth_digest</a></dt> + + <dd>MD5 authentication</dd> + + <dt><a href="mod_auth_ldap.html">mod_auth_ldap</a></dt> + + <dd>User authentication using LDAP.</dd> + + <dt><a href="mod_autoindex.html">mod_autoindex</a></dt> + + <dd>Automatic directory listings.</dd> + + <dt><a href="mod_cern_meta.html">mod_cern_meta</a></dt> + + <dd>Support for HTTP header metafiles.</dd> + + <dt><a href="mod_cgi.html">mod_cgi</a></dt> + + <dd>Invoking CGI scripts.</dd> + + <dt><a href="mod_cgid.html">mod_cgid</a></dt> + + <dd>Invoking CGI scripts using an external daemon.</dd> + + <dt><a href="mod_charset_lite.html">mod_charset_lite</a></dt> + + <dd>Configuring character set translation.</dd> + + <dt><a href="mod_dav.html">mod_dav</a></dt> + + <dd>Class 1,2 <a href="http://www.webdav.org">WebDAV</a> HTTP + extensions</dd> + + <dt><a href="mod_dir.html">mod_dir</a></dt> + + <dd>Basic directory handling.</dd> + + <dt><a href="mod_env.html">mod_env</a></dt> + + <dd>Passing of environments to CGI scripts</dd> + + <dt><a href="mod_example.html">mod_example</a></dt> + + <dd>Demonstrates Apache API</dd> + + <dt><a href="mod_expires.html">mod_expires</a></dt> + + <dd>Apply Expires: headers to resources</dd> + + <dt><a href="mod_ext_filter.html">mod_ext_filter</a></dt> + + <dd>Filtering output with external programs.</dd> + + <dt><a href="mod_file_cache.html">mod_file_cache</a></dt> + + <dd>Caching files in memory for faster serving.</dd> + + <dt><a href="mod_headers.html">mod_headers</a></dt> + + <dd>Add arbitrary HTTP headers to resources</dd> + + <dt><a href="mod_imap.html">mod_imap</a></dt> + + <dd>The imagemap file handler.</dd> + + <dt><a href="mod_include.html">mod_include</a></dt> + + <dd>Server-parsed documents.</dd> + + <dt><a href="mod_info.html">mod_info</a></dt> + + <dd>Server configuration information</dd> + + <dt><a href="mod_isapi.html">mod_isapi</a></dt> + + <dd>Windows ISAPI Extension support</dd> + + <dt><a href="mod_ldap.html">mod_ldap</a></dt> + + <dd>LDAP connection pool and shared memory cache.</dd> + + <dt><a href="mod_log_config.html">mod_log_config</a></dt> + + <dd>User-configurable logging replacement for + mod_log_common.</dd> + + <dt><a href="mod_mime.html">mod_mime</a></dt> + + <dd>Determining document types using file extensions.</dd> + + <dt><a href="mod_mime_magic.html">mod_mime_magic</a></dt> + + <dd>Determining document types using "magic numbers".</dd> + + <dt><a href="mod_negotiation.html">mod_negotiation</a></dt> + + <dd>Content negotiation.</dd> + + <dt><a href="mod_proxy.html">mod_proxy</a></dt> + + <dd>Caching proxy abilities</dd> + + <dt><a href="mod_rewrite.html">mod_rewrite</a></dt> + + <dd>Powerful URI-to-filename mapping using regular + expressions</dd> + + <dt><a href="mod_setenvif.html">mod_setenvif</a></dt> + + <dd>Set environment variables based on client + information</dd> + + <dt><a href="mod_so.html">mod_so</a></dt> + + <dd>Support for loading modules at runtime</dd> + + <dt><a href="mod_speling.html">mod_speling</a></dt> + + <dd>Automatically correct minor typos in URLs</dd> + + <dt><a href="mod_status.html">mod_status</a></dt> + + <dd>Server status display</dd> + + <dt><a href="mod_suexec.html">mod_suexec</a></dt> + + <dd>Run CGI requests as a specified user and group.</dd> + + <dt><a href="mod_userdir.html">mod_userdir</a></dt> + + <dd>User home directories.</dd> + + <dt><a href="mod_unique_id.html">mod_unique_id</a></dt> + + <dd>Generate unique request identifier for every request</dd> + + <dt><a href="mod_usertrack.html">mod_usertrack</a></dt> + + <dd>User tracking using Cookies (replacement for + mod_cookies.c)</dd> + + <dt><a href="mod_vhost_alias.html">mod_vhost_alias</a></dt> + + <dd>Support for dynamically configured mass virtual + hosting</dd> + </dl> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_TEMPLATE.html b/docs/manual/mod/mod_TEMPLATE.html index 0bfe8613ed..675c207a14 100644 --- a/docs/manual/mod/mod_TEMPLATE.html +++ b/docs/manual/mod/mod_TEMPLATE.html @@ -115,8 +115,6 @@ rel="Help"><strong>Module:</strong></a> mod_foo <p><em>Directive3</em> is described here, and so on. - - <!--#include virtual="footer.html" --> </p> </body> diff --git a/docs/manual/mod/mod_access.html b/docs/manual/mod/mod_access.html index f6cef3b3b8..938ab6ece0 100644 --- a/docs/manual/mod/mod_access.html +++ b/docs/manual/mod/mod_access.html @@ -1,346 +1,336 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_access</H1> -<P> -This module provides access control based on client hostname, IP -address, or other characteristics of the client request. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_access.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> access_module -</P> - -<h2>Summary</h2> - -<p>The directives provided by mod_access are used in <CODE><A -HREF="core.html#directory"><Directory></A>, <A -HREF="core.html#files"><Files></A>,</code> and <code> <A -HREF="core.html#location"><Location></A></code> sections as -well as <code><a -href="core.html#accessfilename">.htaccess</a></code> files -to control access to particular parts of the server. Access -can be controlled based on the client hostname, IP address, -or other characteristics of the client request, as captured -in <a href="../env.html">environment variables</a>. The -<code>Allow</code> and <code>Deny</code> directives are used -to specify which clients are or are not allowed access to the -server, while the <code>Order</code> directive sets the -default access state, and configures how the <code>Allow</code> -and <code>Deny</code> directives interact with each other.</p> - -<p>Both host-based access restrictions and password-based -authentication may be implemented simultaneously. In -that case, the <a href="core.html#satsify">Satisfy</a> directive -is used to determine how the two sets of restrictions -interact.</p> - -<p>In general, access restriction directives apply to all access -methods (<code>GET</code>, <code>PUT</code>, <code>POST</code>, etc). -This is the desired behavior in most cases. However, it is possible -to restrict some methods, while leaving other methods unrestricted, by -enclosing the directives in a <a -href="core.html#limit"><Limit></a> section.</p> - -<H2>Directives</H2> - -<UL> -<LI><A HREF="#allow">Allow</A> -<LI><A HREF="#deny">Deny</A> -<LI><A HREF="#order">Order</A> -</UL> - -<P>See also <A HREF="core.html#satisfy">Satisfy</A> - and <A HREF="core.html#require">Require</A>. - -<HR> - - -<H2><A NAME="allow">Allow</a> <a name="allowfromenv">directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Allow} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Allow from - all|<EM>host</em>|env=<em>env-variable</em> - [<em>host</em>|env=<em>env-variable</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access -</P> - -<P> -The <code>Allow</code> directive affects which hosts can access an -area of the server. Access can be controlled by hostname, IP Address, -IP Address range, or by other characteristics of the client -request captured in environment variables.</p> - -<p>The first argument to this directive is always <code>from</code>. -The subsequent arguments can take three different forms. If -<code>Allow from all</code> is specified, then all hosts are allowed -access, subject to the configuration of the <code>Deny</code> and -<code>Order</code> directives as discussed below. To allow only -particular hosts or groups of hosts to access the server, the -<em>host</em> can be specified in any of the following formats:</p> -<DL> - -<DT>A (partial) domain-name</dt> <dd>Example: <code>Allow from -apache.org</code><br> Hosts whose names match, or end in, this string -are allowed access. Only complete components are matched, so the -above example will match <code>foo.apache.org</code> but it will not -match <code>fooapache.org</code>. This configuration will cause the -server to perform a reverse DNS lookup on the client IP address, -regardless of the setting of the <a -href="core.html#hostnamelookups">HostNameLookups</a> directive.</dd> - -<DT>A full IP address</dt> -<DD>Example: <code>Allow from 10.1.2.3</code><br> -An IP address of a host allowed access</dd> - -<DT>A partial IP address</dt> -<dd>Example: <code>Allow from 10.1</code><br> -The first 1 to 3 bytes of an IP address, for subnet restriction.</dd> - -<DT>A network/netmask pair</dt> -<dd>Example: <code>Allow from 10.1.0.0/255.255.0.0</code><br> - A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet - restriction.</dd> - -<DT>A network/nnn CIDR specification</dt> <dd>Example: <code>Allow -from 10.1.0.0/16</code><br> Similar to the previous case, except the -netmask consists of nnn high-order 1 bits.</dd> -</DL> - -<p>Note that the last three examples above match exactly the -same set of hosts.</p> - -<p>The third format of the arguments to the <code>Allow</code> -directive allows access to the server to be controlled based on the -existence of an <a href="../env.html">environment variable</a>. When -<code>Allow from env=</code><em>env-variable</em> is specified, then -the request is allowed access if the environment variable -<em>env-variable</em> exists. The server provides the ability to set -environment variables in a flexible way based on characteristics of -the client request using the directives provided by <a -href="mod_setenvif.html">mod_setenvif</a>. Therefore, this directive -can be used to allow access based on such factors as the clients -<code>User-Agent</code> (browser type), <code>Referer</code>, or other -HTTP request header fields.</P> - -<P> -Example: -</P> -<BLOCKQUOTE><PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_access</h1> + + <p>This module provides access control based on client + hostname, IP address, or other characteristics of the client + request.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_access.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + access_module</p> + + <h2>Summary</h2> + + <p>The directives provided by mod_access are used in <code><a + href="core.html#directory"><Directory></a>, <a + href="core.html#files"><Files></a>,</code> and <code><a + href="core.html#location"><Location></a></code> sections + as well as <code><a + href="core.html#accessfilename">.htaccess</a></code> files to + control access to particular parts of the server. Access can be + controlled based on the client hostname, IP address, or other + characteristics of the client request, as captured in <a + href="../env.html">environment variables</a>. The + <code>Allow</code> and <code>Deny</code> directives are used to + specify which clients are or are not allowed access to the + server, while the <code>Order</code> directive sets the default + access state, and configures how the <code>Allow</code> and + <code>Deny</code> directives interact with each other.</p> + + <p>Both host-based access restrictions and password-based + authentication may be implemented simultaneously. In that case, + the <a href="core.html#satsify">Satisfy</a> directive is used + to determine how the two sets of restrictions interact.</p> + + <p>In general, access restriction directives apply to all + access methods (<code>GET</code>, <code>PUT</code>, + <code>POST</code>, etc). This is the desired behavior in most + cases. However, it is possible to restrict some methods, while + leaving other methods unrestricted, by enclosing the directives + in a <a href="core.html#limit"><Limit></a> section.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#allow">Allow</a></li> + + <li><a href="#deny">Deny</a></li> + + <li><a href="#order">Order</a></li> + </ul> + + <p>See also <a href="core.html#satisfy">Satisfy</a> and <a + href="core.html#require">Require</a>.</p> + <hr /> + + <h2><a id="allow" name="allow">Allow</a> <a id="allowfromenv" + name="allowfromenv">directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Allow} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Allow from + all|<em>host</em>|env=<em>env-variable</em> + [<em>host</em>|env=<em>env-variable</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Limit<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_access</p> + + <p>The <code>Allow</code> directive affects which hosts can + access an area of the server. Access can be controlled by + hostname, IP Address, IP Address range, or by other + characteristics of the client request captured in environment + variables.</p> + + <p>The first argument to this directive is always + <code>from</code>. The subsequent arguments can take three + different forms. If <code>Allow from all</code> is specified, + then all hosts are allowed access, subject to the configuration + of the <code>Deny</code> and <code>Order</code> directives as + discussed below. To allow only particular hosts or groups of + hosts to access the server, the <em>host</em> can be specified + in any of the following formats:</p> + + <dl> + <dt>A (partial) domain-name</dt> + + <dd>Example: <code>Allow from apache.org</code><br /> + Hosts whose names match, or end in, this string are allowed + access. Only complete components are matched, so the above + example will match <code>foo.apache.org</code> but it will + not match <code>fooapache.org</code>. This configuration will + cause the server to perform a reverse DNS lookup on the + client IP address, regardless of the setting of the <a + href="core.html#hostnamelookups">HostNameLookups</a> + directive.</dd> + + <dt>A full IP address</dt> + + <dd>Example: <code>Allow from 10.1.2.3</code><br /> + An IP address of a host allowed access</dd> + + <dt>A partial IP address</dt> + + <dd>Example: <code>Allow from 10.1</code><br /> + The first 1 to 3 bytes of an IP address, for subnet + restriction.</dd> + + <dt>A network/netmask pair</dt> + + <dd>Example: <code>Allow from + 10.1.0.0/255.255.0.0</code><br /> + A network a.b.c.d, and a netmask w.x.y.z. For more + fine-grained subnet restriction.</dd> + + <dt>A network/nnn CIDR specification</dt> + + <dd>Example: <code>Allow from 10.1.0.0/16</code><br /> + Similar to the previous case, except the netmask consists of + nnn high-order 1 bits.</dd> + </dl> + + <p>Note that the last three examples above match exactly the + same set of hosts.</p> + + <p>The third format of the arguments to the <code>Allow</code> + directive allows access to the server to be controlled based on + the existence of an <a href="../env.html">environment + variable</a>. When <code>Allow from + env=</code><em>env-variable</em> is specified, then the request + is allowed access if the environment variable + <em>env-variable</em> exists. The server provides the ability + to set environment variables in a flexible way based on + characteristics of the client request using the directives + provided by <a href="mod_setenvif.html">mod_setenvif</a>. + Therefore, this directive can be used to allow access based on + such factors as the clients <code>User-Agent</code> (browser + type), <code>Referer</code>, or other HTTP request header + fields.</p> + + <p>Example:</p> + + <blockquote> +<pre> SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in <Directory /docroot> Order Deny,Allow Deny from all Allow from env=let_me_in </Directory> -</PRE></BLOCKQUOTE> - -<p>In this case, browsers with a user-agent string beginning with -<TT>KnockKnock/2.0</TT> will be allowed access, and all others will be -denied.</p> -<P> -See also <a href="#deny">Deny</a>, <A HREF="#order">Order</A> -and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>. -</P> -<HR> - -<H2><A NAME="deny">Deny</a> <a name="denyfromenv">directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Deny} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Deny from - all|<EM>host</em>|env=<em>env-variable</em> - [<em>host</em>|env=<em>env-variable</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access -</P> - -<p>This directive allows access to the server to be restricted based -on hostname, IP address, or environment variables. The arguments for -the <code>Deny</code> directive are identical to the arguments for the -<a href="#allow">Allow</a> directive.</p> - -<p>See also <a href="#allow">Allow</a>, <A HREF="#order">Order</A> -and <A HREF="mod_setenvif.html#SetEnvIf">SetEnvIf</A>.</p> -<HR> - -<H2><A NAME="order">Order directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Order} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Order <EM>ordering</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Order Deny,Allow</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Limit<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_access -</P> -<P> -The <CODE>Order</CODE> directive controls the default access state and -the order in which <A HREF="#allow">Allow</A> and <A -HREF="#deny">Deny</A> directives are evaluated. <EM>Ordering</EM> is -one of -</P> -<DL> -<DT>Deny,Allow</dt> <DD>The <CODE>Deny</CODE> directives are evaluated -before the <CODE>Allow</CODE> directives. Access is allowed -by default. Any client which does not match a <code>Deny</code> -directive or does match an <code>Allow</code> directive will be -allowed access to the server.</dd> - -<DT>Allow,Deny</dt> <DD>The <CODE>Allow</CODE> directives are -evaluated before the <CODE>Deny</CODE> directives. Access is -denied by default. Any client which does not match -an <code>Allow</code> directive or does match a <code>Deny</code> -directive will be denied access to the server.</dd> - -<DT>Mutual-failure</dt> <DD>Only those hosts which appear on the -<CODE>Allow</CODE> list and do not appear on the <CODE>Deny</CODE> -list are granted access. This ordering has the same effect as -<code>Order Allow,Deny</code> and is deprecated in favor of that -configuration.</dd> -</DL> - -<P>Keywords may only be separated by a comma; no whitespace is allowed -between them. Note that in all cases every <CODE>Allow</CODE> -and <CODE>Deny</CODE> statement is evaluated.</P> - -<P>In the following example, all hosts in the apache.org domain are -allowed access; all other hosts are denied access. -</P> - -<BLOCKQUOTE><CODE> - Order Deny,Allow<BR> - Deny from all<BR> - Allow from apache.org<BR> -</CODE></BLOCKQUOTE> - -<P>In the next example, all hosts in the apache.org domain are allowed -access, except for the hosts which are in the foo.apache.org -subdomain, who are denied access. All hosts not in the apache.org -domain are denied access because the default state is to deny access -to the server. -</P> - -<blockquote><code> - Order Allow,Deny<br> - Allow from apache.org<br> - Deny from foo.apache.org<br> -</code></blockquote> - -<p>On the other hand, if the <code>Order</code> in the last example is -changed to <code>Deny,Allow</code>, all hosts will be allowed access. -This happens because, regardless of the actual ordering of the -directives in the configuration file, the <code>Allow from -apache.org</code> will be evaluated last and will override the -<code>Deny from foo.apache.org</code>. All hosts not in the -<code>apache.org</code> domain will also be allowed access because the -default state will change to <em>allow</em>.</p> - -<p>The presence of an <code>Order</code> directive can -affect access to a part of the server even in the absence -of accompanying <code>Allow</code> and <code>Deny</code> -directives because of its effect on the default access state. -For example,</p> - -<blockquote><code> -<Directory /www><br> - Order Allow,Deny<br> -</Directory> -</code></blockquote> - -<p>will deny all access to the <code>/www</code> directory because -the default access state will be set to <em>deny</em>.</p> - -<p>The <code>Order</code> directive controls the order of access -directive processing only within each phase of the server's -configuration processing. This implies, for example, that an -<code>Allow</code> or <code>Deny</code> directive occurring -in a <Location> section will always be evaluated after -an <code>Allow</code> or <code>Deny</code> directive occurring -in a <Directory> section or <code>.htaccess</code> file, -regardless of the setting of the <code>Order</code> directive. -For details on the merging of configuration sections, -see the documentation on <a href="../sections.html">How Directory, -Location and Files sections work</a>.</p> - -<P>See also: <A HREF="#deny">Deny</A> and <A HREF="#allow">Allow</A>. -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + </blockquote> + + <p>In this case, browsers with a user-agent string beginning + with <tt>KnockKnock/2.0</tt> will be allowed access, and all + others will be denied.</p> + + <p>See also <a href="#deny">Deny</a>, <a + href="#order">Order</a> and <a + href="mod_setenvif.html#SetEnvIf">SetEnvIf</a>.</p> + <hr /> + + <h2><a id="deny" name="deny">Deny</a> <a id="denyfromenv" + name="denyfromenv">directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Deny} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Deny from + all|<em>host</em>|env=<em>env-variable</em> + [<em>host</em>|env=<em>env-variable</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Limit<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_access</p> + + <p>This directive allows access to the server to be restricted + based on hostname, IP address, or environment variables. The + arguments for the <code>Deny</code> directive are identical to + the arguments for the <a href="#allow">Allow</a> directive.</p> + + <p>See also <a href="#allow">Allow</a>, <a + href="#order">Order</a> and <a + href="mod_setenvif.html#SetEnvIf">SetEnvIf</a>.</p> + <hr /> + + <h2><a id="order" name="order">Order directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Order} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Order + <em>ordering</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>Order + Deny,Allow</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Limit<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_access</p> + + <p>The <code>Order</code> directive controls the default access + state and the order in which <a href="#allow">Allow</a> and <a + href="#deny">Deny</a> directives are evaluated. + <em>Ordering</em> is one of</p> + + <dl> + <dt>Deny,Allow</dt> + + <dd>The <code>Deny</code> directives are evaluated before the + <code>Allow</code> directives. Access is allowed by default. + Any client which does not match a <code>Deny</code> directive + or does match an <code>Allow</code> directive will be allowed + access to the server.</dd> + + <dt>Allow,Deny</dt> + + <dd>The <code>Allow</code> directives are evaluated before + the <code>Deny</code> directives. Access is denied by + default. Any client which does not match an + <code>Allow</code> directive or does match a + <code>Deny</code> directive will be denied access to the + server.</dd> + + <dt>Mutual-failure</dt> + + <dd>Only those hosts which appear on the <code>Allow</code> + list and do not appear on the <code>Deny</code> list are + granted access. This ordering has the same effect as + <code>Order Allow,Deny</code> and is deprecated in favor of + that configuration.</dd> + </dl> + + <p>Keywords may only be separated by a comma; no whitespace is + allowed between them. Note that in all cases every + <code>Allow</code> and <code>Deny</code> statement is + evaluated.</p> + + <p>In the following example, all hosts in the apache.org domain + are allowed access; all other hosts are denied access.</p> + + <blockquote> + <code>Order Deny,Allow<br /> + Deny from all<br /> + Allow from apache.org<br /> + </code> + </blockquote> + + <p>In the next example, all hosts in the apache.org domain are + allowed access, except for the hosts which are in the + foo.apache.org subdomain, who are denied access. All hosts not + in the apache.org domain are denied access because the default + state is to deny access to the server.</p> + + <blockquote> + <code>Order Allow,Deny<br /> + Allow from apache.org<br /> + Deny from foo.apache.org<br /> + </code> + </blockquote> + + <p>On the other hand, if the <code>Order</code> in the last + example is changed to <code>Deny,Allow</code>, all hosts will + be allowed access. This happens because, regardless of the + actual ordering of the directives in the configuration file, + the <code>Allow from apache.org</code> will be evaluated last + and will override the <code>Deny from foo.apache.org</code>. + All hosts not in the <code>apache.org</code> domain will also + be allowed access because the default state will change to + <em>allow</em>.</p> + + <p>The presence of an <code>Order</code> directive can affect + access to a part of the server even in the absence of + accompanying <code>Allow</code> and <code>Deny</code> + directives because of its effect on the default access state. + For example,</p> + + <blockquote> + <code><Directory /www><br /> + Order Allow,Deny<br /> + </Directory></code> + </blockquote> + + <p>will deny all access to the <code>/www</code> directory + because the default access state will be set to + <em>deny</em>.</p> + + <p>The <code>Order</code> directive controls the order of + access directive processing only within each phase of the + server's configuration processing. This implies, for example, + that an <code>Allow</code> or <code>Deny</code> directive + occurring in a <Location> section will always be + evaluated after an <code>Allow</code> or <code>Deny</code> + directive occurring in a <Directory> section or + <code>.htaccess</code> file, regardless of the setting of the + <code>Order</code> directive. For details on the merging of + configuration sections, see the documentation on <a + href="../sections.html">How Directory, Location and Files + sections work</a>.</p> + + <p>See also: <a href="#deny">Deny</a> and <a + href="#allow">Allow</a>. <!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mod_actions.html b/docs/manual/mod/mod_actions.html index 21f503db74..0749de22cf 100644 --- a/docs/manual/mod/mod_actions.html +++ b/docs/manual/mod/mod_actions.html @@ -1,140 +1,115 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_actions</H1> - - -<p>This module provides for executing CGI scripts based on media type or -request method. -</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_actions.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> actions_module -</P> - -<H2>Summary</H2> -<P> -This module has two directives. The Action directive lets you run CGI -scripts whenever a file of a certain type is requested. The Script -directive lets you run CGI scripts whenever a particular method is -used in a request. This makes it much easier to execute scripts that -process files. -</P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#action">Action</A></LI> -<LI><A HREF="#script">Script</A></LI> -</UL> - -<HR> - -<H2><A NAME="action">Action directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Action <EM>action-type cgi-script</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_actions -</P> -<P> -This directive adds an action, which will activate <EM>cgi-script</EM> when -<EM>action-type</EM> is triggered by the request. The <EM>action-type</EM> can -be either a <A HREF="../handler.html">handler</A> or a MIME content type. It -sends the URL and file path of the requested document using the standard CGI -PATH_INFO and PATH_TRANSLATED environment variables. -</P> -<HR> - -<H2><A NAME="script">Script directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Script <EM>method cgi-script</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_actions -</P> - -<P> -This directive adds an action, which will activate <i>cgi-script</i> when -a file is requested using the method of <i>method</i>. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. -</P> -<blockquote> -Any arbitrary method name may be used. <b>Method names are -case-sensitive</b>, so <code>Script PUT</code> and -<code>Script put</code> have two entirely different effects. -</blockquote> -<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 (<EM>e.g.</EM>, foo.html?hi). Otherwise, the request -will proceed normally. -</P> -<P> -Examples: -</P> -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_actions</h1> + + <p>This module provides for executing CGI scripts based on + media type or request method.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_actions.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + actions_module</p> + + <h2>Summary</h2> + + <p>This module has two directives. The Action directive lets + you run CGI scripts whenever a file of a certain type is + requested. The Script directive lets you run CGI scripts + whenever a particular method is used in a request. This makes + it much easier to execute scripts that process files.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#action">Action</a></li> + + <li><a href="#script">Script</a></li> + </ul> + <hr /> + + <h2><a id="action" name="action">Action directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Action <em>action-type + cgi-script</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_actions</p> + + <p>This directive adds an action, which will activate + <em>cgi-script</em> when <em>action-type</em> is triggered by + the request. The <em>action-type</em> can be either a <a + href="../handler.html">handler</a> or a MIME content type. It + sends the URL and file path of the requested document using the + standard CGI PATH_INFO and PATH_TRANSLATED environment + variables.</p> + <hr /> + + <h2><a id="script" name="script">Script directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Script <em>method + cgi-script</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_actions</p> + + <p>This directive adds an action, which will activate + <i>cgi-script</i> when a file is requested using the method of + <i>method</i>. It sends the URL and file path of the requested + document using the standard CGI PATH_INFO and PATH_TRANSLATED + environment variables.</p> + + <blockquote> + Any arbitrary method name may be used. <b>Method names are + case-sensitive</b>, so <code>Script PUT</code> and + <code>Script put</code> have two entirely different + effects. + </blockquote> + + <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 + (<em>e.g.</em>, foo.html?hi). Otherwise, the request will + proceed normally.</p> + + <p>Examples:</p> +<pre> # For <ISINDEX>-style searching Script GET /cgi-bin/search # A CGI PUT handler Script PUT /~bob/put.cgi -</PRE> +</pre> + <!--#include virtual="footer.html" --> + </body> +</html> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_alias.html b/docs/manual/mod/mod_alias.html index 2e86ec4dee..2ebd8d2781 100644 --- a/docs/manual/mod/mod_alias.html +++ b/docs/manual/mod/mod_alias.html @@ -1,418 +1,365 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_alias</H1> -<P> -This module provides for mapping different parts of the -host filesystem in the document tree, and for URL redirection. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_alias.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> alias_module -</P> - -<H2>Summary</H2> - -<P>The directives contained in this module allow for manipulation and -control of URLs as requests arrive at the server. The -<CODE>Alias</CODE> and <CODE>ScriptAlias</CODE> directives are used to -map between URLs and filesystem paths. This allows for content which -is not directly under the <A -HREF="core.html#documentroot"><CODE>DocumentRoot</CODE></A> to be -served as part of the web document tree. The <CODE>ScriptAlias</CODE> -directive has the additional effect of marking the target directory as -containing only CGI scripts. - -<P>The <CODE>Redirect</CODE> directives are used to instruct clients -to make a new request with a different URL. They are often used -when a resource has moved to a new location. - -<P>A more powerful and flexible set of directives for manipulating -URLs is contained in the <A -HREF="mod_rewrite.html"><CODE>mod_rewrite</CODE></A> module. - - -<H2>Directives</H2> -<UL> -<LI><A HREF="#alias">Alias</A> -<LI><A HREF="#aliasmatch">AliasMatch</A> -<LI><A HREF="#redirect">Redirect</A> -<LI><A HREF="#redirectmatch">RedirectMatch</A> -<LI><A HREF="#redirecttemp">RedirectTemp</A> -<LI><A HREF="#redirectperm">RedirectPermanent</A> -<LI><A HREF="#scriptalias">ScriptAlias</A> -<LI><A HREF="#scriptaliasmatch">ScriptAliasMatch</A> -</UL> -<HR> - - -<H2><A NAME="alias">Alias directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Alias} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Alias <EM>URL-path file-path</em>|<em>directory-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<P> -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>. -<P> -Example: -</P> -<BLOCKQUOTE><CODE>Alias /image /ftp/pub/image</CODE></BLOCKQUOTE> -<P> -A request for http://myserver/image/foo.gif would cause the server to -return the file /ftp/pub/image/foo.gif. -</P> -<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/apache/icons/</CODE> then -the url <CODE>/icons</CODE> will not be aliased. -</P> -<P> -Note that you may need to specify additional -<A HREF="core.html#directory"><CODE><Directory></CODE></A> sections -which cover the <EM>destination</EM> of aliases. Aliasing occurs -before <CODE><Directory></CODE> sections are checked, so only -the destination of aliases are affected. (Note however -<A HREF="core.html#location"><CODE><Location></CODE></A> -sections are run through once before aliases are performed, so they -will apply.) -<P> -See also <A HREF="#scriptalias">ScriptAlias</A>. -</P> -<HR> - -<H2><A NAME="aliasmatch">AliasMatch</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AliasMatch <EM>regex file-path</em>|<em>directory-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> - -<P>This directive is equivalent to <A HREF="#alias">Alias</A>, but -makes use of standard regular expressions, instead of simple prefix -matching. The supplied regular expression is matched against the -URL-path, and if it matches, the server will substitute any -parenthesized matches into the given string and use it as a -filename. For example, to activate the <CODE>/icons</CODE> directory, -one might use: -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_alias</h1> + + <p>This module provides for mapping different parts of the host + filesystem in the document tree, and for URL redirection.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_alias.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + alias_module</p> + + <h2>Summary</h2> + + <p>The directives contained in this module allow for + manipulation and control of URLs as requests arrive at the + server. The <code>Alias</code> and <code>ScriptAlias</code> + directives are used to map between URLs and filesystem paths. + This allows for content which is not directly under the <a + href="core.html#documentroot"><code>DocumentRoot</code></a> to + be served as part of the web document tree. The + <code>ScriptAlias</code> directive has the additional effect of + marking the target directory as containing only CGI + scripts.</p> + + <p>The <code>Redirect</code> directives are used to instruct + clients to make a new request with a different URL. They are + often used when a resource has moved to a new location.</p> + + <p>A more powerful and flexible set of directives for + manipulating URLs is contained in the <a + href="mod_rewrite.html"><code>mod_rewrite</code></a> + module.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#alias">Alias</a></li> + + <li><a href="#aliasmatch">AliasMatch</a></li> + + <li><a href="#redirect">Redirect</a></li> + + <li><a href="#redirectmatch">RedirectMatch</a></li> + + <li><a href="#redirecttemp">RedirectTemp</a></li> + + <li><a href="#redirectperm">RedirectPermanent</a></li> + + <li><a href="#scriptalias">ScriptAlias</a></li> + + <li><a href="#scriptaliasmatch">ScriptAliasMatch</a></li> + </ul> + <hr /> + + <h2><a id="alias" name="alias">Alias directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Alias} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Alias <em>URL-path + file-path</em>|<em>directory-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>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>.</p> + + <p>Example:</p> + + <blockquote> + <code>Alias /image /ftp/pub/image</code> + </blockquote> + + <p>A request for http://myserver/image/foo.gif would cause the + server to return the file /ftp/pub/image/foo.gif.</p> + + <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/apache/icons/</code> then the url + <code>/icons</code> will not be aliased.</p> + + <p>Note that you may need to specify additional <a + href="core.html#directory"><code><Directory></code></a> + sections which cover the <em>destination</em> of aliases. + Aliasing occurs before <code><Directory></code> sections + are checked, so only the destination of aliases are affected. + (Note however <a + href="core.html#location"><code><Location></code></a> + sections are run through once before aliases are performed, so + they will apply.)</p> + + <p>See also <a href="#scriptalias">ScriptAlias</a>.</p> + <hr /> + + <h2><a id="aliasmatch" name="aliasmatch">AliasMatch</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AliasMatch <em>regex + file-path</em>|<em>directory-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>This directive is equivalent to <a href="#alias">Alias</a>, + but makes use of standard regular expressions, instead of + simple prefix matching. The supplied regular expression is + matched against the URL-path, and if it matches, the server + will substitute any parenthesized matches into the given string + and use it as a filename. For example, to activate the + <code>/icons</code> directory, one might use:</p> +<pre> AliasMatch ^/icons(.*) /usr/local/apache/icons$1 -</PRE> -</P> - -<HR> - -<H2><A NAME="redirect">Redirect directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Redirect [<EM>status</EM>] - <EM>URL-path URL</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<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>. -</P> -<P> -Example: -</P> -<BLOCKQUOTE><CODE>Redirect /service -http://foo2.bar.com/service</CODE></BLOCKQUOTE> -<P> -If the client requests http://myserver/service/foo.txt, it will be told to -access http://foo2.bar.com/service/foo.txt instead. -</P> -<P> -<STRONG>Note:</STRONG> 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> -<P> -If no <EM>status</EM> argument is given, the redirect will be -"temporary" (HTTP status 302). This indicates to the client that the -resource has moved temporarily. The <EM>status</EM> -argument can be used to return other HTTP status codes: -<P> -<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> -<P> -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). -</P> -<HR> - -<H2><A NAME="redirectmatch">RedirectMatch</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - RedirectMatch [<EM>status</EM>] <EM>regex URL</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> - -<P>This directive is equivalent to <A HREF="#redirect">Redirect</A>, -but makes use of standard regular expressions, instead of simple -prefix matching. The supplied regular expression is matched against -the URL-path, and if it matches, the server will substitute any -parenthesized matches into the given string and use it as a -filename. For example, to redirect all GIF files to like-named JPEG -files on another server, one might use: -<PRE> +</pre> + <br /> + <br /> + + <hr /> + + <h2><a id="redirect" name="redirect">Redirect + directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Redirect} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Redirect + [<em>status</em>] <em>URL-path URL</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <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>.</p> + + <p>Example:</p> + + <blockquote> + <code>Redirect /service http://foo2.bar.com/service</code> + </blockquote> + + <p>If the client requests http://myserver/service/foo.txt, it + will be told to access http://foo2.bar.com/service/foo.txt + instead.</p> + + <p><strong>Note:</strong> 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> + + <p>If no <em>status</em> argument is given, the redirect will + be "temporary" (HTTP status 302). This indicates to the client + that the resource has moved temporarily. The <em>status</em> + argument can be used to return other HTTP status codes:</p> + + <dl> + <dt>permanent</dt> + + <dd>Returns a permanent redirect status (301) indicating that + the resource has moved permanently.</dd> + + <dt>temp</dt> + + <dd>Returns a temporary redirect status (302). This is the + default.</dd> + + <dt>seeother</dt> + + <dd>Returns a "See Other" status (303) indicating that the + resource has been replaced.</dd> + + <dt>gone</dt> + + <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.</dd> + </dl> + + <p>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).</p> + <hr /> + + <h2><a id="redirectmatch" + name="redirectmatch">RedirectMatch</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RedirectMatch + [<em>status</em>] <em>regex URL</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>This directive is equivalent to <a + href="#redirect">Redirect</a>, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, + and if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to redirect all GIF files to like-named JPEG files on + another server, one might use:</p> +<pre> RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg -</PRE> -</P> - -<HR> - -<H2><A NAME="redirecttemp">RedirectTemp directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RedirectTemp <EM>URL-path URL</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<P> -This directive makes the client know that the Redirect is only -temporary (status 302). Exactly equivalent to <CODE>Redirect -temp</CODE>. -</P> -<HR> - -<H2><A NAME="redirectperm">RedirectPermanent directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RedirectPermanent <EM>URL-path URL</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<P> -This directive makes the client know that the Redirect is permanent -(status 301). Exactly equivalent to <CODE>Redirect permanent</CODE>. -</P> -<HR> - -<H2><A NAME="scriptalias">ScriptAlias directive</A></H2> -<P> -<!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptAlias <EM>URL-path file-path</em>|<em>directory-path</em> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> -<P> -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 the second argument which is a full -pathname in the local filesystem. -<P> -Example: -</P> -<BLOCKQUOTE><CODE>ScriptAlias /cgi-bin/ /web/cgi-bin/</CODE></BLOCKQUOTE> -<P> -A request for http://myserver/cgi-bin/foo would cause the server to -run the script /web/cgi-bin/foo. -</P> - -<HR> - -<H2><A NAME="scriptaliasmatch">ScriptAliasMatch</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptAliasMatch - <EM>regex file-path</em>|<em>directory-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_alias -</P> - -<P>This directive is equivalent to <A -HREF="#scriptalias">ScriptAlias</A>, but makes use of standard regular -expressions, instead of simple prefix matching. The supplied regular -expression is matched against the URL-path, and if it matches, the -server will substitute any parenthesized matches into the given string -and use it as a filename. For example, to activate the standard -<CODE>/cgi-bin</CODE>, one might use: -<PRE> +</pre> + <br /> + <br /> + + <hr /> + + <h2><a id="redirecttemp" name="redirecttemp">RedirectTemp + directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Redirect} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RedirectTemp + <em>URL-path URL</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>This directive makes the client know that the Redirect is + only temporary (status 302). Exactly equivalent to + <code>Redirect temp</code>.</p> + <hr /> + + <h2><a id="redirectperm" name="redirectperm">RedirectPermanent + directive</a></h2> + + <p><!--%plaintext <?INDEX {\tt Redirect} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RedirectPermanent + <em>URL-path URL</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>This directive makes the client know that the Redirect is + permanent (status 301). Exactly equivalent to <code>Redirect + permanent</code>.</p> + <hr /> + + <h2><a id="scriptalias" name="scriptalias">ScriptAlias + directive</a></h2> + + <p> + <!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ScriptAlias + <em>URL-path file-path</em>|<em>directory-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>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 the second argument which is a + full pathname in the local filesystem.</p> + + <p>Example:</p> + + <blockquote> + <code>ScriptAlias /cgi-bin/ /web/cgi-bin/</code> + </blockquote> + + <p>A request for http://myserver/cgi-bin/foo would cause the + server to run the script /web/cgi-bin/foo.</p> + <hr /> + + <h2><a id="scriptaliasmatch" + name="scriptaliasmatch">ScriptAliasMatch</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ScriptAliasMatch + <em>regex file-path</em>|<em>directory-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_alias</p> + + <p>This directive is equivalent to <a + href="#scriptalias">ScriptAlias</a>, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, + and if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to activate the standard <code>/cgi-bin</code>, one + might use:</p> +<pre> ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1 -</PRE> -</P> +</pre> + <br /> + <br /> + <!--#include virtual="footer.html" --> + </body> +</html> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_auth.html b/docs/manual/mod/mod_auth.html index d624f6519d..7353c26d0e 100644 --- a/docs/manual/mod/mod_auth.html +++ b/docs/manual/mod/mod_auth.html @@ -1,246 +1,221 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_auth</H1> - -<P>This module provides for user authentication using text files. - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_auth.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> auth_module -</P> - -<H2>Summary</H2> - -<P>This module allows the use of HTTP Basic Authentication to restrict -access by looking up users in plain text password and group files. -Similar functionality and greater scalability is provided by <A -HREF="mod_auth_dbm.html">mod_auth_dbm</A> and <A -HREF="mod_auth_db.html">mod_auth_db</A>. HTTP Digest Authentication -is provided by <A HREF="mod_auth_digest.html">mod_auth_digest</A>. - - -<H2>Directives</H2> - -<UL> -<LI><A HREF="#authgroupfile">AuthGroupFile</A> -<LI><A HREF="#authuserfile">AuthUserFile</A> -<LI><A HREF="#authauthoritative">AuthAuthoritative</A> -</UL> - -<P>See also: <A HREF="core.html#require">require</A> -and <A HREF="core.html#satisfy">satisfy</A>.</P> - -<HR> - - -<H2><A NAME="authgroupfile">AuthGroupFile</A> directive</H2> -<!--%plaintext <?INDEX {\tt AuthGroupFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthGroupFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -The AuthGroupFile directive sets the name of a textual file containing the list -of user groups for user authentication. <EM>File-path</EM> is the path -to the group file. If it is not absolute (<EM>i.e.</EM>, if it -doesn't begin with a slash), it is treated as relative to the ServerRoot. -<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 text 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> - -<H2><A NAME="authuserfile">AuthUserFile</A> directive</H2> -<!--%plaintext <?INDEX {\tt AuthUserFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthUserFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -The AuthUserFile directive sets the name of a textual file containing -the list of users and passwords for user -authentication. <EM>File-path</EM> is the path to the user -file. If it is not absolute (<EM>i.e.</EM>, if it doesn't begin with a -slash), it is treated as relative to the ServerRoot. -<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> -The utility <a href="../programs/htpasswd.html">htpasswd</a> which is -installed as part of the binary distribution, or which can be found in -<code>src/support</code>, is used to maintain this password file. See -the <code>man</code> page for more details. In short -<p> -<blockquote> - <code>htpasswd -c Filename username</code><br> - Create a password file 'Filename' with 'username' - as the initial ID. It will prompt for the password. - <code>htpasswd Filename username2</code><br> - Adds or modifies in password file 'Filename' the 'username'. -</blockquote> -<P> Note that -searching large text files is <EM>very</EM> 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> -<H2><A NAME="authauthoritative">AuthAuthoritative</A> directive</H2> -<!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthAuthoritative on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthAuthoritative on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -Setting the AuthAuthoritative directive explicitly to <STRONG>'off'</STRONG> -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 <STRONG>no userID</STRONG> or -<STRONG>rule</STRONG> 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 <CODE>Require</CODE> 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>, -<CODE>mod_auth_msql.c</CODE>, 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> - -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> 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 NCSA 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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_auth</h1> + + <p>This module provides for user authentication using text + files.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_auth.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + auth_module</p> + + <h2>Summary</h2> + + <p>This module allows the use of HTTP Basic Authentication to + restrict access by looking up users in plain text password and + group files. Similar functionality and greater scalability is + provided by <a href="mod_auth_dbm.html">mod_auth_dbm</a> and <a + href="mod_auth_db.html">mod_auth_db</a>. HTTP Digest + Authentication is provided by <a + href="mod_auth_digest.html">mod_auth_digest</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#authgroupfile">AuthGroupFile</a></li> + + <li><a href="#authuserfile">AuthUserFile</a></li> + + <li><a href="#authauthoritative">AuthAuthoritative</a></li> + </ul> + + <p>See also: <a href="core.html#require">require</a> and <a + href="core.html#satisfy">satisfy</a>.</p> + <hr /> + + <h2><a id="authgroupfile" + name="authgroupfile">AuthGroupFile</a> directive</h2> + <!--%plaintext <?INDEX {\tt AuthGroupFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthGroupFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth + + <p>The AuthGroupFile directive sets the name of a textual file + containing the list of user groups for user authentication. + <em>File-path</em> is the path to the group file. If it is not + absolute (<em>i.e.</em>, if it doesn't begin with a slash), it + is treated as relative to the ServerRoot.</p> + + <p>Each line of the group file contains a groupname followed by + a colon, followed by the member usernames separated by spaces. + Example:</p> + + <blockquote> + <code>mygroup: bob joe anne</code> + </blockquote> + Note that searching large text 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> + + <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 /> + + <h2><a id="authuserfile" name="authuserfile">AuthUserFile</a> + directive</h2> + <!--%plaintext <?INDEX {\tt AuthUserFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthUserFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth + + <p>The AuthUserFile directive sets the name of a textual file + containing the list of users and passwords for user + authentication. <em>File-path</em> is the path to the user + file. If it is not absolute (<em>i.e.</em>, if it doesn't begin + with a slash), it is treated as relative to the ServerRoot.</p> + + <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> + + <p>The utility <a href="../programs/htpasswd.html">htpasswd</a> + which is installed as part of the binary distribution, or which + can be found in <code>src/support</code>, is used to maintain + this password file. See the <code>man</code> page for more + details. In short</p> + + <blockquote> + <code>htpasswd -c Filename username</code><br /> + Create a password file 'Filename' with 'username' as the + initial ID. It will prompt for the password. <code>htpasswd + Filename username2</code><br /> + Adds or modifies in password file 'Filename' the 'username'. + </blockquote> + + <p>Note that searching large text files is <em>very</em> + inefficient; <a + href="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</a> + should be used instead.</p> + + <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> + + <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 /> + + <h2><a id="authauthoritative" + name="authauthoritative">AuthAuthoritative</a> directive</h2> + <!--%plaintext <?INDEX {\tt AuthAuthoritative} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthAuthoritative + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthAuthoritative on</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth + + <p>Setting the AuthAuthoritative directive explicitly to + <strong>'off'</strong> 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 <strong>no + userID</strong> or <strong>rule</strong> 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> + + <p>So if a userID appears in the database of more than one + module; or if a valid <code>Require</code> 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> + + <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>, + <code>mod_auth_msql.c</code>, 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> + + <p><a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> 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 NCSA compliant behaviour.</p> + + <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> + + <p>See also <a href="core.html#authname">AuthName</a>, <a + href="core.html#authtype">AuthType</a> and <a + href="#authgroupfile">AuthGroupFile</a>.</p> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html index d5f28d6db8..a7d7f97ef6 100644 --- a/docs/manual/mod/mod_auth_anon.html +++ b/docs/manual/mod/mod_auth_anon.html @@ -1,322 +1,277 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_auth_anon</H1> - -This module allows "anonymous" user access to authenticated areas. - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_auth_anon.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> anon_auth_module -</P> - - -<H2>Summary</H2> - -<P>This module does access control in a manner similar to -anonymous-ftp sites; <EM>i.e.</EM> have a 'magic' user id 'anonymous' -and the email address as a password. These email addresses can be -logged.</p> - -<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> - -<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> - -<H2><A NAME="Example">Example</A></H2> - -The example below (when combined with the Auth directives -of a htpasswd-file based (or GDM, mSQL <EM>etc.</EM>) 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 <STRONG>not</STRONG> case sensitive. -<LI> -And the Email addresses entered in the passwd field are logged to -the error log file -(<CODE>Anonymous_LogEmail</CODE>) -</UL> -<P> -Excerpt of access.conf: -<BLOCKQUOTE><CODE> -Anonymous_NoUserId off<BR> -Anonymous_MustGiveEmail on<BR> -Anonymous_VerifyEmail on<BR> -Anonymous_LogEmail on<BR> -Anonymous anonymous guest www test welcome<P> -<P> -AuthName "Use 'anonymous' & Email address for guest entry"<BR> -AuthType basic -<P> -# An AuthUserFile/AuthDBUserFile/AuthDBMUserFile<BR> -# directive must be specified, or use<BR> -# Anonymous_Authoritative for public access.<BR> -# In the .htaccess for the public directory, add:<BR> -<Files *><BR> -Order Deny,Allow <BR> -Allow from all <BR> -<P> -Require valid-user <BR> -</Files><BR> -</CODE></BLOCKQUOTE> - -<HR> - -<H2><A NAME="anonymous">Anonymous directive</A></H2> -<!--%plaintext <?INDEX {\tt Anonymous} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous <EM>user</em> [<em>user</em>] ...<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> none<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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 <STRONG>case-IN-sensitive</STRONG>. - <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> - -<H2><A NAME="Authoritative">Anonymous_Authoritative directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_Authoritative on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_Authoritative off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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> - -<H2><A NAME="LogEmail">Anonymous_LogEmail directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_LogEmail on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_LogEmail on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - When set 'on', the default, the 'password' entered (which hopefully - contains a sensible email address) is logged in the error log. -<HR> - -<H2><A NAME="MustGiveEmail">Anonymous_MustGiveEmail directive</A></H2> -<!--%plaintext <?INDEX {\tt Anonymous_MustGiveEmail} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_MustGiveEmail on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_MustGiveEmail on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_anon<P> - - Specifies whether the user must specify an email - address as the password. This prohibits blank passwords. -<HR> - -<H2><A NAME="NoUserID">Anonymous_NoUserID directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_NoUserID on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_NoUserID off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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> - -<H2><A NAME="VerifyEmail">Anonymous_VerifyEmail directive</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Anonymous_VerifyEmail on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Anonymous_VerifyEmail off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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>). - - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_auth_anon</h1> + This module allows "anonymous" user access to authenticated + areas. + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_auth_anon.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + anon_auth_module</p> + + <h2>Summary</h2> + + <p>This module does access control in a manner similar to + anonymous-ftp sites; <em>i.e.</em> have a 'magic' user id + 'anonymous' and the email address as a password. These email + addresses can be logged.</p> + + <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> + + <h2><a id="Directives" name="Directives">Directives</a></h2> + + <ul> + <li><a href="#anonymous">Anonymous</a></li> + + <li><a href="#Authoritative">Anonymous_Authoritative</a></li> + + <li><a href="#LogEmail">Anonymous_LogEmail</a></li> + + <li><a href="#MustGiveEmail">Anonymous_MustGiveEmail</a></li> + + <li><a href="#NoUserID">Anonymous_NoUserID</a></li> + + <li><a href="#VerifyEmail">Anonymous_VerifyEmail</a></li> + </ul> + + <h2><a id="Example" name="Example">Example</a></h2> + The example below (when combined with the Auth directives of a + htpasswd-file based (or GDM, mSQL <em>etc.</em>) 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> + + <li>It insists that the user enters a password. + (<code>Anonymous_MustGiveEmail</code>)</li> + + <li>The password entered must be a valid email address, ie. + contain at least one '@' and a '.'. + (<code>Anonymous_VerifyEmail</code>)</li> + + <li>The userID must be one of <code>anonymous guest www test + welcome</code> and comparison is <strong>not</strong> case + sensitive.</li> + + <li>And the Email addresses entered in the passwd field are + logged to the error log file + (<code>Anonymous_LogEmail</code>)</li> + </ul> + + <p>Excerpt of access.conf:</p> + + <blockquote> + <code>Anonymous_NoUserId off<br /> + Anonymous_MustGiveEmail on<br /> + Anonymous_VerifyEmail on<br /> + Anonymous_LogEmail on<br /> + Anonymous anonymous guest www test welcome</code> + + <p><code>AuthName "Use 'anonymous' & Email address for + guest entry"<br /> + AuthType basic</code></p> + + <p><code># An + AuthUserFile/AuthDBUserFile/AuthDBMUserFile<br /> + # directive must be specified, or use<br /> + # Anonymous_Authoritative for public access.<br /> + # In the .htaccess for the public directory, add:<br /> + <Files *><br /> + Order Deny,Allow<br /> + Allow from all<br /> + </code></p> + + <p><code>Require valid-user<br /> + </Files><br /> + </code></p> + </blockquote> + <hr /> + + <h2><a id="anonymous" name="anonymous">Anonymous + directive</a></h2> + <!--%plaintext <?INDEX {\tt Anonymous} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Anonymous <em>user</em> + [<em>user</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> none<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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> + + <p>Please note that the comparison is + <strong>case-IN-sensitive</strong>.<br /> + I strongly suggest that the magic username + '<code>anonymous</code>' is always one of the allowed + userIDs.</p> + + <p>Example:<br /> + <code>Anonymous anonymous "Not Registered" 'I don\'t + know'</code></p> + + <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'.</p> + <hr /> + + <h2><a id="Authoritative" + name="Authoritative">Anonymous_Authoritative directive</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Anonymous_Authoritative + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>Anonymous_Authoritative off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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> + + <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.</p> + <hr /> + + <h2><a id="LogEmail" name="LogEmail">Anonymous_LogEmail + directive</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Anonymous_LogEmail + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>Anonymous_LogEmail on</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_anon + + <p>When set 'on', the default, the 'password' entered (which + hopefully contains a sensible email address) is logged in the + error log.</p> + <hr /> + + <h2><a id="MustGiveEmail" + name="MustGiveEmail">Anonymous_MustGiveEmail directive</a></h2> + <!--%plaintext <?INDEX {\tt Anonymous_MustGiveEmail} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Anonymous_MustGiveEmail + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>Anonymous_MustGiveEmail on</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_anon + + <p>Specifies whether the user must specify an email address as + the password. This prohibits blank passwords.</p> + <hr /> + + <h2><a id="NoUserID" name="NoUserID">Anonymous_NoUserID + directive</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Anonymous_NoUserID + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>Anonymous_NoUserID off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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.</p> + <hr /> + + <h2><a id="VerifyEmail" + name="VerifyEmail">Anonymous_VerifyEmail directive</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Anonymous_VerifyEmail + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>Anonymous_VerifyEmail off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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>). + <!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_auth_db.html b/docs/manual/mod/mod_auth_db.html index 04e24637ca..92903e725b 100644 --- a/docs/manual/mod/mod_auth_db.html +++ b/docs/manual/mod/mod_auth_db.html @@ -1,250 +1,235 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_auth_db</H1> - -<p>This module provides for user authentication using Berkeley DB -files. </p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_auth_db.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> db_auth_module -</P> - -<h2>Summary</h2> - -<p>This module provides 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.</p> - -<p>On some BSD systems (<EM>e.g.</EM>, FreeBSD and NetBSD) dbm is -automatically mapped to Berkeley DB. You can use either <A -HREF="mod_auth_dbm.html">mod_auth_dbm</A> or mod_auth_db. The latter -makes it more obvious that it's Berkeley DB. On other platforms where -you want to use the DB library you usually have to install it -first. See <A -HREF="http://www.sleepycat.com/">http://www.sleepycat.com/</A> for the -distribution. The interface this module uses is the one from DB -version 1.85 and 1.86, but DB version 2.x can also be used when -compatibility mode is enabled.</p> - -<h2>Directives</h2> - -<UL> -<LI><A HREF="#authdbgroupfile">AuthDBGroupFile</A> -<LI><A HREF="#authdbuserfile">AuthDBUserFile</A> -<LI><A HREF="#authdbauthoritative">AuthDBAuthoritative</A> -</UL> - -<p>See also: <a href="core.html#satisfy">satisfy</a> and -<a href="core.html#require">require</a>.</p> - -<HR> - - -<H2><A NAME="authdbgroupfile">AuthDBGroupFile directive</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBGroupFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_db<P> - -The AuthDBGroupFile directive sets the name of a DB file containing the list -of user groups for user authentication. <EM>File-path</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> - -<H2><A NAME="authdbuserfile">AuthDBUserFile</A> directive</H2> -<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBUserFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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>File-path</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> - -<p>A perl script called -href="../programs/dbmmanage.html">dbmmanage</a> is included with -Apache. This program can be used to create and update DB format -password files for use with this module.</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> -<H2><A NAME="authdbauthoritative">AuthDBAuthoritative</A> directive</H2> -<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBAuthoritative on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDBAuthoritative on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth<P> - -Setting the AuthDBAuthoritative directive explicitly to <STRONG>'off'</STRONG> -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 <STRONG>no userID</STRONG> or -<STRONG>rule</STRONG> 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 <CODE>Require</CODE> 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> - - -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 NCSA 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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_auth_db</h1> + + <p>This module provides for user authentication using Berkeley + DB files.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_auth_db.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + db_auth_module</p> + + <h2>Summary</h2> + + <p>This module provides 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.</p> + + <p>On some BSD systems (<em>e.g.</em>, FreeBSD and NetBSD) dbm + is automatically mapped to Berkeley DB. You can use either <a + href="mod_auth_dbm.html">mod_auth_dbm</a> or mod_auth_db. The + latter makes it more obvious that it's Berkeley DB. On other + platforms where you want to use the DB library you usually have + to install it first. See <a + href="http://www.sleepycat.com/">http://www.sleepycat.com/</a> + for the distribution. The interface this module uses is the one + from DB version 1.85 and 1.86, but DB version 2.x can also be + used when compatibility mode is enabled.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#authdbgroupfile">AuthDBGroupFile</a></li> + + <li><a href="#authdbuserfile">AuthDBUserFile</a></li> + + <li><a + href="#authdbauthoritative">AuthDBAuthoritative</a></li> + </ul> + + <p>See also: <a href="core.html#satisfy">satisfy</a> and <a + href="core.html#require">require</a>.</p> + <hr /> + + <h2><a id="authdbgroupfile" + name="authdbgroupfile">AuthDBGroupFile directive</a></h2> + <!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDBGroupFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_db + + <p>The AuthDBGroupFile directive sets the name of a DB file + containing the list of user groups for user authentication. + <em>File-path</em> is the absolute path to the group file.</p> + + <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> + + <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> + + <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 + + <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 /> + + <h2><a id="authdbuserfile" + name="authdbuserfile">AuthDBUserFile</a> directive</h2> + <!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDBUserFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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>File-path</em> is the absolute path to the + user file.</p> + + <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> + + <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> + + <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> + + <p>A perl script called + href="../programs/dbmmanage.html">dbmmanage is included with + Apache. This program can be used to create and update DB format + password files for use with this module.</p> + See also <a href="core.html#authname">AuthName</a>, <a + href="core.html#authtype">AuthType</a> and <a + href="#authdbgroupfile">AuthDBGroupFile</a>. + <hr /> + + <h2><a id="authdbauthoritative" + name="authdbauthoritative">AuthDBAuthoritative</a> + directive</h2> + <!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDBAuthoritative + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthDBAuthoritative on</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth + + <p>Setting the AuthDBAuthoritative directive explicitly to + <strong>'off'</strong> 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 <strong>no + userID</strong> or <strong>rule</strong> 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> + + <p>So if a userID appears in the database of more than one + module; or if a valid <code>Require</code> 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> + + <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> + + <p>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 NCSA + compliant behaviour.</p> + + <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> + + <p>See also <a href="core.html#authname">AuthName</a>, <a + href="core.html#authtype">AuthType</a> and <a + href="#authdbgroupfile">AuthDBGroupFile</a>.</p> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_auth_dbm.html b/docs/manual/mod/mod_auth_dbm.html index 41e71b0b58..8d9f88af61 100644 --- a/docs/manual/mod/mod_auth_dbm.html +++ b/docs/manual/mod/mod_auth_dbm.html @@ -1,242 +1,226 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_auth_dbm</H1> - -<p>This module provides for user authentication using DBM files.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_auth_dbm.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> dbm_auth_module -</P> - -<h2>Summary</h2> - -<p>This module provides for HTTP Basic Authentication, where the -usernames and passwords are stored in DBM type database files. It is -an alternative to the plain text password files provided by <a -href="mod_auth.html">mod_auth</A> and the Berkely DB password files -provided by <a href="mod_auth_db.html">mod_auth_db</a>.</p> - -<h2>Directives</h2> - -<ul> -<LI><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A> -<LI><A HREF="#authdbmuserfile">AuthDBMUserFile</A> -<LI><A HREF="#authdbmauthoritative">AuthDBMAuthoritative</A> -</ul> - -<p>See also: <a href="core.html#satisfy">Satisfy</a> and -<a href="core.html#require">Require</a>. -<HR> - - -<H2><A NAME="authdbmgroupfile">AuthDBMGroupFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBMGroupFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBMGroupFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_dbm<P> - -The AuthDBMGroupFile directive sets the name of a DBM file containing the list -of user groups for user authentication. <EM>File-path</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> - -<H2><A NAME="authdbmuserfile">AuthDBMUserFile</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBMUserFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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>File-path</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> - -<p>A perl script called -href="../programs/dbmmanage.html">dbmmanage</a> is included with -Apache. This program can be used to create and update DBM format -password files for use with this module.</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> -<H2><A NAME="authdbmauthoritative">AuthDBMAuthoritative</A></H2> -<!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDBMAuthoritative on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <code>AuthDBMAuthoritative on</code><br> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_dbm<P> - -Setting the AuthDBMAuthoritative directive explicitly to <STRONG>'off'</STRONG> -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 <STRONG>no userID</STRONG> or -<STRONG>rule</STRONG> 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 <CODE>Require</CODE> 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> - - -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 NCSA 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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_auth_dbm</h1> + + <p>This module provides for user authentication using DBM + files.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_auth_dbm.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + dbm_auth_module</p> + + <h2>Summary</h2> + + <p>This module provides for HTTP Basic Authentication, where + the usernames and passwords are stored in DBM type database + files. It is an alternative to the plain text password files + provided by <a href="mod_auth.html">mod_auth</a> and the + Berkely DB password files provided by <a + href="mod_auth_db.html">mod_auth_db</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#authdbmgroupfile">AuthDBMGroupFile</a></li> + + <li><a href="#authdbmuserfile">AuthDBMUserFile</a></li> + + <li><a + href="#authdbmauthoritative">AuthDBMAuthoritative</a></li> + </ul> + + <p>See also: <a href="core.html#satisfy">Satisfy</a> and <a + href="core.html#require">Require</a>.</p> + <hr /> + + <h2><a id="authdbmgroupfile" + name="authdbmgroupfile">AuthDBMGroupFile</a></h2> + <!--%plaintext <?INDEX {\tt AuthDBMGroupFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDBMGroupFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_dbm + + <p>The AuthDBMGroupFile directive sets the name of a DBM file + containing the list of user groups for user authentication. + <em>File-path</em> is the absolute path to the group file.</p> + + <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> + + <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> + + <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 + + <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 /> + + <h2><a id="authdbmuserfile" + name="authdbmuserfile">AuthDBMUserFile</a></h2> + <!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDBMUserFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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>File-path</em> is the absolute path to the + user file.</p> + + <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> + + <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> + + <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> + + <p>A perl script called + href="../programs/dbmmanage.html">dbmmanage is included with + Apache. This program can be used to create and update DBM + format password files for use with this module.</p> + See also <a href="core.html#authname">AuthName</a>, <a + href="core.html#authtype">AuthType</a> and <a + href="#authdbmgroupfile">AuthDBMGroupFile</a>. + <hr /> + + <h2><a id="authdbmauthoritative" + name="authdbmauthoritative">AuthDBMAuthoritative</a></h2> + <!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDBMAuthoritative + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthDBMAuthoritative on</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_dbm + + <p>Setting the AuthDBMAuthoritative directive explicitly to + <strong>'off'</strong> 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 <strong>no + userID</strong> or <strong>rule</strong> 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> + + <p>So if a userID appears in the database of more than one + module; or if a valid <code>Require</code> 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> + + <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> + + <p>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 NCSA + compliant behaviour.</p> + + <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> + + <p>See also <a href="core.html#authname">AuthName</a>, <a + href="core.html#authtype">AuthType</a> and <a + href="#authdbmgroupfile">AuthDBMGroupFile</a>.</p> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_auth_digest.html b/docs/manual/mod/mod_auth_digest.html index 8a0108e84a..f20ae0b225 100644 --- a/docs/manual/mod/mod_auth_digest.html +++ b/docs/manual/mod/mod_auth_digest.html @@ -1,73 +1,79 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_auth_digest</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_auth_digest</H1> - -<p>This module provides for user authentication using MD5 Digest -Authentication.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Experimental -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_auth_digest.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> digest_auth_module -</P> - -<h2>Summary</h2> - -<P>This is an updated version of <A -HREF="mod_digest.html">mod_digest</A>. However, it has not been -extensively tested and is therefore marked experimental. If you use -this module, you must make sure to <em>not</em> use mod_digest -(because they share some of the same configuration directives). - -<h2>Directives</h2> - -<ul> -<LI><A HREF="#authdigestfile">AuthDigestFile</A> -<LI><A HREF="#authdigestgroupfile">AuthDigestGroupFile</A> -<LI><A HREF="#authdigestqop">AuthDigestQop</A> -<LI><A HREF="#authdigestnoncelifetime">AuthDigestNonceLifetime</A> -<LI><A HREF="#authdigestnonceformat">AuthDigestNonceFormat</A> -<LI><A HREF="#authdigestnccheck">AuthDigestNcCheck</A> -<LI><A HREF="#authdigestalgorithm">AuthDigestAlgorithm</A> -<LI><A HREF="#authdigestdomain">AuthDigestDomain</A> -</ul> - -<p>See also: <a href="core.html#require">Require</a> and -<a href="core.html#satisfy">Satisfy</a>. - -<H3><A NAME="usingdigest">Using Digest Authentication</A></H3> - -<P>Using MD5 Digest authentication is very simple. Simply set up -authentication normally, using "AuthType Digest" and "AuthDigestFile" -instead of the normal "AuthType Basic" and "AuthUserFile"; also, -replace any "AuthGroupFile" with "AuthDigestGroupFile". Then add a -"AuthDigestDomain" directive containing at least the root URI(s) for -this protection space. Example: - -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_auth_digest</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_auth_digest</h1> + + <p>This module provides for user authentication using MD5 + Digest Authentication.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_auth_digest.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + digest_auth_module</p> + + <h2>Summary</h2> + + <p>This is an updated version of <a + href="mod_digest.html">mod_digest</a>. However, it has not been + extensively tested and is therefore marked experimental. If you + use this module, you must make sure to <em>not</em> use + mod_digest (because they share some of the same configuration + directives).</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#authdigestfile">AuthDigestFile</a></li> + + <li><a + href="#authdigestgroupfile">AuthDigestGroupFile</a></li> + + <li><a href="#authdigestqop">AuthDigestQop</a></li> + + <li><a + href="#authdigestnoncelifetime">AuthDigestNonceLifetime</a></li> + + <li><a + href="#authdigestnonceformat">AuthDigestNonceFormat</a></li> + + <li><a href="#authdigestnccheck">AuthDigestNcCheck</a></li> + + <li><a + href="#authdigestalgorithm">AuthDigestAlgorithm</a></li> + + <li><a href="#authdigestdomain">AuthDigestDomain</a></li> + </ul> + + <p>See also: <a href="core.html#require">Require</a> and <a + href="core.html#satisfy">Satisfy</a>.</p> + + <h3><a id="usingdigest" name="usingdigest">Using Digest + Authentication</a></h3> + + <p>Using MD5 Digest authentication is very simple. Simply set + up authentication normally, using "AuthType Digest" and + "AuthDigestFile" instead of the normal "AuthType Basic" and + "AuthUserFile"; also, replace any "AuthGroupFile" with + "AuthDigestGroupFile". Then add a "AuthDigestDomain" directive + containing at least the root URI(s) for this protection space. + Example:</p> +<pre> <Location /private/> AuthType Digest AuthName "private area" @@ -75,338 +81,287 @@ this protection space. Example: AuthDigestFile /web/auth/.digest_pw Require valid-user </Location> -</PRE> - -<P><strong>Note:</strong> MD5 authentication provides a more secure -password system than Basic authentication, but only works with supporting -browsers. As of this writing (July 1999), the only major browsers which -support digest authentication are <A -HREF="http://www.microsoft.com/windows/ie/">Internet Explorer 5.0</A> and -<A HREF="http://www.w3.org/Amaya/">Amaya</A>. 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. - - -<HR> - - - - -<H2><A NAME="authdigestfile">AuthDigestFile</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest<BR> - -<P>The AuthDigestFile directive sets the name of a textual file containing -the list of users and encoded passwords for digest authentication. -<EM>File-path</EM> is the absolute path to the user file. - -<P>The digest file uses a special format. Files in this format can be -created using the <a href="../programs/htdigest.html">htdigest</a> -utility found in the support/ subdirectory of the Apache distribution. - -<HR> - -<H2><A NAME="authdigestgroupfile">AuthDigestGroupFile</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestGroupFile <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P>The AuthDigestGroupFile directive sets the name of a textual file -containing the list of groups and their members (user names). -<EM>File-path</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 text files is <EM>very</EM> inefficient. - -<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. - -<HR> - -<H2><A NAME="authdigestqop">AuthDigestQop</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestQop none|auth|auth-int -[auth|auth-int]<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestQop auth</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P>The AuthDigestQop directive determines the quality-of-protection to use. -<EM>auth</EM> will only do authentication (username/password); -<EM>auth-int</EM> is authentication plus integrity checking (an MD5 hash -of the entity is also computed and checked); <EM>none</EM> will cause the -module to use the old RFC-2069 digest algorithm (which does not include -integrity checking). Both <EM>auth</em> and <EM>auth-int</EM> may be -specified, in which the case the browser will choose which of these to -use. <EM>none</EM> should only be used if the browser for some reason -does not like the challenge it receives otherwise. - -<P><STRONG><EM>auth-int</EM> is not implemented yet</STRONG>. - -<HR> - -<H2><A NAME="authdigestnoncelifetime">AuthDigestNonceLifetime</A> -directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestNonceLifetime <EM>seconds</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestNonceLifetime 300</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P>The AuthDigestNonceLifetime directive controls how long the server -nonce is valid. When the client contacts the server using an expired -nonce the server will send back a 401 with <code>stale=true</code>. If -<EM>seconds</EM> is greater than 0 then it specifies the amount of -time for which the nonce is valid; this should probably never be set -to less than 10 seconds. If <EM>seconds</EM> is less than 0 then -the nonce never expires. - -<!-- Not implemented yet -If <EM>seconds</EM> is 0 then the nonce may be used exactly once -by the client. Note that while one-time-nonces provide higher security -against replay attacks, they also have significant performance -implications, as the browser cannot pipeline or multiple connections -for the requests. Because browsers cannot easily detect that -one-time-nonces are being used, this may lead to browsers trying to -pipeline requests and receiving 401 responses for all but the first -request, requiring the browser to resend the requests. Note also that -the protection against reply attacks only makes sense for dynamically -generated content and things like POST requests; for static content -the attacker may already have the complete response, so one-time-nonces -do not make sense here. ---> - -<HR> -<H2><A NAME="authdigestnonceformat">AuthDigestNonceFormat</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestNonceFormat <EM>???</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestNonceFormat ???</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P><STRONG>Not implemented yet.</STRONG> -<!-- -<P>The AuthDigestNonceFormat directive determines how the nonce is -generated. ---> - -<HR> -<H2><A NAME="authdigestnccheck">AuthDigestNcCheck</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestNcCheck On|Off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestNcCheck Off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P><STRONG>Not implemented yet.</STRONG> -<!-- -<P>The AuthDigestNcCheck directive enables or disables the checking of the -nonce-count sent by the server. - -<P>While recommended from a security standpoint, turning this directive -On has one important performance implication. To check the nonce-count -*all* requests (which have an Authorization header, irrespective of -whether they require digest authentication) must be serialized through -a critical section. If the server is handling a large number of -requests which contain the Authorization header then this may noticeably -impact performance. ---> - -<HR> -<H2><A NAME="authdigestalgorithm">AuthDigestAlgorithm</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestAlgorithm MD5|MD5-sess<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>AuthDigestAlgorithm MD5</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P>The AuthDigestAlgorithm directive selects the algorithm used to calculate -the challenge and response hashes. - -<P><STRONG><EM>MD5-sess</EM> is not correctly implemented yet</STRONG>. -<!-- -<P>To use <EM>MD5-sess</EM> you must first code up the -<VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> . ---> - -<HR> -<H2><A NAME="authdigestdomain">AuthDigestDomain</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AuthDigestDomain <EM>URI</em> -[<em>URI</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_auth_digest - -<P>The AuthDigestDomain directive allows you to specify one or more URIs -which are in the same protection space (i.e. use the same realm and -username/password info). The specified URIs are prefixes, i.e. the client -will assume that all URIs "below" these are also protected by the same -username/password. The URIs may be either absolute URIs (i.e. inluding a -scheme, host, port, etc) or relative URIs. - -<P>This directive <em>should</em> always be specified and contain at least -the (set of) root URI(s) for this space. Omitting to do so will cause the -client to send the Authorization header for <em>every request</em> sent to -this server. Apart from increasing the size of the request, it may also -have a detrimental effect on performance if "AuthDigestNcCheck" is on. - -<P>The URIs specified can also point to different servers, in which case -clients (which understand this) will then share username/password info -across multiple servers without prompting the user each time. - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + + <p><strong>Note:</strong> MD5 authentication provides a more + secure password system than Basic authentication, but only + works with supporting browsers. As of this writing (July 1999), + the only major browsers which support digest authentication are + <a href="http://www.microsoft.com/windows/ie/">Internet + Explorer 5.0</a> and <a + href="http://www.w3.org/Amaya/">Amaya</a>. 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 /> + + <h2><a id="authdigestfile" + name="authdigestfile">AuthDigestFile</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest<br /> + + + <p>The AuthDigestFile directive sets the name of a textual file + containing the list of users and encoded passwords for digest + authentication. <em>File-path</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 <a + href="../programs/htdigest.html">htdigest</a> utility found in + the support/ subdirectory of the Apache distribution.</p> + <hr /> + + <h2><a id="authdigestgroupfile" + name="authdigestgroupfile">AuthDigestGroupFile</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestGroupFile + <em>file-path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p>The AuthDigestGroupFile directive sets the name of a textual + file containing the list of groups and their members (user + names). <em>File-path</em> is the absolute path to the group + file.</p> + + <p>Each line of the group file contains a groupname followed by + a colon, followed by the member usernames separated by spaces. + Example:</p> + + <blockquote> + <code>mygroup: bob joe anne</code> + </blockquote> + Note that searching large text files is <em>very</em> + inefficient. + + <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> + <hr /> + + <h2><a id="authdigestqop" + name="authdigestqop">AuthDigestQop</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestQop + none|auth|auth-int [auth|auth-int]<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>AuthDigestQop + auth</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p>The AuthDigestQop directive determines the + quality-of-protection to use. <em>auth</em> will only do + authentication (username/password); <em>auth-int</em> is + authentication plus integrity checking (an MD5 hash of the + entity is also computed and checked); <em>none</em> will cause + the module to use the old RFC-2069 digest algorithm (which does + not include integrity checking). Both <em>auth</em> and + <em>auth-int</em> may be specified, in which the case the + browser will choose which of these to use. <em>none</em> should + only be used if the browser for some reason does not like the + challenge it receives otherwise.</p> + + <p><strong><em>auth-int</em> is not implemented + yet</strong>.</p> + <hr /> + + <h2><a id="authdigestnoncelifetime" + name="authdigestnoncelifetime">AuthDigestNonceLifetime</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestNonceLifetime + <em>seconds</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthDigestNonceLifetime 300</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p>The AuthDigestNonceLifetime directive controls how long the + server nonce is valid. When the client contacts the server + using an expired nonce the server will send back a 401 with + <code>stale=true</code>. If <em>seconds</em> is greater than 0 + then it specifies the amount of time for which the nonce is + valid; this should probably never be set to less than 10 + seconds. If <em>seconds</em> is less than 0 then the nonce + never expires. <!-- Not implemented yet + If <EM>seconds</EM> is 0 then the nonce may be used exactly once + by the client. Note that while one-time-nonces provide higher security + against replay attacks, they also have significant performance + implications, as the browser cannot pipeline or multiple connections + for the requests. Because browsers cannot easily detect that + one-time-nonces are being used, this may lead to browsers trying to + pipeline requests and receiving 401 responses for all but the first + request, requiring the browser to resend the requests. Note also that + the protection against reply attacks only makes sense for dynamically + generated content and things like POST requests; for static content + the attacker may already have the complete response, so one-time-nonces + do not make sense here. + --> + </p> + <hr /> + + <h2><a id="authdigestnonceformat" + name="authdigestnonceformat">AuthDigestNonceFormat</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestNonceFormat + <em>???</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthDigestNonceFormat ???</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p><strong>Not implemented yet.</strong> <!-- + <P>The AuthDigestNonceFormat directive determines how the nonce is + generated. + --> + </p> + <hr /> + + <h2><a id="authdigestnccheck" + name="authdigestnccheck">AuthDigestNcCheck</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestNcCheck + On|Off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthDigestNcCheck Off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p><strong>Not implemented yet.</strong> <!-- + <P>The AuthDigestNcCheck directive enables or disables the checking of the + nonce-count sent by the server. + + <P>While recommended from a security standpoint, turning this directive + On has one important performance implication. To check the nonce-count + *all* requests (which have an Authorization header, irrespective of + whether they require digest authentication) must be serialized through + a critical section. If the server is handling a large number of + requests which contain the Authorization header then this may noticeably + impact performance. + --> + </p> + <hr /> + + <h2><a id="authdigestalgorithm" + name="authdigestalgorithm">AuthDigestAlgorithm</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestAlgorithm + MD5|MD5-sess<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>AuthDigestAlgorithm MD5</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p>The AuthDigestAlgorithm directive selects the algorithm used + to calculate the challenge and response hashes.</p> + + <p><strong><em>MD5-sess</em> is not correctly implemented + yet</strong>. <!-- + <P>To use <EM>MD5-sess</EM> you must first code up the + <VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> . + --> + </p> + <hr /> + + <h2><a id="authdigestdomain" + name="authdigestdomain">AuthDigestDomain</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AuthDigestDomain + <em>URI</em> [<em>URI</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> AuthConfig<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_auth_digest + + <p>The AuthDigestDomain directive allows you to specify one or + more URIs which are in the same protection space (i.e. use the + same realm and username/password info). The specified URIs are + prefixes, i.e. the client will assume that all URIs "below" + these are also protected by the same username/password. The + URIs may be either absolute URIs (i.e. inluding a scheme, host, + port, etc) or relative URIs.</p> + + <p>This directive <em>should</em> always be specified and + contain at least the (set of) root URI(s) for this space. + Omitting to do so will cause the client to send the + Authorization header for <em>every request</em> sent to this + server. Apart from increasing the size of the request, it may + also have a detrimental effect on performance if + "AuthDigestNcCheck" is on.</p> + + <p>The URIs specified can also point to different servers, in + which case clients (which understand this) will then share + username/password info across multiple servers without + prompting the user each time. + <!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_autoindex.html b/docs/manual/mod/mod_autoindex.html index b06ba0570b..a5635161e9 100644 --- a/docs/manual/mod/mod_autoindex.html +++ b/docs/manual/mod/mod_autoindex.html @@ -1,152 +1,185 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_autoindex</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_autoindex</H1> - -The module mod_autoindex generates directory indexes, automatically, similar to -the Unix <em>ls</em> command or the Win32 <em>dir</em> shell command. -<P> - -Automatic index generation must be enabled with by the <CODE>Options</CODE> -directive's <CODE><I>[+]</I>Indexes</CODE> option. See the -<A HREF="core.html#options"><CODE>Options</CODE></a> directive for -more details. - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_autoindex.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> autoindex_module -</P> - - -<H2>Summary</H2> -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="mod_dir.html#directoryindex">DirectoryIndex</A> directive sets -the name of this file. -This is controlled by <A HREF="mod_dir.html"><CODE>mod_dir</CODE></A>. - -<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. These -are controlled by <CODE>mod_autoindex</CODE>. -</UL> -The two functions are separated so that you can completely remove -(or replace) automatic index generation should you want to. -<P> -Automatic index generation is enabled with using -<CODE>Options +Indexes</CODE>. See the -<A HREF="core.html#options"><CODE>Options</CODE></a> directive for -more details. -<P> -If the <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP> -option is given with the <A HREF="#indexoptions"><SAMP>IndexOptions</SAMP></A> -directive, the column headers are links that control the -order of the display. If you select a header link, the -listing will be regenerated, sorted by the values in that -column. Selecting the same header repeatedly toggles -between ascending and descending order. These column header links are -suppressed with <A HREF="#indexoptions">IndexOptions</A> directive's -<SAMP>SuppressColumnSorting</SAMP> option. -</P> -<P> -Note that when the display is sorted by "Size", -it's the <EM>actual</EM> size of the files that's used, -not the displayed value - so a 1010-byte file will -always be displayed before a 1011-byte file (if in ascending -order) even though they both are shown as "1K". -</P> - -<H2>Directives</H2> - -<UL> -<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="#headername">HeaderName</A> -<LI><A HREF="#indexignore">IndexIgnore</A> -<LI><A HREF="#indexoptions">IndexOptions</A> -<LI><A HREF="#indexorderdefault">IndexOrderDefault</A> -<LI><A HREF="#readmename">ReadmeName</A> -</UL> - -<p>See also: <A HREF="core.html#options">Options</A> and <A -HREF="mod_dir.html#directoryindex">DirectoryIndex</A>.</p> - -<H2>Autoindex Request Query Arguments</H2> - -<P>Apache 2.0.23 reorganized the Query Arguments for Column Sorting, and introduced -an entire group of new query options. To effectively eliminate all client control -over the output, the <SAMP><A HREF="#indexoptions:ignoreclient">IndexOptions -IgnoreClient</A></SAMP> option was introduced.</P> - -<P>The column sorting headers themselves are self-referencing hyperlinks that add the -sort query options shown below. Any option below may be added to any request for the -directory resource. - -<ul> -<li><SAMP>C=N</SAMP> sorts the directory by file name -<li><SAMP>C=M</SAMP> sorts the directory by last-modified date, then file name -<li><SAMP>C=S</SAMP> sorts the directory by size, then file name -<li><SAMP>C=D</SAMP> sorts the directory by description, then file name<br /> - -<li><SAMP>O=A</SAMP> sorts the listing in Ascending Order -<li><SAMP>O=D</SAMP> sorts the listing in Descending Order<br /> - -<li><SAMP>F=0</SAMP> formats the listing as a simple list (not FancyIndexed) -<li><SAMP>F=1</SAMP> formats the listing as a FancyIndexed list -<li><SAMP>F=2</SAMP> formats the listing as an HTMLTable FancyIndexed list<br /> - -<li><SAMP>V=0</SAMP> disables version sorting -<li><SAMP>V=1</SAMP> enables version sorting<br /> - -<li><SAMP>P=<EM>pattern</EM></SAMP> lists only files matching the given <EM>pattern</EM> -</ul> - -<P>Note that the 'P'attern query argument is tested <em>after</em> the usual IndexIgnore -directives are processed, and all file names are still subjected to the same criteria -as any other autoindex listing. The Query Arguments parser in mod_autoindex will stop -abruptly when an unrecognized option is encountered. The Query Arguments must be well -formed, according to the table above.</P> - -<P>The simple example below, which can be clipped and saved in a header.html file, -illustrates these query options. Note that the unknown "X" argument, for the -submit button, is listed last to assure the arguments are all parsed before -mod_autoindex encounters the X=Go input.</P> - -<pre><FORM METHOD="GET"> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_autoindex</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_autoindex</h1> + The module mod_autoindex generates directory indexes, + automatically, similar to the Unix <em>ls</em> command or the + Win32 <em>dir</em> shell command. + + <p>Automatic index generation must be enabled with by the + <code>Options</code> directive's <code><i>[+]</i>Indexes</code> + option. See the <a + href="core.html#options"><code>Options</code></a> directive for + more details.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_autoindex.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + autoindex_module</p> + + <h2>Summary</h2> + 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="mod_dir.html#directoryindex">DirectoryIndex</a> + directive sets the name of this file. This is controlled by + <a href="mod_dir.html"><code>mod_dir</code></a>.</li> + + <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. These are controlled by + <code>mod_autoindex</code>.</li> + </ul> + The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to. + + <p>Automatic index generation is enabled with using + <code>Options +Indexes</code>. See the <a + href="core.html#options"><code>Options</code></a> directive for + more details.</p> + + <p>If the <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp> + option is given with the <a + href="#indexoptions"><samp>IndexOptions</samp></a> directive, + the column headers are links that control the order of the + display. If you select a header link, the listing will be + regenerated, sorted by the values in that column. Selecting the + same header repeatedly toggles between ascending and descending + order. These column header links are suppressed with <a + href="#indexoptions">IndexOptions</a> directive's + <samp>SuppressColumnSorting</samp> option.</p> + + <p>Note that when the display is sorted by "Size", it's the + <em>actual</em> size of the files that's used, not the + displayed value - so a 1010-byte file will always be displayed + before a 1011-byte file (if in ascending order) even though + they both are shown as "1K".</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#addalt">AddAlt</a></li> + + <li><a href="#addaltbyencoding">AddAltByEncoding</a></li> + + <li><a href="#addaltbytype">AddAltByType</a></li> + + <li><a href="#adddescription">AddDescription</a></li> + + <li><a href="#addicon">AddIcon</a></li> + + <li><a href="#addiconbyencoding">AddIconByEncoding</a></li> + + <li><a href="#addiconbytype">AddIconByType</a></li> + + <li><a href="#defaulticon">DefaultIcon</a></li> + + <li><a href="#headername">HeaderName</a></li> + + <li><a href="#indexignore">IndexIgnore</a></li> + + <li><a href="#indexoptions">IndexOptions</a></li> + + <li><a href="#indexorderdefault">IndexOrderDefault</a></li> + + <li><a href="#readmename">ReadmeName</a></li> + </ul> + + <p>See also: <a href="core.html#options">Options</a> and <a + href="mod_dir.html#directoryindex">DirectoryIndex</a>.</p> + + <h2>Autoindex Request Query Arguments</h2> + + <p>Apache 2.0.23 reorganized the Query Arguments for Column + Sorting, and introduced an entire group of new query options. + To effectively eliminate all client control over the output, + the <samp><a href="#indexoptions:ignoreclient">IndexOptions + IgnoreClient</a></samp> option was introduced.</p> + + <p>The column sorting headers themselves are self-referencing + hyperlinks that add the sort query options shown below. Any + option below may be added to any request for the directory + resource.</p> + + <ul> + <li><samp>C=N</samp> sorts the directory by file name</li> + + <li><samp>C=M</samp> sorts the directory by last-modified + date, then file name</li> + + <li><samp>C=S</samp> sorts the directory by size, then file + name</li> + + <li><samp>C=D</samp> sorts the directory by description, then + file name<br /> + </li> + + <li><samp>O=A</samp> sorts the listing in Ascending + Order</li> + + <li><samp>O=D</samp> sorts the listing in Descending + Order<br /> + </li> + + <li><samp>F=0</samp> formats the listing as a simple list + (not FancyIndexed)</li> + + <li><samp>F=1</samp> formats the listing as a FancyIndexed + list</li> + + <li><samp>F=2</samp> formats the listing as an HTMLTable + FancyIndexed list<br /> + </li> + + <li><samp>V=0</samp> disables version sorting</li> + + <li><samp>V=1</samp> enables version sorting<br /> + </li> + + <li><samp>P=<em>pattern</em></samp> lists only files matching + the given <em>pattern</em></li> + </ul> + + <p>Note that the 'P'attern query argument is tested + <em>after</em> the usual IndexIgnore directives are processed, + and all file names are still subjected to the same criteria as + any other autoindex listing. The Query Arguments parser in + mod_autoindex will stop abruptly when an unrecognized option is + encountered. The Query Arguments must be well formed, according + to the table above.</p> + + <p>The simple example below, which can be clipped and saved in + a header.html file, illustrates these query options. Note that + the unknown "X" argument, for the submit button, is listed last + to assure the arguments are all parsed before mod_autoindex + encounters the X=Go input.</p> +<pre> +<FORM METHOD="GET"> Show me a <SELECT NAME="F"> <OPTION VALUE="0"> Plain list <OPTION VALUE="1" SELECTED> Fancy list @@ -170,781 +203,792 @@ mod_autoindex encounters the X=Go input.</P> <INPUT TYPE="submit" NAME="X" VALUE="Go"> </FORM> </pre> - -<HR> - -<H2><A NAME="addalt">AddAlt</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddAlt} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddAlt <EM>string file</em> -[<em>file</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -<EM>AddAlt</EM> provides the alternate text to display for a file, instead of an icon, -for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <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, has image loading -disabled, or fails to retrieve the icon. - -<HR> -<H2><A NAME="addaltbyencoding">AddAltByEncoding</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddAltByEncoding <EM>string MIME-encoding</em> - [<em>MIME-encoding</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -<EM>AddAltByEncoding</EM> provides the alternate text to display for a file, instead -of an icon, for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. -<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, has image loading disabled, or -fails to retrieve the icon. - -<HR> -<H2><A NAME="addaltbytype">AddAltByType</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddAltByType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddAltByType <EM>string MIME-type</em> - [<em>MIME-type</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -<EM>AddAltByType</EM> sets the alternate text to display for a file, instead of -an icon, for <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. -<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, has image loading -disabled, or fails to retrieve the icon. - -<HR> - -<H2><A NAME="adddescription">AddDescription</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddDescription} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddDescription <EM>string file</em> - [<em>file</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the description to display for a file, for -<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. -<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> -The typical, default description field is 23 bytes wide. 6 more bytes are -added by the <CODE>IndexOptions SuppressIcon</CODE> option, 7 bytes are -added by the <CODE>IndexOptions SuppressSize</CODE> option, and 19 bytes -are added by the <CODE>IndexOptions SuppressLastModified</CODE> option. -Therefore, the widest default the description column is ever assigned is 55 bytes. -<P> -See the <a href="#indexoptions:descriptionwidth">DescriptionWidth</a> -<samp>IndexOptions</samp> keyword for details on overriding the size of this -column, or allowing descriptions of unlimited length. -</P> -<blockquote> -<b>Caution:</b> Descriptive text defined with <samp>AddDescription</samp> -may contain HTML markup, such as tags and character entities. If the -width of the description column should happen to truncate a tagged -element (such as cutting off the end of a bolded phrase), the results -may affect the rest of the directory listing. -</blockquote> -<HR> - -<H2><A NAME="addicon">AddIcon</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddIcon} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddIcon <EM>icon name</em> - [<em>name</em>] ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the icon to display next to a file ending in <EM>name</EM> for -<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <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> - -<H2><A NAME="addiconbyencoding">AddIconByEncoding</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddIconByEncoding <EM>icon MIME-encoding</em> - [<em>MIME-encoding</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the icon to display next to files with -<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. -<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> - -<H2><A NAME="addiconbytype">AddIconByType</A> directive</H2> -<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddIconByType <EM>icon MIME-type</em> - [<em>MIME-type</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -This sets the icon to display next to files of type <EM>MIME-type</EM> for -<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. <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> - -<H2><A NAME="defaulticon">DefaultIcon</A> directive</H2> -<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DefaultIcon <EM>url</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<P> - -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for -<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP>. -<EM>Url</EM> is a (%-escaped) relative URL to the icon. Examples: -<BLOCKQUOTE><CODE> -DefaultIcon /icon/unknown.xbm -</CODE></BLOCKQUOTE><P><HR> - -<H2><A NAME="fancyindexing">FancyIndexing</A> directive</H2> -<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> -<A - HREF="directive-dict.html#Deprecated" - REL="Help" -><STRONG>Deprecated:</STRONG></A> See <A HREF="#indexoptions">IndexOptions</A> - <SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP><BR> -<P> -The FancyIndexing directive was replaced by the -<SAMP><A HREF="#indexoptions:fancyindexing">FancyIndexing</A></SAMP> option to the -<A HREF="#indexoptions">IndexOptions</A> directive, and is no longer supported -in Apache 2.0. -</P> -<HR> - -<H2><A NAME="headername">HeaderName</A> directive</H2> -<!--%plaintext <?INDEX {\tt HeaderName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> HeaderName <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> behavior changed in version 1.3.7; - see text - -<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. -</P> -<BLOCKQUOTE><STRONG>Changes with Apache 1.3.7:</STRONG> -Both HeaderName and <A HREF="#readmename">ReadmeName</A> now treat <EM>Filename</EM> -as a URI path relative to the one used to access the directory being indexed. -<EM>Filename</EM> must resolve to a document with a major content type of -"<SAMP>text/*</SAMP>" (<EM>e.g.</EM>, <SAMP>text/html</SAMP>, <SAMP>text/plain</SAMP>, -<EM>etc.</EM>). This means that <EM>filename</EM> may refer to a CGI script if the -script's actual file type (as opposed to its output) is marked as -<SAMP>text/html</SAMP> such as with a directive like: -<PRE> + <hr /> + + <h2><a id="addalt" name="addalt">AddAlt</a> directive</h2> + <!--%plaintext <?INDEX {\tt AddAlt} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddAlt <em>string + file</em> [<em>file</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p><em>AddAlt</em> provides the alternate text to display for a + file, instead of an icon, for <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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, has image loading disabled, or fails to + retrieve the icon.</p> + <hr /> + + <h2><a id="addaltbyencoding" + name="addaltbyencoding">AddAltByEncoding</a> directive</h2> + <!--%plaintext <?INDEX {\tt AddAltByEncoding} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddAltByEncoding + <em>string MIME-encoding</em> [<em>MIME-encoding</em>] + ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p><em>AddAltByEncoding</em> provides the alternate text to + display for a file, instead of an icon, for <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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, has image loading disabled, or + fails to retrieve the icon.</p> + <hr /> + + <h2><a id="addaltbytype" name="addaltbytype">AddAltByType</a> + directive</h2> + <!--%plaintext <?INDEX {\tt AddAltByType} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddAltByType <em>string + MIME-type</em> [<em>MIME-type</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p><em>AddAltByType</em> sets the alternate text to display for + a file, instead of an icon, for <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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, has image loading disabled, or + fails to retrieve the icon.</p> + <hr /> + + <h2><a id="adddescription" + name="adddescription">AddDescription</a> directive</h2> + <!--%plaintext <?INDEX {\tt AddDescription} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddDescription + <em>string file</em> [<em>file</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p>This sets the description to display for a file, for + <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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:</p> + + <blockquote> + <code>AddDescription "The planet Mars" + /web/pics/mars.gif</code> + </blockquote> + + <p>The typical, default description field is 23 bytes wide. 6 + more bytes are added by the + <code>IndexOptions SuppressIcon</code> option, 7 bytes are + added by the <code>IndexOptions SuppressSize</code> + option, and 19 bytes are added by the + <code>IndexOptions SuppressLastModified</code> option. + Therefore, the widest default the description column is ever + assigned is 55 bytes.</p> + + <p>See the <a + href="#indexoptions:descriptionwidth">DescriptionWidth</a> + <samp>IndexOptions</samp> keyword for details on overriding the + size of this column, or allowing descriptions of unlimited + length.</p> + + <blockquote> + <b>Caution:</b> Descriptive text defined with + <samp>AddDescription</samp> may contain HTML markup, such as + tags and character entities. If the width of the description + column should happen to truncate a tagged element (such as + cutting off the end of a bolded phrase), the results may + affect the rest of the directory listing. + </blockquote> + <hr /> + + <h2><a id="addicon" name="addicon">AddIcon</a> directive</h2> + <!--%plaintext <?INDEX {\tt AddIcon} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddIcon <em>icon + name</em> [<em>name</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p>This sets the icon to display next to a file ending in + <em>name</em> for <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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> + + <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:</p> + + <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. + <hr /> + + <h2><a id="addiconbyencoding" + name="addiconbyencoding">AddIconByEncoding</a> directive</h2> + <!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddIconByEncoding + <em>icon MIME-encoding</em> [<em>MIME-encoding</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p>This sets the icon to display next to files with <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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> + + <p><em>Mime-encoding</em> is a wildcard expression matching + required the content-encoding. Examples:</p> + + <blockquote> + <code>AddIconByEncoding /icons/compress.xbm x-compress</code> + </blockquote> + <hr /> + + <h2><a id="addiconbytype" + name="addiconbytype">AddIconByType</a> directive</h2> + <!--%plaintext <?INDEX {\tt AddIconByType} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddIconByType <em>icon + MIME-type</em> [<em>MIME-type</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p>This sets the icon to display next to files of type + <em>MIME-type</em> for <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <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> + + <p><em>Mime-type</em> is a wildcard expression matching + required the mime types. Examples:</p> + + <blockquote> + <code>AddIconByType (IMG,/icons/image.xbm) image/*</code> + </blockquote> + <hr /> + + <h2><a id="defaulticon" name="defaulticon">DefaultIcon</a> + directive</h2> + <!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DefaultIcon + <em>url</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <p>The DefaultIcon directive sets the icon to display for files + when no specific icon is known, for <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp>. + <em>Url</em> is a (%-escaped) relative URL to the icon. + Examples:</p> + + <blockquote> + <code>DefaultIcon /icon/unknown.xbm</code> + </blockquote> + <hr /> + + <h2><a id="fancyindexing" + name="fancyindexing">FancyIndexing</a> directive</h2> + <!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> + <a href="directive-dict.html#Deprecated" + rel="Help"><strong>Deprecated:</strong></a> See <a + href="#indexoptions">IndexOptions</a> <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp><br /> + + + <p>The FancyIndexing directive was replaced by the <samp><a + href="#indexoptions:fancyindexing">FancyIndexing</a></samp> + option to the <a href="#indexoptions">IndexOptions</a> + directive, and is no longer supported in Apache 2.0.</p> + <hr /> + + <h2><a id="headername" name="headername">HeaderName</a> + directive</h2> + <!--%plaintext <?INDEX {\tt HeaderName} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> HeaderName + <em>filename</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex <br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> behavior changed + in version 1.3.7; see text + + <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.</p> + + <blockquote> + <strong>Changes with Apache 1.3.7:</strong> Both HeaderName + and <a href="#readmename">ReadmeName</a> now treat + <em>Filename</em> as a URI path relative to the one used to + access the directory being indexed. <em>Filename</em> must + resolve to a document with a major content type of + "<samp>text/*</samp>" (<em>e.g.</em>, <samp>text/html</samp>, + <samp>text/plain</samp>, <em>etc.</em>). This means that + <em>filename</em> may refer to a CGI script if the script's + actual file type (as opposed to its output) is marked as + <samp>text/html</samp> such as with a directive like: +<pre> AddType text/html .cgi -</PRE> -<A HREF="../content-negotiation.html">Content negotiation</A> -will be performed if the <SAMP>MultiViews</SAMP> -<A HREF="core.html#options">option</A> is enabled. -If <EM>filename</EM> resolves to a static <SAMP>text/html</SAMP> document -(not a CGI script) and the -<SAMP>Includes</SAMP> <A HREF="core.html#options">option</A> is enabled, -the file will be processed for server-side includes (see the -<A HREF="mod_include.html"><SAMP>mod_include</SAMP></A> documentation). -</BLOCKQUOTE> -<P> -If the file specified by <SAMP>HeaderName</SAMP> contains the -beginnings of an HTML document (<HTML>, <HEAD>, etc) then -you will probably want to set <A -HREF="#indexoptions:suppresshtmlpreamble"><SAMP>IndexOptions -+SuppressHTMLPreamble</SAMP></A>, so that these tags are not -repeated. -<P> -See also <A HREF="#readmename">ReadmeName</A>. -<P><HR> - -<H2><A NAME="indexignore">IndexIgnore</A> directive</H2> -<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexIgnore <EM>file</em> [<em>file</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex<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> - -<H2><A NAME="indexoptions">IndexOptions</A> directive</H2> -<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexOptions [+|-]<em>option</em> - [[+|-]<em>option</em>] ... (Apache 1.3.3 and later) -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex -<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> '+/-' syntax and merging of multiple - <SAMP>IndexOptions</SAMP> directives is only available with - Apache 1.3.3 and later; specific options are listed below. -<P> - -The IndexOptions directive specifies the behavior of the directory indexing. -<EM>Option</EM> can be one of -<DL> -<dt><a name="indexoptions:descriptionwidth">DescriptionWidth=[<em>n</em> | *] - (<em>Apache 1.3.10 or 2.0.23 and later</em>)</a></dt> -<dd>The <samp>DescriptionWidth</samp> keyword allows you to specify the -width of the description column in characters.</dd> -<dd><samp>-DescriptionWidth</samp> (or unset) allows mod_autoindex to calculate -the best width.</dd> -<dd><samp>DescriptionWidth=n</samp> fixes the column width to n bytes wide.</dd> -<dd><samp>DescriptionWidth=*</samp> grows the column to the width necessary to -accommodate the longest description string.</dd> -<dd><b>See the section on <a href="#adddescription"><samp>AddDescription</samp></a> -for dangers inherent in truncating descriptions.</b></dd> -<DT><A NAME="indexoptions:fancyindexing">FancyIndexing</A> -<DD><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> -This turns on fancy indexing of directories. -<dt><a name="indexoptions:foldersfirst">FoldersFirst - (<i>Apache 1.3.10 or 2.0.23 and later</i>)</a></dt> -<dd> -If this option is enabled, subdirectory listings -will <i>always</i> appear first, followed by normal files in the -directory. The listing is basically broken into two components, -the files and the subdirectories, and each is sorted separately and -then displayed subdirectories-first. For instance, if the sort order -is descending by name, and <samp>FoldersFirst</samp> is enabled, -subdirectory <samp>Zed</samp> will be listed before subdirectory -<samp>Beta</samp>, which will be listed before normal files -<samp>Gamma</samp> and <samp>Alpha</samp>. -<b>This option only has an effect if -<a href="#indexoptions:fancyindexing"><samp>FancyIndexing</samp></a> -is also enabled.</b></dd> -<DT><A NAME="indexoptions:htmltable">HTMLTable</A> - <i>(Experimental, Apache 2.0.23 and later)</i> -<DD><!--%plaintext <?INDEX {\tt HTMLTable} index option> --> -This experimental option with FancyIndexing constructs a simple table for the -fancy directory listing. Note this will confuse older browsers. It is particularly -necessary if file names or description text will alternate between left-to-right -and right-to-left reading order, as can happen on WinNT or other utf-8 -enabled platforms. -<DT><A NAME="indexoptions:iconsarelinks">IconsAreLinks</A> -<DD> -<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> -This makes the icons part of the anchor for the filename, for -fancy indexing. -<DT><A NAME="indexoptions:iconheight">IconHeight[=pixels] (<EM>Apache 1.3 and later</EM>)</A> -<DD> -<!--%plaintext <?INDEX {\tt IconHeight} index option> --> -Presence of this option, when used with IconWidth, will cause the server -to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the -<SAMP>IMG</SAMP> tag for the file icon. This allows browser to -precalculate the page layout without having to wait until all the -images have been loaded. If no value is given for the option, it -defaults to the standard height of the icons supplied with the Apache -software. -<DT><A NAME="indexoptions:iconwidth">IconWidth[=pixels] (<EM>Apache 1.3 and later</EM>)</A> -<DD> -<!--%plaintext <?INDEX {\tt IconWidth} index option> --> -Presence of this option, when used with IconHeight, will cause the server -to include <SAMP>HEIGHT</SAMP> and <SAMP>WIDTH</SAMP> attributes in the -<SAMP>IMG</SAMP> tag for the file icon. This allows browser to -precalculate the page layout without having to wait until all the -images have been loaded. If no value is given for the option, it -defaults to the standard width of the icons supplied with the Apache -software. -<DT><A NAME="indexoptions:ignoreclient">IgnoreClient</A> -<DD> -<!--%plaintext <?INDEX {\tt IgnoreClient} index option> --> -This option causes mod_autoindex to ignore all query variables from the -client, including sort order (implies <SAMP><A - HREF="#indexoptions:suppresscolumnsorting">SuppressColumnSorting</A></SAMP>.) -<DT><A NAME="indexoptions:namewidth">NameWidth=[<EM>n</EM> | *] (<EM>Apache 1.3.2 and later</EM>)</A> -<DD> -The NameWidth keyword allows you to specify the width of the -filename column in bytes. -<dd><samp>-NameWidth</samp> (or unset) allows mod_autoindex to calculate -the best width.</dd> -<dd><samp>NameWidth=n</samp> fixes the column width to n bytes wide.</dd> -<dd><samp>NameWidth=*</samp> grows the column to the necessary width.</dd> -<DT><A NAME="indexoptions:scanhtmltitles">ScanHTMLTitles</A> -<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><A NAME="indexoptions:suppresscolumnsorting">SuppressColumnSorting</A> - (<EM>Apache 1.3 and later</EM>) -<DD> -<!--%plaintext <?INDEX {\tt SuppressColumnSorting} index option> --> -If specified, Apache will not make the column headings in a FancyIndexed -directory listing into links for sorting. The default behavior is -for them to be links; selecting the column heading will sort the directory -listing by the values in that column. <STRONG>Prior to Apache 2.0.23, this -also disabled parsing the Query Arguments for the sort string.</STRONG> -That behavior is now controlled by <A HREF="#indexoptions:ignoreclient" - >IndexOptions IgnoreClient</A> in Apache 2.0.23. -<DT><A NAME="indexoptions:suppressdescription">SuppressDescription</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> -This will suppress the file description in fancy indexing listings. -By default, no file descriptions are defined, and so the use of this option -will regain 23 characters of screen space to use for something else. -See <A HREF="#adddescription"><samp>AddDescription</samp></A> -for information about setting the file description. See also the -<A -HREF="#indexoptions:descriptionwidth"><samp>DescriptionWidth</samp></A> -index option to limit the size of the description column. - -<DT><A NAME="indexoptions:suppresshtmlpreamble">SuppressHTMLPreamble</A> - (<EM>Apache 1.3 and later</EM>) -<DD> -<!--%plaintext <?INDEX {\tt SuppressHTMLPreamble} index option> --> -If the directory actually contains a file specified by the -<A - HREF="#headername" ->HeaderName</A> -directive, the module usually includes the contents of the file -after a standard HTML preamble (<HTML>, <HEAD>, <EM>et -cetera</EM>). The SuppressHTMLPreamble option disables this behaviour, -causing the module to start the display with the header file contents. -The header file must contain appropriate HTML instructions in this case. -If there is no header file, the preamble is generated as usual. -<DT><A NAME="indexoptions:suppressicon">SuppressIcon</A> - (<EM>Apache 2.0.23 and later</EM>) -<DD> -<!--%plaintext <?INDEX {\tt SuppressIcon} index option> --> -This will suppress the icon in fancy indexing listings. Combining -both <EM>SuppressIcon</EM> and <EM>SuppressRules</EM> yields proper -HTML 3.2 output, which by the final specification prohibits IMG and HR -tags from the PRE block (used to format FancyIndexed listings.) -<DT><A NAME="indexoptions:suppresslastmodified">SuppressLastModified</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> -This will suppress the display of the last modification date, in fancy -indexing listings. -<DT><A NAME="indexoptions:suppressrules">SuppressRules</A> - (<EM>Apache 2.0.23 and later</EM>) -<DD> -<!--%plaintext <?INDEX {\tt SuppressRules} index option> --> -This will suppress the horizontal rule lines (HR tags) in directory listings. -Combining both <EM>SuppressIcon</EM> and <EM>SuppressRules</EM> yeilds proper -HTML 3.2 output, which by the final specification prohibits IMG and HR tags -from the PRE block (used to format FancyIndexed listings.) -<DT><A NAME="indexoptions:suppresssize">SuppressSize</A> -<DD> -<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> -This will suppress the file size in fancy indexing listings. -<DT><A NAME="indexoptions:trackmodified">TrackModified -(<EM>Apache 1.3.15 or 2.0.23 and later</EM>)</A> -<DD> -<!--%plaintext <?INDEX {\tt TrackModified} index option> --> -This returns the Last-Modified and ETag values for the listed directory -in the HTTP header. It is only valid if the operating system and file -system return appropriate stat() results. Some Unix systems do so, as -do OS2's JFS and Win32's NTFS volumes. OS2 and Win32 FAT volumes, -for example, do not. Once this feature is enabled, the client or proxy -can track changes to the list of files when they perform a HEAD request. -Note some operating systems correctly track new and removed files, but -do not track changes for sizes or dates of the files within the directory. -<STRONG>Changes to the size or date stamp of an existing file will not -update the Last-Modified header on all Unix platforms.</STRONG> If this -is a concern, leave this option disabled. -<DT><A NAME="indexoptions:versionsort">VersionSort (<EM>Apache 2.0a3 and later</EM>)</A> -<DD> -The VersionSort keyword causes files containing version numbers to -sort in a natural way. Strings are sorted as usual, except that -substrings of digits in the name and description are compared -according to their numeric value. - -For example: -<BLOCKQUOTE><pre> +</pre> + <a href="../content-negotiation.html">Content negotiation</a> + will be performed if the <samp>MultiViews</samp> <a + href="core.html#options">option</a> is enabled. If + <em>filename</em> resolves to a static <samp>text/html</samp> + document (not a CGI script) and the <samp>Includes</samp> <a + href="core.html#options">option</a> is enabled, the file will + be processed for server-side includes (see the <a + href="mod_include.html"><samp>mod_include</samp></a> + documentation). + </blockquote> + + <p>If the file specified by <samp>HeaderName</samp> contains + the beginnings of an HTML document (<HTML>, <HEAD>, + etc) then you will probably want to set <a + href="#indexoptions:suppresshtmlpreamble"><samp>IndexOptions + +SuppressHTMLPreamble</samp></a>, so that these tags are not + repeated.</p> + + <p>See also <a href="#readmename">ReadmeName</a>.</p> + <hr /> + + <h2><a id="indexignore" name="indexignore">IndexIgnore</a> + directive</h2> + <!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> IndexIgnore + <em>file</em> [<em>file</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex + + <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:</p> + + <blockquote> + <code>IndexIgnore README .htaccess *~</code> + </blockquote> + <hr /> + + <h2><a id="indexoptions" name="indexoptions">IndexOptions</a> + directive</h2> + <!--%plaintext <?INDEX {\tt IndexOptions} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> IndexOptions + [+|-]<em>option</em> [[+|-]<em>option</em>] ... (Apache 1.3.3 + and later) <br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex <br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> '+/-' syntax and + merging of multiple <samp>IndexOptions</samp> directives is + only available with Apache 1.3.3 and later; specific options + are listed below. + + <p>The IndexOptions directive specifies the behavior of the + directory indexing. <em>Option</em> can be one of</p> + + <dl> + <dt><a id="indexoptions:descriptionwidth" + name="indexoptions:descriptionwidth">DescriptionWidth=[<em>n</em> + | *] (<em>Apache 1.3.10 or 2.0.23 and later</em>)</a></dt> + + <dd>The <samp>DescriptionWidth</samp> keyword allows you to + specify the width of the description column in + characters.</dd> + + <dd><samp>-DescriptionWidth</samp> (or unset) allows + mod_autoindex to calculate the best width.</dd> + + <dd><samp>DescriptionWidth=n</samp> fixes the column width to + n bytes wide.</dd> + + <dd><samp>DescriptionWidth=*</samp> grows the column to the + width necessary to accommodate the longest description + string.</dd> + + <dd><b>See the section on <a + href="#adddescription"><samp>AddDescription</samp></a> for + dangers inherent in truncating descriptions.</b></dd> + + <dt><a id="indexoptions:fancyindexing" + name="indexoptions:fancyindexing">FancyIndexing</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> + This turns on fancy indexing of directories.</dd> + + <dt><a id="indexoptions:foldersfirst" + name="indexoptions:foldersfirst">FoldersFirst (<i>Apache + 1.3.10 or 2.0.23 and later</i>)</a></dt> + + <dd>If this option is enabled, subdirectory listings will + <i>always</i> appear first, followed by normal files in the + directory. The listing is basically broken into two + components, the files and the subdirectories, and each is + sorted separately and then displayed subdirectories-first. + For instance, if the sort order is descending by name, and + <samp>FoldersFirst</samp> is enabled, subdirectory + <samp>Zed</samp> will be listed before subdirectory + <samp>Beta</samp>, which will be listed before normal files + <samp>Gamma</samp> and <samp>Alpha</samp>. <b>This option + only has an effect if <a + href="#indexoptions:fancyindexing"><samp>FancyIndexing</samp></a> + is also enabled.</b></dd> + + <dt><a id="indexoptions:htmltable" + name="indexoptions:htmltable">HTMLTable</a> <i>(Experimental, + Apache 2.0.23 and later)</i></dt> + + <dd> + <!--%plaintext <?INDEX {\tt HTMLTable} index option> --> + This experimental option with FancyIndexing constructs a + simple table for the fancy directory listing. Note this will + confuse older browsers. It is particularly necessary if file + names or description text will alternate between + left-to-right and right-to-left reading order, as can happen + on WinNT or other utf-8 enabled platforms.</dd> + + <dt><a id="indexoptions:iconsarelinks" + name="indexoptions:iconsarelinks">IconsAreLinks</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> + This makes the icons part of the anchor for the filename, for + fancy indexing.</dd> + + <dt><a id="indexoptions:iconheight" + name="indexoptions:iconheight">IconHeight[=pixels] + (<em>Apache 1.3 and later</em>)</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt IconHeight} index option> --> + Presence of this option, when used with IconWidth, will cause + the server to include <samp>HEIGHT</samp> and + <samp>WIDTH</samp> attributes in the <samp>IMG</samp> tag for + the file icon. This allows browser to precalculate the page + layout without having to wait until all the images have been + loaded. If no value is given for the option, it defaults to + the standard height of the icons supplied with the Apache + software.</dd> + + <dt><a id="indexoptions:iconwidth" + name="indexoptions:iconwidth">IconWidth[=pixels] (<em>Apache + 1.3 and later</em>)</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt IconWidth} index option> --> + Presence of this option, when used with IconHeight, will + cause the server to include <samp>HEIGHT</samp> and + <samp>WIDTH</samp> attributes in the <samp>IMG</samp> tag for + the file icon. This allows browser to precalculate the page + layout without having to wait until all the images have been + loaded. If no value is given for the option, it defaults to + the standard width of the icons supplied with the Apache + software.</dd> + + <dt><a id="indexoptions:ignoreclient" + name="indexoptions:ignoreclient">IgnoreClient</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt IgnoreClient} index option> --> + This option causes mod_autoindex to ignore all query + variables from the client, including sort order (implies + <samp><a + href="#indexoptions:suppresscolumnsorting">SuppressColumnSorting</a></samp>.)</dd> + + <dt><a id="indexoptions:namewidth" + name="indexoptions:namewidth">NameWidth=[<em>n</em> | *] + (<em>Apache 1.3.2 and later</em>)</a></dt> + + <dd>The NameWidth keyword allows you to specify the width of + the filename column in bytes.</dd> + + <dd><samp>-NameWidth</samp> (or unset) allows mod_autoindex + to calculate the best width.</dd> + + <dd><samp>NameWidth=n</samp> fixes the column width to n + bytes wide.</dd> + + <dd><samp>NameWidth=*</samp> grows the column to the + necessary width.</dd> + + <dt><a id="indexoptions:scanhtmltitles" + name="indexoptions:scanhtmltitles">ScanHTMLTitles</a></dt> + + <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.</dd> + + <dt><a id="indexoptions:suppresscolumnsorting" + name="indexoptions:suppresscolumnsorting">SuppressColumnSorting</a> + (<em>Apache 1.3 and later</em>)</dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressColumnSorting} index option> --> + If specified, Apache will not make the column headings in a + FancyIndexed directory listing into links for sorting. The + default behavior is for them to be links; selecting the + column heading will sort the directory listing by the values + in that column. <strong>Prior to Apache 2.0.23, this also + disabled parsing the Query Arguments for the sort + string.</strong> That behavior is now controlled by <a + href="#indexoptions:ignoreclient">IndexOptions + IgnoreClient</a> in Apache 2.0.23.</dd> + + <dt><a id="indexoptions:suppressdescription" + name="indexoptions:suppressdescription">SuppressDescription</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> + This will suppress the file description in fancy indexing + listings. By default, no file descriptions are defined, and + so the use of this option will regain 23 characters of screen + space to use for something else. See <a + href="#adddescription"><samp>AddDescription</samp></a> for + information about setting the file description. See also the + <a + href="#indexoptions:descriptionwidth"><samp>DescriptionWidth</samp></a> + index option to limit the size of the description + column.</dd> + + <dt><a id="indexoptions:suppresshtmlpreamble" + name="indexoptions:suppresshtmlpreamble">SuppressHTMLPreamble</a> + (<em>Apache 1.3 and later</em>)</dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressHTMLPreamble} index option> --> + If the directory actually contains a file specified by the <a + href="#headername">HeaderName</a> directive, the module + usually includes the contents of the file after a standard + HTML preamble (<HTML>, <HEAD>, <em>et + cetera</em>). The SuppressHTMLPreamble option disables this + behaviour, causing the module to start the display with the + header file contents. The header file must contain + appropriate HTML instructions in this case. If there is no + header file, the preamble is generated as usual.</dd> + + <dt><a id="indexoptions:suppressicon" + name="indexoptions:suppressicon">SuppressIcon</a> (<em>Apache + 2.0.23 and later</em>)</dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressIcon} index option> --> + This will suppress the icon in fancy indexing listings. + Combining both <em>SuppressIcon</em> and + <em>SuppressRules</em> yields proper HTML 3.2 output, which + by the final specification prohibits IMG and HR tags from the + PRE block (used to format FancyIndexed listings.)</dd> + + <dt><a id="indexoptions:suppresslastmodified" + name="indexoptions:suppresslastmodified">SuppressLastModified</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> + This will suppress the display of the last modification date, + in fancy indexing listings.</dd> + + <dt><a id="indexoptions:suppressrules" + name="indexoptions:suppressrules">SuppressRules</a> + (<em>Apache 2.0.23 and later</em>)</dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressRules} index option> --> + This will suppress the horizontal rule lines (HR tags) in + directory listings. Combining both <em>SuppressIcon</em> and + <em>SuppressRules</em> yeilds proper HTML 3.2 output, which + by the final specification prohibits IMG and HR tags from the + PRE block (used to format FancyIndexed listings.)</dd> + + <dt><a id="indexoptions:suppresssize" + name="indexoptions:suppresssize">SuppressSize</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt SuppressSize} index option> --> + This will suppress the file size in fancy indexing + listings.</dd> + + <dt><a id="indexoptions:trackmodified" + name="indexoptions:trackmodified">TrackModified (<em>Apache + 1.3.15 or 2.0.23 and later</em>)</a></dt> + + <dd> + <!--%plaintext <?INDEX {\tt TrackModified} index option> --> + This returns the Last-Modified and ETag values for the listed + directory in the HTTP header. It is only valid if the + operating system and file system return appropriate stat() + results. Some Unix systems do so, as do OS2's JFS and Win32's + NTFS volumes. OS2 and Win32 FAT volumes, for example, do not. + Once this feature is enabled, the client or proxy can track + changes to the list of files when they perform a HEAD + request. Note some operating systems correctly track new and + removed files, but do not track changes for sizes or dates of + the files within the directory. <strong>Changes to the size + or date stamp of an existing file will not update the + Last-Modified header on all Unix platforms.</strong> If this + is a concern, leave this option disabled.</dd> + + <dt><a id="indexoptions:versionsort" + name="indexoptions:versionsort">VersionSort (<em>Apache 2.0a3 + and later</em>)</a></dt> + + <dd> + The VersionSort keyword causes files containing version + numbers to sort in a natural way. Strings are sorted as + usual, except that substrings of digits in the name and + description are compared according to their numeric value. + For example: + + <blockquote> +<pre> foo-1.7 foo-1.7.2 foo-1.7.12 foo-1.8.2 foo-1.8.2a foo-1.12 -</pre></BLOCKQUOTE> +</pre> + </blockquote> + If the number starts with a zero, then it is considered to + be a fraction: -If the number starts with a zero, then it is considered to be a - fraction: -<BLOCKQUOTE><pre> + <blockquote> +<pre> foo-1.001 foo-1.002 foo-1.030 foo-1.04 -</pre></BLOCKQUOTE> -<DT><H3>Incremental IndexOptions</H3> -<DD>Apache 1.3.3 introduced some significant changes in the handling of -<SAMP>IndexOptions</SAMP> directives. In particular, -<BR /><BR /> -<UL> - <LI>Multiple <SAMP>IndexOptions</SAMP> directives for a single - directory are now merged together. The result of the example above - will now be the equivalent of - <CODE>IndexOptions FancyIndexing ScanHTMLTitles</CODE>. - </LI> - <LI>The addition of the incremental syntax (<EM>i.e.</EM>, prefixing - keywords with '+' or '-'). - </LI> -</UL> -<BR /> -Whenever a '+' or '-' prefixed keyword is encountered, it is applied -to the current <SAMP>IndexOptions</SAMP> settings (which may have been -inherited from an upper-level directory). However, whenever an unprefixed -keyword is processed, it clears all inherited options and any incremental -settings encountered so far. Consider the following example: -<BLOCKQUOTE><CODE>IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing -<BR /> -IndexOptions +SuppressSize -<BR /> -</CODE></BLOCKQUOTE> -The net effect is equivalent to -<CODE>IndexOptions FancyIndexing +SuppressSize</CODE>, because -the unprefixed <CODE>FancyIndexing</CODE> discarded the incremental -keywords before it, but allowed them to start accumulating again -afterward. -<BR /><BR /> -To unconditionally set the <CODE>IndexOptions</CODE> for a -particular directory, clearing the inherited settings, specify -keywords without any '+' or '-' prefixes. -</DD> -</DL> - -<HR> - -<H2><A NAME="indexorderdefault">IndexOrderDefault</A> directive</H2> -<!--%plaintext <?INDEX {\tt IndexOrderDefault} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> IndexOrderDefault - Ascending|Descending Name|Date|Size|Description -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess -<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes -<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex -<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> IndexOrderDefault is only available in -Apache 1.3.4 and later. - -<P> -The <SAMP>IndexOrderDefault</SAMP> directive is used in combination with -the <A HREF="#indexoptions:fancyindexing"><SAMP>FancyIndexing</SAMP></A> -index option. By default, fancyindexed directory listings are displayed -in ascending order by filename; the <SAMP>IndexOrderDefault</SAMP> allows -you to change this initial display order. -</P> -<P> -<SAMP>IndexOrderDefault</SAMP> takes two arguments. The first must be either -<SAMP>Ascending</SAMP> or <SAMP>Descending</SAMP>, indicating the direction -of the sort. The second argument must be one of the keywords -<SAMP>Name</SAMP>, <SAMP>Date</SAMP>, <SAMP>Size</SAMP>, or -<SAMP>Description</SAMP>, and identifies the primary key. The secondary -key is <EM>always</EM> the ascending filename. -</P> -<P> -You can force a directory listing to only be displayed in a particular -order by combining this directive with the -<A HREF="#indexoptions:suppresscolumnsorting" -><SAMP>SuppressColumnSorting</SAMP></A> index option; this will prevent -the client from requesting the directory listing in a different order. -</P> - -<HR> - -<H2><A NAME="readmename">ReadmeName</A> directive</H2> -<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ReadmeName <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_autoindex - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> some features only available after - 1.3.6; see <A HREF="#headername">HeaderName</A> - -<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 location being indexed. -</P> -<P>See also <A HREF="#headername">HeaderName</A>, where this behavior is -described in greater detail.<P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + </blockquote> + </dd> + + <dd> + <h3>Incremental IndexOptions</h3> + </dd> + + <dd> + Apache 1.3.3 introduced some significant changes in the + handling of <samp>IndexOptions</samp> directives. In + particular,<br /> + <br /> + + + <ul> + <li>Multiple <samp>IndexOptions</samp> directives for a + single directory are now merged together. The result of + the example above will now be the equivalent of + <code>IndexOptions FancyIndexing ScanHTMLTitles</code>.</li> + + <li>The addition of the incremental syntax + (<em>i.e.</em>, prefixing keywords with '+' or '-').</li> + </ul> + <br /> + Whenever a '+' or '-' prefixed keyword is encountered, it + is applied to the current <samp>IndexOptions</samp> + settings (which may have been inherited from an upper-level + directory). However, whenever an unprefixed keyword is + processed, it clears all inherited options and any + incremental settings encountered so far. Consider the + following example: + + <blockquote> + <code>IndexOptions +ScanHTMLTitles -IconsAreLinks + FancyIndexing<br /> + IndexOptions +SuppressSize<br /> + </code> + </blockquote> + The net effect is equivalent to + <code>IndexOptions FancyIndexing +SuppressSize</code>, + because the unprefixed <code>FancyIndexing</code> discarded + the incremental keywords before it, but allowed them to + start accumulating again afterward.<br /> + <br /> + To unconditionally set the <code>IndexOptions</code> for a + particular directory, clearing the inherited settings, + specify keywords without any '+' or '-' prefixes. + </dd> + </dl> + <hr /> + + <h2><a id="indexorderdefault" + name="indexorderdefault">IndexOrderDefault</a> directive</h2> + <!--%plaintext <?INDEX {\tt IndexOrderDefault} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> IndexOrderDefault + Ascending|Descending Name|Date|Size|Description <br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess <br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes <br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base <br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex <br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + IndexOrderDefault is only available in Apache 1.3.4 and later. + + <p>The <samp>IndexOrderDefault</samp> directive is used in + combination with the <a + href="#indexoptions:fancyindexing"><samp>FancyIndexing</samp></a> + index option. By default, fancyindexed directory listings are + displayed in ascending order by filename; the + <samp>IndexOrderDefault</samp> allows you to change this + initial display order.</p> + + <p><samp>IndexOrderDefault</samp> takes two arguments. The + first must be either <samp>Ascending</samp> or + <samp>Descending</samp>, indicating the direction of the sort. + The second argument must be one of the keywords + <samp>Name</samp>, <samp>Date</samp>, <samp>Size</samp>, or + <samp>Description</samp>, and identifies the primary key. The + secondary key is <em>always</em> the ascending filename.</p> + + <p>You can force a directory listing to only be displayed in a + particular order by combining this directive with the <a + href="#indexoptions:suppresscolumnsorting"><samp>SuppressColumnSorting</samp></a> + index option; this will prevent the client from requesting the + directory listing in a different order.</p> + <hr /> + + <h2><a id="readmename" name="readmename">ReadmeName</a> + directive</h2> + <!--%plaintext <?INDEX {\tt ReadmeName} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ReadmeName + <em>filename</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_autoindex <br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> some features + only available after 1.3.6; see <a + href="#headername">HeaderName</a> + + <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 location being indexed.</p> + + <p>See also <a href="#headername">HeaderName</a>, where this + behavior is described in greater detail.</p> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mod_cern_meta.html b/docs/manual/mod/mod_cern_meta.html index e210c7558e..1a5400e935 100644 --- a/docs/manual/mod/mod_cern_meta.html +++ b/docs/manual/mod/mod_cern_meta.html @@ -1,169 +1,138 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache module mod_cern_meta</H1> - -<p>This module provides for CERN httpd metafile semantics.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_cern_meta.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> cern_meta_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later. -</P> - - -<H2>Summary</H2> - -<!-- XXX: Should mention other possibilities in Apache: mod_header --> - -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="#metafiles">MetaFiles</A> -<LI><A HREF="#metadir">MetaDir</A> -<LI><A HREF="#metasuffix">MetaSuffix</A> -</UL> - -<HR> - -<H2><A NAME="metafiles">MetaFiles</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MetaFiles on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MetaFiles off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> per-directory config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cern_meta<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> MetaFiles is only available in Apache 1.3 -and later.<P> - -Turns on/off Meta file processing on a per-directory basis. This option was introduced in Apache 1.3. - -<hr> - -<H2><A NAME="metadir">MetaDir</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MetaDir <EM>directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MetaDir .web</CODE><BR> -<STRONG>Context: (Apache prior to 1.3)</STRONG> server config<BR> -<STRONG>Context: (Apache 1.3)</STRONG> per-directory config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cern_meta<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> 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. - -<hr> - -<H2><A NAME="metasuffix">MetaSuffix</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MetaSuffix <EM>suffix</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MetaSuffix .meta</CODE><BR> -<STRONG>Context: (Apache prior to 1.3)</STRONG> server config<BR> -<STRONG>Context: (Apache 1.3)</STRONG> per-directory config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cern_meta<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> 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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Apache module mod_cern_meta</h1> + + <p>This module provides for CERN httpd metafile semantics.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_cern_meta.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + cern_meta_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.1 and later.</p> + + <h2>Summary</h2> + <!-- XXX: Should mention other possibilities in Apache: mod_header --> + 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.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#metafiles">MetaFiles</a></li> + + <li><a href="#metadir">MetaDir</a></li> + + <li><a href="#metasuffix">MetaSuffix</a></li> + </ul> + <hr /> + + <h2><a id="metafiles" name="metafiles">MetaFiles</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MetaFiles on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MetaFiles + off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> per-directory + config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_cern_meta<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> MetaFiles is + only available in Apache 1.3 and later. + + <p>Turns on/off Meta file processing on a per-directory basis. + This option was introduced in Apache 1.3.</p> + <hr /> + + <h2><a id="metadir" name="metadir">MetaDir</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MetaDir + <em>directory</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MetaDir + .web</code><br /> + <strong>Context: (Apache prior to 1.3)</strong> server + config<br /> + <strong>Context: (Apache 1.3)</strong> per-directory + config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_cern_meta<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> 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.</p> + <hr /> + + <h2><a id="metasuffix" name="metasuffix">MetaSuffix</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MetaSuffix + <em>suffix</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MetaSuffix + .meta</code><br /> + <strong>Context: (Apache prior to 1.3)</strong> server + config<br /> + <strong>Context: (Apache 1.3)</strong> per-directory + config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_cern_meta<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> 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> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html index 9ebcc793c6..e478a22681 100644 --- a/docs/manual/mod/mod_cgi.html +++ b/docs/manual/mod/mod_cgi.html @@ -1,250 +1,218 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_cgi</H1> - -<p>This module provides for execution of CGI scripts.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_cgi.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> cgi_module -</P> - - -<H2>Summary</H2> -<!-- XXX: Should have references to CGI definition/RFC --> -<!-- XXX: Should mention Options ExecCGI --> - -<p>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 containing 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> - -<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.</p> - -<p>For an introduction to using CGI scripts with Apache, see our -tutorial on <a href="../howto/cgi.html">Dynamic Content With CGI</a>.</p> - -<p>When using a multi-threaded MPM under unix, the module <a -href="mod_cgid.html">mod_cgid</a> should be used in place of this -module. At the user level, the two modules are essentially -identical.</p> - -<h2>Directives</h2> - -<ul> -<li><a href="#scriptlog">ScriptLog</a></li> -<li><a href="#scriptloglength">ScriptLogLength</a></li> -<li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li> -</ul> - -<p>See also: <a href="core.html#options">Options</a>, <a -href="mod_alias.html#scriptalias">ScriptAlias</a>, <a -href="mod_mime.html#addtype">AddType</a> and <a -href="mod_mime.html#addhandler">AddHandler</a>. - -<H2>CGI Environment variables</H2> -The server will set the CGI environment variables as described in the -<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI specification</A>, with the -following provisions: -<DL> -<DT>REMOTE_HOST -<DD>This will only be set if <A HREF="core.html#hostnamelookups"><CODE>HostnameLookups</CODE></A> -is set to <CODE>on</CODE> (it is off by default), and if a reverse DNS -lookup of the accessing host's address indeed finds a host name. -<DT>REMOTE_IDENT -<DD>This will only be set if -<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <CODE>on</CODE> -and the accessing host supports the ident protocol. Note that the contents -of this variable cannot be relied upon because it can easily be faked, and if -there is a proxy between the client and the server, it is usually -totally useless. -<DT>REMOTE_USER -<DD>This will only be set if the CGI script is subject to authentication. -</DL> -<P> - -<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. - -<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> - %% [<EM>time</EM>] <EM>request-line</EM> - %% <EM>HTTP-status</EM> <EM>CGI-script-filename</EM> -</PRE> - -If the error is that CGI script cannot be run, the log file will -contain -an extra two lines: - -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_cgi</h1> + + <p>This module provides for execution of CGI scripts.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_cgi.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + cgi_module</p> + + <h2>Summary</h2> + <!-- XXX: Should have references to CGI definition/RFC --> + <!-- XXX: Should mention Options ExecCGI --> + + <p>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 containing 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> + + <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.</p> + + <p>For an introduction to using CGI scripts with Apache, see + our tutorial on <a href="../howto/cgi.html">Dynamic Content + With CGI</a>.</p> + + <p>When using a multi-threaded MPM under unix, the module <a + href="mod_cgid.html">mod_cgid</a> should be used in place of + this module. At the user level, the two modules are essentially + identical.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#scriptlog">ScriptLog</a></li> + + <li><a href="#scriptloglength">ScriptLogLength</a></li> + + <li><a href="#scriptlogbuffer">ScriptLogBuffer</a></li> + </ul> + + <p>See also: <a href="core.html#options">Options</a>, <a + href="mod_alias.html#scriptalias">ScriptAlias</a>, <a + href="mod_mime.html#addtype">AddType</a> and <a + href="mod_mime.html#addhandler">AddHandler</a>.</p> + + <h2>CGI Environment variables</h2> + The server will set the CGI environment variables as described + in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI + specification</a>, with the following provisions: + + <dl> + <dt>REMOTE_HOST</dt> + + <dd>This will only be set if <a + href="core.html#hostnamelookups"><code>HostnameLookups</code></a> + is set to <code>on</code> (it is off by default), and if a + reverse DNS lookup of the accessing host's address indeed + finds a host name.</dd> + + <dt>REMOTE_IDENT</dt> + + <dd>This will only be set if <a + href="core.html#identitycheck">IdentityCheck</a> is set to + <code>on</code> and the accessing host supports the ident + protocol. Note that the contents of this variable cannot be + relied upon because it can easily be faked, and if there is a + proxy between the client and the server, it is usually + totally useless.</dd> + + <dt>REMOTE_USER</dt> + + <dd>This will only be set if the CGI script is subject to + authentication.</dd> + </dl> + + <h2><a id="cgi_debug" 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. + + <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> + %% [<em>time</em>] <em>request-line</em> + %% <em>HTTP-status</em> <em>CGI-script-filename</em> +</pre> + If the error is that CGI script cannot be run, the log file + will contain an extra two lines: +<pre> %%error - <EM>error-message</EM> -</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> + <em>error-message</em> +</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 - <EM>All HTTP request headers received</EM> - <EM>POST or PUT entity (if any)</EM> + <em>All HTTP request headers received</em> + <em>POST or PUT entity (if any)</em> %response - <EM>All headers output by the CGI script</EM> + <em>All headers output by the CGI script</em> %stdout - <EM>CGI standard output</EM> + <em>CGI standard output</em> %stderr - <EM>CGI standard error</EM> -</PRE> - -(The %stdout and %stderr parts may be missing if the script did not -output -anything on standard output or standard error). - -<HR> - -<H3><A NAME="scriptlog">ScriptLog</A> directive</H3> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptLog <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> none<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> 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> - -<hr> - -<H3><A NAME="scriptloglength">ScriptLogLength</A> directive</H3> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptLogLength <EM>bytes</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> 10385760<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> 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. - -<hr> - -<H3><A NAME="scriptlogbuffer">ScriptLogBuffer</A></H3> - -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScriptLogBuffer <EM>bytes</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> 1024<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> 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. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> + <em>CGI standard error</em> +</pre> + (The %stdout and %stderr parts may be missing if the script did + not output anything on standard output or standard error). + <hr /> + + <h3><a id="scriptlog" name="scriptlog">ScriptLog</a> + directive</h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ScriptLog + <em>filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> none<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> 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> + + <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> + <hr /> + + <h3><a id="scriptloglength" + name="scriptloglength">ScriptLogLength</a> directive</h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ScriptLogLength + <em>bytes</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> 10385760<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> 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.</p> + <hr /> + + <h3><a id="scriptlogbuffer" + name="scriptlogbuffer">ScriptLogBuffer</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ScriptLogBuffer + <em>bytes</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> 1024<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> 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. <!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_cgid.html b/docs/manual/mod/mod_cgid.html index 396d608d5c..be5337f31b 100644 --- a/docs/manual/mod/mod_cgid.html +++ b/docs/manual/mod/mod_cgid.html @@ -1,101 +1,88 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_cgid</H1> - -<p>This module provides for execution of CGI scripts using an external -CGI daemon.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base (unix threaded MPMs only) -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_cgid.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> cgid_module -</P> - - -<H2>Summary</H2> - -<p>On certain unix operating systems, forking a process from a -multi-threaded server is a very expensive operation because the new -process will replicate all the threads of the parent process. In -order to avoid incurring this expense on each CGI invocation, mod_cgid -creates an external daemon that is responsible for forking child -processes to run CGI scripts. The main server communicates with this -daemon using a unix domain socket.</p> - -<p>This module is used by default whenever a multi-threaded MPM is -selected during the compilation process. At the user level, this -module is identical in configuration and operation to <a -href="mod_cgi.html">mod_cgi</a>. The only exception is the additional -directive <code>ScriptSock</code> which gives the name of the socket -to use for communication with the cgi daemon.</p> - -<h2>Directives</h2> - -<ul> -<li><a href="mod_cgi.html#scriptlog">ScriptLog</a></li> -<li><a href="mod_cgi.html#scriptloglength">ScriptLogLength</a></li> -<li><a href="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</a></li> -<li><a href="#scriptsock">ScriptSock</a></li> -</ul> - -<hr> - -<H3><A NAME="scriptsock">ScriptSock</A> directive</H3> - -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Scriptsock <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> logs/cgisock<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<br> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cgid</p> - -<p>This directive sets the name of the socket to use for communication -with the CGI daemon. The socket will be opened using the permissions -of the user who starts Apache (usually root). To maintain the security -of communications with CGI scripts, it is important that no other -user has permission to write in the directory where the socket is -located.</p> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_cgid</h1> + + <p>This module provides for execution of CGI scripts using an + external CGI daemon.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base (unix threaded + MPMs only)<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_cgid.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + cgid_module</p> + + <h2>Summary</h2> + + <p>On certain unix operating systems, forking a process from a + multi-threaded server is a very expensive operation because the + new process will replicate all the threads of the parent + process. In order to avoid incurring this expense on each CGI + invocation, mod_cgid creates an external daemon that is + responsible for forking child processes to run CGI scripts. The + main server communicates with this daemon using a unix domain + socket.</p> + + <p>This module is used by default whenever a multi-threaded MPM + is selected during the compilation process. At the user level, + this module is identical in configuration and operation to <a + href="mod_cgi.html">mod_cgi</a>. The only exception is the + additional directive <code>ScriptSock</code> which gives the + name of the socket to use for communication with the cgi + daemon.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="mod_cgi.html#scriptlog">ScriptLog</a></li> + + <li><a + href="mod_cgi.html#scriptloglength">ScriptLogLength</a></li> + + <li><a + href="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</a></li> + + <li><a href="#scriptsock">ScriptSock</a></li> + </ul> + <hr /> + + <h3><a id="scriptsock" name="scriptsock">ScriptSock</a> + directive</h3> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Scriptsock + <em>filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> logs/cgisock<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_cgid</p> + + <p>This directive sets the name of the socket to use for + communication with the CGI daemon. The socket will be opened + using the permissions of the user who starts Apache (usually + root). To maintain the security of communications with CGI + scripts, it is important that no other user has permission to + write in the directory where the socket is located.</p> + <!--#include virtual="footer.html" --> + </body> +</html> diff --git a/docs/manual/mod/mod_charset_lite.html b/docs/manual/mod/mod_charset_lite.html index 720aa275a5..6b8ccf963b 100644 --- a/docs/manual/mod/mod_charset_lite.html +++ b/docs/manual/mod/mod_charset_lite.html @@ -1,285 +1,232 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_charset_lite</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_charset_lite</H1> - -<p>This module provides the ability to specify character set - translation or recoding.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Experimental -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_charset_lite.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> charset_lite_module -</P> - - <H2>Summary</H2> - <P> - This is an <STRONG>experimental</STRONG> module and should be used with - care. Experiment with your <CODE>mod_charset_lite</CODE> configuration to - ensure that it performs the desired function. - </P> - <P> - <CODE>mod_charset_lite</CODE> allows the administrator to specify the - source character set of objects as well as the character set they should - be translated into before sending to the client. - <CODE>mod_charset_lite</CODE> does not translate the data itself but - instead tells Apache what translation to perform. - <CODE>mod_charset_lite</CODE> is applicable to EBCDIC and ASCII - host environments. In an EBCDIC environment, Apache normally translates - text content from the code page of the Apache process locale to - ISO-8859-1. <CODE>mod_charset_lite</CODE> can be used to specify that - a different translation is to be performed. In an ASCII environment, - Apache normally performs no translation, so <CODE>mod_charset_lite</CODE> - is needed in order for any translation to take place. - </P> - - <p>This module will only work if <code>APACHE_XLATE</code> is defined - at compile time.</p> - - <P> - This module provides a small subset of configuration mechanisms - implemented by Russian Apache and its associated <CODE>mod_charset</CODE>. - </P> - - <H2>Directives</H2> - <UL> - <LI><A HREF="#charsetsourceenc">CharsetSourceEnc</A> - <LI><A HREF="#charsetdefault">CharsetDefault</A> - <LI><A HREF="#charsetoptions">CharsetOptions</A> - </LI> - </UL> - - <H2>Common Problems</H2> - - <H3>Invalid character set names</H3> - - <P> - The character set name parameters of CharsetSourceEnc and CharsetDefault - must be acceptable to the translation mechanism used by APR on the system - where mod_charset_lite is deployed. These character set names are not - standardized and are usually not the same as the corresponding values used - in http headers. Currently, APR can only use iconv(3), so you can easily - test your character set names using the iconv(1) program, as follows: - </P> - - <PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_charset_lite</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_charset_lite</h1> + + <p>This module provides the ability to specify character set + translation or recoding.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_charset_lite.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + charset_lite_module</p> + + <h2>Summary</h2> + + <p>This is an <strong>experimental</strong> module and should + be used with care. Experiment with your + <code>mod_charset_lite</code> configuration to ensure that it + performs the desired function.</p> + + <p><code>mod_charset_lite</code> allows the administrator to + specify the source character set of objects as well as the + character set they should be translated into before sending to + the client. <code>mod_charset_lite</code> does not translate + the data itself but instead tells Apache what translation to + perform. <code>mod_charset_lite</code> is applicable to EBCDIC + and ASCII host environments. In an EBCDIC environment, Apache + normally translates text content from the code page of the + Apache process locale to ISO-8859-1. + <code>mod_charset_lite</code> can be used to specify that a + different translation is to be performed. In an ASCII + environment, Apache normally performs no translation, so + <code>mod_charset_lite</code> is needed in order for any + translation to take place.</p> + + <p>This module will only work if <code>APACHE_XLATE</code> is + defined at compile time.</p> + + <p>This module provides a small subset of configuration + mechanisms implemented by Russian Apache and its associated + <code>mod_charset</code>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#charsetsourceenc">CharsetSourceEnc</a></li> + + <li><a href="#charsetdefault">CharsetDefault</a></li> + + <li><a href="#charsetoptions">CharsetOptions</a></li> + </ul> + + <h2>Common Problems</h2> + + <h3>Invalid character set names</h3> + + <p>The character set name parameters of CharsetSourceEnc and + CharsetDefault must be acceptable to the translation mechanism + used by APR on the system where mod_charset_lite is deployed. + These character set names are not standardized and are usually + not the same as the corresponding values used in http headers. + Currently, APR can only use iconv(3), so you can easily test + your character set names using the iconv(1) program, as + follows:</p> +<pre> iconv -f charsetsourceenc-value -t charsetdefault-value - </PRE> - - <H3>Mismatch between character set of content and translation rules</H3> - - <P> - If the translation rules don't make sense for the content, translation - can fail in various ways, including: - </P> - - <UL> - <LI> - The translation mechanism may return a bad return code, and the connection - will be aborted. - <LI> - The translation mechanism may silently place special characters (e.g., question - marks) in the output buffer when it cannot translate the input buffer. - </UL> - - <HR> - - <H2><A NAME="charsetsourceenc">CharsetSourceEnc</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> CharsetSourceEnc <EM>charset</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> directory, virtual host - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>FileInfo</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_charset_lite - <BR> - - <P> - The <CODE>CharsetSourceEnc</CODE> directive specifies the source charset - of files in the associated container. - </P> - - <P> - The value of the <EM>charset</EM> argument must be accepted as a valid - character set name by the character set support in APR. Generally, this - means that it must be supported by iconv. - </P> - - Example: - - <PRE> + +</pre> + + <h3>Mismatch between character set of content and translation + rules</h3> + + <p>If the translation rules don't make sense for the content, + translation can fail in various ways, including:</p> + + <ul> + <li>The translation mechanism may return a bad return code, + and the connection will be aborted.</li> + + <li>The translation mechanism may silently place special + characters (e.g., question marks) in the output buffer when + it cannot translate the input buffer.</li> + </ul> + <hr /> + + <h2><a id="charsetsourceenc" + name="charsetsourceenc">CharsetSourceEnc</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CharsetSourceEnc + <em>charset</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, virtual + host<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> + <em>FileInfo</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_charset_lite<br /> + </p> + + <p>The <code>CharsetSourceEnc</code> directive specifies the + source charset of files in the associated container.</p> + + <p>The value of the <em>charset</em> argument must be accepted + as a valid character set name by the character set support in + APR. Generally, this means that it must be supported by + iconv.</p> + Example: +<pre> <Directory "/export/home/trawick/apacheinst/htdocs/convert"> CharsetSourceEnc UTF-16BE CharsetDefault ISO8859-1 </Directory> - </PRE> - - The character set names in this example work with the iconv - translation support in Solaris 8. - <P> - -<hr> - - <H2><A NAME="charsetdefault">CharsetDefault</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> CharsetDefault <EM>charset</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> directory, virtual host - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>FileInfo</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_charset_lite - <BR> - - <P> - The <CODE>CharsetDefault</CODE> directive specifies the charset that - content in the associated container should be translated to. - </P> - - <P> - The value of the <EM>charset</EM> argument must be accepted as a valid - character set name by the character set support in APR. Generally, this - means that it must be supported by iconv. - </P> - - Example: - - <PRE> + +</pre> + The character set names in this example work with the iconv + translation support in Solaris 8. + <hr /> + + <h2><a id="charsetdefault" + name="charsetdefault">CharsetDefault</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CharsetDefault + <em>charset</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, virtual + host<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> + <em>FileInfo</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_charset_lite<br /> + </p> + + <p>The <code>CharsetDefault</code> directive specifies the + charset that content in the associated container should be + translated to.</p> + + <p>The value of the <em>charset</em> argument must be accepted + as a valid character set name by the character set support in + APR. Generally, this means that it must be supported by + iconv.</p> + Example: +<pre> <Directory "/export/home/trawick/apacheinst/htdocs/convert"> CharsetSourceEnc UTF-16BE CharsetDefault ISO8859-1 </Directory> - </PRE> - - <P> - -<hr> - - <H2><A NAME="charsetoptions">CharsetOptions</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> CharsetOptions <EM>option</em> - [<em>option</em>] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoImplicitAdd</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> directory, virtual host - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>FileInfo</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_charset_lite - <BR> - - <P> - The <CODE>CharsetOptions</CODE> directive configures certain behaviors - of <CODE>mod_charset_lite</CODE>. <EM>Option</EM> can be one of - <DL> - <DT>DebugLevel=<EM>n</EM> - <DD> - The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of - debug messages generated by <CODE>mod_charset_lite</CODE>. By default, no - messages are generated. This is equivalent to <SAMP>DebugLevel=0</SAMP>. - With higher numbers, more debug messages are generated, and server - performance will be degraded. The actual meanings of the numeric values - are described with the definitions of the DBGLVL_ constants near the - beginning of <CODE>mod_charset_lite.c</CODE>. - <DT>ImplicitAdd | NoImplicitAdd - <DD> - The <SAMP>ImplicitAdd</SAMP> keyword specifies that - <CODE>mod_charset_lite</CODE> should implicitly insert its filter when - the configuration specifies that the character set of content should be - translated. If the filter chain is explicitly configured using the - AddOutputFilter directive, <SAMP>NoImplicitAdd</SAMP> should be specified so - that <CODE>mod_charset_lite</CODE> doesn't add its filter. - </DL> - </P> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> +</pre> + <hr /> + + <h2><a id="charsetoptions" + name="charsetoptions">CharsetOptions</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CharsetOptions + <em>option</em> [<em>option</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>DebugLevel=0</em> + <em>NoImplicitAdd</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, virtual + host<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> + <em>FileInfo</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_charset_lite<br /> + </p> + + <p>The <code>CharsetOptions</code> directive configures certain + behaviors of <code>mod_charset_lite</code>. <em>Option</em> can + be one of</p> + + <dl> + <dt>DebugLevel=<em>n</em></dt> + + <dd>The <samp>DebugLevel</samp> keyword allows you to specify + the level of debug messages generated by + <code>mod_charset_lite</code>. By default, no messages are + generated. This is equivalent to <samp>DebugLevel=0</samp>. + With higher numbers, more debug messages are generated, and + server performance will be degraded. The actual meanings of + the numeric values are described with the definitions of the + DBGLVL_ constants near the beginning of + <code>mod_charset_lite.c</code>.</dd> + + <dt>ImplicitAdd | NoImplicitAdd</dt> + + <dd>The <samp>ImplicitAdd</samp> keyword specifies that + <code>mod_charset_lite</code> should implicitly insert its + filter when the configuration specifies that the character + set of content should be translated. If the filter chain is + explicitly configured using the AddOutputFilter directive, + <samp>NoImplicitAdd</samp> should be specified so that + <code>mod_charset_lite</code> doesn't add its filter.</dd> + </dl> + <br /> + <br /> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_dav.html b/docs/manual/mod/mod_dav.html index 46b6c26313..fa0bd97ef7 100644 --- a/docs/manual/mod/mod_dav.html +++ b/docs/manual/mod/mod_dav.html @@ -1,253 +1,214 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_dav</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_dav</H1> - -<p>This module provides Distributed Authoring and Versioning -(<a href="http://www.webdav.org/">WebDAV</a>) functionality.</p> - -<A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_dav.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> dav_module - -<h2>Summary</h2> - -<p>This module provides class 1 and class 2 -<A HREF="http://www.webdav.org">WebDAV</A> ('Web-based -Distributed Authoring and Versioning') functionality for Apache. -This extension to the HTTP protocol allows creating, moving, -copying, and deleting resources and collections on a remote web -server.</p> - -<P> -To enable mod_dav, add the following to a container in your <CODE>httpd.conf</CODE> file:</P> - -<blockquote> -<CODE>Dav On</CODE> -</blockquote> - -<p>Also, specify a valid filename for the DAV lock database by adding -the following to the global section in your <CODE>httpd.conf</CODE> -file:</p> - -<blockquote> -<CODE>DavLockDB /tmp/DavLock </CODE><EM>(Any web-server writable filename, without an extension)</EM> -</blockquote> - - - -<H2>Directives</H2> -<UL> -<LI><A HREF="#DAV">Dav</A> -<LI><A HREF="#DAVLockDB">DavLockDB</A> -<LI><A HREF="#DAVMinTimeout">DavMinTimeout</A> -<LI><A HREF="#DAVDepthInfinity">DavDepthInfinity</A> -</UL> - -<HR> - -<H2><A NAME="DAV">Dav</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Dav on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <CODE>Dav off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_dav<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.4 and above - -<p>Use the <CODE>Dav</CODE> directive to enable the WebDAV HTTP methods -for the given container. -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 DAV-enabled locations.</P> - -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Example</STRONG>:<BR><BR> -<CODE>DavLockDB /tmp/DavLock<BR> -<BR> -<Location /foo><BR> -Dav On<BR> -<BR> -AuthType Basic<BR> -AuthName DAV<BR> -AuthUserFile user.passwd<BR> -<BR> - <LimitExcept GET HEAD OPTIONS><BR> - require user admin<BR> - </LimitExcept><BR> -</Location><BR> -</CODE> -</TD></TR> -</TABLE> - -<BR> -<HR> - -<H2><A NAME="DavLockDB">DavLockDB</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DavLockDB <em>filename</em><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_dav - -<p>Use the <CODE>DavLockDB</CODE> directive to specify the full path to the -lock database, excluding an extension. The default (file system) -implementation of mod_dav uses a SDBM database to track user locks. -The utility <CODE>modules/dav/util/lockview</CODE> can be -used from the server to display all locks in a lock database.</P> - -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Example</STRONG>:<BR><BR> -<CODE>DavLockDB /tmp/DavLock<BR> -<BR> -</CODE> -</TD></TR> -</TABLE> - -<BR> -<HR> - -<H2><A NAME="DavMinTimeout">DavMinTimeout</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DavMinTimeout <em>seconds</em><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <CODE>DavMinTimeout 0</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_dav - -<p>When a client requests a DAV resource lock, it can also specify a time -when the lock will be automatically removed by the server. This value -is only a request, and the server can ignore it or inform the client -of an arbitrary value.</P> - -<p>Use the <CODE>DavMinTimeout</CODE> directive to specify, in seconds, -the minimum lock timeout to return to a client. Microsoft Web Folders -defaults to a timeout of 120 seconds; the <CODE>DavMinTimeout</CODE> -can override this to a higher value (like 600 seconds) to reduce the chance -of the client losing the lock due to network latency.</P> - -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Example</STRONG>:<BR><BR> -<CODE><Location /MSWord><BR> -DavMinTimeout 600<BR> -</Location><BR> -<BR> -</CODE> -</TD></TR> -</TABLE> - -<BR> -<HR> - -<H2><A NAME="DavDepthInfinity">DavDepthInfinity</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DavDepthInfinity on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <CODE>DavDepthInfinity off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_dav - -<p>Use the <CODE>DavDepthInfinity</CODE> directive to allow the processing -of PROPFIND requests containing the header 'Depth: Infinity'. -Because this type of request could constitute a denial-of-service attack, -by default it is not allowed.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_dav</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_dav</h1> + + <p>This module provides Distributed Authoring and Versioning + (<a href="http://www.webdav.org/">WebDAV</a>) + functionality.</p> + <a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension <br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_dav.c <br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> dav_module + + <h2>Summary</h2> + + <p>This module provides class 1 and class 2 <a + href="http://www.webdav.org">WebDAV</a> ('Web-based Distributed + Authoring and Versioning') functionality for Apache. This + extension to the HTTP protocol allows creating, moving, + copying, and deleting resources and collections on a remote web + server.</p> + + <p>To enable mod_dav, add the following to a container in your + <code>httpd.conf</code> file:</p> + + <blockquote> + <code>Dav On</code> + </blockquote> + + <p>Also, specify a valid filename for the DAV lock database by + adding the following to the global section in your + <code>httpd.conf</code> file:</p> + + <blockquote> + <code>DavLockDB /tmp/DavLock </code> + <em>(Any web-server writable filename, without an + extension)</em> + </blockquote> + + <h2>Directives</h2> + + <ul> + <li><a href="#DAV">Dav</a></li> + + <li><a href="#DAVLockDB">DavLockDB</a></li> + + <li><a href="#DAVMinTimeout">DavMinTimeout</a></li> + + <li><a href="#DAVDepthInfinity">DavDepthInfinity</a></li> + </ul> + <hr /> + + <h2><a id="DAV" name="DAV">Dav</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Dav on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>Dav + off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_dav<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.4 and + above + + <p>Use the <code>Dav</code> directive to enable the WebDAV HTTP + methods for the given container. 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 DAV-enabled locations.</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" cellspacing="0" + cellpadding="10"> + <tr> + <td><strong>Example</strong>:<br /> + <br /> + <code>DavLockDB /tmp/DavLock<br /> + <br /> + <Location /foo><br /> + Dav On<br /> + <br /> + AuthType Basic<br /> + AuthName DAV<br /> + AuthUserFile user.passwd<br /> + <br /> + <LimitExcept GET HEAD OPTIONS><br /> + require user admin<br /> + </LimitExcept><br /> + </Location><br /> + </code> </td> + </tr> + </table> + <br /> + + <hr /> + + <h2><a id="DavLockDB" name="DavLockDB">DavLockDB</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DavLockDB + <em>filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_dav + + <p>Use the <code>DavLockDB</code> directive to specify the full + path to the lock database, excluding an extension. The default + (file system) implementation of mod_dav uses a SDBM database to + track user locks. The utility + <code>modules/dav/util/lockview</code> can be used from the + server to display all locks in a lock database.</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" cellspacing="0" + cellpadding="10"> + <tr> + <td><strong>Example</strong>:<br /> + <br /> + <code>DavLockDB /tmp/DavLock<br /> + <br /> + </code> </td> + </tr> + </table> + <br /> + + <hr /> + + <h2><a id="DavMinTimeout" + name="DavMinTimeout">DavMinTimeout</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DavMinTimeout + <em>seconds</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>DavMinTimeout + 0</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_dav + + <p>When a client requests a DAV resource lock, it can also + specify a time when the lock will be automatically removed by + the server. This value is only a request, and the server can + ignore it or inform the client of an arbitrary value.</p> + + <p>Use the <code>DavMinTimeout</code> directive to specify, in + seconds, the minimum lock timeout to return to a client. + Microsoft Web Folders defaults to a timeout of 120 seconds; the + <code>DavMinTimeout</code> can override this to a higher value + (like 600 seconds) to reduce the chance of the client losing + the lock due to network latency.</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" cellspacing="0" + cellpadding="10"> + <tr> + <td><strong>Example</strong>:<br /> + <br /> + <code><Location /MSWord><br /> + DavMinTimeout 600<br /> + </Location><br /> + <br /> + </code> </td> + </tr> + </table> + <br /> + + <hr /> + + <h2><a id="DavDepthInfinity" + name="DavDepthInfinity">DavDepthInfinity</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DavDepthInfinity + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>DavDepthInfinity + off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_dav + + <p>Use the <code>DavDepthInfinity</code> directive to allow the + processing of PROPFIND requests containing the header 'Depth: + Infinity'. Because this type of request could constitute a + denial-of-service attack, by default it is not allowed.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_dir.html b/docs/manual/mod/mod_dir.html index 672f333e16..d1573a6674 100644 --- a/docs/manual/mod/mod_dir.html +++ b/docs/manual/mod/mod_dir.html @@ -1,119 +1,115 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_dir</H1> - -<p>This module provides for "trailing slash" redirects and serving -directory index files.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_dir.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> dir_module -</P> - -<H2>Summary</H2> -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. -This is controlled by <CODE>mod_dir</CODE>. -<LI>Otherwise, a listing generated by the server. This is provided by -<A HREF="mod_autoindex.html"><CODE>mod_autoindex</CODE></A>. -</UL> -The two functions are separated so that you can completely remove -(or replace) automatic index generation should you want to. -<P>A "trailing slash" redirect is issued when the server receives a -request for a URL <SAMP>http://servername/foo/dirname</SAMP> where -<SAMP>dirname</SAMP> is a directory. Directories require a trailing -slash, so <CODE>mod_dir</CODE> issues a redirect to -<SAMP>http://servername/foo/dirname/</SAMP>. - -<H2>Directives</H2> - -<MENU> -<LI><A HREF="#directoryindex">DirectoryIndex</A> -</MENU> -<HR> - -<H2><A NAME="directoryindex">DirectoryIndex</A> directive</H2> -<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> DirectoryIndex <EM>local-url</em> - [<em>local-url</em>] ...<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>DirectoryIndex index.html</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_dir</h1> + + <p>This module provides for "trailing slash" redirects and + serving directory index files.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_dir.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + dir_module</p> + + <h2>Summary</h2> + 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. This is controlled by + <code>mod_dir</code>.</li> + + <li>Otherwise, a listing generated by the server. This is + provided by <a + href="mod_autoindex.html"><code>mod_autoindex</code></a>.</li> + </ul> + The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to. + + <p>A "trailing slash" redirect is issued when the server + receives a request for a URL + <samp>http://servername/foo/dirname</samp> where + <samp>dirname</samp> is a directory. Directories require a + trailing slash, so <code>mod_dir</code> issues a redirect to + <samp>http://servername/foo/dirname/</samp>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#directoryindex">DirectoryIndex</a></li> + </ul> + <hr /> + + <h2><a id="directoryindex" + name="directoryindex">DirectoryIndex</a> directive</h2> + <!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DirectoryIndex + <em>local-url</em> [<em>local-url</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>DirectoryIndex + index.html</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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> + + <p>Example:</p> + + <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;</p> + + <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><!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html index 65d330075b..295b875eba 100644 --- a/docs/manual/mod/mod_env.html +++ b/docs/manual/mod/mod_env.html @@ -1,159 +1,123 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache module mod_env</H1> - -<p>This module provides for modifying the environment which -is passed to CGI scripts and SSI pages.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_env.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> env_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later. -</P> - -<H2>Summary</H2> - -<p>This module allows for control of the environment that will be -provided to CGI scripts and SSI pages. Environment variables may be -passed from the shell which invoked the httpd process. Alternatively, -environment variables may be set or unset within the configuration -process.</p> - -<p>For additional information, we provide a document on -<a href="../env.html">Environment Variables in Apache</a>.</p> - -<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> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> PassEnv <EM>env-variable</em> - [<em>env-variable</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_env<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> PassEnv is only available in -Apache 1.1 and later.<P> - -Specifies one or more environment variables to pass to CGI scripts -and SSI pages from the environment of the shell which invoked -the httpd process. Example: -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Apache module mod_env</h1> + + <p>This module provides for modifying the environment which is + passed to CGI scripts and SSI pages.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_env.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + env_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.1 and later.</p> + + <h2>Summary</h2> + + <p>This module allows for control of the environment that will + be provided to CGI scripts and SSI pages. Environment variables + may be passed from the shell which invoked the httpd process. + Alternatively, environment variables may be set or unset within + the configuration process.</p> + + <p>For additional information, we provide a document on <a + href="../env.html">Environment Variables in Apache</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#passenv">PassEnv</a></li> + + <li><a href="#setenv">SetEnv</a></li> + + <li><a href="#unsetenv">UnsetEnv</a></li> + </ul> + <hr /> + + <h2><a id="passenv" name="passenv">PassEnv</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> PassEnv + <em>env-variable</em> [<em>env-variable</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_env<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> PassEnv is only + available in Apache 1.1 and later. + + <p>Specifies one or more environment variables to pass to CGI + scripts and SSI pages from the environment of the shell which + invoked the httpd process. Example:</p> +<pre> PassEnv LD_LIBRARY_PATH -</PRE> - -<HR> - -<H2><A NAME="setenv">SetEnv</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SetEnv <EM>env-variable value</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_env<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SetEnv is only available in -Apache 1.1 and later.<P> - -Sets an environment variable, which is then passed on to CGI -scripts and SSI pages. Example: -<PRE> +</pre> + <hr /> + + <h2><a id="setenv" name="setenv">SetEnv</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> SetEnv <em>env-variable + value</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_env<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> SetEnv is only + available in Apache 1.1 and later. + + <p>Sets an environment variable, which is then passed on to CGI + scripts and SSI pages. Example:</p> +<pre> SetEnv SPECIAL_PATH /foo/bin -</PRE> - -<HR> - -<H2><A NAME="unsetenv">UnsetEnv</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> UnsetEnv <EM>env-variable</em> - [<em>env-variable</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_env<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> UnsetEnv is only available in -Apache 1.1 and later.<P> - -Removes one or more environment variables from those passed on to -CGI scripts and SSI pages. Example: -<PRE> +</pre> + <hr /> + + <h2><a id="unsetenv" name="unsetenv">UnsetEnv</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> UnsetEnv + <em>env-variable</em> [<em>env-variable</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_env<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> UnsetEnv is only + available in Apache 1.1 and later. + + <p>Removes one or more environment variables from those passed + on to CGI scripts and SSI pages. Example:</p> +<pre> UnsetEnv LD_LIBRARY_PATH -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + <!--#include virtual="footer.html" --> + </body> +</html> diff --git a/docs/manual/mod/mod_example.html b/docs/manual/mod/mod_example.html index 79d3a8751f..96ca75f6ad 100644 --- a/docs/manual/mod/mod_example.html +++ b/docs/manual/mod/mod_example.html @@ -1,201 +1,165 @@ -<!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" - > - <!--#include virtual="header.html" --> - -<blockquote><strong>Warning:</strong> -This document has not been updated to take into account changes -made in the 2.0 version of the Apache HTTP Server. Some of the -information may still be relevant, but please use it -with care. -</blockquote> - - <H1 ALIGN="CENTER">Module mod_example</H1> - <P> - This module 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> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_example.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> example_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later. -</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 syntaxes. 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> - <H2>Directives</H2> - <P> - <UL> - <LI><A HREF="#example">Example</A> - </LI> - </UL> - </P> - - <h2>Compiling the example module</h2> - <P> - To include the example module in your server, follow the steps below: - </P> - <OL> - <LI>Uncomment the "AddModule modules/example/mod_example" line near - the bottom of - the <CODE>src/Configuration</CODE> file. If there isn't one, add - it; it should look like this: - <PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <blockquote> + <strong>Warning:</strong> This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. + </blockquote> + + <h1 align="CENTER">Module mod_example</h1> + + <p>This module 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> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_example.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + example_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.2 and later.</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 + syntaxes. 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> + + <h2>Directives</h2> + + <ul> + <li><a href="#example">Example</a></li> + </ul> + <br /> + <br /> + + + <h2>Compiling the example module</h2> + + <p>To include the example module in your server, follow the + steps below:</p> + + <ol> + <li> + Uncomment the "AddModule modules/example/mod_example" line + near the bottom of the <code>src/Configuration</code> file. + If there isn't one, add it; it should look like this: +<pre> AddModule 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> - <H2> - Using the <SAMP>mod_example</SAMP> Module - </H2> - <P> - To activate the example module, include a block similar to the - following in your <SAMP>srm.conf</SAMP> file: - </P> - <PRE> + +</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> + + <h2>Using the <samp>mod_example</samp> Module</h2> + + <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> + +</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> - - <HR> - <H2><A NAME="example"> - Example directive - </A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> Example - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> None - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Options - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_example - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <SAMP>Example</SAMP> is only - available in Apache 1.2 and later. - </P> - <P> - The <SAMP>Example</SAMP> directive just sets a demonstration flag which the - example module's content handler displays. 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. The effect of this directive - one can observe under the point "<SAMP>Example directive declared - here: YES/NO</SAMP>". - </P> - <!--#include virtual="footer.html" --> - </BODY> -</HTML> + +</pre> + + <p>After reloading/restarting your server, you should be able + to browse to this location and see the brief display mentioned + earlier.</p> + <hr /> + + <h2><a id="example" name="example">Example directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Example<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> None<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Options<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_example<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + <samp>Example</samp> is only available in Apache 1.2 and + later.</p> + + <p>The <samp>Example</samp> directive just sets a demonstration + flag which the example module's content handler displays. 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. The effect of this + directive one can observe under the point "<samp>Example + directive declared here: YES/NO</samp>".</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_expires.html b/docs/manual/mod/mod_expires.html index c80b194ae0..bae83e9873 100644 --- a/docs/manual/mod/mod_expires.html +++ b/docs/manual/mod/mod_expires.html @@ -1,350 +1,260 @@ -<!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" - > - <!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_expires</H1> - <P> - This module provides for the generation of <CODE>Expires</CODE> HTTP - headers according to user-specified criteria. - </P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_expires.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> expires_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later. -</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> - <ul> - <LI><A - HREF="#expiresactive" - >ExpiresActive</A> - </LI> - <LI><A - HREF="#expiresbytype" - >ExpiresByType</A> - </LI> - <LI><A - HREF="#expiresdefault" - >ExpiresDefault</A> - </LI> - </ul> - - <H2> - <A NAME="AltSyn">Alternate Interval Syntax</A> - </H2> - <P> - The - <A - HREF="#expiresdefault" - ><SAMP>ExpiresDefault</SAMP></A> - and - <A - HREF="#expiresbytype" - ><SAMP>ExpiresByType</SAMP></A> - directives can also be defined in a more readable syntax of the form: - </P> - <DL> - <DD><CODE>ExpiresDefault "<base> [plus] {<num> <type>}*" - <BR> - ExpiresByType type/encoding "<base> [plus] - {<num> <type>}*"</CODE> - </DD> - </DL> - <P> - where <base> is one of: - </P> - <MENU> - <LI><SAMP>access</SAMP> - </LI> - <LI><SAMP>now</SAMP> (equivalent to '<SAMP>access</SAMP>') - </LI> - <LI><SAMP>modification</SAMP> - </LI> - </MENU> - <P> - The '<SAMP>plus</SAMP>' keyword is optional. <num> should be an - integer value [acceptable to <SAMP>atoi()</SAMP>], and <type> - is one of: - </P> - <MENU> - <LI><SAMP>years</SAMP> - </LI> - <LI><SAMP>months</SAMP> - </LI> - <LI><SAMP>weeks</SAMP> - </LI> - <LI><SAMP>days</SAMP> - </LI> - <LI><SAMP>hours</SAMP> - </LI> - <LI><SAMP>minutes</SAMP> - </LI> - <LI><SAMP>seconds</SAMP> - </LI> - </MENU> - <P> - For example, any of the following directives can be used to make - documents expire 1 month after being accessed, by default: - </P> - <DL> - <DD><CODE>ExpiresDefault "access plus 1 month" - <BR> - ExpiresDefault "access plus 4 weeks" - <BR> - ExpiresDefault "access plus 30 days"</CODE> - </DD> - </DL> - <P> - The expiry time can be fine-tuned by adding several '<num> - <type>' clauses: - </P> - <DL> - <DD><CODE>ExpiresByType text/html "access plus 1 month 15 days 2 hours" - <BR> - ExpiresByType image/gif "modification plus 5 hours 3 minutes"</CODE> - </DD> - </DL> - <P> - Note that if you use a modification date based setting, the Expires - header will <STRONG>not</STRONG> be added to content that does - not come from a file on disk. This is due to the fact that there is - no modification time for such content. - - <HR> - <H2><A NAME="expiresactive"> - ExpiresActive directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresActive} directive> --> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExpiresActive on|off - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Indexes - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> 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> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExpiresByType <EM>MIME-type - <code>seconds</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Indexes - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> 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> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_expires</h1> + + <p>This module provides for the generation of + <code>Expires</code> HTTP headers according to user-specified + criteria.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_expires.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + expires_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.2 and later.</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> + + <ul> + <li><a href="#expiresactive">ExpiresActive</a></li> + + <li><a href="#expiresbytype">ExpiresByType</a></li> + + <li><a href="#expiresdefault">ExpiresDefault</a></li> + </ul> + + <h2><a id="AltSyn" name="AltSyn">Alternate Interval + Syntax</a></h2> + + <p>The <a + href="#expiresdefault"><samp>ExpiresDefault</samp></a> and <a + href="#expiresbytype"><samp>ExpiresByType</samp></a> directives + can also be defined in a more readable syntax of the form:</p> + + <dl> + <dd><code>ExpiresDefault "<base> [plus] {<num> + <type>}*"<br /> + ExpiresByType type/encoding "<base> [plus] + {<num> <type>}*"</code></dd> + </dl> + + <p>where <base> is one of:</p> + + <ul> + <li><samp>access</samp></li> + + <li><samp>now</samp> (equivalent to + '<samp>access</samp>')</li> + + <li><samp>modification</samp></li> + </ul> + + <p>The '<samp>plus</samp>' keyword is optional. <num> + should be an integer value [acceptable to <samp>atoi()</samp>], + and <type> is one of:</p> + + <ul> + <li><samp>years</samp></li> + + <li><samp>months</samp></li> + + <li><samp>weeks</samp></li> + + <li><samp>days</samp></li> + + <li><samp>hours</samp></li> + + <li><samp>minutes</samp></li> + + <li><samp>seconds</samp></li> + </ul> + + <p>For example, any of the following directives can be used to + make documents expire 1 month after being accessed, by + default:</p> + + <dl> + <dd><code>ExpiresDefault "access plus 1 month"<br /> + ExpiresDefault "access plus 4 weeks"<br /> + ExpiresDefault "access plus 30 days"</code></dd> + </dl> + + <p>The expiry time can be fine-tuned by adding several + '<num> <type>' clauses:</p> + + <dl> + <dd><code>ExpiresByType text/html "access plus 1 month 15 + days 2 hours"<br /> + ExpiresByType image/gif "modification plus 5 hours 3 + minutes"</code></dd> + </dl> + + <p>Note that if you use a modification date based setting, the + Expires header will <strong>not</strong> be added to content + that does not come from a file on disk. This is due to the fact + that there is no modification time for such content.</p> + <hr /> + + <h2><a id="expiresactive" name="expiresactive">ExpiresActive + directive</a></h2> + <!--%plaintext <?INDEX {\tt ExpiresActive} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ExpiresActive + on|off<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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 id="expiresbytype" name="expiresbytype">ExpiresByType + directive</a></h2> + <!--%plaintext <?INDEX {\tt ExpiresByType} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ExpiresByType + <em>MIME-type <code>seconds</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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> +<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> - <P> - You can also specify the expiration time calculation using an - <A - HREF="#AltSyn" - >alternate syntax</A>, - described later in this document. - </P> - <HR> - <H2><A NAME="expiresdefault"> - ExpiresDefault directive - </A></H2> - <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> --> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExpiresDefault <EM><code>seconds</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Indexes - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> 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, and the - <A - HREF="#AltSyn" - >alternate syntax</A> - description as well. - </P> - - <!--#include virtual="footer.html" --> - </BODY> -</HTML> + +</pre> + <br /> + <br /> + + + <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> + + <p>You can also specify the expiration time calculation using + an <a href="#AltSyn">alternate syntax</a>, described later in + this document.</p> + <hr /> + + <h2><a id="expiresdefault" name="expiresdefault">ExpiresDefault + directive</a></h2> + <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ExpiresDefault + <em><code>seconds</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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, and the <a href="#AltSyn">alternate syntax</a> + description as well.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_ext_filter.html b/docs/manual/mod/mod_ext_filter.html index d6f663fdc3..50afe50bb2 100644 --- a/docs/manual/mod/mod_ext_filter.html +++ b/docs/manual/mod/mod_ext_filter.html @@ -1,82 +1,76 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_ext_filter</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_ext_filter</H1> - - <P>This module provides the ability to pass the response body - through an external program before delivering to the client.</p> - -<p><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Experimental -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_ext_filter.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> ext_filter_module</p> - - - <H2>Summary</H2> - <P> - This is an <STRONG>experimental</STRONG> module and should be used with - care. Test your <CODE>mod_ext_filter</CODE> configuration carefully to - ensure that it performs the desired function. You may wish to review - XXX for background on the Apache filtering model. - </P> - - <P> - <CODE>mod_ext_filter</CODE> presents a simple and familiar programming - model for filters. With this module, a program which reads from stdin and - writes to stdout (i.e., a Unix-style filter command) can be a filter for - Apache. This filtering mechanism is much slower than using a filter which - is specially written for the Apache API and runs inside of the Apache - server process, but it does have the following benefits: - </P> - - <UL> - <LI>the programming model is much simpler - <LI>any programming/scripting language can be used, provided that - it allows the program to read from standard input and write to standard - output - <LI>existing programs can be used unmodified as Apache filters - </UL> - - <P> - Even when the performance characteristics are not suitable for production - use, <CODE>mod_ext_filter</CODE> can be used as a prototype environment - for filters. - </P> - - <H2>Directives</H2> - <UL> - <LI><A HREF="#extfilterdefine">ExtFilterDefine</A> - <LI><A HREF="#extfilteroptions">ExtFilterOptions</A> - </LI> - </UL> - - - <H2>Examples</H2> - - <H3>Generating HTML from some other type of response</H3> - - <PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_ext_filter</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_ext_filter</h1> + + <p>This module provides the ability to pass the response body + through an external program before delivering to the + client.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_ext_filter.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + ext_filter_module</p> + + <h2>Summary</h2> + + <p>This is an <strong>experimental</strong> module and should + be used with care. Test your <code>mod_ext_filter</code> + configuration carefully to ensure that it performs the desired + function. You may wish to review XXX for background on the + Apache filtering model.</p> + + <p><code>mod_ext_filter</code> presents a simple and familiar + programming model for filters. With this module, a program + which reads from stdin and writes to stdout (i.e., a Unix-style + filter command) can be a filter for Apache. This filtering + mechanism is much slower than using a filter which is specially + written for the Apache API and runs inside of the Apache server + process, but it does have the following benefits:</p> + + <ul> + <li>the programming model is much simpler</li> + + <li>any programming/scripting language can be used, provided + that it allows the program to read from standard input and + write to standard output</li> + + <li>existing programs can be used unmodified as Apache + filters</li> + </ul> + + <p>Even when the performance characteristics are not suitable + for production use, <code>mod_ext_filter</code> can be used as + a prototype environment for filters.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#extfilterdefine">ExtFilterDefine</a></li> + + <li><a href="#extfilteroptions">ExtFilterOptions</a></li> + </ul> + + <h2>Examples</h2> + + <h3>Generating HTML from some other type of response</h3> +<pre> # mod_ext_filter directive to define a filter to HTML-ize text/c files # using the external program /usr/bin/enscript, with the type of the # result set to text/html @@ -97,11 +91,11 @@ REL="Help" ExtFilterOptions DebugLevel=1 </Directory> - </PRE> + +</pre> - <H3>Implementing a content encoding filter</H3> - - <PRE> + <h3>Implementing a content encoding filter</h3> +<pre> # mod_ext_filter directive to define the external filter ExtFilterDefine gzip mode=output cmd=/bin/gzip @@ -114,10 +108,11 @@ REL="Help" Header set Content-Encoding gzip </Location> - </PRE> + +</pre> - <H3>Slowing down the server</H3> - <PRE> + <h3>Slowing down the server</h3> +<pre> # mod_ext_filter directive to define a filter which runs everything # through cat; cat doesn't modify anything; it just introduces extra # pathlength and consumes more resources @@ -130,163 +125,144 @@ REL="Help" SetOutputFilter slowdown slowdown slowdown </Location> - </PRE> - - <HR> - - <H2><A NAME="extfilterdefine">ExtFilterDefine</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExtFilterDefine <EM>filtername</EM> <EM>parameters</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> none - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_ext_filter - - <P> - The <CODE>ExtFilterDefine</CODE> directive defines the characteristics of - an external filter, including the program to run and its arguments. - </P> - - <P> - <EM>filtername</EM> specifies the name of the filter being defined. This name - can then be used in SetOutputFilter directives. It must be unique among all - registered filters. <EM>At the present time, no error is reported by the - register-filter API, so a problem with duplicate names isn't reported to the - user.</EM> - </P> - - <P> - Subsequent parameters can appear in any order and define the external command - to run and certain other characteristics. The only required parameter is - <EM>cmd=</EM>. These parameters are: - </P> - - <DL> - <DT>cmd=<EM>cmdline</EM> - <DD> - The <SAMP>cmd=</SAMP> keyword allows you to specify the external command - to run. If there are arguments after the program name, the command line - should be surrounded in quotation marks. - <DT>mode=<EM>mode</EM> - <DD> - <EM>mode</EM> should be <EM>output</EM> for now (the default). In the - future, <EM>mode=input</EM> will be used to specify a filter for request - bodies. - <DT>intype=<EM>imt</EM> - <DD> - This parameter specifies the internet media - type (i.e., MIME type) of documents which should be filtered. By default, - all documents are filtered. If <CODE>intype=</CODE> is specified, - the filter will be disabled for documents of other types. - <DT>outtype=<EM>imt</EM> - <DD> - This parameter specifies the internet media - type (i.e., MIME type) of filtered documents. It is useful when the filter - changes the internet media type as part of the filtering operation. By - default, the internet media type is unchanged. - <DT>PreservesContentLength - <DD> - The <SAMP>PreservesContentLength</SAMP> keyword specifies that the filter - preserves the content length. This is not the default, as most filters - change the content length. In the event that the filter doesn't modify the - length, this keyword should be specified. - </DL> - -<hr> - - <H2><A NAME="extfilteroptions">ExtFilterOptions</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> ExtFilterOptions <EM>option</em> - [<em>option</EM>] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoLogStderr</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> directory - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> none - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_ext_filter - - <P> - The <CODE>ExtFilterOptions</CODE> directive specifies special processing - options for <CODE>mod_ext_filter</CODE>. <EM>Option</EM> can be one of - <DL> - <DT>DebugLevel=<EM>n</EM> - <DD> - The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of - debug messages generated by <CODE>mod_ext_filter</CODE>. By default, no - debug messages are generated. This is equivalent to - <SAMP>DebugLevel=0</SAMP>. With higher numbers, more debug messages are - generated, and server performance will be degraded. The actual meanings - of the numeric values are described with the definitions of the DBGLVL_ - constants near the beginning of <CODE>mod_ext_filter.c</CODE>. - <P> - Note: The core directive LogLevel should be used to cause debug messages - to be stored in the Apache error log. - <DT>LogStderr | NoLogStderr - <DD> - The <SAMP>LogStderr</SAMP> keyword specifies that messages written to - standard error by the external filter program will be saved in the Apache - error log. <SAMP>NoLogStderr</SAMP> disables this feature. - </DL> - </P> - - Example: - - <PRE> + +</pre> + <hr /> + + <h2><a id="extfilterdefine" + name="extfilterdefine">ExtFilterDefine</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ExtFilterDefine + <em>filtername</em> <em>parameters</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> none<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_ext_filter</p> + + <p>The <code>ExtFilterDefine</code> directive defines the + characteristics of an external filter, including the program to + run and its arguments.</p> + + <p><em>filtername</em> specifies the name of the filter being + defined. This name can then be used in SetOutputFilter + directives. It must be unique among all registered filters. + <em>At the present time, no error is reported by the + register-filter API, so a problem with duplicate names isn't + reported to the user.</em></p> + + <p>Subsequent parameters can appear in any order and define the + external command to run and certain other characteristics. The + only required parameter is <em>cmd=</em>. These parameters + are:</p> + + <dl> + <dt>cmd=<em>cmdline</em></dt> + + <dd>The <samp>cmd=</samp> keyword allows you to specify the + external command to run. If there are arguments after the + program name, the command line should be surrounded in + quotation marks.</dd> + + <dt>mode=<em>mode</em></dt> + + <dd><em>mode</em> should be <em>output</em> for now (the + default). In the future, <em>mode=input</em> will be used to + specify a filter for request bodies.</dd> + + <dt>intype=<em>imt</em></dt> + + <dd>This parameter specifies the internet media type (i.e., + MIME type) of documents which should be filtered. By default, + all documents are filtered. If <code>intype=</code> is + specified, the filter will be disabled for documents of other + types.</dd> + + <dt>outtype=<em>imt</em></dt> + + <dd>This parameter specifies the internet media type (i.e., + MIME type) of filtered documents. It is useful when the + filter changes the internet media type as part of the + filtering operation. By default, the internet media type is + unchanged.</dd> + + <dt>PreservesContentLength</dt> + + <dd>The <samp>PreservesContentLength</samp> keyword specifies + that the filter preserves the content length. This is not the + default, as most filters change the content length. In the + event that the filter doesn't modify the length, this keyword + should be specified.</dd> + </dl> + <hr /> + + <h2><a id="extfilteroptions" + name="extfilteroptions">ExtFilterOptions</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ExtFilterOptions + <em>option</em> [<em>option</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>DebugLevel=0</em> + <em>NoLogStderr</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> none<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_ext_filter</p> + + <p>The <code>ExtFilterOptions</code> directive specifies + special processing options for <code>mod_ext_filter</code>. + <em>Option</em> can be one of</p> + + <dl> + <dt>DebugLevel=<em>n</em></dt> + + <dd> + The <samp>DebugLevel</samp> keyword allows you to specify + the level of debug messages generated by + <code>mod_ext_filter</code>. By default, no debug messages + are generated. This is equivalent to + <samp>DebugLevel=0</samp>. With higher numbers, more debug + messages are generated, and server performance will be + degraded. The actual meanings of the numeric values are + described with the definitions of the DBGLVL_ constants + near the beginning of <code>mod_ext_filter.c</code>. + + <p>Note: The core directive LogLevel should be used to + cause debug messages to be stored in the Apache error + log.</p> + </dd> + + <dt>LogStderr | NoLogStderr</dt> + + <dd>The <samp>LogStderr</samp> keyword specifies that + messages written to standard error by the external filter + program will be saved in the Apache error log. + <samp>NoLogStderr</samp> disables this feature.</dd> + </dl> + <br /> + <br /> + Example: +<pre> ExtFilterOptions LogStderr DebugLevel=0 - </PRE> - - Messages written to the filter's standard error will be stored in the Apache - error log. No debug messages will be generated by - <CODE>mod_ext_filter</CODE>. + +</pre> + Messages written to the filter's standard error will be stored + in the Apache error log. No debug messages will be generated by + <code>mod_ext_filter</code>. - <P> + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_file_cache.html b/docs/manual/mod/mod_file_cache.html index 8e8b34325b..e684f7ed71 100644 --- a/docs/manual/mod/mod_file_cache.html +++ b/docs/manual/mod/mod_file_cache.html @@ -1,268 +1,223 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_file_cache</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_file_cache</H1> - <P> - <STRONG>This module should be used with care. You can easily create a - broken site using mod_file_cache, so read this document - carefully.</STRONG> - </P> - - <P> - <EM>Caching</EM> frequently requested files that change very - infrequently is a technique for reducing server load. mod_file_cache - provides two techniques for caching frequently requested - <EM>static</EM> files. - Through configuration directives, you can direct mod_file_cache - to either open then mmap()a file, or to pre-open a file and save - the file's open <EM>file handle</EM>. Both techniques reduce server - load when processing requests for these files by doing part of the - work (specifically, the file I/O) for serving the file when the server - is started rather than during each request. - </P> - - <P> - <CODE>mod_file_cache</CODE> is not compiled into the server by - default. To use <CODE>mod_file_cache</CODE> you have to enable the - following line in the server build <CODE>Configuration</CODE> file: - <PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_file_cache</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_file_cache</h1> + + <p><strong>This module should be used with care. You can easily + create a broken site using mod_file_cache, so read this + document carefully.</strong></p> + + <p><em>Caching</em> frequently requested files that change very + infrequently is a technique for reducing server load. + mod_file_cache provides two techniques for caching frequently + requested <em>static</em> files. Through configuration + directives, you can direct mod_file_cache to either open then + mmap()a file, or to pre-open a file and save the file's open + <em>file handle</em>. Both techniques reduce server load when + processing requests for these files by doing part of the work + (specifically, the file I/O) for serving the file when the + server is started rather than during each request.</p> + + <p><code>mod_file_cache</code> is not compiled into the server + by default. To use <code>mod_file_cache</code> you have to + enable the following line in the server build + <code>Configuration</code> file:</p> +<pre> AddModule modules/experimental/mod_file_cache.o - </PRE> - </P> - - <P> - Notice: You cannot use this for speeding up CGI programs or other files - which are served by special content handlers. It can only be used for - regular files which are usually served by the Apache core content handler. - </P> - - <P> - This module is an extension of and borrows heavily from the - mod_mmap_static module in Apache 1.3. - </P> - <H2>Summary</H2> - <P> - <CODE>mod_file_cache</CODE> caches a list of statically configured - files via <CODE>MMapFile</CODE> or <CODE>CacheFile</CODE> directives - in the main server configuration. - </P> - - <P> - Not all platforms support both directives. For - example, Apache on Windows does not currently support the MMapStatic - directive, while other platforms, like AIX, support both. You will - receive an error message in the server error log if you attempt to - use an unsupported directive. If given an unsupported directive, the - server will start but the file will not be cached. On platforms that - support both directives, you should experiment with both to see - which works best for you. - </P> - - <H3><CODE>MmapFile</CODE> Directive </H3> - <P> - The <CODE>MmapFile</CODE> directive of <CODE>mod_file_cache</CODE> - maps a list of statically configured files into memory through the - system call <CODE>mmap()</CODE>. This system call is available on - most modern Unix derivates, but not on all. There are sometimes - system-specific limits on the size and number of files that can be - mmap()d, experimentation is probably the easiest way to find out. - </P> - <P> - This mmap()ing is done once at server start or restart, only. So whenever - one of the mapped files changes on the filesystem you <EM>have</EM> to - restart the server (see the <A HREF="../stopping.html">Stopping and - Restarting</A> documentation). To reiterate that point: if the - files are modified <EM>in place</EM> without restarting the server - you may end up serving requests that are completely bogus. You - should update files by unlinking the old copy and putting a new - copy in place. Most tools such as <CODE>rdist</CODE> and - <CODE>mv</CODE> do this. The reason why this modules doesn't take - care of changes to the files is that this check would need an extra - <CODE>stat()</CODE> every time which is a waste and against the - intent of I/O reduction. - </P> - - <H3><CODE>CacheFile</CODE> Directive </H3> - <P> - The <CODE>CacheFile</CODE> directive of <CODE>mod_file_cache</CODE> - opens an active <EM>handle</EM> or <EM>file descriptor</EM> to the - file (or files) listed in the configuration directive and places - these open file handles in the cache. When the file is requested, - the server retrieves the handle from the cache and passes it to the - sendfile() (or TransmitFile() on Windows), socket API. - </P> - <P> - Insert more details about sendfile API... - </P> - <P> - This file handle caching is done once at server start or restart, - only. So whenever one of the cached files changes on the filesystem - you <EM>have</EM> to restart the server (see the <A - HREF="../stopping.html">Stopping and Restarting</A> documentation). - To reiterate that point: if the files are modified <EM>in - place</EM> without restarting the server you may end up serving - requests that are completely bogus. You should update files by - unlinking the old copy and putting a new copy in place. Most tools - such as <CODE>rdist</CODE> and <CODE>mv</CODE> do this. - </P> - - <H2>Directives</H2> - <UL> - <LI><A HREF="#mmapfile">MMapFile</A> - </LI> - <LI><A HREF="#cachefile">CacheFile</A> - </LI> - </UL> - - <HR> - - <H2><A NAME="mmapfile">MMapFile</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename</EM> [<em>filename</em>] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server-config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_file_cache - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Only in Apache 1.3 (via - mod_mmap_statis) or later. - - <P> - The <CODE>MMapFile</CODE> directive maps one or more files (given as - whitespace separated arguments) into memory at server startup time. They - are automatically unmapped on a server shutdown. When the files have changed - on the filesystem at least a HUP or USR1 signal should be send to the server - to re-mmap them. - </P> - - <P> - Be careful with the <EM>filename</EM> arguments: They have to literally - match the filesystem path Apache's URL-to-filename translation handlers - create. We cannot compare inodes or other stuff to match paths through - symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE> - system calls which is not acceptable. This module may or may not work - with filenames rewritten by <CODE>mod_alias</CODE> or - <CODE>mod_rewrite</CODE>. - </P> - - Example: - - <PRE> + +</pre> + <br /> + <br /> + + + <p>Notice: You cannot use this for speeding up CGI programs or + other files which are served by special content handlers. It + can only be used for regular files which are usually served by + the Apache core content handler.</p> + + <p>This module is an extension of and borrows heavily from the + mod_mmap_static module in Apache 1.3.</p> + + <h2>Summary</h2> + + <p><code>mod_file_cache</code> caches a list of statically + configured files via <code>MMapFile</code> or + <code>CacheFile</code> directives in the main server + configuration.</p> + + <p>Not all platforms support both directives. For example, + Apache on Windows does not currently support the MMapStatic + directive, while other platforms, like AIX, support both. You + will receive an error message in the server error log if you + attempt to use an unsupported directive. If given an + unsupported directive, the server will start but the file will + not be cached. On platforms that support both directives, you + should experiment with both to see which works best for + you.</p> + + <h3><code>MmapFile</code> Directive</h3> + + <p>The <code>MmapFile</code> directive of + <code>mod_file_cache</code> maps a list of statically + configured files into memory through the system call + <code>mmap()</code>. This system call is available on most + modern Unix derivates, but not on all. There are sometimes + system-specific limits on the size and number of files that can + be mmap()d, experimentation is probably the easiest way to find + out.</p> + + <p>This mmap()ing is done once at server start or restart, + only. So whenever one of the mapped files changes on the + filesystem you <em>have</em> to restart the server (see the <a + href="../stopping.html">Stopping and Restarting</a> + documentation). To reiterate that point: if the files are + modified <em>in place</em> without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as <code>rdist</code> and + <code>mv</code> do this. The reason why this modules doesn't + take care of changes to the files is that this check would need + an extra <code>stat()</code> every time which is a waste and + against the intent of I/O reduction.</p> + + <h3><code>CacheFile</code> Directive</h3> + + <p>The <code>CacheFile</code> directive of + <code>mod_file_cache</code> opens an active <em>handle</em> or + <em>file descriptor</em> to the file (or files) listed in the + configuration directive and places these open file handles in + the cache. When the file is requested, the server retrieves the + handle from the cache and passes it to the sendfile() (or + TransmitFile() on Windows), socket API.</p> + + <p>Insert more details about sendfile API...</p> + + <p>This file handle caching is done once at server start or + restart, only. So whenever one of the cached files changes on + the filesystem you <em>have</em> to restart the server (see the + <a href="../stopping.html">Stopping and Restarting</a> + documentation). To reiterate that point: if the files are + modified <em>in place</em> without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as <code>rdist</code> and + <code>mv</code> do this.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#mmapfile">MMapFile</a></li> + + <li><a href="#cachefile">CacheFile</a></li> + </ul> + <hr /> + + <h2><a id="mmapfile" name="mmapfile">MMapFile</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MMapFile + <em>filename</em> [<em>filename</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server-config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_file_cache<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Only in Apache + 1.3 (via mod_mmap_statis) or later.</p> + + <p>The <code>MMapFile</code> directive maps one or more files + (given as whitespace separated arguments) into memory at server + startup time. They are automatically unmapped on a server + shutdown. When the files have changed on the filesystem at + least a HUP or USR1 signal should be send to the server to + re-mmap them.</p> + + <p>Be careful with the <em>filename</em> arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links <em>etc.</em> + because that again would cost extra <code>stat()</code> system + calls which is not acceptable. This module may or may not work + with filenames rewritten by <code>mod_alias</code> or + <code>mod_rewrite</code>.</p> + Example: +<pre> MMapFile /usr/local/apache/htdocs/index.html - </PRE> - -<hr> - - <H2><A NAME="cachefile">CacheFile</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> CacheFile <EM>filename</EM> [<em>filename</em>] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server-config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_file_cache - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Only available in Apache 2.0 or later. - - <P> - The <CODE>CacheFile</CODE> directive opens handles to one or more - files (given as whitespace separated arguments) and places these - handles into the cache at server startup time. Handles to cached - files are automatically closed on a server shutdown. When the files - have changed on the filesystem, the server should be restarted to - to re-cache them. - </P> - - <P> - Be careful with the <EM>filename</EM> arguments: They have to literally - match the filesystem path Apache's URL-to-filename translation handlers - create. We cannot compare inodes or other stuff to match paths through - symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE> - system calls which is not acceptable. This module may or may not work - with filenames rewritten by <CODE>mod_alias</CODE> or - <CODE>mod_rewrite</CODE>. - </P> - - Example: - - <PRE> + +</pre> + <hr /> + + <h2><a id="cachefile" name="cachefile">CacheFile</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CacheFile + <em>filename</em> [<em>filename</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server-config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_file_cache<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Only available + in Apache 2.0 or later.</p> + + <p>The <code>CacheFile</code> directive opens handles to one or + more files (given as whitespace separated arguments) and places + these handles into the cache at server startup time. Handles to + cached files are automatically closed on a server shutdown. + When the files have changed on the filesystem, the server + should be restarted to to re-cache them.</p> + + <p>Be careful with the <em>filename</em> arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links <em>etc.</em> + because that again would cost extra <code>stat()</code> system + calls which is not acceptable. This module may or may not work + with filenames rewritten by <code>mod_alias</code> or + <code>mod_rewrite</code>.</p> + Example: +<pre> CacheFile /usr/local/apache/htdocs/index.html - </PRE> - - <P> - <STRONG>Note</STRONG>: don't bother asking for a for a directive which - recursively caches all the files in a directory. Try this - instead... - See the <A HREF="core.html#include">Include</A> directive, and consider this command: - <PRE> + +</pre> + + <p><strong>Note</strong>: don't bother asking for a for a + directive which recursively caches all the files in a + directory. Try this instead... See the <a + href="core.html#include">Include</a> directive, and consider + this command:</p> +<pre> find /www/htdocs -type f -print \ | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf - </PRE> + +</pre> + <!--#include virtual="footer.html" --> + </body> +</html> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html index 6b7b887c1c..be2e1f80bd 100644 --- a/docs/manual/mod/mod_headers.html +++ b/docs/manual/mod/mod_headers.html @@ -1,297 +1,300 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_headers</H1> - -<p>This module provides for the customization of HTTP request and -response headers.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_headers.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> headers_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later. -RequestHeader appeared in Apache 2.0. -</P> - -<h2>Summary</h2> - -This module provides directives to control and modify HTTP -request and response headers. Headers can be merged, -replaced or removed. - -<H2>Directives</H2> -<UL> -<LI><A HREF="#requestheader">RequestHeader</A> -<LI><A HREF="#header">Header</A> -</UL> - -<H2>Order of Processing</H2> - -<p>The directives provided by mod_header can occur almost anywhere within -the server configuration. They are valid in the main server config and virtual -host sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files.</p> - -<P>The directives are processed in the following order: -<OL> -<LI>main server -<LI>virtual host -<LI><Directory> sections and .htaccess -<LI><Location> -<LI><Files> -</OL> - -<p>Order is important. These two headers have a different effect if -reversed:</p> - -<blockquote><code> -RequestHeader append MirrorID "mirror 12"<br> -RequestHeader unset MirrorID -</code></blockquote> - -<p>This way round, the MirrorID header is not set. If reversed, the -MirrorID header is set to "mirror 12".</P> - -<H2>Examples</H2> -<OL> -<LI>Copy all request headers that begin with "TS" to the response headers:</LI> -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_headers</h1> + + <p>This module provides for the customization of HTTP request + and response headers.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_headers.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + headers_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.2 and later. RequestHeader appeared in Apache 2.0.</p> + + <h2>Summary</h2> + This module provides directives to control and modify HTTP + request and response headers. Headers can be merged, replaced + or removed. + + <h2>Directives</h2> + + <ul> + <li><a href="#requestheader">RequestHeader</a></li> + + <li><a href="#header">Header</a></li> + </ul> + + <h2>Order of Processing</h2> + + <p>The directives provided by mod_header can occur almost + anywhere within the server configuration. They are valid in the + main server config and virtual host sections, inside + <Directory>, <Location> and <Files> sections, + and within .htaccess files.</p> + + <p>The directives are processed in the following order:</p> + + <ol> + <li>main server</li> + + <li>virtual host</li> + + <li><Directory> sections and .htaccess</li> + + <li><Location></li> + + <li><Files></li> + </ol> + + <p>Order is important. These two headers have a different + effect if reversed:</p> + + <blockquote> + <code>RequestHeader append MirrorID "mirror 12"<br /> + RequestHeader unset MirrorID</code> + </blockquote> + + <p>This way round, the MirrorID header is not set. If reversed, + the MirrorID header is set to "mirror 12".</p> + + <h2>Examples</h2> + + <ol> + <li>Copy all request headers that begin with "TS" to the + response headers:</li> + + <li style="list-style: none"> +<pre> Header echo ^TS* -</PRE> - -<LI>Add a header, MyHeader, to the response including a timestamp for when -the request was received and how long it took to begin serving the -request. This header can be used by the client to intuit load on -the server or in isolating bottlenecks between the client and the -server.</LI> -<PRE> +</pre> + </li> + + <li>Add a header, MyHeader, to the response including a + timestamp for when the request was received and how long it + took to begin serving the request. This header can be used by + the client to intuit load on the server or in isolating + bottlenecks between the client and the server.</li> + + <li style="list-style: none"> +<pre> Header add MyHeader "%D %t" -</PRE> -results in this header being added to the response: -<PRE> +</pre> + results in this header being added to the response: +<pre> MyHeader: D=3775428 t=991424704447256 -</PRE> -<LI>Say hello to Joe</LI> -<PRE> +</pre> + </li> + + <li>Say hello to Joe</li> + + <li style="list-style: none"> +<pre> Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request." -</PRE> -results in this header being added to the response: -<PRE> +</pre> + results in this header being added to the response: +<pre> MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request. -</PRE> - -<LI>Conditionally send MyHeader on the response if and only if header -"MyRequestHeader" is present on the request. This is useful for -constructing headers in response to some client stimulus. Note that -this example requires the services of the mod_setenvif module.</LI> -<PRE> - SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<BR> +</pre> + </li> + + <li>Conditionally send MyHeader on the response if and only + if header "MyRequestHeader" is present on the request. This + is useful for constructing headers in response to some client + stimulus. Note that this example requires the services of the + mod_setenvif module.</li> + + <li style="list-style: none"> +<pre> + SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br /> Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader -</PRE> -If the header "MyRequestHeader: value" is present on the HTTP request, the response -will contain the following header: -<PRE> +</pre> + If the header "MyRequestHeader: value" is present on the + HTTP request, the response will contain the following + header: +<pre> MyHeader: D=3775428 t=991424704447256 mytext -</PRE> -</OL> - -<HR> - -<H2><A NAME="requestheader">RequestHeader</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RequestHeader set|append|add - <EM>header</EM> <EM>value</EM><BR> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RequestHeader unset <EM>header</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, access.conf, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_header<P> - -<p>This directive can replace, merge or remove HTTP request -headers. The header is modified just before the content handler is -run, allowing incoming headers to be modified. The action it performs -is determined by the first argument. This can be one of the following -values:</p> - -<UL> -<LI><STRONG>set</STRONG><BR> - The request header is set, replacing any previous header with this name - -<LI><STRONG>append</STRONG><BR> - The request 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><STRONG>add</STRONG><BR> - The request 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><STRONG>unset</STRONG><BR> - The request header of this name is removed, if it exists. If there are - multiple headers of the same name, all will be removed. -</UL> - -<p>This argument is followed by a header name, which can include the -final colon, but it is not required. Case is ignored. For -<code>add</code>, <code>append</code> and <code>set</code> 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.</p> - -<p>The <code>RequestHeader</code> directive is processed just before -the request is run by its handler in the fixup phase. This should -allow headers generated by the browser, or by Apache input filters to -be overridden or modified.</p> - -<HR> - -<H2><A NAME="header">Header</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Header set|append|add - <EM>header</EM> <EM>value</EM> <EM>[env=[!]environment-variable]</EM><BR> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Header unset <EM>header</EM><BR> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Header echo <EM>header</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, access.conf, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_header<P> - -<p>This directive can replace, merge or remove HTTP response -headers. The header is modified just after the content handler and -output filters are run, allowing outgoing headers to be modified. The -action it performs is determined by the first argument. This can be -one of the following values:</p> - -<UL> -<LI><STRONG>set</STRONG><BR> - The response header is set, replacing any previous header with this name. - The <EM>value</EM> may be a format string. - -<LI><STRONG>append</STRONG><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><STRONG>add</STRONG><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><STRONG>unset</STRONG><BR> - The response header of this name is removed, if it exists. If there are - multiple headers of the same name, all will be removed. - -<LI><STRONG>echo</STRONG><BR> - Request headers with this name are echoed back in the response headers. - <EM>header</EM> may be a regular expression. -</UL> - -<p>This argument is followed by a <EM>header</EM> name, which can include the -final colon, but it is not required. Case is ignored for set, append, add -and unset. The <EM>header</EM> name for echo is case sensitive and may be a -regular expression.</p> - -<P>For <code>add</code>, <code>append</code> and <code>set</code> a -<EM>value</EM> is specified as the third argument. If <EM>value</EM> -contains spaces, it should be surrounded by doublequotes. -<EM>value</EM> may be a character string, a string containing format -specifiers or a combination of both. The following format specifiers -are supported in <EM>value</EM>: -<PRE> -%t: The time the request was received in Universal Coordinated Time - since the epoch (Jan. 1, 1970) measured in microseconds. The - value is preceded by "t=". +</pre> + </li> + </ol> + <hr /> + + <h2><a id="requestheader" + name="requestheader">RequestHeader</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RequestHeader + set|append|add <em>header</em> <em>value</em><br /> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RequestHeader unset + <em>header</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, access.conf, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_header + + <p>This directive can replace, merge or remove HTTP request + headers. The header is modified just before the content handler + is run, allowing incoming headers to be modified. The action it + performs is determined by the first argument. This can be one + of the following values:</p> + + <ul> + <li><strong>set</strong><br /> + The request header is set, replacing any previous header + with this name</li> + + <li><strong>append</strong><br /> + The request 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> + + <li><strong>add</strong><br /> + The request 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> + + <li><strong>unset</strong><br /> + The request header of this name is removed, if it exists. If + there are multiple headers of the same name, all will be + removed.</li> + </ul> + + <p>This argument is followed by a header name, which can + include the final colon, but it is not required. Case is + ignored. For <code>add</code>, <code>append</code> and + <code>set</code> 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.</p> + + <p>The <code>RequestHeader</code> directive is processed just + before the request is run by its handler in the fixup phase. + This should allow headers generated by the browser, or by + Apache input filters to be overridden or modified.</p> + <hr /> + + <h2><a id="header" name="header">Header</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Header set|append|add + <em>header</em> <em>value</em> + <em>[env=[!]environment-variable]</em><br /> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Header unset + <em>header</em><br /> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Header echo + <em>header</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, access.conf, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_header + + <p>This directive can replace, merge or remove HTTP response + headers. The header is modified just after the content handler + and output filters are run, allowing outgoing headers to be + modified. The action it performs is determined by the first + argument. This can be one of the following values:</p> + + <ul> + <li><strong>set</strong><br /> + The response header is set, replacing any previous header + with this name. The <em>value</em> may be a format + string.</li> + + <li><strong>append</strong><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> + + <li><strong>add</strong><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> + + <li><strong>unset</strong><br /> + The response header of this name is removed, if it exists. + If there are multiple headers of the same name, all will be + removed.</li> + + <li><strong>echo</strong><br /> + Request headers with this name are echoed back in the + response headers. <em>header</em> may be a regular + expression.</li> + </ul> + + <p>This argument is followed by a <em>header</em> name, which + can include the final colon, but it is not required. Case is + ignored for set, append, add and unset. The <em>header</em> + name for echo is case sensitive and may be a regular + expression.</p> + + <p>For <code>add</code>, <code>append</code> and + <code>set</code> a <em>value</em> is specified as the third + argument. If <em>value</em> contains spaces, it should be + surrounded by doublequotes. <em>value</em> may be a character + string, a string containing format specifiers or a combination + of both. The following format specifiers are supported in + <em>value</em>:</p> +<pre> +%t: The time the request was received in Universal Coordinated Time + since the epoch (Jan. 1, 1970) measured in microseconds. The + value is preceded by "t=". %D: The time from when the request was received to the time the headers are sent on the wire. This is a measure of the - duration of the request. The value is preceded by "D=". -</PRE> - -<p>When the <code>Header</code> directive is used with the -<code>add</code>, <code>append</code>, or <code>set</code> argument, a -fourth argument may be used to specify conditions under which the -action will be taken. If the <a href="../env.html">environment -variable</a> specified in the <code>env=...</code> argument exists (or -if the environment variable does not exist and <code>env=!...</code> -is specified) then the action specified by the <code>Header</code> -directive will take effect. Otherwise, the directive will have no -effect on the request.</p> - -<p>The Header directives are processed just before the response is -sent to the network. These means that it is possible to set and/or -override most headers, except for those headers added by the header -filter.</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> + duration of the request. The value is preceded by "D=". +</pre> + + <p>When the <code>Header</code> directive is used with the + <code>add</code>, <code>append</code>, or <code>set</code> + argument, a fourth argument may be used to specify conditions + under which the action will be taken. If the <a + href="../env.html">environment variable</a> specified in the + <code>env=...</code> argument exists (or if the environment + variable does not exist and <code>env=!...</code> is specified) + then the action specified by the <code>Header</code> directive + will take effect. Otherwise, the directive will have no effect + on the request.</p> + + <p>The Header directives are processed just before the response + is sent to the network. These means that it is possible to set + and/or override most headers, except for those headers added by + the header filter.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_imap.html b/docs/manual/mod/mod_imap.html index d8e6719feb..a3f1dc2cd2 100644 --- a/docs/manual/mod/mod_imap.html +++ b/docs/manual/mod/mod_imap.html @@ -1,349 +1,363 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_imap</H1> - -<p>This module provides for server-side imagemap processing.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_imap.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> imap_module -<BR> -<A -HREF="module-dict.html#compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later. -</P> - - - -<H2>Summary</H2> - -<p>This module processes <CODE>.map</CODE> files, thereby 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.</p> - -<p>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>Directives</H2> -<UL> -<LI><A HREF="#imapmenu">ImapMenu</A> -<LI><A HREF="#imapdefault">ImapDefault</A> -<LI><A HREF="#imapbase">ImapBase</A> -</UL> - -<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> - - -<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> - -<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/imagemap1.map"> <BR> -<IMG ISMAP SRC="/images/imagemap1.gif"> <BR> -</A> -</CODE></BLOCKQUOTE><P> - - -<hr> - -<H2><A NAME="imapmenu">ImapMenu</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ImapMenu - none|formatted|semiformatted|unformatted<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_imap<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> 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> - -<hr> - -<H2><A NAME="imapdefault">ImapDefault</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ImapDefault - error|nocontent|map|referer|<em>URL</em><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_imap<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> 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. Its 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. - -<hr> - -<H2><A NAME="imapbase">ImapBase</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ImapBase map|referer|<em>URL</em><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Indexes<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_imap<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> 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. Its 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>. - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_imap</h1> + + <p>This module provides for server-side imagemap + processing.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_imap.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + imap_module<br /> + <a href="module-dict.html#compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.1 and later.</p> + + <h2>Summary</h2> + + <p>This module processes <code>.map</code> files, thereby + 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.</p> + + <p>The following directive will activate files ending with + <code>.map</code> as imagemap files:</p> + + <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>Directives</h2> + + <ul> + <li><a href="#imapmenu">ImapMenu</a></li> + + <li><a href="#imapdefault">ImapDefault</a></li> + + <li><a href="#imapbase">ImapBase</a></li> + </ul> + + <h2>New Features</h2> + The imagemap module adds some new features that were not + possible with previously distributed imagemap programs. + + <ul> + <li>URL references relative to the Referer: information.</li> + + <li>Default <BASE> assignment through a new map + directive <code>base</code>.</li> + + <li>No need for <code>imagemap.conf</code> file.</li> + + <li>Point references.</li> + + <li>Configurable generation of imagemap menus.</li> + </ul> + <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</dt> + + <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.</dd> + + <dt><code>default</code> Directive</dt> + + <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.</dd> + + <dt><code>poly</code> Directive</dt> + + <dd>Takes three to one-hundred points, and is obeyed if the + user selected coordinates fall within the polygon defined by + these points.</dd> + + <dt><code>circle</code></dt> + + <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.</dd> + + <dt><code>rect</code> Directive</dt> + + <dd>Takes the coordinates of two opposing corners of a + rectangle. Obeyed if the point selected is within this + rectangle.</dd> + + <dt><code>point</code> Directive</dt> + + <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.</dd> + </dl> + + <h3>Values</h3> + The values for each of the directives can any of the following: + + + <dl> + <dt>a URL</dt> + + <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.</dd> + + <dt><code>map</code></dt> + + <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'.</dd> + + <dt><code>menu</code></dt> + + <dd>Synonymous with <code>map</code>.</dd> + + <dt><code>referer</code></dt> + + <dd>Equivalent to the URL of the referring document. Defaults + to <code>http://servername/</code> if no Referer: header was + present.</dd> + + <dt><code>nocontent</code></dt> + + <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>.</dd> + + <dt><code>error</code></dt> + + <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>.</dd> + </dl> + + <h3>Coordinates</h3> + + <dl> + <dt><code>0,0 200,200</code></dt> + + <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.</dd> + </dl> + + <h3>Quoted Text</h3> + + <dl> + <dt><code>"Menu Text"</code></dt> + + <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.</dd> + </dl> + + <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> + + <h2>Referencing your mapfile</h2> + + <blockquote> + <code><A HREF="/maps/imagemap1.map"><br /> + <IMG ISMAP SRC="/images/imagemap1.gif"><br /> + </A></code> + </blockquote> + <hr /> + + <h2><a id="imapmenu" name="imapmenu">ImapMenu</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ImapMenu + none|formatted|semiformatted|unformatted<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_imap<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> 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.</p> + + <dl> + <dt><code>none</code></dt> + + <dd>If ImapMenu is <code>none</code>, no menu is generated, + and the <code>default</code> action is performed.</dd> + + <dt><code>formatted</code></dt> + + <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.</dd> + + <dt><code>semiformatted</code></dt> + + <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.</dd> + + <dt><code>unformatted</code></dt> + + <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.</dd> + </dl> + <hr /> + + <h2><a id="imapdefault" name="imapdefault">ImapDefault</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ImapDefault + error|nocontent|map|referer|<em>URL</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_imap<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> 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. Its 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> + <hr /> + + <h2><a id="imapbase" name="imapbase">ImapBase</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ImapBase + map|referer|<em>URL</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Indexes<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_imap<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> 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. Its 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>. + <!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html index 7f137cf973..8d9623cb46 100644 --- a/docs/manual/mod/mod_include.html +++ b/docs/manual/mod/mod_include.html @@ -1,329 +1,396 @@ -<!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" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_include</H1> - -<p>This module provides for server-parsed html documents.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_include.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> includes_module -</P> - -<h2>Summary</h2> - -<p>This module provides a filter which will process files before they -are sent to the client. The processing is controlled by specially -formated SGML comments, referred to as <em>elements</em>. These -elements allow conditional text, the inclusion other files or -programs, as well as the setting and printing of environment -variables.</p> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#xbithack">XBitHack</A> -</UL> - -<p>See also: <a href="core.html#options">Options</a> -and <a href="core.html.html#SetOutputFilter">SetOutputFilter</a>.</p> - - -<H2>Enabling Server-Side Includes</H2> - -<p>Server Side Includes are implemented by the <code>INCLUDES</code> -<a href="../filter.html">filter</a>. 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>: -</p> - -<blockquote><code> -AddType text/html .shtml<br> -<FilesMatch "\.shtml(\..+)?$"><br> - SetOutputFilter INCLUDES<br> -</FilesMatch> -</code></blockquote> - -<p>Be careful to properly scope the INCLUDES filter to process only -the correct files. The filter is <strong>not</strong> restricted to -processing only HTML files. So, for example, if the INCLUDES filter -is activated using a <code><Directory></code> section and that -directory includes GIF files, mod_include will process the GIF files. -This can have two adverse consequences: 1. there will be extra -overhead in serving these files, and 2. these files could become -corrupted if they happen to contain something that looks like an SSI -element.</p> - -<p>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):</p> - -<blockquote><code> -Options +Includes -</code></blockquote> - -<p>For backwards compatibility, the <code>server-parsed</code> <a -href="../handler.html">handler</a> also activates the INCLUDES filter. -As well, Apache will activate the INCLUDES filter for any document -with mime type <code>text/x-server-parsed-html</code> or -<code>text/x-server-parsed-html3</code> (and the resulting output will -have the mime type <code>text/html</code>).</p> - -<p>For more information, see our <a href="../howto/ssi.html">Tutorial -on Server Side Includes</a>.</p> - -<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><a name="echo">echo</a></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. -<DT>encoding -<DD>Specifies how Apache should encode special characters contained -in the variable before outputting them. If set to "none", no encoding -will be done. If set to "url", then URL encoding (also known as -%-encoding; this is appropriate for use within URLs in links, etc.) -will be performed. At the start of an <CODE>echo</CODE> element, -the default is set to "entity", resulting in entity encoding (which -is appropriate in the context of a block-level HTML element, eg. -a paragraph of text). This can be changed by adding an -<CODE>encoding</CODE> attribute, which will remain in effect until -the next <CODE>encoding</CODE> attribute is encountered or the -element ends, whichever comes first. Note that the -<CODE>encoding</CODE> attribute must <EM>precede</EM> the corresponding -<CODE>var</CODE> attribute to be effective, and that only special -characters as defined in the ISO-8859-1 character encoding will be -encoded. This encoding process may not have the desired result if -a different character encoding is in use. -Apache 1.3.12 and above; previous versions do no encoding. - -</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. - Starting with Apache 1.3.12, special characters are entity encoded (see the - <A HREF="#echo"><CODE>echo</CODE></A> element for details) before being - output. 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> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_include</h1> + + <p>This module provides for server-parsed html documents.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_include.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + includes_module</p> + + <h2>Summary</h2> + + <p>This module provides a filter which will process files + before they are sent to the client. The processing is + controlled by specially formated SGML comments, referred to as + <em>elements</em>. These elements allow conditional text, the + inclusion other files or programs, as well as the setting and + printing of environment variables.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#xbithack">XBitHack</a></li> + </ul> + + <p>See also: <a href="core.html#options">Options</a> and <a + href="core.html.html#SetOutputFilter">SetOutputFilter</a>.</p> + + <h2>Enabling Server-Side Includes</h2> + + <p>Server Side Includes are implemented by the + <code>INCLUDES</code> <a href="../filter.html">filter</a>. 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>:</p> + + <blockquote> + <code>AddType text/html .shtml<br /> + <FilesMatch "\.shtml(\..+)?$"><br /> + SetOutputFilter INCLUDES<br /> + </FilesMatch></code> + </blockquote> + + <p>Be careful to properly scope the INCLUDES filter to process + only the correct files. The filter is <strong>not</strong> + restricted to processing only HTML files. So, for example, if + the INCLUDES filter is activated using a + <code><Directory></code> section and that directory + includes GIF files, mod_include will process the GIF files. + This can have two adverse consequences: 1. there will be extra + overhead in serving these files, and 2. these files could + become corrupted if they happen to contain something that looks + like an SSI element.</p> + + <p>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):</p> + + <blockquote> + <code>Options +Includes</code> + </blockquote> + + <p>For backwards compatibility, the <code>server-parsed</code> + <a href="../handler.html">handler</a> also activates the + INCLUDES filter. As well, Apache will activate the INCLUDES + filter for any document with mime type + <code>text/x-server-parsed-html</code> or + <code>text/x-server-parsed-html3</code> (and the resulting + output will have the mime type <code>text/html</code>).</p> + + <p>For more information, see our <a + href="../howto/ssi.html">Tutorial on Server Side + Includes</a>.</p> + + <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></dt> + + <dd> + This command controls various aspects of the parsing. The + valid attributes are: + + <dl> + <dt>errmsg</dt> + + <dd>The value is a message that is sent back to the + client if an error occurs whilst parsing the + document.</dd> + + <dt>sizefmt</dt> + + <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.</dd> + + <dt>timefmt</dt> + + <dd>The value is a string to be used by the + <code>strftime(3)</code> library routine when printing + dates.</dd> + </dl> + </dd> + + <dt><strong><a id="echo" name="echo">echo</a></strong></dt> + + <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</dt> + + <dd>The value is the name of the variable to print.</dd> + + <dt>encoding</dt> + + <dd>Specifies how Apache should encode special characters + contained in the variable before outputting them. If set + to "none", no encoding will be done. If set to "url", + then URL encoding (also known as %-encoding; this is + appropriate for use within URLs in links, etc.) will be + performed. At the start of an <code>echo</code> element, + the default is set to "entity", resulting in entity + encoding (which is appropriate in the context of a + block-level HTML element, eg. a paragraph of text). This + can be changed by adding an <code>encoding</code> + attribute, which will remain in effect until the next + <code>encoding</code> attribute is encountered or the + element ends, whichever comes first. Note that the + <code>encoding</code> attribute must <em>precede</em> the + corresponding <code>var</code> attribute to be effective, + and that only special characters as defined in the + ISO-8859-1 character encoding will be encoded. This + encoding process may not have the desired result if a + different character encoding is in use. Apache 1.3.12 and + above; previous versions do no encoding.</dd> + </dl> + </dd> + + <dt><strong>exec</strong></dt> + + <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</dt> + + <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> + + <p>If the script returns a Location: header instead of + output, then this will be translated into an HTML + anchor.</p> + + <p>The <code>include virtual</code> element should be + used in preference to <code>exec cgi</code>.</p> + </dd> + + <dt>cmd</dt> + + <dd>The server will execute the given string using + <code>/bin/sh</code>. The include variables are available + to the command.</dd> + </dl> + </dd> + + <dt><strong>fsize</strong></dt> + + <dd> + This command prints the size of the specified file, subject + to the <code>sizefmt</code> format specification. + Attributes: + + <dl> + <dt>file</dt> + + <dd>The value is a path relative to the directory + containing the current document being parsed.</dd> + + <dt>virtual</dt> + + <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.</dd> + </dl> + </dd> + + <dt><strong>flastmod</strong></dt> + + <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.</dd> + + <dt><strong>include</strong></dt> + + <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:</p> + + <dl> + <dt>file</dt> + + <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.</dd> + + <dt>virtual</dt> + + <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.</dd> + </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. + </dd> + + <dt><strong>printenv</strong></dt> + + <dd>This prints out a listing of all existing variables and + their values. Starting with Apache 1.3.12, special characters + are entity encoded (see the <a + href="#echo"><code>echo</code></a> element for details) + before being output. No attributes.</dd> + + <dd>For example: <code><!--#printenv --></code></dd> + + <dd>Apache 1.2 and above.</dd> + + <dt><strong>set</strong></dt> + + <dd> + This sets the value of a variable. Attributes: + + <dl> + <dt>var</dt> + + <dd>The name of the variable to set.</dd> + + <dt>value</dt> + + <dd>The value to give a variable.</dd> + </dl> + For example: <code><!--#set var="category" value="help" + --></code> + </dd> + + <dd>Apache 1.2 and above.</dd> + </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</dt> -<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: + <dd>The current date in Greenwich Mean Time.</dd> -<PRE> + <dt>DATE_LOCAL</dt> + + <dd>The current date in the local time zone.</dd> + + <dt>DOCUMENT_NAME</dt> + + <dd>The filename (excluding directories) of the document + requested by the user.</dd> + + <dt>DOCUMENT_URI</dt> + + <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.</dd> + + <dt>LAST_MODIFIED</dt> + + <dd>The last modification date of the document requested by + the user.</dd> + </dl> + + <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:</p> +<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:</p> +<pre> <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> -</PRE> +</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>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> -<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> + <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:</p> +<pre> <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> in foo <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> @@ -331,149 +398,152 @@ otherwise: <!--#else --> in neither <!--#endif --> -</PRE> - -<H2><A NAME="flowctrl">Flow Control Elements</A></H2> - -These are available in Apache 1.2 and above. The basic flow control -elements are: - -<PRE> - <!--#if expr="<EM>test_condition</EM>" --> - <!--#elif expr="<EM>test_condition</EM>" --> +</pre> + + <h2><a id="flowctrl" name="flowctrl">Flow Control + Elements</a></h2> + These are available in Apache 1.2 and above. The basic flow + control elements are: +<pre> + <!--#if expr="<em>test_condition</em>" --> + <!--#elif expr="<em>test_condition</em>" --> <!--#else --> <!--#endif --> -</PRE> - -<P> The <STRONG><CODE>if</CODE></STRONG> 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 <STRONG><CODE>elif</CODE></STRONG>, <STRONG><CODE>else</CODE></STRONG>. - or <STRONG><CODE>endif</CODE></STRONG> element is included in the - output stream. - -<P> The <STRONG><CODE>elif</CODE></STRONG> or <STRONG><CODE>else</CODE></STRONG> - statements are be used the put text into the output stream - if the original test_condition was false. These elements - are optional. - -<P> The <STRONG><CODE>endif</CODE></STRONG> element ends the - <STRONG><CODE>if</CODE></STRONG> element and is required. - -<P> <EM>test_condition</EM> is one of the following: - -<DL> - -<DT><EM>string</EM><DD>true if <EM>string</EM> is not empty - -<DT><EM>string1</EM> = <EM>string2</EM> - <BR> - <EM>string1</EM> != <EM>string2</EM> - <BR> - <EM>string1</EM> < <EM>string2</EM> - <BR> - <EM>string1</EM> <= <EM>string2</EM> - <BR> - <EM>string1</EM> > <EM>string2</EM> - <BR> - <EM>string1</EM> >= <EM>string2</EM> - -<DD>Compare string1 with string 2. If string2 has the form <EM>/string/</EM> - then it is compared as a regular expression. - Regular expressions have the same syntax as those found in the - Unix <SAMP>egrep</SAMP> command. - -<DT>( <EM>test_condition</EM> ) - <DD>true if <EM>test_condition</EM> is true -<DT>! <EM>test_condition</EM> - <DD>true if <EM>test_condition</EM> is false -<DT><EM>test_condition1</EM> && <EM>test_condition2</EM> - <DD>true if both <EM>test_condition1</EM> and - <EM>test_condition2</EM> are true -<DT><EM>test_condition1</EM> || <EM>test_condition2</EM> - <DD>true if either <EM>test_condition1</EM> or - <EM>test_condition2</EM> is true -</DL> - -<P> "<EM>=</EM>" and "<EM>!=</EM>" bind more tightly than "<EM>&&</EM>" and - "<EM>||</EM>". - "<EM>!</EM>" 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: <EM>'string'</EM>. - 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> - <EM>string1 string2</EM> results in <EM>string1 string2</EM> - <EM>'string1 string2'</EM> results in <EM>string1 string2</EM> -</PRE> - -<H2>Using Server Side Includes for ErrorDocuments</H2> - -There is <A HREF="../misc/custom_errordocs.html">a document</A> which -describes how to use the features of mod_include to offer internationalized -customized server error documents. -<P> - -<HR> - -<H2><A NAME="xbithack">XBitHack</A> directive</H2> -<!--%plaintext <?INDEX {\tt XBitHack} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> XBitHack on|off|full<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>XBitHack off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> Options<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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>. XBitHack can take on 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><STRONG>Note:</STRONG> 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> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + + <p>The <strong><code>if</code></strong> 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 <strong><code>elif</code></strong>, + <strong><code>else</code></strong>. or + <strong><code>endif</code></strong> element is included in the + output stream.</p> + + <p>The <strong><code>elif</code></strong> or + <strong><code>else</code></strong> statements are be used the + put text into the output stream if the original test_condition + was false. These elements are optional.</p> + + <p>The <strong><code>endif</code></strong> element ends the + <strong><code>if</code></strong> element and is required.</p> + + <p><em>test_condition</em> is one of the following:</p> + + <dl> + <dt><em>string</em></dt> + + <dd>true if <em>string</em> is not empty</dd> + + <dt><em>string1</em> = <em>string2</em><br /> + <em>string1</em> != <em>string2</em><br /> + <em>string1</em> < <em>string2</em><br /> + <em>string1</em> <= <em>string2</em><br /> + <em>string1</em> > <em>string2</em><br /> + <em>string1</em> >= <em>string2</em></dt> + + <dd>Compare string1 with string 2. If string2 has the form + <em>/string/</em> then it is compared as a regular + expression. Regular expressions have the same syntax as those + found in the Unix <samp>egrep</samp> command.</dd> + + <dt>( <em>test_condition</em> )</dt> + + <dd>true if <em>test_condition</em> is true</dd> + + <dt>! <em>test_condition</em></dt> + + <dd>true if <em>test_condition</em> is false</dd> + + <dt><em>test_condition1</em> && + <em>test_condition2</em></dt> + + <dd>true if both <em>test_condition1</em> and + <em>test_condition2</em> are true</dd> + + <dt><em>test_condition1</em> || <em>test_condition2</em></dt> + + <dd>true if either <em>test_condition1</em> or + <em>test_condition2</em> is true</dd> + </dl> + + <p>"<em>=</em>" and "<em>!=</em>" bind more tightly than + "<em>&&</em>" and "<em>||</em>". "<em>!</em>" binds + most tightly. Thus, the following are equivalent:</p> +<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: + <em>'string'</em>. 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,</p> +<pre> + <em>string1 string2</em> results in <em>string1 string2</em> + <em>'string1 string2'</em> results in <em>string1 string2</em> +</pre> + + <h2>Using Server Side Includes for ErrorDocuments</h2> + There is <a href="../misc/custom_errordocs.html">a document</a> + which describes how to use the features of mod_include to offer + internationalized customized server error documents. + <hr /> + + <h2><a id="xbithack" name="xbithack">XBitHack</a> + directive</h2> + <!--%plaintext <?INDEX {\tt XBitHack} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> XBitHack + on|off|full<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>XBitHack + off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Options<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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>. XBitHack can take on + the following values:</p> + + <dl> + <dt>off</dt> + + <dd>No special treatment of executable files.</dd> + + <dt>on</dt> + + <dd>Any file that has the user-execute bit set will be + treated as a server-parsed html document.</dd> + + <dt>full</dt> + + <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><strong>Note:</strong> 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).</p> + </dd> + </dl> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mod_info.html b/docs/manual/mod/mod_info.html index 610bcee45d..4aac4425f1 100644 --- a/docs/manual/mod/mod_info.html +++ b/docs/manual/mod/mod_info.html @@ -1,127 +1,103 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_info</H1> - -<p>This module provides a comprehensive overview of the server -configuration including all installed modules and directives in the -configuration files.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_info.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> info_module -<BR> -<A -HREF="module-dict.html#compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later. -</P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#addmoduleinfo">AddModuleInfo</A> -</UL> - -<h2>Using mod_info</h2> - -<P> -To configure it, add the following to your <CODE>httpd.conf</CODE> file. - -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_info</h1> + + <p>This module provides a comprehensive overview of the server + configuration including all installed modules and directives in + the configuration files.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_info.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + info_module<br /> + <a href="module-dict.html#compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.1 and later.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#addmoduleinfo">AddModuleInfo</a></li> + </ul> + + <h2>Using mod_info</h2> + + <p>To configure it, add the following to your + <code>httpd.conf</code> file.</p> +<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> - -<H2><A NAME="addmoduleinfo">AddModuleInfo</A></H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AddModuleInfo <EM>module-name string</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_info<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above<P> - -This allows the content of <EM>string</EM> to be shown as -HTML interpreted, -<STRONG>Additional Information</STRONG> for the module <EM>module-name</EM>. -Example: -<BLOCKQUOTE> -<PRE> +</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.</strong> + + <p><strong>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.</strong></p> + </blockquote> + <hr /> + + <h2><a id="addmoduleinfo" + name="addmoduleinfo">AddModuleInfo</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AddModuleInfo + <em>module-name string</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_info<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3 and + above + + <p>This allows the content of <em>string</em> to be shown as + HTML interpreted, <strong>Additional Information</strong> for + the module <em>module-name</em>. Example:</p> + + <blockquote> +<pre> AddModuleInfo mod_auth.c 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>' -</PRE> -</BLOCKQUOTE> +</pre> + </blockquote> + <!--#include virtual="footer.html" --> + </body> +</html> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_isapi.html b/docs/manual/mod/mod_isapi.html index a44fb4cdcd..a8d55a5b66 100644 --- a/docs/manual/mod/mod_isapi.html +++ b/docs/manual/mod/mod_isapi.html @@ -1,376 +1,365 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_isapi</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Module mod_isapi</H1> - -<P>This module supports ISAPI Extensions within Apache for Windows.</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_isapi.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> isapi_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> WIN32 only -</P> - -<H2>Summary</H2> - -<P>This module implements the Internet Server extension API. It allows - Internet Server extensions (<EM>e.g.</EM> ISAPI .dll modules) to be - served by Apache for Windows, subject to the noted restrictions.</P> - -<P>ISAPI extension modules (.dll files) are written by third parties. The - Apache Group does not author these modules, so we provide no support for - them. Please contact the ISAPI's author directly if you are experiencing - problems running their ISAPI extention. <STRONG>Please <EM>do not</EM> - post such problems to Apache's lists or bug reporting pages.</STRONG></P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#isapifilecache">ISAPIFileCache</A> -<LI><A HREF="#isapireadaheadbuffer">ISAPIReadAheadBuffer</A> -<LI><A HREF="#isapilognotsupported">ISAPILogNotSupported</A> -<LI><A HREF="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</A> -<LI><A HREF="#isapiappendlogtoquery">ISAPIAppendLogToQuery</A> -</UL> - -<H2>Usage</H2> - -<P>In the server configuration file, use the AddHandler directive to - associate ISAPI files with the <CODE>isapi-isa</CODE> handler, and map - it to the with their file extensions. To enable any .dll file to be - processed as an ISAPI extention, edit the httpd.conf file and add the - following line:</P> - -<PRE> - AddHandler isapi-isa .dll -</PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_isapi</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_isapi</h1> + + <p>This module supports ISAPI Extensions within Apache for + Windows.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_isapi.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + isapi_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> WIN32 only</p> + + <h2>Summary</h2> + + <p>This module implements the Internet Server extension API. It + allows Internet Server extensions (<em>e.g.</em> ISAPI .dll + modules) to be served by Apache for Windows, subject to the + noted restrictions.</p> + + <p>ISAPI extension modules (.dll files) are written by third + parties. The Apache Group does not author these modules, so we + provide no support for them. Please contact the ISAPI's author + directly if you are experiencing problems running their ISAPI + extention. <strong>Please <em>do not</em> post such problems to + Apache's lists or bug reporting pages.</strong></p> + + <h2>Directives</h2> -<P>There is no capability within the Apache server to leave a requested - module loaded. However, you may preload and keep a specific module loaded - by using the following syntax in your httpd.conf: + <ul> + <li><a href="#isapifilecache">ISAPIFileCache</a></li> -<PRE> + <li><a + href="#isapireadaheadbuffer">ISAPIReadAheadBuffer</a></li> + + <li><a + href="#isapilognotsupported">ISAPILogNotSupported</a></li> + + <li><a + href="#isapiappendlogtoerrors">ISAPIAppendLogToErrors</a></li> + + <li><a + href="#isapiappendlogtoquery">ISAPIAppendLogToQuery</a></li> + </ul> + + <h2>Usage</h2> + + <p>In the server configuration file, use the AddHandler + directive to associate ISAPI files with the + <code>isapi-isa</code> handler, and map it to the with their + file extensions. To enable any .dll file to be processed as an + ISAPI extention, edit the httpd.conf file and add the following + line:</p> +<pre> + AddHandler isapi-isa .dll +</pre> + + <p>There is no capability within the Apache server to leave a + requested module loaded. However, you may preload and keep a + specific module loaded by using the following syntax in your + httpd.conf:</p> +<pre> ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll -</PRE> - -<P>Whether or not you have preloaded an ISAPI extension, all ISAPI - extensions are governed by the same permissions and restrictions - as CGI scripts. That is, <CODE>Options ExecCGI</CODE> must be set for - the directory that contains the ISAPI .dll file.</P> - -<P>Review the <A HREF="#notes">Additional Notes</A> and the - <A HREF="#journal">Programmer's Journal</A> for additional details and - clarification of the specific ISAPI support offered by mod_isapi.</P> - -<H2><A NAME="notes">Additional Notes</A></H2> - -<P>Apache's ISAPI implementation conforms to all of the ISAPI 2.0 - specification, except for some "Microsoft-specific" extensions dealing - with asynchronous I/O. Apache's I/O model does not allow asynchronous - reading and writing in a manner that the ISAPI could access. If an ISA - tries to access unsupported features, including async I/O, a message is - placed in the error log to help with debugging. Since these messages - can become a flood, the directive <CODE>ISAPILogNotSupported Off</CODE> - exists to quiet this noise.</P> - -<P>Some servers, like Microsoft IIS, load the ISAPI extension into the server - and keep it loaded until memory usage is too high, or unless configuration - options are specified. Apache currently loads and unloads the ISAPI - extension each time it is requested, unless the ISAPICacheFile directive - is specified. This is inefficient, but Apache's memory model makes this - the most effective method. Many ISAPI modules are subtly incompatible - with the Apache server, and unloading these modules helps to ensure the - stability of the server.</P> - -<P>Also, remember that while Apache supports ISAPI Extensions, it - <STRONG>does not support ISAPI Filters.</STRONG> Support for filters may - be added at a later date, but no support is planned at this time.</P> - -<H2><A NAME="journal">Programmer's Journal</A></H2> - -<P>If you are programming Apache 2.0 mod_isapi modules, you must limit your - calls to ServerSupportFunction to the following directives:</P> - -<DL> - <DT>HSE_REQ_SEND_URL_REDIRECT_RESP - <DD>Redirect the user to another location.<BR> - This must be a fully qualified URL (e.g. http://server/location). - <DT>HSE_REQ_SEND_URL - <DD>Redirect the user to another location.<BR> - This cannot be a fully qualified URL, you are not allowed - to pass the protocol or a server name (e.g. simply /location).<BR> - This redirection is handled by the server, not the browser.<BR> - <STRONG>Warning:</STRONG> in their recent documentation, Microsoft - appears to have abandoned the distinction between the two - HSE_REQ_SEND_URL functions. Apache continues to treat them as two - distinct functions with different requirements and behaviors. - <DT>HSE_REQ_SEND_RESPONSE_HEADER - <DD>Apache accepts a response body following the header if it follows - the blank line (two consecutive newlines) in the headers string - argument. This body cannot contain NULLs, since the headers - argument is NULL terminated. - <DT>HSE_REQ_DONE_WITH_SESSION - <DD>Apache considers this a no-op, since the session will be finished - when the ISAPI returns from processing. - <DT>HSE_REQ_MAP_URL_TO_PATH - <DD>Apache will translate a virtual name to a physical name. - <DT>HSE_APPEND_LOG_PARAMETER - <DD>This logged message may be captured in any of the following logs: - <UL> - <LI>in the \"%{isapi-parameter}n\" component in a CustomLog directive - <LI>in the %q log component with the ISAPIAppendLogToQuery On directive - <LI>in the error log with the ISAPIAppendLogToErrors On directive - </UL> - The first option, the %{isapi-parameter}n component, is always available - and prefered. - <DT>HSE_REQ_IS_KEEP_CONN - <DD>Will return the negotiated Keep-Alive status. - <DT>HSE_REQ_SEND_RESPONSE_HEADER_EX - <DD>Will behave as documented, although the fKeepConn flag is ignored. - <DT>HSE_REQ_IS_CONNECTED - <DD>Will report false if the request has been aborted. -</DL> - -<P>Apache returns FALSE to any unsupported call to ServerSupportFunction, and - sets the GetLastError value to ERROR_INVALID_PARAMETER.</P> - -<P>ReadClient retrieves the request body exceeding the initial buffer - (defined by ISAPIReadAheadBuffer). Based on the ISAPIReadAheadBuffer - setting (number of bytes to buffer prior to calling the ISAPI handler) - shorter requests are sent complete to the extension when it is invoked. - If the request is longer, the ISAPI extension must use ReadClient to - retrieve the remaining request body.</P> - -<P>WriteClient is supported, but only with the HSE_IO_SYNC flag or - no option flag (value of 0). Any other WriteClient request will - be rejected with a return value of FALSE, and a GetLastError - value of ERROR_INVALID_PARAMETER.</P> - -<P>GetServerVariable is supported, although extended server variables do not - exist (as defined by other servers.) All the usual Apache CGI environment - variables are available from GetServerVariable, as well as the ALL_HTTP - and ALL_RAW values.</P> - -<P>Apache 2.0 mod_isapi supports additional features introduced in later - versions of the ISAPI specification, as well as limited emulation of - async I/O and the TransmitFile semantics. Apache also supports preloading - ISAPI .dlls for performance, neither of which were not available under - Apache 1.3 mod_isapi.</P> - -<HR> - -<H2><A NAME="isapifilecache">ISAPIFileCache directive</A></H2> -<!--%plaintext <?INDEX {\tt ISAPIFileCache} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ISAPIFileCache <EM>file</em> [<em>file</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_isapi<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 2.0 and later, Win32 only<P> - - Specifies a space-separated list of file names to be loaded - when the Apache server is launched, and remain loaded until - the server is shut down. This directive may be repeated - for every ISAPI .dll file desired. The full path name of - each file should be specified. - <P> -<HR> - -<H2><A NAME="isapireadaheadbuffer">ISAPIReadAheadBuffer directive</A></H2> -<!--%plaintext <?INDEX {\tt ISAPIReadAheadBuffer} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ISAPIReadAheadBuffer <EM>size</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> 49152<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_isapi<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P> - - - Defines the maximum size of the Read Ahead Buffer sent to - ISAPI extensions when they are initially invoked. All - remaining data must be retrieved using the ReadClient - callback; some ISAPI extensions may not support the - ReadClient function. Refer questions to the ISAPI extension's - author. - <P> -<HR> - -<H2><A NAME="isapilognotsupported">ISAPILogNotSupported directive</A></H2> -<!--%plaintext <?INDEX {\tt ISAPILogNotSupported} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ISAPILogNotSupported on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> on<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_isapi<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P> - - Logs all requests for unsupported features from ISAPI extensions - in the server error log. While this should be turned off once - all desired ISAPI modules are functioning, it defaults to on - to help administrators track down problems. - <P> -<HR> - -<H2><A NAME="isapiappendlogtoerrors">ISAPIAppendLogToErrors directive</A></H2> -<!--%plaintext <?INDEX {\tt ISAPIAppendLogToErrors} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToErrors on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> off<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_isapi<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P> - - Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions - to the server error log. - <P> -<HR> - -<H2><A NAME="isapiappendlogtoquery">ISAPIAppendLogToQuery directive</A></H2> -<!--%plaintext <?INDEX {\tt ISAPIAppendLogToQuery} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ISAPIAppendLogToQuery on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> off<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_isapi<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.13 and later, Win32 only<P> - - Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions - to the query field (appended to the CustomLog %q component). - <P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + + <p>Whether or not you have preloaded an ISAPI extension, all + ISAPI extensions are governed by the same permissions and + restrictions as CGI scripts. That is, <code>Options + ExecCGI</code> must be set for the directory that contains the + ISAPI .dll file.</p> + + <p>Review the <a href="#notes">Additional Notes</a> and the <a + href="#journal">Programmer's Journal</a> for additional details + and clarification of the specific ISAPI support offered by + mod_isapi.</p> + + <h2><a id="notes" name="notes">Additional Notes</a></h2> + + <p>Apache's ISAPI implementation conforms to all of the ISAPI + 2.0 specification, except for some "Microsoft-specific" + extensions dealing with asynchronous I/O. Apache's I/O model + does not allow asynchronous reading and writing in a manner + that the ISAPI could access. If an ISA tries to access + unsupported features, including async I/O, a message is placed + in the error log to help with debugging. Since these messages + can become a flood, the directive <code>ISAPILogNotSupported + Off</code> exists to quiet this noise.</p> + + <p>Some servers, like Microsoft IIS, load the ISAPI extension + into the server and keep it loaded until memory usage is too + high, or unless configuration options are specified. Apache + currently loads and unloads the ISAPI extension each time it is + requested, unless the ISAPICacheFile directive is specified. + This is inefficient, but Apache's memory model makes this the + most effective method. Many ISAPI modules are subtly + incompatible with the Apache server, and unloading these + modules helps to ensure the stability of the server.</p> + + <p>Also, remember that while Apache supports ISAPI Extensions, + it <strong>does not support ISAPI Filters.</strong> Support for + filters may be added at a later date, but no support is planned + at this time.</p> + + <h2><a id="journal" name="journal">Programmer's + Journal</a></h2> + + <p>If you are programming Apache 2.0 mod_isapi modules, you + must limit your calls to ServerSupportFunction to the following + directives:</p> + + <dl> + <dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt> + + <dd>Redirect the user to another location.<br /> + This must be a fully qualified URL (e.g. + http://server/location).</dd> + + <dt>HSE_REQ_SEND_URL</dt> + + <dd>Redirect the user to another location.<br /> + This cannot be a fully qualified URL, you are not allowed to + pass the protocol or a server name (e.g. simply + /location).<br /> + This redirection is handled by the server, not the + browser.<br /> + <strong>Warning:</strong> in their recent documentation, + Microsoft appears to have abandoned the distinction between + the two HSE_REQ_SEND_URL functions. Apache continues to treat + them as two distinct functions with different requirements + and behaviors.</dd> + + <dt>HSE_REQ_SEND_RESPONSE_HEADER</dt> + + <dd>Apache accepts a response body following the header if it + follows the blank line (two consecutive newlines) in the + headers string argument. This body cannot contain NULLs, + since the headers argument is NULL terminated.</dd> + + <dt>HSE_REQ_DONE_WITH_SESSION</dt> + + <dd>Apache considers this a no-op, since the session will be + finished when the ISAPI returns from processing.</dd> + + <dt>HSE_REQ_MAP_URL_TO_PATH</dt> + + <dd>Apache will translate a virtual name to a physical + name.</dd> + + <dt>HSE_APPEND_LOG_PARAMETER</dt> + + <dd> + This logged message may be captured in any of the following + logs: + + <ul> + <li>in the \"%{isapi-parameter}n\" component in a + CustomLog directive</li> + + <li>in the %q log component with the + ISAPIAppendLogToQuery On directive</li> + + <li>in the error log with the ISAPIAppendLogToErrors On + directive</li> + </ul> + The first option, the %{isapi-parameter}n component, is + always available and prefered. + </dd> + + <dt>HSE_REQ_IS_KEEP_CONN</dt> + + <dd>Will return the negotiated Keep-Alive status.</dd> + + <dt>HSE_REQ_SEND_RESPONSE_HEADER_EX</dt> + + <dd>Will behave as documented, although the fKeepConn flag is + ignored.</dd> + + <dt>HSE_REQ_IS_CONNECTED</dt> + + <dd>Will report false if the request has been aborted.</dd> + </dl> + + <p>Apache returns FALSE to any unsupported call to + ServerSupportFunction, and sets the GetLastError value to + ERROR_INVALID_PARAMETER.</p> + + <p>ReadClient retrieves the request body exceeding the initial + buffer (defined by ISAPIReadAheadBuffer). Based on the + ISAPIReadAheadBuffer setting (number of bytes to buffer prior + to calling the ISAPI handler) shorter requests are sent + complete to the extension when it is invoked. If the request is + longer, the ISAPI extension must use ReadClient to retrieve the + remaining request body.</p> + + <p>WriteClient is supported, but only with the HSE_IO_SYNC flag + or no option flag (value of 0). Any other WriteClient request + will be rejected with a return value of FALSE, and a + GetLastError value of ERROR_INVALID_PARAMETER.</p> + + <p>GetServerVariable is supported, although extended server + variables do not exist (as defined by other servers.) All the + usual Apache CGI environment variables are available from + GetServerVariable, as well as the ALL_HTTP and ALL_RAW + values.</p> + + <p>Apache 2.0 mod_isapi supports additional features introduced + in later versions of the ISAPI specification, as well as + limited emulation of async I/O and the TransmitFile semantics. + Apache also supports preloading ISAPI .dlls for performance, + neither of which were not available under Apache 1.3 + mod_isapi.</p> + <hr /> + + <h2><a id="isapifilecache" name="isapifilecache">ISAPIFileCache + directive</a></h2> + <!--%plaintext <?INDEX {\tt ISAPIFileCache} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ISAPIFileCache + <em>file</em> [<em>file</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> None<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_isapi<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 2.0 and + later, Win32 only + + <p>Specifies a space-separated list of file names to be loaded + when the Apache server is launched, and remain loaded until the + server is shut down. This directive may be repeated for every + ISAPI .dll file desired. The full path name of each file should + be specified.</p> + <hr /> + + <h2><a id="isapireadaheadbuffer" + name="isapireadaheadbuffer">ISAPIReadAheadBuffer + directive</a></h2> + <!--%plaintext <?INDEX {\tt ISAPIReadAheadBuffer} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ISAPIReadAheadBuffer + <em>size</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> 49152<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> None<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_isapi<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13 + and later, Win32 only + + <p>Defines the maximum size of the Read Ahead Buffer sent to + ISAPI extensions when they are initially invoked. All remaining + data must be retrieved using the ReadClient callback; some + ISAPI extensions may not support the ReadClient function. Refer + questions to the ISAPI extension's author.</p> + <hr /> + + <h2><a id="isapilognotsupported" + name="isapilognotsupported">ISAPILogNotSupported + directive</a></h2> + <!--%plaintext <?INDEX {\tt ISAPILogNotSupported} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ISAPILogNotSupported + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> on<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> None<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_isapi<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13 + and later, Win32 only + + <p>Logs all requests for unsupported features from ISAPI + extensions in the server error log. While this should be turned + off once all desired ISAPI modules are functioning, it defaults + to on to help administrators track down problems.</p> + <hr /> + + <h2><a id="isapiappendlogtoerrors" + name="isapiappendlogtoerrors">ISAPIAppendLogToErrors + directive</a></h2> + <!--%plaintext <?INDEX {\tt ISAPIAppendLogToErrors} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ISAPIAppendLogToErrors + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> off<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> None<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_isapi<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13 + and later, Win32 only + + <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI + extensions to the server error log.</p> + <hr /> + + <h2><a id="isapiappendlogtoquery" + name="isapiappendlogtoquery">ISAPIAppendLogToQuery + directive</a></h2> + <!--%plaintext <?INDEX {\tt ISAPIAppendLogToQuery} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ISAPIAppendLogToQuery + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> off<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> None<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_isapi<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.13 + and later, Win32 only + + <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI + extensions to the query field (appended to the CustomLog %q + component).</p> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html index 78c2c53b29..43df3a461e 100644 --- a/docs/manual/mod/mod_log_config.html +++ b/docs/manual/mod/mod_log_config.html @@ -1,105 +1,100 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_log_config</H1> -<P> -This module provides for logging of the requests made to -the server, using the Common Log Format or a user-specified format. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_log_config.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> config_log_module -</P> - - -<H2>Summary</H2> - -<p>This module provides for flexible logging of client requests. Logs -are written in a customizable format, and may be written directly to a -file, or to an external program. Conditional logging is provided so -that individual requests may be included or excluded from the logs -based on characteristics of the request.</p> - -<P> -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 step. -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> - -<p>See also: <a href="../logs.html">Apache Log Files</a>.</p> - -<H2>Directives</H2> - -<UL> -<LI><A HREF="#cookielog">CookieLog</A></LI> -<LI><A HREF="#customlog">CustomLog</A></LI> -<LI><A HREF="#logformat">LogFormat</A></LI> -<LI><A HREF="#transferlog">TransferLog</A></LI> -</UL> - -<H2><A NAME="formats">Custom Log Formats</A></H2> - -<p>The format argument to the <CODE>LogFormat</CODE> and -<CODE>CustomLog</CODE> directives 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 the c-type control characters "\n" and -"\t" to represent new-lines and tabs. Literal quotes and back-slashes -should be escaped with back-slashes.</p> - -<p>The characteristics of the request itself are logged by placing -"%" directives in the format string, which are replaced in the log file -by the values as follows:</p> - -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_log_config</h1> + + <p>This module provides for logging of the requests made to the + server, using the Common Log Format or a user-specified + format.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_log_config.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + config_log_module</p> + + <h2>Summary</h2> + + <p>This module provides for flexible logging of client + requests. Logs are written in a customizable format, and may be + written directly to a file, or to an external program. + Conditional logging is provided so that individual requests may + be included or excluded from the logs based on characteristics + of the request.</p> + + <p>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 + step. 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> + + <p>See also: <a href="../logs.html">Apache Log Files</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#cookielog">CookieLog</a></li> + + <li><a href="#customlog">CustomLog</a></li> + + <li><a href="#logformat">LogFormat</a></li> + + <li><a href="#transferlog">TransferLog</a></li> + </ul> + + <h2><a id="formats" name="formats">Custom Log Formats</a></h2> + + <p>The format argument to the <code>LogFormat</code> and + <code>CustomLog</code> directives 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 the c-type control + characters "\n" and "\t" to represent new-lines and tabs. + Literal quotes and back-slashes should be escaped with + back-slashes.</p> + + <p>The characteristics of the request itself are logged by + placing "%" directives in the format string, which are replaced + in the log file by the values as follows:</p> +<pre> %...a: Remote IP-address %...A: Local IP-address %...B: Bytes sent, excluding HTTP headers. %...b: Bytes sent, excluding HTTP headers. In CLF format - i.e. a '-' rather than a 0 when no bytes are sent. -%...{Foobar}C: The contents of cookie "Foobar" in the request sent to the + i.e. a '-' rather than a 0 when no bytes are sent. +%...{Foobar}C: The contents of cookie "Foobar" in the request sent to the server. %...D: The time taken to serve the request, in microseconds. %...{FOOBAR}e: The contents of the environment variable FOOBAR %...f: Filename %...h: Remote host -%...H The request protocol +%...H The request protocol %...{Foobar}i: The contents of Foobar: header line(s) in the request sent to the server. %...l: Remote logname (from identd, if supplied) -%...m The request method +%...m The request method %...{Foobar}n: The contents of note "Foobar" from another module. %...{Foobar}o: The contents of Foobar: header line(s) in the reply. %...p: The canonical Port of the server serving the request %...P: The process ID of the child that serviced the request. -%...q The query string (prepended with a ? if a query string exists, - otherwise an empty string) +%...q The query string (prepended with a ? if a query string exists, + otherwise an empty string) %...r: First line of request %...s: Status. For requests that got internally redirected, this is the status of the *original* request --- %...>s for the last. @@ -117,272 +112,254 @@ by the values as follows:</p> '-' = connection will be closed after the response is sent. (This directive was %...c in late versions of Apache 1.3, but this conflicted with the historical ssl %...{var}c syntax.) -</PRE> - -<p>The "..." can be nothing at all (<EM>e.g.</EM>, <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). 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 <STRONG>not</STRONG> return some sort of normal -status.</p> - -<p>Note that there is no escaping performed on the strings from -%...r, %...i and %...o. This is mainly to comply with the requirements -of the Common Log Format. This implies that clients can insert -control characters into the log, so care should be taken when dealing -with raw log files.</p> - -<p>Some commonly used log format strings are:</p> - -<dl> -<dt>Common Log Format (CLF)</dt> -<dd><CODE>"%h %l %u %t \"%r\" %>s %b"</CODE></dd> - -<dt>Common Log Format with Virtual Host</dt> -<dd><code>"%v %h %l %u %t \"%r\" %>s %b"</CODE></dd> - -<dt>NCSA extended/combined log format</dt> -<dd> <CODE>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""</CODE></dd> - -<dt>Referer log format</dt> -<dd><code>"%{Referer}i -> %U"</code></dd> - -<dt>Agent (Browser) log format</dt> -<dd><code>"%{User-agent}i"</code></dd> -</dl> - -<P>Note that the canonical <A -HREF="core.html#servername">ServerName</A> and <A -HREF="core.html#port">Port</A> of the server serving the request are -used for <CODE>%v</CODE> and <CODE>%p</CODE> respectively. This -happens regardless of the <A -HREF="core.html#usecanonicalname">UseCanonicalName</A> setting because -otherwise log analysis programs would have to duplicate the entire -vhost matching algorithm in order to decide what host really served -the request.</p> - -<H2>Security Considerations</H2> - -<p>See the <A HREF="../misc/security_tips.html#serverroot">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> - - -<H2><A NAME="cookielog">CookieLog</A> directive</H2> -<!--%plaintext <?INDEX {\tt CookieLog} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieLog <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_cookies<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.2 and above</p> - -<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 mod_cookies, and is deprecated.</p> - -<HR> -<H2><A NAME="customlog">CustomLog</A> -<a NAME="customlogconditional">directive</a></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CustomLog <EM>file</em>|<em>pipe</EM> - <EM>format</em>|<em>nickname</EM> [env=[!]<EM>environment-variable</EM>]<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3 - or later. Conditional logging available in 1.3.5 or later. -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config</p> - -<p>The <code>CustomLog</code> directive is used to log requests -to the server. A log format is specified, and the logging can -optionally be made conditional on request characteristics -using environment variables.</p> - -<P>The first argument, which specifies the location to which the -logs will be written, can take on one of the following two -types of values:</p> - -<dl> -<dt><em>file</em> -<dd>A filename, relative to the -<a href="core.html#serverroot">ServerRoot</a>.</dd> - -<dt><em>pipe</em> -<dd>The pipe character "<code>|</code>", followed by the path to a -program to receive the log information on its standard input. -<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.</dd> -</dl> - -<P>The second argument specifies what will be written to the -log file. It can specify either a <em>nickname</em> -defined by a previous <a href="#logformat">LogFormat</a> -directive, or it can be an explicit <em>format</em> string -as described in the <a href="#formats">log formats</a> section.</p> - -<p>For example, the following two sets of directives have exactly -the same effect:</p> +</pre> + <p>The "..." can be nothing at all (<em>e.g.</em>, <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). 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 <strong>not</strong> return some sort of normal status.</p> + + <p>Note that there is no escaping performed on the strings from + %...r, %...i and %...o. This is mainly to comply with the + requirements of the Common Log Format. This implies that + clients can insert control characters into the log, so care + should be taken when dealing with raw log files.</p> + + <p>Some commonly used log format strings are:</p> + + <dl> + <dt>Common Log Format (CLF)</dt> + + <dd><code>"%h %l %u %t \"%r\" %>s %b"</code></dd> + + <dt>Common Log Format with Virtual Host</dt> + + <dd><code>"%v %h %l %u %t \"%r\" %>s %b"</code></dd> + + <dt>NCSA extended/combined log format</dt> + + <dd><code>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\""</code></dd> + + <dt>Referer log format</dt> + + <dd><code>"%{Referer}i -> %U"</code></dd> + + <dt>Agent (Browser) log format</dt> + + <dd><code>"%{User-agent}i"</code></dd> + </dl> + + <p>Note that the canonical <a + href="core.html#servername">ServerName</a> and <a + href="core.html#port">Port</a> of the server serving the + request are used for <code>%v</code> and <code>%p</code> + respectively. This happens regardless of the <a + href="core.html#usecanonicalname">UseCanonicalName</a> setting + because otherwise log analysis programs would have to duplicate + the entire vhost matching algorithm in order to decide what + host really served the request.</p> + + <h2>Security Considerations</h2> + + <p>See the <a + href="../misc/security_tips.html#serverroot">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 /> + + <h2><a id="cookielog" name="cookielog">CookieLog</a> + directive</h2> + <!--%plaintext <?INDEX {\tt CookieLog} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CookieLog + <em>filename</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_cookies<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Only available + in Apache 1.2 and above</p> + + <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 mod_cookies, and is + deprecated.</p> + <hr /> + + <h2><a id="customlog" name="customlog">CustomLog</a> <a + id="customlogconditional" + name="customlogconditional">directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CustomLog + <em>file</em>|<em>pipe</em> <em>format</em>|<em>nickname</em> + [env=[!]<em>environment-variable</em>]<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Nickname only + available in Apache 1.3 or later. Conditional logging available + in 1.3.5 or later.<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_log_config</p> + + <p>The <code>CustomLog</code> directive is used to log requests + to the server. A log format is specified, and the logging can + optionally be made conditional on request characteristics using + environment variables.</p> + + <p>The first argument, which specifies the location to which + the logs will be written, can take on one of the following two + types of values:</p> + + <dl> + <dt><em>file</em></dt> + + <dd>A filename, relative to the <a + href="core.html#serverroot">ServerRoot</a>.</dd> + + <dt><em>pipe</em></dt> + + <dd>The pipe character "<code>|</code>", followed by the path + to a program to receive the log information on its standard + input. <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.</dd> + </dl> + + <p>The second argument specifies what will be written to the + log file. It can specify either a <em>nickname</em> defined by + a previous <a href="#logformat">LogFormat</a> directive, or it + can be an explicit <em>format</em> string as described in the + <a href="#formats">log formats</a> section.</p> + + <p>For example, the following two sets of directives have + exactly the same effect:</p> <pre> # CustomLog with format nickname - LogFormat "%h %l %u %t \"%r\" %>s %b" common + LogFormat "%h %l %u %t \"%r\" %>s %b" common CustomLog logs/access_log common # CustomLog with explicit format string - CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b" + CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b" </pre> -<p>The third argument is optional and allows the decision on whether -or not to log a particular request to be based on the presence or -absence of a particular variable in the server environment. If the -specified <a href="../env.html">environment variable</a> is set for -the request (or is not set, in the case of a -'<CODE>env=!<EM>name</EM></CODE>' clause), then the request will be -logged.</P> - -<P>Environment variables can be set on a <EM>per</EM>-request basis -using the <A HREF="mod_setenvif.html">mod_setenvif</A> and/or <A -HREF="mod_rewrite.html">mod_rewrite</A> modules. For example, if you -don't want to record requests for all GIF images on your server in a -separate logfile but not your main log, you can use: -</P> -<PRE> + <p>The third argument is optional and allows the decision on + whether or not to log a particular request to be based on the + presence or absence of a particular variable in the server + environment. If the specified <a href="../env.html">environment + variable</a> is set for the request (or is not set, in the case + of a '<code>env=!<em>name</em></code>' clause), then the + request will be logged.</p> + + <p>Environment variables can be set on a <em>per</em>-request + basis using the <a href="mod_setenvif.html">mod_setenvif</a> + and/or <a href="mod_rewrite.html">mod_rewrite</a> modules. For + example, if you don't want to record requests for all GIF + images on your server in a separate logfile but not your main + log, you can use:</p> +<pre> SetEnvIf Request_URI \.gif$ gif-image CustomLog gif-requests.log common env=gif-image CustomLog nongif-requests.log common env=!gif-image -</PRE> - -<HR> -<H2><A NAME="logformat">LogFormat</A> directive</H2> -<!--%plaintext <?INDEX {\tt LogFormat} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LogFormat <EM>format</em>|<em>nickname</EM> - [<EM>nickname</EM>] -<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LogFormat "%h %l %u %t \"%r\" -%>s %b"</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Nickname only available in Apache 1.3 - or later -<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config</p> - -<p>This directive specifies the format of the access log file.</p> - -<p>The <code>LogFormat</code> directive can take one of two forms. In -the first form, where only one argument is specified, this directive -sets the log format which will be used by logs specified in subsequent -<a href="#transferlog">TransferLog</a> directives. The single -argument can specify an explicit <em>format</em> as discussed in <a -href="#formats">custom log formats</a> section above. Alternatively, -it can use a <em>nickname</em> to refer to a log format defined -in a previous <code>LogFormat</code> directive as described below.</p> - -<p>The second form of the <code>LogFormat</code> directive associates -an explicit <em>format</em> with a <em>nickname</em>. This -<em>nickname</em> can then be used in subsequent -<code>LogFormat</code> or <a href="#customlog">CustomLog</a> -directives rather than repeating the entire format string. A -<SAMP>LogFormat</SAMP> directive which defines a nickname <STRONG>does -nothing else</STRONG> -- that is, it <EM>only</EM> defines the -nickname, it doesn't actually apply the format and make it the -default. Therefore, it will not affect subsequent <a -href="#transferlog">TransferLog</a> directives. -</P> - -<HR> - -<H2><A NAME="transferlog">TransferLog</A> directive</H2> -<!--%plaintext <?INDEX {\tt TransferLog} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> TransferLog <EM>file</em>|<em>pipe</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> none<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_log_config</p> - -<p>This directive has exactly the same arguments and effect as the <a -href="#customlog">CustomLog</a> directive, with the exception that it -does not allow the log format to be specified explicitly or for -conditional logging of requests. Instead, the log format is -determined by the most recently specified specified <a -href="#logformat">LogFormat</a> directive (which does not define a -nickname). Common Log Format is used if no other format has been -specified.</p> - -<p>Example:</p> - +</pre> + <hr /> + + <h2><a id="logformat" name="logformat">LogFormat</a> + directive</h2> + <!--%plaintext <?INDEX {\tt LogFormat} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> LogFormat + <em>format</em>|<em>nickname</em> [<em>nickname</em>]<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>LogFormat "%h %l + %u %t \"%r\" %>s %b"</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Nickname only + available in Apache 1.3 or later<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_log_config</p> + + <p>This directive specifies the format of the access log + file.</p> + + <p>The <code>LogFormat</code> directive can take one of two + forms. In the first form, where only one argument is specified, + this directive sets the log format which will be used by logs + specified in subsequent <a href="#transferlog">TransferLog</a> + directives. The single argument can specify an explicit + <em>format</em> as discussed in <a href="#formats">custom log + formats</a> section above. Alternatively, it can use a + <em>nickname</em> to refer to a log format defined in a + previous <code>LogFormat</code> directive as described + below.</p> + + <p>The second form of the <code>LogFormat</code> directive + associates an explicit <em>format</em> with a + <em>nickname</em>. This <em>nickname</em> can then be used in + subsequent <code>LogFormat</code> or <a + href="#customlog">CustomLog</a> directives rather than + repeating the entire format string. A <samp>LogFormat</samp> + directive which defines a nickname <strong>does nothing + else</strong> -- that is, it <em>only</em> defines the + nickname, it doesn't actually apply the format and make it the + default. Therefore, it will not affect subsequent <a + href="#transferlog">TransferLog</a> directives.</p> + <hr /> + + <h2><a id="transferlog" name="transferlog">TransferLog</a> + directive</h2> + <!--%plaintext <?INDEX {\tt TransferLog} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> TransferLog + <em>file</em>|<em>pipe</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> none<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_log_config</p> + + <p>This directive has exactly the same arguments and effect as + the <a href="#customlog">CustomLog</a> directive, with the + exception that it does not allow the log format to be specified + explicitly or for conditional logging of requests. Instead, the + log format is determined by the most recently specified + specified <a href="#logformat">LogFormat</a> directive (which + does not define a nickname). Common Log Format is used if no + other format has been specified.</p> + + <p>Example:</p> <pre> LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" TransferLog logs/access_log </pre> + <!--#include virtual="footer.html" --> + </body> +</html> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_mime_magic.html b/docs/manual/mod/mod_mime_magic.html index 3e0327abf2..893b2205b4 100644 --- a/docs/manual/mod/mod_mime_magic.html +++ b/docs/manual/mod/mod_mime_magic.html @@ -1,121 +1,182 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_mime_magic</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]"> - </DIV> - - <H1 align="CENTER">Module mod_mime_magic</H1> - - <p>This module provides for determining the MIME type of a file by - looking at a few bytes of its contents.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_mime_magic.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> mime_magic_module -</P> - - - - <H2>Summary</H2> - - <p>This module determines the MIME type of files in the same way the - Unix file(1) command works: it looks at the first few bytes of - the file. It is intended as a "second line of defense" for cases - that <a href="mod_mime.html">mod_mime</a> can't resolve. To assure - that mod_mime gets first try at determining a file's MIME type, - be sure to list mod_mime_magic <STRONG>before</STRONG> mod_mime - in the configuration. - - <p>This module is derived from a free version of the - <CODE>file(1)</CODE> command for Unix, which uses "magic numbers" - and other hints from a file's contents to figure out what the - contents are. This module is active only if the magic file is - specified by the <A - HREF="#mimemagicfile"><CODE>MimeMagicFile</CODE></A> directive. - - - <H2>Directives</H2> - <P> - <UL> - <LI><A HREF="#mimemagicfile">MimeMagicFile</A> - </LI> - </UL> - </P> - - <h2>Format of the Magic File</h2> - -<P> - The contents of the file are plain ASCII text in 4-5 columns. - Blank lines are allowed but ignored. - Commented lines use a hash mark "#". - The remaining lines are parsed for the following columns: - <table border=1> - <tr valign=top> - <TH>Column</TH> - <TH>Description</TH> - </TR> - <tr valign=top> - <TD>1</TD> - <TD>byte number to begin checking from - <BR> - ">" indicates a dependency upon the previous non-">" line</TD> - </TR><tr valign=top> - <TD>2</TD> - <TD>type of data to match - <table border=1> - <TR><TD>byte</TD><TD>single character</TD></TR> - <TR><TD>short</TD><TD>machine-order 16-bit integer</TD></TR> - <TR><TD>long</TD><TD>machine-order 32-bit integer</TD></TR> - <TR><TD>string</TD><TD>arbitrary-length string</TD></TR> - <TR><TD>date</TD><TD>long integer date - (seconds since Unix epoch/1970)</TD></TR> - <TR><TD>beshort</TD><TD>big-endian 16-bit integer</TD></TR> - <TR><TD>belong</TD><TD>big-endian 32-bit integer</TD></TR> - <TR><TD>bedate</TD><TD>big-endian 32-bit integer date</TD></TR> - <TR><TD>leshort</TD><TD>little-endian 16-bit integer</TD></TR> - <TR><TD>lelong</TD><TD>little-endian 32-bit integer</TD></TR> - <TR><TD>ledate</TD><TD>little-endian 32-bit integer date</TD></TR> - </TABLE> - </TD> - </TR><tr valign=top> - <TD>3</TD> - <TD>contents of data to match</TD> - </TR><tr valign=top> - <TD>4</TD> - <TD>MIME type if matched</TD> - </TR><tr valign=top> - <TD>5</TD> - <TD>MIME encoding if matched (optional)</TD> - </TR> - </TABLE> - - <P> - For example, the following magic file lines - would recognize some audio formats. - -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_mime_magic</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]" /> + </div> + + <h1 align="CENTER">Module mod_mime_magic</h1> + + <p>This module provides for determining the MIME type of a file + by looking at a few bytes of its contents.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_mime_magic.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mime_magic_module</p> + + <h2>Summary</h2> + + <p>This module determines the MIME type of files in the same + way the Unix file(1) command works: it looks at the first few + bytes of the file. It is intended as a "second line of defense" + for cases that <a href="mod_mime.html">mod_mime</a> can't + resolve. To assure that mod_mime gets first try at determining + a file's MIME type, be sure to list mod_mime_magic + <strong>before</strong> mod_mime in the configuration.</p> + + <p>This module is derived from a free version of the + <code>file(1)</code> command for Unix, which uses "magic + numbers" and other hints from a file's contents to figure out + what the contents are. This module is active only if the magic + file is specified by the <a + href="#mimemagicfile"><code>MimeMagicFile</code></a> + directive.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#mimemagicfile">MimeMagicFile</a></li> + </ul> + <br /> + <br /> + + + <h2>Format of the Magic File</h2> + + <p>The contents of the file are plain ASCII text in 4-5 + columns. Blank lines are allowed but ignored. Commented lines + use a hash mark "#". The remaining lines are parsed for the + following columns:</p> + + <table border="1"> + <tr valign="top"> + <th>Column</th> + + <th>Description</th> + </tr> + + <tr valign="top"> + <td>1</td> + + <td>byte number to begin checking from<br /> + ">" indicates a dependency upon the previous non-">" + line</td> + </tr> + + <tr valign="top"> + <td>2</td> + + <td> + type of data to match + + <table border="1"> + <tr> + <td>byte</td> + + <td>single character</td> + </tr> + + <tr> + <td>short</td> + + <td>machine-order 16-bit integer</td> + </tr> + + <tr> + <td>long</td> + + <td>machine-order 32-bit integer</td> + </tr> + + <tr> + <td>string</td> + + <td>arbitrary-length string</td> + </tr> + + <tr> + <td>date</td> + + <td>long integer date (seconds since Unix + epoch/1970)</td> + </tr> + + <tr> + <td>beshort</td> + + <td>big-endian 16-bit integer</td> + </tr> + + <tr> + <td>belong</td> + + <td>big-endian 32-bit integer</td> + </tr> + + <tr> + <td>bedate</td> + + <td>big-endian 32-bit integer date</td> + </tr> + + <tr> + <td>leshort</td> + + <td>little-endian 16-bit integer</td> + </tr> + + <tr> + <td>lelong</td> + + <td>little-endian 32-bit integer</td> + </tr> + + <tr> + <td>ledate</td> + + <td>little-endian 32-bit integer date</td> + </tr> + </table> + </td> + </tr> + + <tr valign="top"> + <td>3</td> + + <td>contents of data to match</td> + </tr> + + <tr valign="top"> + <td>4</td> + + <td>MIME type if matched</td> + </tr> + + <tr valign="top"> + <td>5</td> + + <td>MIME encoding if matched (optional)</td> + </tr> + </table> + + <p>For example, the following magic file lines would recognize + some audio formats.</p> +<pre> # Sun/NeXT audio data 0 string .snd >12 belong 1 audio/basic @@ -126,13 +187,11 @@ REL="Help" >12 belong 6 audio/basic >12 belong 7 audio/basic >12 belong 23 audio/x-adpcm -</PRE> - - Or these would recognize the difference between "*.doc" files containing - Microsoft Word or FrameMaker documents. (These are incompatible file - formats which use the same file suffix.) - -<PRE> +</pre> + Or these would recognize the difference between "*.doc" files + containing Microsoft Word or FrameMaker documents. (These are + incompatible file formats which use the same file suffix.) +<pre> # Frame 0 string \<MakerFile application/x-frame 0 string \<MIFFile application/x-frame @@ -146,47 +205,43 @@ REL="Help" 0 string \376\067\0\043 application/msword 0 string \320\317\021\340\241\261 application/msword 0 string \333\245-\0\0\0 application/msword -</PRE> - - An optional MIME encoding can be included as a fifth column. - For example, this can recognize gzipped files and set the encoding - for them. - -<PRE> +</pre> + An optional MIME encoding can be included as a fifth column. + For example, this can recognize gzipped files and set the + encoding for them. +<pre> # gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver) 0 string \037\213 application/octet-stream x-gzip -</PRE> - - <H2>Performance Issues</H2> - - This module is not for every system. If your system is barely keeping - up with its load or if you're performing a web server benchmark, - you may not want to enable this because the processing is not free. - <P> - However, an effort was made to improve the performance of the original - file(1) code to make it fit in a busy web server. - It was designed for a server where there are thousands of users who - publish their own documents. - This is probably very common on intranets. - Many times, it's helpful - if the server can make more intelligent decisions about a file's - contents than the file name allows - ...even if just to reduce the "why doesn't my page work" calls - when users improperly name their own files. - You have to decide if the extra work suits your environment. - <P> - When compiling an Apache server, this module should be at or near the - top of the list of modules in the Configuration file. The modules are - listed in increasing priority so that will mean this one is used only - as a last resort, just like it was designed to. - - <H2><A NAME="notes">Notes</A></H2> - - The following notes apply to the mod_mime_magic module and are - included here for compliance with contributors' copyright restrictions - that require their acknowledgment. - -<PRE> +</pre> + + <h2>Performance Issues</h2> + This module is not for every system. If your system is barely + keeping up with its load or if you're performing a web server + benchmark, you may not want to enable this because the + processing is not free. + + <p>However, an effort was made to improve the performance of + the original file(1) code to make it fit in a busy web server. + It was designed for a server where there are thousands of users + who publish their own documents. This is probably very common + on intranets. Many times, it's helpful if the server can make + more intelligent decisions about a file's contents than the + file name allows ...even if just to reduce the "why doesn't my + page work" calls when users improperly name their own files. + You have to decide if the extra work suits your + environment.</p> + + <p>When compiling an Apache server, this module should be at or + near the top of the list of modules in the Configuration file. + The modules are listed in increasing priority so that will mean + this one is used only as a last resort, just like it was + designed to.</p> + + <h2><a id="notes" name="notes">Notes</a></h2> + The following notes apply to the mod_mime_magic module and are + included here for compliance with contributors' copyright + restrictions that require their acknowledgment. +<pre> /* * mod_mime_magic: MIME type lookup via file magic numbers * Copyright (c) 1996-1997 Cisco Systems, Inc. @@ -230,7 +285,7 @@ REL="Help" * - Memory allocation is done through the Apache API's pool structure. * - All functions have had necessary Apache API request or server * structures passed to them where necessary to call other Apache API - * routines. (<EM>i.e.</EM>, usually for logging, files, or memory allocation in + * routines. (<em>i.e.</em>, usually for logging, files, or memory allocation in * itself or a called function.) * - struct magic has been converted from an array to a single-ended linked * list because it only grows one record at a time, it's only accessed @@ -244,46 +299,31 @@ REL="Help" * - Command-line flags have been removed since they will never be used here. * */ -</PRE> - - <HR> - <H2><A NAME="mimemagicfile"> - MimeMagicFile - </A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> MimeMagicFile <EM>file-path</EM> - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> none - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Extension - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_mime_magic - <P> - - The <CODE>MimeMagicFile</CODE> directive can be used to enable this module, - the default file is distributed at <CODE>conf/magic</CODE>. - Non-rooted paths are relative to the ServerRoot. Virtual hosts - will use the same file as the main server unless a more specific setting - is used, in which case the more specific setting overrides the main server's - file. - <P> - - </BODY> -</HTML> +</pre> + <hr /> + + <h2><a id="mimemagicfile" + name="mimemagicfile">MimeMagicFile</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MimeMagicFile + <em>file-path</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> none<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_mime_magic</p> + + <p>The <code>MimeMagicFile</code> directive can be used to + enable this module, the default file is distributed at + <code>conf/magic</code>. Non-rooted paths are relative to the + ServerRoot. Virtual hosts will use the same file as the main + server unless a more specific setting is used, in which case + the more specific setting overrides the main server's file.</p> + </body> +</html> + diff --git a/docs/manual/mod/mod_mmap_static.html b/docs/manual/mod/mod_mmap_static.html index 5a9749c439..2b2c9b3148 100644 --- a/docs/manual/mod/mod_mmap_static.html +++ b/docs/manual/mod/mod_mmap_static.html @@ -1,152 +1,126 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_mmap_static</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_mmap_static</H1> - - <P> - This module provides mmap()ing of a statically configured list - of frequently requested but not changed files. - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Experimental -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_mmap_static.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> mmap_static_module -</P> - - <H2>Summary</H2> - <P> - This is an <STRONG>experimental</STRONG> module and should be used with - care. You can easily create a broken site using this module, read this - document carefully. - <CODE>mod_mmap_static</CODE> maps a list of statically configured files (via - <CODE>MMapFile</CODE> directives in the main server configuration) into - memory through the system call <CODE>mmap()</CODE>. This system - call is available on most modern Unix derivates, but not on all. There - are sometimes system-specific limits on the size and number of files that - can be mmap()d, experimentation is probably the easiest way to find out. - </P> - <P> - This mmap()ing is done once at server start or restart, only. So whenever - one of the mapped files changes on the filesystem you <EM>have</EM> to - restart the server by at least sending it a HUP or USR1 signal (see the - <A HREF="../stopping.html">Stopping and Restarting</A> documentation). To - reiterate that point: if the files are modified <EM>in place</EM> without - restarting the server you may end up serving requests that are completely - bogus. You should update files by unlinking the old copy and putting a new - copy in place. Most tools such as <CODE>rdist</CODE> and <CODE>mv</CODE> do - this. The reason why this modules doesn't take care of changes to the files - is that this check would need an extra <CODE>stat()</CODE> every time which - is a waste and against the intent of I/O reduction. - </P> - - <H2>Directives</H2> - <UL> - <LI><A HREF="#mmapfile">MMapFile</A> - </LI> - </UL> - - <HR> - - <H2><A NAME="mmapfile">MMapFile</A> directive</H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename</em> - [<em>filename</em>] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>None</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server-config - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM> - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Experimental - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_mmap_static - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Only available in Apache 1.3 or later - - <P> - The <CODE>MMapFile</CODE> directive maps one or more files (given as - whitespace separated arguments) into memory at server startup time. They - are automatically unmapped on a server shutdown. When the files have changed - on the filesystem at least a HUP or USR1 signal should be send to the server - to re-mmap them. - </P> - - <P> - Be careful with the <EM>filename</EM> arguments: They have to literally - match the filesystem path Apache's URL-to-filename translation handlers - create. We cannot compare inodes or other stuff to match paths through - symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE> - system calls which is not acceptable. This module may or may not work - with filenames rewritten by <CODE>mod_alias</CODE> or - <CODE>mod_rewrite</CODE>... it is an experiment after all. - </P> - - <P> - Notice: You cannot use this for speeding up CGI programs or other files - which are served by special content handlers. It can only be used for - regular files which are usually served by the Apache core content handler. - </P> - - Example: - - <PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_mmap_static</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_mmap_static</h1> + + <p>This module provides mmap()ing of a statically configured + list of frequently requested but not changed files.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_mmap_static.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mmap_static_module</p> + + <h2>Summary</h2> + + <p>This is an <strong>experimental</strong> module and should + be used with care. You can easily create a broken site using + this module, read this document carefully. + <code>mod_mmap_static</code> maps a list of statically + configured files (via <code>MMapFile</code> directives in the + main server configuration) into memory through the system call + <code>mmap()</code>. This system call is available on most + modern Unix derivates, but not on all. There are sometimes + system-specific limits on the size and number of files that can + be mmap()d, experimentation is probably the easiest way to find + out.</p> + + <p>This mmap()ing is done once at server start or restart, + only. So whenever one of the mapped files changes on the + filesystem you <em>have</em> to restart the server by at least + sending it a HUP or USR1 signal (see the <a + href="../stopping.html">Stopping and Restarting</a> + documentation). To reiterate that point: if the files are + modified <em>in place</em> without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as <code>rdist</code> and + <code>mv</code> do this. The reason why this modules doesn't + take care of changes to the files is that this check would need + an extra <code>stat()</code> every time which is a waste and + against the intent of I/O reduction.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#mmapfile">MMapFile</a></li> + </ul> + <hr /> + + <h2><a id="mmapfile" name="mmapfile">MMapFile</a> + directive</h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MMapFile + <em>filename</em> [<em>filename</em>] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server-config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_mmap_static<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Only available + in Apache 1.3 or later</p> + + <p>The <code>MMapFile</code> directive maps one or more files + (given as whitespace separated arguments) into memory at server + startup time. They are automatically unmapped on a server + shutdown. When the files have changed on the filesystem at + least a HUP or USR1 signal should be send to the server to + re-mmap them.</p> + + <p>Be careful with the <em>filename</em> arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links <em>etc.</em> + because that again would cost extra <code>stat()</code> system + calls which is not acceptable. This module may or may not work + with filenames rewritten by <code>mod_alias</code> or + <code>mod_rewrite</code>... it is an experiment after all.</p> + + <p>Notice: You cannot use this for speeding up CGI programs or + other files which are served by special content handlers. It + can only be used for regular files which are usually served by + the Apache core content handler.</p> + Example: +<pre> MMapFile /usr/local/apache/htdocs/index.html - </PRE> - - <P> - <STRONG>Note</STRONG>: don't bother asking for a for a <CODE>MMapDir</CODE> - directive which - recursively maps all the files in a directory. Use Unix the way it was - meant to be used. For example, see the - <A HREF="core.html#include">Include</A> directive, and consider this command: - <PRE> + +</pre> + + <p><strong>Note</strong>: don't bother asking for a for a + <code>MMapDir</code> directive which recursively maps all the + files in a directory. Use Unix the way it was meant to be used. + For example, see the <a href="core.html#include">Include</a> + directive, and consider this command:</p> +<pre> find /www/htdocs -type f -print \ | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf - </PRE> + +</pre> + <!--#include virtual="footer.html" --> + </body> +</html> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_negotiation.html b/docs/manual/mod/mod_negotiation.html index d53bb52c87..ae7bf9f5e2 100644 --- a/docs/manual/mod/mod_negotiation.html +++ b/docs/manual/mod/mod_negotiation.html @@ -1,223 +1,228 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_negotiation</H1> - -<p>This module provides for <A -HREF="../content-negotiation.html">content negotiation</A>.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_negotiation.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> negotiation_module -</P> - -<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> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A> -<LI><A HREF="#languagepriority">LanguagePriority</A> -</UL> - -<STRONG>See also</STRONG>: -<A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A>, -<A HREF="./mod_mime.html#addencoding">AddEncoding</A>, -<A HREF="./mod_mime.html#addlanguage">AddLanguage</A>, -<A HREF="./mod_mime.html#addtype">AddType</A>, and -<A HREF="core.html#options">Options</A>. - -<H2>Type maps</H2> -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. Apache only recognizes encodings that are -defined by an <A HREF="mod_mime.html#addencoding">AddEncoding</A> directive. -This normally includes the encodings <CODE>x-compress</CODE> for compress'd -files, and <CODE>x-gzip</CODE> for gzip'd files. The <CODE>x-</CODE> prefix -is ignored for encoding comparisons. -<DT>Content-Language: -<DD>The language of the variant, as an Internet standard language tag -(RFC 1766). An example is <CODE>en</CODE>, meaning English. -<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 a -semi-colon, with a syntax of <CODE>name=value</CODE>. Common parameters -include: -<DL> -<DT>level -<DD>an integer specifying the version of the media type. -For <CODE>text/html</CODE> this defaults to 2, otherwise 0. -<DT>qs -<DD>a floating-point number with a value in the range 0.0 to 1.0, - indicating the relative 'quality' of this variant - compared to the other available variants, independent of the client's - capabilities. For example, a jpeg file is usually of higher source - quality than an ascii file if it is attempting to represent a - photograph. However, if the resource being represented is ascii art, - then an ascii file would have a higher source quality than a jpeg file. - All qs values are therefore specific to a given resource. -</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> - -<H2>MultiViews</H2> -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> - - - -<HR> - - -<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>CacheNegotiatedDocs off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_negotiation<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available -in Apache 1.1 and later. The syntax changed in version 2.0.<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. - -<P>Prior to version 2.0, CacheNegotiatedDocs did not take an argument; -it was turned on by the presence of the directive by itself. - -<hr> - -<H2><A NAME="languagepriority">LanguagePriority</A> directive</H2> -<!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>MIME-lang</em> - [<em>MIME-lang</EM>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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 any other means. Correctly implemented -HTTP/1.1 requests will mean this directive has no effect. - -<P> - -<STRONG>See also</STRONG>: -<A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A> and -<A HREF="./mod_mime.html#addlanguage">AddLanguage</A> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_negotiation</h1> + + <p>This module provides for <a + href="../content-negotiation.html">content negotiation</a>.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_negotiation.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + negotiation_module</p> + + <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> + + <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.</li> + </ul> + + <h2>Directives</h2> + + <ul> + <li><a + href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li> + + <li><a href="#languagepriority">LanguagePriority</a></li> + </ul> + <strong>See also</strong>: <a + href="./mod_mime.html#defaultlanguage">DefaultLanguage</a>, <a + href="./mod_mime.html#addencoding">AddEncoding</a>, <a + href="./mod_mime.html#addlanguage">AddLanguage</a>, <a + href="./mod_mime.html#addtype">AddType</a>, and <a + href="core.html#options">Options</a>. + + <h2>Type maps</h2> + 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:</dt> + + <dd>The encoding of the file. Apache only recognizes + encodings that are defined by an <a + href="mod_mime.html#addencoding">AddEncoding</a> directive. + This normally includes the encodings <code>x-compress</code> + for compress'd files, and <code>x-gzip</code> for gzip'd + files. The <code>x-</code> prefix is ignored for encoding + comparisons.</dd> + + <dt>Content-Language:</dt> + + <dd>The language of the variant, as an Internet standard + language tag (RFC 1766). An example is <code>en</code>, + meaning English.</dd> + + <dt>Content-Length:</dt> + + <dd>The length of the file, in bytes. If this header is not + present, then the actual length of the file is used.</dd> + + <dt>Content-Type:</dt> + + <dd> + The MIME media type of the document, with optional + parameters. Parameters are separated from the media type + and from one another by a semi-colon, with a syntax of + <code>name=value</code>. Common parameters include: + + <dl> + <dt>level</dt> + + <dd>an integer specifying the version of the media type. + For <code>text/html</code> this defaults to 2, otherwise + 0.</dd> + + <dt>qs</dt> + + <dd>a floating-point number with a value in the range 0.0 + to 1.0, indicating the relative 'quality' of this variant + compared to the other available variants, independent of + the client's capabilities. For example, a jpeg file is + usually of higher source quality than an ascii file if it + is attempting to represent a photograph. However, if the + resource being represented is ascii art, then an ascii + file would have a higher source quality than a jpeg file. + All qs values are therefore specific to a given + resource.</dd> + </dl> + Example: + + <blockquote> + <code>Content-Type: image/jpeg; qs=0.8</code> + </blockquote> + </dd> + + <dt>URI:</dt> + + <dd>The path to the file containing this variant, relative to + the map file.</dd> + </dl> + + <h2>MultiViews</h2> + 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. + <hr /> + + <h2><a id="cachenegotiateddocs" + name="cachenegotiateddocs">CacheNegotiatedDocs</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CacheNegotiatedDocs + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>CacheNegotiatedDocs off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_negotiation<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + CacheNegotiatedDocs is only available in Apache 1.1 and later. + The syntax changed in version 2.0. + + <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> + + <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.</p> + + <p>Prior to version 2.0, CacheNegotiatedDocs did not take an + argument; it was turned on by the presence of the directive by + itself.</p> + <hr /> + + <h2><a id="languagepriority" + name="languagepriority">LanguagePriority</a> directive</h2> + <!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> LanguagePriority + <em>MIME-lang</em> [<em>MIME-lang</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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:</p> + + <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>Note that this directive only has an effect if a 'best' + language cannot be determined by any other means. Correctly + implemented HTTP/1.1 requests will mean this directive has no + effect.</p> + + <p><strong>See also</strong>: <a + href="./mod_mime.html#defaultlanguage">DefaultLanguage</a> and + <a href="./mod_mime.html#addlanguage">AddLanguage</a> + <!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html index 61e8216519..f307a84326 100644 --- a/docs/manual/mod/mod_proxy.html +++ b/docs/manual/mod/mod_proxy.html @@ -1,26 +1,25 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_proxy</TITLE> -</HEAD> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> -<blockquote><strong>Note:</strong> -Mod_proxy has been moved out of the httpd-2.0 tree, but is available -elsewhere <insert location> for building with the httpd-2.0 source -distribution. -</blockquote> + <title>Apache module mod_proxy</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <blockquote> + <strong>Note:</strong> Mod_proxy has been moved out of the + httpd-2.0 tree, but is available elsewhere <insert + location> for building with the httpd-2.0 source + distribution. + </blockquote> + <!--#include virtual="footer.html" --> + </body> +</html> diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index 4e12cc47f0..30e298ff5d 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -1,752 +1,731 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <!--%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" -> -<BLOCKQUOTE><!-- page indentation --> -<!--#include virtual="header.html" --> - -<BR> -<H1 ALIGN="CENTER">Module mod_rewrite<BR>URL Rewriting Engine</H1> - -<p>This module provides a rule-based rewriting engine to rewrite requested -URLs on the fly.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_rewrite.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> rewrite_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later. -</P> - - -<P> -<HR NOSHADE SIZE=1> - -<BR> -<H2>Summary</H2> - -<BLOCKQUOTE> -<BLOCKQUOTE> -<BLOCKQUOTE> -<EM>``The great thing about mod_rewrite is it gives you all the -configurability and flexibility of Sendmail. The downside to -mod_rewrite is that it gives you all the configurability and -flexibility of Sendmail.''</EM> -<DIV ALIGN=RIGHT> --- Brian Behlendorf<BR> -Apache Group -</DIV> -</BLOCKQUOTE> -</BLOCKQUOTE> -</BLOCKQUOTE> - -<BLOCKQUOTE> -<BLOCKQUOTE> -<BLOCKQUOTE> -<EM>`` -Despite the tons of examples and docs, mod_rewrite -is voodoo. Damned cool voodoo, but still voodoo. -''</EM> -<DIV ALIGN=RIGHT> --- Brian Moore<BR> -bem@news.cmc.net -</DIV> -</BLOCKQUOTE> -</BLOCKQUOTE> -</BLOCKQUOTE> - -Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation! - -<P> -This module uses a rule-based rewriting engine (based on a regular-expression -parser) to rewrite requested URLs on the fly. It supports an unlimited number -of rules and an unlimited number of attached rule conditions for each rule to -provide a really flexible and powerful URL manipulation mechanism. The URL -manipulations can depend on various tests, for instance server variables, -environment variables, HTTP headers, time stamps and even external database -lookups in various formats can be used to achieve a really granular URL -matching. - -<P> -This module operates on the full URLs (including the path-info part) both in -per-server context (<CODE>httpd.conf</CODE>) and per-directory context -(<CODE>.htaccess</CODE>) and can even generate query-string parts on result. -The rewritten result can lead to internal sub-processing, external request -redirection or even to an internal proxy throughput. - -<P> -But all this functionality and flexibility has its drawback: complexity. So -don't expect to understand this entire module in just one day. - -<P> -This module was invented and originally written in April 1996<BR> -and gifted exclusively to the The Apache Group in July 1997 by - -<P> -<BLOCKQUOTE> -<A HREF="http://www.engelschall.com/"><CODE>Ralf S. Engelschall</CODE></A><BR> -<A HREF="mailto:rse@engelschall.com"><CODE>rse@engelschall.com</CODE></A><BR> -<A HREF="http://www.engelschall.com/"><CODE>www.engelschall.com</CODE></A> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<H2>Table Of Contents</H2> - -<P> -<STRONG>Internal Processing</STRONG> -<UL> - <LI><A HREF="#InternalAPI">API Phases</A> - <LI><A HREF="#InternalRuleset">Ruleset Processing</A> - <LI><A HREF="#InternalBackRefs">Regex Back-Reference Availability</A> -</UL> -<P> -<STRONG>Configuration Directives</STRONG> -<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="#RewriteLock">RewriteLock</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> -<STRONG>Miscellaneous</STRONG> -<UL> - <LI><A HREF="#EnvVar">Environment Variables</A> - <LI><A HREF="#Solutions">Practical Solutions</A> -</UL> - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Internal">Internal Processing</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<P> -The internal processing of this module is very complex but needs to be -explained once even to the average user to avoid common mistakes and to let -you exploit its full functionality. - -<H2><A NAME="InternalAPI">API Phases</A></H2> - -<P> -First you have to understand that when Apache processes a HTTP request it does -this in phases. A hook for each of these phases is provided by the Apache API. -Mod_rewrite uses two of these hooks: the URL-to-filename translation hook -which is used after the HTTP request has been read but before any authorization -starts and the Fixup hook which is triggered after the authorization phases -and after the per-directory config files (<CODE>.htaccess</CODE>) have been -read, but before the content handler is activated. - -<P> -So, after a request comes in and Apache has determined the corresponding -server (or virtual server) the rewriting engine starts processing of all -mod_rewrite directives from the per-server configuration in the -URL-to-filename phase. A few steps later when the final data directories are -found, the per-directory configuration directives of mod_rewrite are triggered -in the Fixup phase. In both situations mod_rewrite rewrites URLs either to new -URLs or to filenames, although there is no obvious distinction between them. -This is a usage of the API which was not intended to be this way when the API -was designed, but as of Apache 1.x this is the only way mod_rewrite can -operate. To make this point more clear remember the following two points: - -<OL> -<LI>Although mod_rewrite rewrites URLs to URLs, URLs to filenames and - even filenames to filenames, the API currently provides only a - URL-to-filename hook. In Apache 2.0 the two missing hooks will be - added to make the processing more clear. But this point has no - drawbacks for the user, it is just a fact which should be - remembered: Apache does more in the URL-to-filename hook than the - API intends for it. -<P> -<LI>Unbelievably mod_rewrite provides URL manipulations in per-directory - context, <EM>i.e.</EM>, within <CODE>.htaccess</CODE> files, - although these are reached a very long time after the URLs have - been translated to filenames. It has to be this way because - <CODE>.htaccess</CODE> files live in the filesystem, so processing - has already reached this stage. In other words: According to the - API phases at this time it is too late for any URL manipulations. - To overcome this chicken and egg problem mod_rewrite uses a trick: - When you manipulate a URL/filename in per-directory context - mod_rewrite first rewrites the filename back to its corresponding - URL (which is usually impossible, but see the <CODE>RewriteBase</CODE> - directive below for the trick to achieve this) and then initiates - a new internal sub-request with the new URL. This restarts - processing of the API phases. - <P> - Again mod_rewrite tries hard to make this complicated step totally - transparent to the user, but you should remember here: While URL - manipulations in per-server context are really fast and efficient, - per-directory rewrites are slow and inefficient due to this chicken and - egg problem. But on the other hand this is the only way mod_rewrite can - provide (locally restricted) URL manipulations to the average user. -</OL> - -<P> -Don't forget these two points! - -<H2><A NAME="InternalRuleset">Ruleset Processing</A></H2> - -Now when mod_rewrite is triggered in these two API phases, it reads the -configured rulesets from its configuration structure (which itself was either -created on startup for per-server context or during the directory walk of the -Apache kernel for per-directory context). Then the URL rewriting engine is -started with the contained ruleset (one or more rules together with their -conditions). The operation of the URL rewriting engine itself is exactly the -same for both configuration contexts. Only the final result processing is -different. - -<P> -The order of rules in the ruleset is important because the rewriting engine -processes them in a special (and not very obvious) order. The -rule is this: The rewriting engine loops through the ruleset rule by rule -(<CODE>RewriteRule</CODE> directives) and when a particular rule matches it -optionally loops through existing corresponding conditions -(<CODE>RewriteCond</CODE> directives). For historical reasons the conditions -are given first, and so the control flow is a little bit long-winded. See -Figure 1 for more details. - -<P> -<DIV ALIGN=CENTER> -<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> -<TR> -<TD BGCOLOR="#CCCCCC"><IMG - SRC="../images/mod_rewrite_fig1.gif" - WIDTH="428" HEIGHT="385" - ALT="[Needs graphics capability to display]"></TD> -</TR> -<TR> -<TD ALIGN=CENTER> -<STRONG>Figure 1:</STRONG> The control flow through the rewriting ruleset -</TD> -</TR> -</TABLE> -</DIV> - -<P> -As you can see, first the URL is matched against the <EM>Pattern</EM> of each -rule. When it fails mod_rewrite immediately stops processing this rule and -continues with the next rule. If the <EM>Pattern</EM> matches, mod_rewrite -looks for corresponding rule conditions. If none are present, it just -substitutes the URL with a new value which is constructed from the string -<EM>Substitution</EM> and goes on with its rule-looping. But if conditions -exist, it starts an inner loop for processing them in the order that -they are listed. For conditions the logic is different: we don't match a -pattern against the current URL. Instead we first create a string -<EM>TestString</EM> by expanding variables, back-references, map lookups, -<EM>etc.</EM> and then we try to match <EM>CondPattern</EM> against it. If the -pattern doesn't match, the complete set of conditions and the corresponding -rule fails. If the pattern matches, then the next condition is processed -until no more conditions are available. If all conditions match, processing -is continued with the substitution of the URL with <EM>Substitution</EM>. - -<h2><a name="quoting">Quoting Special Characters</a></h2> -<p> -As of Apache 1.3.20, special characters in <i>TestString</i> and -<i>Substitution</i> strings can be escaped (that is, treated as -normal characters without their usual special meaning) by prefixing them -with a slosh ('\') character. In other words, you can include an -actual dollar-sign character in a <i>Substitution</i> string -by using '<code>\$</code>'; this keeps mod_rewrite from trying -to treat it as a backreference. -</p> - -<H2><A NAME="InternalBackRefs">Regex Back-Reference Availability</A></H2> - -One important thing here has to be remembered: Whenever you -use parentheses in <EM>Pattern</EM> or in one of the <EM>CondPattern</EM>, -back-references are internally created which can be used with the -strings <CODE>$N</CODE> and <CODE>%N</CODE> (see below). These -are available for creating the strings <EM>Substitution</EM> and -<EM>TestString</EM>. Figure 2 shows to which locations the back-references are -transfered for expansion. - -<P> -<DIV ALIGN=CENTER> -<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> -<TR> -<TD BGCOLOR="#CCCCCC"><IMG - SRC="../images/mod_rewrite_fig2.gif" - WIDTH="381" HEIGHT="179" - ALT="[Needs graphics capability to display]"></TD> -</TR> -<TR> -<TD ALIGN=CENTER> -<STRONG>Figure 2:</STRONG> The back-reference flow through a rule -</TD> -</TR> -</TABLE> -</DIV> - -<P> -We know this was a crash course on mod_rewrite's internal processing. But -you will benefit from this knowledge when reading the following documentation -of the available directives. - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Configuration">Configuration Directives</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<H3><A NAME="RewriteEngine">RewriteEngine</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - RewriteEngine on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <CODE>RewriteEngine off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> - server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteEngine</CODE> 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 <CODE>SCRIPT_URx</CODE> -environment variables. - -<P> -Use this directive to disable the module instead of commenting out -all the <CODE>RewriteRule</CODE> directives! - -<P> -Note that, by default, rewrite configurations are not inherited. -This means that you need to have a <CODE>RewriteEngine on</CODE> -directive for each virtual host in which you wish to use it. - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteOptions">RewriteOptions</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteOptions <EM>Option</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteOptions</CODE> 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 are inherited. In per-directory - context this means that conditions and rules of the parent directory's - <CODE>.htaccess</CODE> configuration are inherited. -</UL> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLog">RewriteLog</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteLog <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteLog</CODE> 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 ('<CODE>/</CODE>') 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="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note</STRONG>: 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 then output to a logfile it still creates the logfile -output internally. <STRONG>This will slow down the server with no advantage -to the administrator!</STRONG> -To disable logging either remove or comment out the -<CODE>RewriteLog</CODE> directive or use <CODE>RewriteLogLevel 0</CODE>! -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Security</STRONG>: 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> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> -<PRE> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <blockquote> + <!-- page indentation --> + <!--#include virtual="header.html" --> + <br /> + + + <h1 align="CENTER">Module mod_rewrite<br /> + URL Rewriting Engine</h1> + + <p>This module provides a rule-based rewriting engine to + rewrite requested URLs on the fly.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_rewrite.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + rewrite_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.2 and later.</p> + <hr noshade="noshade" size="1" /> + <br /> + + + <h2>Summary</h2> + + <blockquote> + <blockquote> + <blockquote> + <em>``The great thing about mod_rewrite is it gives you + all the configurability and flexibility of Sendmail. + The downside to mod_rewrite is that it gives you all + the configurability and flexibility of Sendmail.''</em> + + + <div align="RIGHT"> + -- Brian Behlendorf<br /> + Apache Group + </div> + </blockquote> + </blockquote> + </blockquote> + + <blockquote> + <blockquote> + <blockquote> + <em>`` Despite the tons of examples and docs, + mod_rewrite is voodoo. Damned cool voodoo, but still + voodoo. ''</em> + + <div align="RIGHT"> + -- Brian Moore<br /> + bem@news.cmc.net + </div> + </blockquote> + </blockquote> + </blockquote> + Welcome to mod_rewrite, the Swiss Army Knife of URL + manipulation! + + <p>This module uses a rule-based rewriting engine (based on a + regular-expression parser) to rewrite requested URLs on the + fly. It supports an unlimited number of rules and an + unlimited number of attached rule conditions for each rule to + provide a really flexible and powerful URL manipulation + mechanism. The URL manipulations can depend on various tests, + for instance server variables, environment variables, HTTP + headers, time stamps and even external database lookups in + various formats can be used to achieve a really granular URL + matching.</p> + + <p>This module operates on the full URLs (including the + path-info part) both in per-server context + (<code>httpd.conf</code>) and per-directory context + (<code>.htaccess</code>) and can even generate query-string + parts on result. The rewritten result can lead to internal + sub-processing, external request redirection or even to an + internal proxy throughput.</p> + + <p>But all this functionality and flexibility has its + drawback: complexity. So don't expect to understand this + entire module in just one day.</p> + + <p>This module was invented and originally written in April + 1996<br /> + and gifted exclusively to the The Apache Group in July 1997 + by</p> + + <blockquote> + <a href="http://www.engelschall.com/"><code>Ralf S. + Engelschall</code></a><br /> + <a + href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a><br /> + <a + href="http://www.engelschall.com/"><code>www.engelschall.com</code></a> + </blockquote> + <hr noshade="noshade" size="1" /> + + <h2>Table Of Contents</h2> + + <p><strong>Internal Processing</strong></p> + + <ul> + <li><a href="#InternalAPI">API Phases</a></li> + + <li><a href="#InternalRuleset">Ruleset Processing</a></li> + + <li><a href="#InternalBackRefs">Regex Back-Reference + Availability</a></li> + </ul> + + <p><strong>Configuration Directives</strong></p> + + <ul> + <li><a href="#RewriteEngine">RewriteEngine</a></li> + + <li><a href="#RewriteOptions">RewriteOptions</a></li> + + <li><a href="#RewriteLog">RewriteLog</a></li> + + <li><a href="#RewriteLogLevel">RewriteLogLevel</a></li> + + <li><a href="#RewriteLock">RewriteLock</a></li> + + <li><a href="#RewriteMap">RewriteMap</a></li> + + <li><a href="#RewriteBase">RewriteBase</a></li> + + <li><a href="#RewriteCond">RewriteCond</a></li> + + <li><a href="#RewriteRule">RewriteRule</a></li> + </ul> + <strong>Miscellaneous</strong> + + <ul> + <li><a href="#EnvVar">Environment Variables</a></li> + + <li><a href="#Solutions">Practical Solutions</a></li> + </ul> + <hr noshade="noshade" size="1" /> + + <center> + <h1><a id="Internal" name="Internal">Internal + Processing</a></h1> + </center> + <hr noshade="noshade" size="1" /> + + <p>The internal processing of this module is very complex but + needs to be explained once even to the average user to avoid + common mistakes and to let you exploit its full + functionality.</p> + + <h2><a id="InternalAPI" name="InternalAPI">API + Phases</a></h2> + + <p>First you have to understand that when Apache processes a + HTTP request it does this in phases. A hook for each of these + phases is provided by the Apache API. Mod_rewrite uses two of + these hooks: the URL-to-filename translation hook which is + used after the HTTP request has been read but before any + authorization starts and the Fixup hook which is triggered + after the authorization phases and after the per-directory + config files (<code>.htaccess</code>) have been read, but + before the content handler is activated.</p> + + <p>So, after a request comes in and Apache has determined the + corresponding server (or virtual server) the rewriting engine + starts processing of all mod_rewrite directives from the + per-server configuration in the URL-to-filename phase. A few + steps later when the final data directories are found, the + per-directory configuration directives of mod_rewrite are + triggered in the Fixup phase. In both situations mod_rewrite + rewrites URLs either to new URLs or to filenames, although + there is no obvious distinction between them. This is a usage + of the API which was not intended to be this way when the API + was designed, but as of Apache 1.x this is the only way + mod_rewrite can operate. To make this point more clear + remember the following two points:</p> + + <ol> + <li>Although mod_rewrite rewrites URLs to URLs, URLs to + filenames and even filenames to filenames, the API + currently provides only a URL-to-filename hook. In Apache + 2.0 the two missing hooks will be added to make the + processing more clear. But this point has no drawbacks for + the user, it is just a fact which should be remembered: + Apache does more in the URL-to-filename hook than the API + intends for it.</li> + + <li> + Unbelievably mod_rewrite provides URL manipulations in + per-directory context, <em>i.e.</em>, within + <code>.htaccess</code> files, although these are reached + a very long time after the URLs have been translated to + filenames. It has to be this way because + <code>.htaccess</code> files live in the filesystem, so + processing has already reached this stage. In other + words: According to the API phases at this time it is too + late for any URL manipulations. To overcome this chicken + and egg problem mod_rewrite uses a trick: When you + manipulate a URL/filename in per-directory context + mod_rewrite first rewrites the filename back to its + corresponding URL (which is usually impossible, but see + the <code>RewriteBase</code> directive below for the + trick to achieve this) and then initiates a new internal + sub-request with the new URL. This restarts processing of + the API phases. + + <p>Again mod_rewrite tries hard to make this complicated + step totally transparent to the user, but you should + remember here: While URL manipulations in per-server + context are really fast and efficient, per-directory + rewrites are slow and inefficient due to this chicken and + egg problem. But on the other hand this is the only way + mod_rewrite can provide (locally restricted) URL + manipulations to the average user.</p> + </li> + </ol> + + <p>Don't forget these two points!</p> + + <h2><a id="InternalRuleset" name="InternalRuleset">Ruleset + Processing</a></h2> + Now when mod_rewrite is triggered in these two API phases, it + reads the configured rulesets from its configuration + structure (which itself was either created on startup for + per-server context or during the directory walk of the Apache + kernel for per-directory context). Then the URL rewriting + engine is started with the contained ruleset (one or more + rules together with their conditions). The operation of the + URL rewriting engine itself is exactly the same for both + configuration contexts. Only the final result processing is + different. + + <p>The order of rules in the ruleset is important because the + rewriting engine processes them in a special (and not very + obvious) order. The rule is this: The rewriting engine loops + through the ruleset rule by rule (<code>RewriteRule</code> + directives) and when a particular rule matches it optionally + loops through existing corresponding conditions + (<code>RewriteCond</code> directives). For historical reasons + the conditions are given first, and so the control flow is a + little bit long-winded. See Figure 1 for more details.</p> + + <div align="CENTER"> + <table cellspacing="0" cellpadding="2" border="0"> + <tr> + <td bgcolor="#CCCCCC"><img + src="../images/mod_rewrite_fig1.gif" width="428" + height="385" + alt="[Needs graphics capability to display]" /></td> + </tr> + + <tr> + <td align="CENTER"><strong>Figure 1:</strong> The + control flow through the rewriting ruleset</td> + </tr> + </table> + </div> + + <p>As you can see, first the URL is matched against the + <em>Pattern</em> of each rule. When it fails mod_rewrite + immediately stops processing this rule and continues with the + next rule. If the <em>Pattern</em> matches, mod_rewrite looks + for corresponding rule conditions. If none are present, it + just substitutes the URL with a new value which is + constructed from the string <em>Substitution</em> and goes on + with its rule-looping. But if conditions exist, it starts an + inner loop for processing them in the order that they are + listed. For conditions the logic is different: we don't match + a pattern against the current URL. Instead we first create a + string <em>TestString</em> by expanding variables, + back-references, map lookups, <em>etc.</em> and then we try + to match <em>CondPattern</em> against it. If the pattern + doesn't match, the complete set of conditions and the + corresponding rule fails. If the pattern matches, then the + next condition is processed until no more conditions are + available. If all conditions match, processing is continued + with the substitution of the URL with + <em>Substitution</em>.</p> + + <h2><a id="quoting" name="quoting">Quoting Special + Characters</a></h2> + + <p>As of Apache 1.3.20, special characters in + <i>TestString</i> and <i>Substitution</i> strings can be + escaped (that is, treated as normal characters without their + usual special meaning) by prefixing them with a slosh ('\') + character. In other words, you can include an actual + dollar-sign character in a <i>Substitution</i> string by + using '<code>\$</code>'; this keeps mod_rewrite from trying + to treat it as a backreference.</p> + + <h2><a id="InternalBackRefs" name="InternalBackRefs">Regex + Back-Reference Availability</a></h2> + One important thing here has to be remembered: Whenever you + use parentheses in <em>Pattern</em> or in one of the + <em>CondPattern</em>, back-references are internally created + which can be used with the strings <code>$N</code> and + <code>%N</code> (see below). These are available for creating + the strings <em>Substitution</em> and <em>TestString</em>. + Figure 2 shows to which locations the back-references are + transfered for expansion. + + <div align="CENTER"> + <table cellspacing="0" cellpadding="2" border="0"> + <tr> + <td bgcolor="#CCCCCC"><img + src="../images/mod_rewrite_fig2.gif" width="381" + height="179" + alt="[Needs graphics capability to display]" /></td> + </tr> + + <tr> + <td align="CENTER"><strong>Figure 2:</strong> The + back-reference flow through a rule</td> + </tr> + </table> + </div> + + <p>We know this was a crash course on mod_rewrite's internal + processing. But you will benefit from this knowledge when + reading the following documentation of the available + directives.</p> + <hr noshade="noshade" size="1" /> + + <center> + <h1><a id="Configuration" + name="Configuration">Configuration Directives</a></h1> + </center> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteEngine" + name="RewriteEngine">RewriteEngine</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteEngine + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>RewriteEngine + off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache + 1.2<br /> + + + <p>The <code>RewriteEngine</code> 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 <code>SCRIPT_URx</code> + environment variables.</p> + + <p>Use this directive to disable the module instead of + commenting out all the <code>RewriteRule</code> + directives!</p> + + <p>Note that, by default, rewrite configurations are not + inherited. This means that you need to have a + <code>RewriteEngine on</code> directive for each virtual host + in which you wish to use it.</p> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteOptions" + name="RewriteOptions">RewriteOptions</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteOptions + <em>Option</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache + 1.2<br /> + + + <p>The <code>RewriteOptions</code> 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:</p> + + <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 are inherited. In per-directory context this means + that conditions and rules of the parent directory's + <code>.htaccess</code> configuration are inherited.</li> + </ul> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteLog" name="RewriteLog">RewriteLog</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteLog + <em>file-path</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache + 1.2<br /> + + + <p>The <code>RewriteLog</code> 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 + ('<code>/</code>') 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="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Note</strong>: 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 then output to a + logfile it still creates the logfile output internally. + <strong>This will slow down the server with no advantage + to the administrator!</strong> To disable logging either + remove or comment out the <code>RewriteLog</code> + directive or use <code>RewriteLogLevel 0</code>!</td> + </tr> + </table> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Security</strong>: 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><strong>Example:</strong></p> + + <blockquote> +<pre> RewriteLog "/usr/local/var/apache/logs/rewrite.log" -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLogLevel">RewriteLogLevel</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteLogLevel <EM>Level</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>RewriteLogLevel 0</CODE> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteLogLevel</CODE> directive sets 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="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> Using a high value for <EM>Level</EM> will slow down -your Apache server dramatically! Use the rewriting logfile at -a <EM>Level</EM> greater than 2 only for debugging! -</TD></TR> -</TABLE> - - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> -<PRE> +</pre> + </blockquote> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteLogLevel" + name="RewriteLogLevel">RewriteLogLevel</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteLogLevel + <em>Level</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>RewriteLogLevel 0</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache + 1.2<br /> + + + <p>The <code>RewriteLogLevel</code> directive sets 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> + + <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="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Notice:</strong> Using a high value for + <em>Level</em> will slow down your Apache server + dramatically! Use the rewriting logfile at a + <em>Level</em> greater than 2 only for debugging!</td> + </tr> + </table> + + <p><strong>Example:</strong></p> + + <blockquote> +<pre> RewriteLogLevel 3 -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLock">RewriteLock</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteLock <EM>file-path</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3<BR> - -<P> -This directive sets the filename for a synchronization lockfile which -mod_rewrite needs to communicate with <SAMP>RewriteMap</SAMP> -<EM>programs</EM>. Set this lockfile to a local path (not on a NFS-mounted -device) when you want to use a rewriting map-program. It is not required for -other types of rewriting maps. - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteMap">RewriteMap</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteMap <EM>MapName </EM> - <EM>MapType</EM>:<EM>MapSource</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> not used per default<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteMap</CODE> directive defines a <EM>Rewriting Map</EM> -which can be used inside rule substitution strings by the mapping-functions -to insert/substitute fields through a key lookup. The source of this -lookup can be of various types. -<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 one of the following constructs: - -<BLOCKQUOTE><STRONG> -<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> -<CODE>}</CODE><BR> -<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> -<CODE>|</CODE> <EM>DefaultValue</EM> <CODE>}</CODE> -</STRONG></BLOCKQUOTE> - -When such a construct 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 construct is substituted by <EM>SubstValue</EM>. If -the key is not found then it is substituted by <EM>DefaultValue</EM> or -by the empty string if no <EM>DefaultValue</EM> was specified. - -<P> -The following combinations for <EM>MapType</EM> and <EM>MapSource</EM> -can be used: - -<UL> -<LI><STRONG>Standard Plain Text</STRONG><BR> - MapType: <CODE>txt</CODE>, MapSource: Unix filesystem path to valid regular - file - <P> - This is the standard rewriting map feature where the <EM>MapSource</EM> is - a plain ASCII file containing either blank lines, comment lines (starting - with a '#' character) or pairs like the following - one per line. - - <BLOCKQUOTE><STRONG> - <EM>MatchingKey</EM> <EM>SubstValue</EM> - </STRONG></BLOCKQUOTE> - - <P> - Example: -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> +</pre> + </blockquote> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteLock" + name="RewriteLock">RewriteLock</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteLock + <em>file-path</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache + 1.3<br /> + + + <p>This directive sets the filename for a synchronization + lockfile which mod_rewrite needs to communicate with + <samp>RewriteMap</samp> <em>programs</em>. Set this lockfile + to a local path (not on a NFS-mounted device) when you want + to use a rewriting map-program. It is not required for other + types of rewriting maps.</p> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteMap" name="RewriteMap">RewriteMap</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteMap + <em>MapName</em> <em>MapType</em>:<em>MapSource</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> not used per + default<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> <em>Not + applicable</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 + (partially), Apache 1.3<br /> + + + <p>The <code>RewriteMap</code> directive defines a + <em>Rewriting Map</em> which can be used inside rule + substitution strings by the mapping-functions to + insert/substitute fields through a key lookup. The source of + this lookup can be of various types.</p> + + <p>The <a id="mapfunc" 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 one of the following constructs:</p> + + <blockquote> + <strong><code>${</code> <em>MapName</em> <code>:</code> + <em>LookupKey</em> <code>}</code><br /> + <code>${</code> <em>MapName</em> <code>:</code> + <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> + <code>}</code></strong> + </blockquote> + When such a construct 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 construct is substituted by + <em>SubstValue</em>. If the key is not found then it is + substituted by <em>DefaultValue</em> or by the empty string + if no <em>DefaultValue</em> was specified. + + <p>The following combinations for <em>MapType</em> and + <em>MapSource</em> can be used:</p> + + <ul> + <li> + <strong>Standard Plain Text</strong><br /> + MapType: <code>txt</code>, MapSource: Unix filesystem + path to valid regular file + + <p>This is the standard rewriting map feature where the + <em>MapSource</em> is a plain ASCII file containing + either blank lines, comment lines (starting with a '#' + character) or pairs like the following - one per + line.</p> + + <blockquote> + <strong><em>MatchingKey</em> + <em>SubstValue</em></strong> + </blockquote> + + <p>Example:</p> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> ## ## map.txt -- rewriting map ## Ralf.S.Engelschall rse # Bastard Operator From Hell Mr.Joe.Average joe # Mr. Average -</PRE></TD></TR> -</TABLE> - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> +</pre> + </td> + </tr> + </table> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> RewriteMap real-to-user txt:/path/to/file/map.txt -</PRE></TD></TR> -</TABLE> - -<P> -<LI><STRONG>Randomized Plain Text</STRONG><BR> - MapType: <CODE>rnd</CODE>, MapSource: Unix filesystem path to valid regular - file - <P> - This is identical to the Standard Plain Text variant above but with a - special - post-processing feature: After looking up a value it is parsed according - to contained ``<CODE>|</CODE>'' characters which have the meaning of - ``or''. - In other words they indicate a set of alternatives from which the actual - returned value is chosen randomly. Although this sounds crazy and useless, - it - was actually designed for load balancing in a reverse proxy situation where - the looked up values are server names. - Example: -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> +</pre> + </td> + </tr> + </table> + </li> + + <li> + <strong>Randomized Plain Text</strong><br /> + MapType: <code>rnd</code>, MapSource: Unix filesystem + path to valid regular file + + <p>This is identical to the Standard Plain Text variant + above but with a special post-processing feature: After + looking up a value it is parsed according to contained + ``<code>|</code>'' characters which have the meaning of + ``or''. In other words they indicate a set of + alternatives from which the actual returned value is + chosen randomly. Although this sounds crazy and useless, + it was actually designed for load balancing in a reverse + proxy situation where the looked up values are server + names. Example:</p> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> ## ## map.txt -- rewriting map ## static www1|www2|www3|www4 dynamic www5|www6 -</PRE></TD></TR> -</TABLE> - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> +</pre> + </td> + </tr> + </table> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> RewriteMap servers rnd:/path/to/file/map.txt -</PRE></TD></TR> -</TABLE> - -<P> -<LI><STRONG>Hash File</STRONG><BR> - MapType: <CODE>dbm</CODE>, MapSource: Unix filesystem path to valid - regular file - <P> - Here the source is a binary NDBM format file containing the same contents - as a <EM>Plain Text</EM> format file, but in a special representation - which is optimized for really fast lookups. You can create such a file with - any NDBM tool or with the following Perl script: - <P> - <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> - <TR><TD><PRE> +</pre> + </td> + </tr> + </table> + </li> + + <li> + <strong>Hash File</strong><br /> + MapType: <code>dbm</code>, MapSource: Unix filesystem + path to valid regular file + + <p>Here the source is a binary NDBM format file + containing the same contents as a <em>Plain Text</em> + format file, but in a special representation which is + optimized for really fast lookups. You can create such a + file with any NDBM tool or with the following Perl + script:</p> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> #!/path/to/bin/perl ## ## txt2dbm -- convert txt map to dbm format @@ -760,169 +739,198 @@ while (<TXT>) { $DB{$1} = $2 if (m|^\s*(\S+)\s+(\S+)$|); } dbmclose(%DB); -close(TXT)</PRE></TD></TR> - </TABLE> - <P> - <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> - <TR><TD><PRE>$ txt2dbm map.txt map.db </PRE></TD></TR> - </TABLE> -<P> -<LI><STRONG>Internal Function</STRONG><BR> - MapType: <CODE>int</CODE>, MapSource: Internal Apache function - <P> - Here the source is an internal Apache function. Currently you cannot - create your own, but the following functions already exists: - <UL> - <LI><STRONG>toupper</STRONG>:<BR> - Converts the looked up key to all upper case. - <LI><STRONG>tolower</STRONG>:<BR> - Converts the looked up key to all lower case. - <LI><STRONG>escape</STRONG>:<BR> - Translates special characters in the looked up key to hex-encodings. - <LI><STRONG>unescape</STRONG>:<BR> - Translates hex-encodings in the looked up key back to special characters. - </UL> -<P> -<LI><STRONG>External Rewriting Program</STRONG><BR> - MapType: <CODE>prg</CODE>, MapSource: Unix filesystem path to valid - regular file - <P> - Here the source is a program, not a map file. To create it you - can use the language of your choice, but the result has to be a - executable (<EM>i.e.</EM>, either object-code or a script with the - magic cookie trick '<CODE>#!/path/to/interpreter</CODE>' as the - first line). - <P> - This program is started once at startup of the Apache servers and then - communicates with the rewriting engine over its <CODE>stdin</CODE> and - <CODE>stdout</CODE> file-handles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string on - <CODE>stdin</CODE>. It then has to give back the looked-up value as a - newline-terminated string on <CODE>stdout</CODE> or the four-character - string ``<CODE>NULL</CODE>'' if it fails (<EM>i.e.</EM>, there is no - corresponding value - for the given key). A trivial program which will implement a 1:1 map - (<EM>i.e.</EM>, key == value) could be: - <P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> +close(TXT) +</pre> + </td> + </tr> + </table> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> +$ txt2dbm map.txt map.db +</pre> + </td> + </tr> + </table> + </li> + + <li> + <strong>Internal Function</strong><br /> + MapType: <code>int</code>, MapSource: Internal Apache + function + + <p>Here the source is an internal Apache function. + Currently you cannot create your own, but the following + functions already exists:</p> + + <ul> + <li><strong>toupper</strong>:<br /> + Converts the looked up key to all upper case.</li> + + <li><strong>tolower</strong>:<br /> + Converts the looked up key to all lower case.</li> + + <li><strong>escape</strong>:<br /> + Translates special characters in the looked up key to + hex-encodings.</li> + + <li><strong>unescape</strong>:<br /> + Translates hex-encodings in the looked up key back to + special characters.</li> + </ul> + </li> + + <li> + <strong>External Rewriting Program</strong><br /> + MapType: <code>prg</code>, MapSource: Unix filesystem + path to valid regular file + + <p>Here the source is a program, not a map file. To + create it you can use the language of your choice, but + the result has to be a executable (<em>i.e.</em>, either + object-code or a script with the magic cookie trick + '<code>#!/path/to/interpreter</code>' as the first + line).</p> + + <p>This program is started once at startup of the Apache + servers and then communicates with the rewriting engine + over its <code>stdin</code> and <code>stdout</code> + file-handles. For each map-function lookup it will + receive the key to lookup as a newline-terminated string + on <code>stdin</code>. It then has to give back the + looked-up value as a newline-terminated string on + <code>stdout</code> or the four-character string + ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there + is no corresponding value for the given key). A trivial + program which will implement a 1:1 map (<em>i.e.</em>, + key == value) could be:</p> + + <table border="0" cellspacing="1" cellpadding="5" + bgcolor="#F0F0F0"> + <tr> + <td> +<pre> #!/usr/bin/perl $| = 1; while (<STDIN>) { # ...put here any transformations or lookups... print $_; } -</PRE></TD></TR> -</TABLE> - <P> - But be very careful:<BR> - <OL> - <LI>``<EM>Keep it simple, stupid</EM>'' (KISS), because - if this program hangs it will hang the Apache server - when the rule occurs. - <LI>Avoid one common mistake: never do buffered I/O on <CODE>stdout</CODE>! - This will cause a deadloop! Hence the ``<CODE>$|=1</CODE>'' in the - above example... - <LI>Use the <SAMP>RewriteLock</SAMP> directive to define a lockfile - mod_rewrite can use to synchronize the communication to the program. - By default no such synchronization takes place. - </OL> -</UL> - -The <CODE>RewriteMap</CODE> directive can occur more than once. For each -mapping-function use one <CODE>RewriteMap</CODE> directive to declare its -rewriting mapfile. While you cannot <STRONG>declare</STRONG> a map in -per-directory context it is of course possible to <STRONG>use</STRONG> -this map in per-directory context. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note:</STRONG> For plain text and DBM format files the looked-up -keys are cached in-core -until the <CODE>mtime</CODE> of the mapfile changes or the server does a -restart. This way you can have map-functions in rules which are used -for <STRONG>every</STRONG> request. This is no problem, because the -external lookup only happens once! -</TD></TR> -</TABLE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteBase">RewriteBase</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteBase <EM>URL-path</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>default is the physical directory path</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteBase</CODE> directive explicitly sets the base URL for -per-directory rewrites. As you will see below, <CODE>RewriteRule</CODE> can be -used in per-directory config files (<CODE>.htaccess</CODE>). There it will act -locally, <EM>i.e.</EM>, 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 back to the path. - -<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. <STRONG>But at most websites URLs are -NOT directly related to physical filename paths, so this -assumption will usually be wrong!</STRONG> There you have to use the -<CODE>RewriteBase</CODE> directive to specify the correct URL-prefix. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> If your webserver's URLs are <STRONG>not</STRONG> -directly related to physical file paths, you have to use -<CODE>RewriteBase</CODE> in every -<CODE>.htaccess</CODE> files where you want to use <CODE>RewriteRule</CODE> -directives. -</TD></TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> - -<BLOCKQUOTE> - Assume the following per-directory config file: - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> +</pre> + </td> + </tr> + </table> + + <p>But be very careful:<br /> + </p> + + <ol> + <li>``<em>Keep it simple, stupid</em>'' (KISS), because + if this program hangs it will hang the Apache server + when the rule occurs.</li> + + <li>Avoid one common mistake: never do buffered I/O on + <code>stdout</code>! This will cause a deadloop! Hence + the ``<code>$|=1</code>'' in the above example...</li> + + <li>Use the <samp>RewriteLock</samp> directive to + define a lockfile mod_rewrite can use to synchronize + the communication to the program. By default no such + synchronization takes place.</li> + </ol> + </li> + </ul> + The <code>RewriteMap</code> directive can occur more than + once. For each mapping-function use one + <code>RewriteMap</code> directive to declare its rewriting + mapfile. While you cannot <strong>declare</strong> a map in + per-directory context it is of course possible to + <strong>use</strong> this map in per-directory context. + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Note:</strong> For plain text and DBM format + files the looked-up keys are cached in-core until the + <code>mtime</code> of the mapfile changes or the server + does a restart. This way you can have map-functions in + rules which are used for <strong>every</strong> request. + This is no problem, because the external lookup only + happens once!</td> + </tr> + </table> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteBase" + name="RewriteBase">RewriteBase</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteBase + <em>URL-path</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>default is the + physical directory path</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> directory, + .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> + <em>FileInfo</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache + 1.2<br /> + + + <p>The <code>RewriteBase</code> directive explicitly sets the + base URL for per-directory rewrites. As you will see below, + <code>RewriteRule</code> can be used in per-directory config + files (<code>.htaccess</code>). There it will act locally, + <em>i.e.</em>, 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 back to the + path.</p> + + <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. <strong>But at most websites URLs are NOT + directly related to physical filename paths, so this + assumption will usually be wrong!</strong> There you have to + use the <code>RewriteBase</code> directive to specify the + correct URL-prefix.</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Notice:</strong> If your webserver's URLs are + <strong>not</strong> directly related to physical file + paths, you have to use <code>RewriteBase</code> in every + <code>.htaccess</code> files where you want to use + <code>RewriteRule</code> directives.</td> + </tr> + </table> + + <p><strong>Example:</strong></p> + + <blockquote> + Assume the following per-directory config file: + + <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, <EM>i.e.</EM>, the server -# has a 'Alias /xyz /abc/def' directive <EM>e.g.</EM> +# Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server +# has a 'Alias /xyz /abc/def' directive <em>e.g.</em> # RewriteEngine On @@ -933,25 +941,25 @@ RewriteBase /xyz # now the rewriting rules RewriteRule ^oldstuff\.html$ newstuff.html -</PRE></TD></TR> -</TABLE> - -<P> -In the above example, a request to <CODE>/xyz/oldstuff.html</CODE> -gets correctly -rewritten to the physical file <CODE>/abc/def/newstuff.html</CODE>. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<FONT SIZE=-1> -<STRONG>Note - For Apache hackers:</STRONG><BR> -The following list gives detailed information about the internal -processing steps: - -<P> -<PRE> -Request: +</pre> + </td> + </tr> + </table> + + <p>In the above example, a request to + <code>/xyz/oldstuff.html</code> gets correctly rewritten to + the physical file <code>/abc/def/newstuff.html</code>.</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td> + <font size="-1"><strong>Note - For Apache + hackers:</strong><br /> + The following list gives detailed information about + the internal processing steps:</font> +<pre> +<font size="-1">Request: /xyz/oldstuff.html Internal Processing: @@ -962,397 +970,428 @@ Internal Processing: 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 internally 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> - -<H3><A NAME="RewriteCond">RewriteCond</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteCond <EM>TestString</EM> - <EM>CondPattern</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteCond</CODE> directive defines a rule condition. Precede a -<CODE>RewriteRule</CODE> directive with one or more <CODE>RewriteCond</CODE> -directives. - -The following rewriting rule is only used if its pattern matches the current -state of the URI <STRONG>and</STRONG> if these additional conditions apply -too. - -<P> -<EM>TestString</EM> is a string which can contains the following -expanded constructs in addition to plain text: - -<UL> -<LI><STRONG>RewriteRule backreferences</STRONG>: These are backreferences of - the form - -<BLOCKQUOTE><STRONG> -<CODE>$N</CODE> -</STRONG></BLOCKQUOTE> - -(0 <= N <= 9) which provide access to the grouped parts (parenthesis!) -of the pattern from the corresponding <CODE>RewriteRule</CODE> directive (the -one following the current bunch of <CODE>RewriteCond</CODE> directives). - -<P> -<LI><STRONG>RewriteCond backreferences</STRONG>: These are backreferences of -the form - -<BLOCKQUOTE><STRONG> -<CODE>%N</CODE> -</STRONG></BLOCKQUOTE> - -(1 <= N <= 9) which provide access to the grouped parts (parentheses!) of -the pattern from the last matched <CODE>RewriteCond</CODE> directive in the -current bunch of conditions. - -<P> -<LI><STRONG>RewriteMap expansions</STRONG>: These are expansions of the form - -<BLOCKQUOTE><STRONG> -<CODE>${mapname:key|default}</CODE> -</STRONG></BLOCKQUOTE> - -See <A HREF="#mapfunc">the documentation for RewriteMap</A> for more details. - -<P> -<LI><STRONG>Server-Variables</STRONG>: These are variables - of the form - -<BLOCKQUOTE><STRONG> -<CODE>%{</CODE> <EM>NAME_OF_VARIABLE</EM> <CODE>}</CODE> -</STRONG></BLOCKQUOTE> - -where <EM>NAME_OF_VARIABLE</EM> can be a string -taken from the following list: - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD VALIGN=TOP> -<STRONG>HTTP headers:</STRONG><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> -<STRONG>connection & request:</STRONG><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> -<STRONG>server internals:</STRONG><P> -<FONT SIZE=-1> -DOCUMENT_ROOT<BR> -SERVER_ADMIN<BR> -SERVER_NAME<BR> -SERVER_ADDR<BR> -SERVER_PORT<BR> -SERVER_PROTOCOL<BR> -SERVER_SOFTWARE<BR> -</FONT> -</TD> - -<TD VALIGN=TOP> -<STRONG>system stuff:</STRONG><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> -<STRONG>specials:</STRONG><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="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> - -<p><STRONG>Notice:</STRONG> These variables all correspond to -the similarly named HTTP MIME-headers, C variables of the Apache -server or <CODE>struct tm</CODE> fields of the Unix system. Most -are documented elsewhere in the Manual or in the CGI specification. -Those that are special to mod_rewrite include:</p> - -<dl> -<dt><code>IS_SUBREQ</code></dt> -<dd>Will contain the text "true" if the request currently -being processed is a sub-request, "false" otherwise. Sub-requests may -be generated by modules that need to resolve additional files or URIs -in order to complete their tasks.</dd> - -<dt><code>API_VERSION</code></dt> -<dd>This is the version of the Apache module API (the internal -interface between server and module) in the current httpd build, as -defined in include/ap_mmn.h. The module API version corresponds to the -version of Apache in use (in the release version of Apache 1.3.14, for -instance, it is 19990320:10), but is mainly of interest to module -authors.</dd> - -<dt><code>THE_REQUEST</code></dt> -<dd>The full HTTP request line sent by the browser to the server -(e.g., "<code>GET /index.html HTTP/1.1</code>"). This does not include -any additional headers sent by the browser.</dd> - -<dt><code>REQUEST_URI</code></dt> -<dd>The resource requested in the HTTP request line. (In the -example above, this would be "/index.html".)</dd> - -<dt><code>REQUEST_FILENAME</code></dt> -<dd>The full local filesystem path to the file or script -matching the request.</dd> -</dl> - -</TD></TR> -</TABLE> - -</UL> - -<P> -Special Notes: - -<OL> -<LI>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, <EM>i.e.</EM>, the value of the <CODE>filename</CODE> field of -the internal -<CODE>request_rec</CODE> 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 <CODE>uri</CODE> -field of <CODE>request_rec</CODE>). - -<P> -<LI>There is the special format: <CODE>%{ENV:variable}</CODE> where -<EM>variable</EM> can be any environment variable. This is looked-up via -internal Apache structures and (if not found there) via <CODE>getenv()</CODE> -from the Apache server process. - -<P> -<LI>There is the special format: <CODE>%{HTTP:header}</CODE> where -<EM>header</EM> can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: <CODE>%{HTTP:Proxy-Connection}</CODE> -is the value of the HTTP header ``<CODE>Proxy-Connection:</CODE>''. - -<P> -<LI>There is the special format <CODE>%{LA-U:variable}</CODE> for look-aheads -which perform an internal (URL-based) sub-request to determine the final value -of <EM>variable</EM>. Use this when you want to use a variable for rewriting -which is actually set later in an API phase and thus is not available at the -current stage. For instance when you want to rewrite according to the -<CODE>REMOTE_USER</CODE> variable from within the per-server context -(<CODE>httpd.conf</CODE> file) you have to use <CODE>%{LA-U:REMOTE_USER}</CODE> -because this variable is set by the authorization phases which come -<EM>after</EM> the URL translation phase where mod_rewrite operates. On the -other hand, because mod_rewrite implements its per-directory context -(<CODE>.htaccess</CODE> file) via the Fixup phase of the API and because the -authorization phases come <EM>before</EM> this phase, you just can use -<CODE>%{REMOTE_USER}</CODE> there. - -<P> -<LI>There is the special format: <CODE>%{LA-F:variable}</CODE> which performs an -internal (filename-based) sub-request to determine the final value of -<EM>variable</EM>. Most of the time this is the same as LA-U above. -</OL> - -<P> -<EM>CondPattern</EM> is the condition pattern, <EM>i.e.</EM>, a regular -expression -which is applied to the current instance of the <EM>TestString</EM>, -<EM>i.e.</EM>, <EM>TestString</EM> is evaluated and then matched against -<EM>CondPattern</EM>. - -<P> -<STRONG>Remember:</STRONG> <EM>CondPattern</EM> is a standard -<EM>Extended Regular Expression</EM> with some additions: - -<OL> -<LI>You can prefix the pattern string with a '<CODE>!</CODE>' character -(exclamation mark) to specify a <STRONG>non</STRONG>-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>'<STRONG><CondPattern</STRONG>' (is lexically lower)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexically to <EM>TestString</EM>. True if -<EM>TestString</EM> is lexically lower than <EM>CondPattern</EM>. -<P> -<LI>'<STRONG>>CondPattern</STRONG>' (is lexically greater)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexically to <EM>TestString</EM>. True if -<EM>TestString</EM> is lexically greater than <EM>CondPattern</EM>. -<P> -<LI>'<STRONG>=CondPattern</STRONG>' (is lexically equal)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexically to <EM>TestString</EM>. True if -<EM>TestString</EM> is lexically equal to <EM>CondPattern</EM>, i.e the -two strings are exactly equal (character by character). -If <EM>CondPattern</EM> is just <SAMP>""</SAMP> (two quotation marks) this -compares <EM>TestString</EM> to the empty string. -<P> -<LI>'<STRONG>-d</STRONG>' (is <STRONG>d</STRONG>irectory)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a directory. -<P> -<LI>'<STRONG>-f</STRONG>' (is regular <STRONG>f</STRONG>ile)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a regular file. -<P> -<LI>'<STRONG>-s</STRONG>' (is regular file with <STRONG>s</STRONG>ize)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a regular file with size greater than zero. -<P> -<LI>'<STRONG>-l</STRONG>' (is symbolic <STRONG>l</STRONG>ink)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a symbolic link. -<P> -<LI>'<STRONG>-F</STRONG>' (is existing file via subrequest)<BR> -Checks if <EM>TestString</EM> 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>'<STRONG>-U</STRONG>' (is existing URL via subrequest)<BR> -Checks if <EM>TestString</EM> 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 server's performance! -</UL> -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> -All of these tests can also be prefixed by an exclamation mark ('!') -to negate their meaning. -</TD></TR> -</TABLE> -</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 <CODE>RewriteCond</CODE> directive. <EM>Flags</EM> -is a comma-separated list of the following flags: - -<UL> -<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> - This makes the test case-insensitive, <EM>i.e.</EM>, there is - no difference between 'A-Z' and 'a-z' both in the expanded - <EM>TestString</EM> and the <EM>CondPattern</EM>. - This flag is effective only for comparisons between - <EM>TestString</EM> and <EM>CondPattern</EM>. It has no - effect on filesystem and subrequest checks. -<P> -<LI>'<STRONG><CODE>ornext|OR</CODE></STRONG>' (<STRONG>or</STRONG> next condition)<BR> - Use this to combine rule conditions with a local OR instead of the - implicit AND. Typical example: - <P> -<BLOCKQUOTE><PRE> +</font> +</pre> + <font size="-1">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 + internally 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> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteCond" + name="RewriteCond">RewriteCond</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteCond + <em>TestString</em> <em>CondPattern</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> + <em>FileInfo</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 + (partially), Apache 1.3<br /> + + + <p>The <code>RewriteCond</code> directive defines a rule + condition. Precede a <code>RewriteRule</code> directive with + one or more <code>RewriteCond</code> directives. The + following rewriting rule is only used if its pattern matches + the current state of the URI <strong>and</strong> if these + additional conditions apply too.</p> + + <p><em>TestString</em> is a string which can contains the + following expanded constructs in addition to plain text:</p> + + <ul> + <li> + <strong>RewriteRule backreferences</strong>: These are + backreferences of the form + + <blockquote> + <strong><code>$N</code></strong> + </blockquote> + (0 <= N <= 9) which provide access to the grouped + parts (parenthesis!) of the pattern from the + corresponding <code>RewriteRule</code> directive (the one + following the current bunch of <code>RewriteCond</code> + directives). + </li> + + <li> + <strong>RewriteCond backreferences</strong>: These are + backreferences of the form + + <blockquote> + <strong><code>%N</code></strong> + </blockquote> + (1 <= N <= 9) which provide access to the grouped + parts (parentheses!) of the pattern from the last matched + <code>RewriteCond</code> directive in the current bunch + of conditions. + </li> + + <li> + <strong>RewriteMap expansions</strong>: These are + expansions of the form + + <blockquote> + <strong><code>${mapname:key|default}</code></strong> + </blockquote> + See <a href="#mapfunc">the documentation for + RewriteMap</a> for more details. + </li> + + <li> + <strong>Server-Variables</strong>: These are variables of + the form + + <blockquote> + <strong><code>%{</code> <em>NAME_OF_VARIABLE</em> + <code>}</code></strong> + </blockquote> + where <em>NAME_OF_VARIABLE</em> can be a string taken + from the following list: + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td valign="TOP"> + <strong>HTTP headers:</strong> + + <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></p> + </td> + + <td valign="TOP"> + <strong>connection & request:</strong> + + <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></p> + </td> + </tr> + + <tr> + <td valign="TOP"> + <strong>server internals:</strong> + + <p><font size="-1">DOCUMENT_ROOT<br /> + SERVER_ADMIN<br /> + SERVER_NAME<br /> + SERVER_ADDR<br /> + SERVER_PORT<br /> + SERVER_PROTOCOL<br /> + SERVER_SOFTWARE<br /> + </font></p> + </td> + + <td valign="TOP"> + <strong>system stuff:</strong> + + <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></p> + </td> + + <td valign="TOP"> + <strong>specials:</strong> + + <p><font size="-1">API_VERSION<br /> + THE_REQUEST<br /> + REQUEST_URI<br /> + REQUEST_FILENAME<br /> + IS_SUBREQ<br /> + </font></p> + </td> + </tr> + </table> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td> + <p><strong>Notice:</strong> These variables all + correspond to the similarly named HTTP + MIME-headers, C variables of the Apache server or + <code>struct tm</code> fields of the Unix system. + Most are documented elsewhere in the Manual or in + the CGI specification. Those that are special to + mod_rewrite include:</p> + + <dl> + <dt><code>IS_SUBREQ</code></dt> + + <dd>Will contain the text "true" if the request + currently being processed is a sub-request, + "false" otherwise. Sub-requests may be generated + by modules that need to resolve additional files + or URIs in order to complete their tasks.</dd> + + <dt><code>API_VERSION</code></dt> + + <dd>This is the version of the Apache module API + (the internal interface between server and + module) in the current httpd build, as defined in + include/ap_mmn.h. The module API version + corresponds to the version of Apache in use (in + the release version of Apache 1.3.14, for + instance, it is 19990320:10), but is mainly of + interest to module authors.</dd> + + <dt><code>THE_REQUEST</code></dt> + + <dd>The full HTTP request line sent by the + browser to the server (e.g., "<code>GET + /index.html HTTP/1.1</code>"). This does not + include any additional headers sent by the + browser.</dd> + + <dt><code>REQUEST_URI</code></dt> + + <dd>The resource requested in the HTTP request + line. (In the example above, this would be + "/index.html".)</dd> + + <dt><code>REQUEST_FILENAME</code></dt> + + <dd>The full local filesystem path to the file or + script matching the request.</dd> + </dl> + </td> + </tr> + </table> + </li> + </ul> + + <p>Special Notes:</p> + + <ol> + <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME + contain the same value, <em>i.e.</em>, the value of the + <code>filename</code> field of the internal + <code>request_rec</code> 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 + <code>uri</code> field of <code>request_rec</code>).</li> + + <li>There is the special format: + <code>%{ENV:variable}</code> where <em>variable</em> can be + any environment variable. This is looked-up via internal + Apache structures and (if not found there) via + <code>getenv()</code> from the Apache server process.</li> + + <li>There is the special format: + <code>%{HTTP:header}</code> where <em>header</em> can be + any HTTP MIME-header name. This is looked-up from the HTTP + request. Example: <code>%{HTTP:Proxy-Connection}</code> is + the value of the HTTP header + ``<code>Proxy-Connection:</code>''.</li> + + <li>There is the special format + <code>%{LA-U:variable}</code> for look-aheads which perform + an internal (URL-based) sub-request to determine the final + value of <em>variable</em>. Use this when you want to use a + variable for rewriting which is actually set later in an + API phase and thus is not available at the current stage. + For instance when you want to rewrite according to the + <code>REMOTE_USER</code> variable from within the + per-server context (<code>httpd.conf</code> file) you have + to use <code>%{LA-U:REMOTE_USER}</code> because this + variable is set by the authorization phases which come + <em>after</em> the URL translation phase where mod_rewrite + operates. On the other hand, because mod_rewrite implements + its per-directory context (<code>.htaccess</code> file) via + the Fixup phase of the API and because the authorization + phases come <em>before</em> this phase, you just can use + <code>%{REMOTE_USER}</code> there.</li> + + <li>There is the special format: + <code>%{LA-F:variable}</code> which performs an internal + (filename-based) sub-request to determine the final value + of <em>variable</em>. Most of the time this is the same as + LA-U above.</li> + </ol> + + <p><em>CondPattern</em> is the condition pattern, + <em>i.e.</em>, a regular expression which is applied to the + current instance of the <em>TestString</em>, <em>i.e.</em>, + <em>TestString</em> is evaluated and then matched against + <em>CondPattern</em>.</p> + + <p><strong>Remember:</strong> <em>CondPattern</em> is a + standard <em>Extended Regular Expression</em> with some + additions:</p> + + <ol> + <li>You can prefix the pattern string with a + '<code>!</code>' character (exclamation mark) to specify a + <strong>non</strong>-matching pattern.</li> + + <li> + There are some special variants of <em>CondPatterns</em>. + Instead of real regular expression strings you can also + use one of the following: + + <ul> + <li>'<strong><CondPattern</strong>' (is lexically + lower)<br /> + Treats the <em>CondPattern</em> as a plain string and + compares it lexically to <em>TestString</em>. True if + <em>TestString</em> is lexically lower than + <em>CondPattern</em>.</li> + + <li>'<strong>>CondPattern</strong>' (is lexically + greater)<br /> + Treats the <em>CondPattern</em> as a plain string and + compares it lexically to <em>TestString</em>. True if + <em>TestString</em> is lexically greater than + <em>CondPattern</em>.</li> + + <li>'<strong>=CondPattern</strong>' (is lexically + equal)<br /> + Treats the <em>CondPattern</em> as a plain string and + compares it lexically to <em>TestString</em>. True if + <em>TestString</em> is lexically equal to + <em>CondPattern</em>, i.e the two strings are exactly + equal (character by character). If <em>CondPattern</em> + is just <samp>""</samp> (two quotation marks) this + compares <em>TestString</em> to the empty string.</li> + + <li>'<strong>-d</strong>' (is + <strong>d</strong>irectory)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a directory.</li> + + <li>'<strong>-f</strong>' (is regular + <strong>f</strong>ile)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a regular file.</li> + + <li>'<strong>-s</strong>' (is regular file with + <strong>s</strong>ize)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a regular file with size greater + than zero.</li> + + <li>'<strong>-l</strong>' (is symbolic + <strong>l</strong>ink)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a symbolic link.</li> + + <li>'<strong>-F</strong>' (is existing file via + subrequest)<br /> + Checks if <em>TestString</em> 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!</li> + + <li>'<strong>-U</strong>' (is existing URL via + subrequest)<br /> + Checks if <em>TestString</em> 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 server's performance!</li> + </ul> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Notice:</strong> All of these tests can + also be prefixed by an exclamation mark ('!') to + negate their meaning.</td> + </tr> + </table> + </li> + </ol> + + <p>Additionally you can set special flags for + <em>CondPattern</em> by appending</p> + + <blockquote> + <strong><code>[</code><em>flags</em><code>]</code></strong> + </blockquote> + as the third argument to the <code>RewriteCond</code> + directive. <em>Flags</em> is a comma-separated list of the + following flags: + + <ul> + <li>'<strong><code>nocase|NC</code></strong>' + (<strong>n</strong>o <strong>c</strong>ase)<br /> + This makes the test case-insensitive, <em>i.e.</em>, there + is no difference between 'A-Z' and 'a-z' both in the + expanded <em>TestString</em> and the <em>CondPattern</em>. + This flag is effective only for comparisons between + <em>TestString</em> and <em>CondPattern</em>. It has no + effect on filesystem and subrequest checks.</li> + + <li> + '<strong><code>ornext|OR</code></strong>' + (<strong>or</strong> next condition)<br /> + Use this to combine rule conditions with a local OR + instead of the implicit AND. Typical example: + + <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 would have to write the cond/rule three times. -</UL> - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> - -To rewrite the Homepage of a site according to the ``<CODE>User-Agent:</CODE>'' -header of the request, you can use the following: - -<BLOCKQUOTE><PRE> +</pre> + </blockquote> + Without this flag you would have to write the cond/rule + three times. + </li> + </ul> + + <p><strong>Example:</strong></p> + + <blockquote> + To rewrite the Homepage of a site according to the + ``<code>User-Agent:</code>'' header of the request, you can + use the following: + + <blockquote> +<pre> RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* RewriteRule ^/$ /homepage.max.html [L] @@ -1360,437 +1399,532 @@ 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, <EM>etc.</EM> If you use the Lynx browser (which is Terminal-based), then you -get the min homepage, which contains no images, no tables, <EM>etc.</EM> If you -use any other browser you get the standard homepage. -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteRule">RewriteRule</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteRule <EM>Pattern</EM> <EM>Substitution</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteRule</CODE> directive is the real rewriting workhorse. The -directive can occur more than once. Each directive then defines one single -rewriting rule. The <STRONG>definition order</STRONG> of these rules is -<STRONG>important</STRONG>, 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 and later 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 originally requested URL, because -any number of rules may already have 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>Text:</STRONG> - <STRONG><CODE>.</CODE></STRONG> Any single character - <STRONG><CODE>[</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: One of chars - <STRONG><CODE>[^</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: None of chars - text1<STRONG><CODE>|</CODE></STRONG>text2 Alternative: text1 or text2 - -<STRONG>Quantifiers:</STRONG> - <STRONG><CODE>?</CODE></STRONG> 0 or 1 of the preceding text - <STRONG><CODE>*</CODE></STRONG> 0 or N of the preceding text (N > 0) - <STRONG><CODE>+</CODE></STRONG> 1 or N of the preceding text (N > 1) - -<STRONG>Grouping:</STRONG> - <STRONG><CODE>(</CODE></STRONG>text<STRONG><CODE>)</CODE></STRONG> Grouping of text +</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, <em>etc.</em> + If you use the Lynx browser (which is Terminal-based), then + you get the min homepage, which contains no images, no + tables, <em>etc.</em> If you use any other browser you get + the standard homepage. + </blockquote> + <hr noshade="noshade" size="1" /> + + <h3><a id="RewriteRule" + name="RewriteRule">RewriteRule</a></h3> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> RewriteRule + <em>Pattern</em> <em>Substitution</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>None</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, + virtual host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> + <em>FileInfo</em><br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_rewrite.c<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 + (partially), Apache 1.3<br /> + + + <p>The <code>RewriteRule</code> directive is the real + rewriting workhorse. The directive can occur more than once. + Each directive then defines one single rewriting rule. The + <strong>definition order</strong> of these rules is + <strong>important</strong>, because this order is used when + applying the rules at run-time.</p> + + <p><a id="patterns" name="patterns"><em>Pattern</em></a> can + be (for Apache 1.1.x a System V8 and for Apache 1.2.x and + later a POSIX) <a id="regexp" 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 originally requested URL, + because any number of rules may already have matched and made + alterations to it.</p> + + <p>Some hints about the syntax of regular expressions:</p> + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td valign="TOP"> +<pre> +<strong>Text:</strong> + <strong><code>.</code></strong> Any single character + <strong><code>[</code></strong>chars<strong><code>]</code></strong> Character class: One of chars + <strong><code>[^</code></strong>chars<strong><code>]</code></strong> Character class: None of chars + text1<strong><code>|</code></strong>text2 Alternative: text1 or text2 + +<strong>Quantifiers:</strong> + <strong><code>?</code></strong> 0 or 1 of the preceding text + <strong><code>*</code></strong> 0 or N of the preceding text (N > 0) + <strong><code>+</code></strong> 1 or N of the preceding text (N > 1) + +<strong>Grouping:</strong> + <strong><code>(</code></strong>text<strong><code>)</code></strong> Grouping of text (either to set the borders of an alternative or - for making backreferences where the <STRONG>N</STRONG>th group can - be used on the RHS of a RewriteRule with <CODE>$</CODE><STRONG>N</STRONG>) - -<STRONG>Anchors:</STRONG> - <STRONG><CODE>^</CODE></STRONG> Start of line anchor - <STRONG><CODE>$</CODE></STRONG> End of line anchor - -<STRONG>Escaping:</STRONG> - <STRONG><CODE>\</CODE></STRONG>char escape that particular char - (for instance to specify the chars "<CODE>.[]()</CODE>" <EM>etc.</EM>) -</PRE> -</TD> -</TR> -</TABLE> - -<P> -For more information about regular expressions either have a look at your -local regex(3) manpage or its <CODE>src/regex/regex.3</CODE> copy in the -Apache 1.3 distribution. If you are interested in more detailed -information about regular expressions and their variants (POSIX regex, Perl -regex, <EM>etc.</EM>) have a look at the following dedicated book on this topic: - -<BLOCKQUOTE> -<EM>Mastering Regular Expressions</EM><BR> -Jeffrey E.F. Friedl<BR> -Nutshell Handbook Series<BR> -O'Reilly & Associates, Inc. 1997<BR> -ISBN 1-56592-257-3<BR> -</BLOCKQUOTE> - -<P> -Additionally in mod_rewrite the NOT character ('<CODE>!</CODE>') is a possible -pattern prefix. This gives you the ability to negate a pattern; to say, for -instance: ``<EM>if the current URL does <STRONG>NOT</STRONG> match this -pattern</EM>''. This can be used for exceptional cases, where it is easier to -match the negative pattern, or as a last default rule. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> 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 <CODE>$N</CODE> 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>back-references <CODE>$N</CODE> to the RewriteRule pattern -<LI>back-references <CODE>%N</CODE> to the last matched RewriteCond pattern -<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><STRONG>N</STRONG> (<STRONG>N</STRONG>=0..9) identifiers which -will be replaced by the contents of the <STRONG>N</STRONG>th group of the matched -<EM>Pattern</EM>. The server-variables are the same as for the -<EM>TestString</EM> of a <CODE>RewriteCond</CODE> directive. The -mapping-functions come from the <CODE>RewriteMap</CODE> 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 <STRONG>completely replaced</STRONG> by the <EM>Substitution</EM> and the -rewriting process goes on until there are no more rules unless explicitly -terminated by a <CODE><STRONG>L</STRONG></CODE> flag - see below. - -<P> -There is a special substitution string named '<CODE>-</CODE>' which means: -<STRONG>NO substitution</STRONG>! Sounds silly? No, it is useful to provide rewriting -rules which <STRONG>only</STRONG> match some URLs but do no substitution, <EM>e.g.</EM>, in -conjunction with the <STRONG>C</STRONG> (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="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note</STRONG>: There is a special feature: When you prefix a substitution -field with <CODE>http://</CODE><EM>thishost</EM>[<EM>:thisport</EM>] then -<STRONG>mod_rewrite</STRONG> 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. -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Remember:</STRONG> An unconditional external redirect to your own server will -not work with the prefix <CODE>http://thishost</CODE> because of this feature. -To achieve such a self-redirect, you have to use the <STRONG>R</STRONG>-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 <CODE>RewriteRule</CODE> directive. <EM>Flags</EM> is a -comma-separated list of the following flags: - -<UL> -<LI>'<STRONG><CODE>redirect|R</CODE> [=<EM>code</EM>]</STRONG>' (force <A NAME="redirect"><STRONG>r</STRONG>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 <EM>code</EM> 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: <CODE>temp</CODE> (default), <CODE>permanent</CODE>, - <CODE>seeother</CODE>. - Use it for rules which should - canonicalize the URL and give it back to the client, <EM>e.g.</EM>, translate - ``<CODE>/~</CODE>'' into ``<CODE>/u/</CODE>'' or always append a slash to - <CODE>/u/</CODE><EM>user</EM>, etc.<BR> - <P> - <STRONG>Note:</STRONG> 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>, rewriting continues. - 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 <STRONG>f</STRONG>orbidden)<BR> - This forces the current URL to be forbidden, <EM>i.e.</EM>, 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 <STRONG>g</STRONG>one)<BR> - This forces the current URL to be gone, <EM>i.e.</EM>, it immediately sends back a - HTTP response of 410 (GONE). Use this flag to mark pages which no longer - exist as gone. -<P> -<LI>'<STRONG><CODE>proxy|P</CODE></STRONG>' (force <STRONG>p</STRONG>roxy)<BR> - This flag forces the substitution part to be internally forced as a proxy - request and immediately (<EM>i.e.</EM>, rewriting rule processing stops here) put - through the <A HREF="mod_proxy.html">proxy module</A>. You have to make - sure that the substitution string is a valid URI (<EM>e.g.</EM>, typically starting - with <CODE>http://</CODE><EM>hostname</EM>) 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 <A - HREF="mod_proxy.html#proxypass">ProxyPass</A> directive, to map some - remote stuff into the namespace of the local server. - <P> - Notice: To use this functionality make sure you have the proxy module - compiled into your Apache server program. If you don't know please check - whether <CODE>mod_proxy.c</CODE> is part of the ``<CODE>httpd -l</CODE>'' - output. If yes, this functionality is available to mod_rewrite. If not, - then you first have to rebuild the ``<CODE>httpd</CODE>'' program with - mod_proxy enabled. -<P> -<LI>'<STRONG><CODE>last|L</CODE></STRONG>' (<STRONG>l</STRONG>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. For - example, use it to rewrite the root-path URL ('<CODE>/</CODE>') to a real - one, <EM>e.g.</EM>, '<CODE>/e/www/</CODE>'. -<P> -<LI>'<STRONG><CODE>next|N</CODE></STRONG>' (<STRONG>n</STRONG>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, <EM>i.e.</EM>, to - immediately go to the top of the loop. <BR> - <STRONG>But be careful not to create an infinite loop!</STRONG> -<P> -<LI>'<STRONG><CODE>chain|C</CODE></STRONG>' (<STRONG>c</STRONG>hained with next rule)<BR> - This flag chains the current rule with the next rule (which itself can - be chained with the following rule, <EM>etc.</EM>). This has the following - effect: if a rule matches, then processing continues as usual, <EM>i.e.</EM>, the - flag has no effect. If the rule does <STRONG>not</STRONG> match, then all following - chained rules are skipped. For instance, use it to remove the - ``<CODE>.www</CODE>'' part inside a per-directory rule set when you let an - external redirect happen (where the ``<CODE>.www</CODE>'' part should not to - occur!). -<P> -<LI>'<STRONG><CODE>type|T</CODE></STRONG>=<EM>MIME-type</EM>' (force MIME <STRONG>t</STRONG>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 <CODE>mod_alias</CODE> - directive <CODE>ScriptAlias</CODE> which internally forces all files inside - the mapped directory to have a MIME type of - ``<CODE>application/x-httpd-cgi</CODE>''. -<P> -<LI>'<STRONG><CODE>nosubreq|NS</CODE></STRONG>' (used only if <STRONG>n</STRONG>o internal <STRONG>s</STRONG>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 <CODE>mod_include</CODE> tries to find out - information about possible directory default files (<CODE>index.xxx</CODE>). - 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>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> - This makes the <EM>Pattern</EM> case-insensitive, <EM>i.e.</EM>, there is - no difference between 'A-Z' and 'a-z' when <EM>Pattern</EM> is matched - against the current URL. -<P> -<LI>'<STRONG><CODE>qsappend|QSA</CODE></STRONG>' (<STRONG>q</STRONG>uery <STRONG>s</STRONG>tring - <STRONG>a</STRONG>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>noescape|NE</CODE></STRONG>' (<STRONG>n</STRONG>o URI <STRONG>e</STRONG>scaping of output)<BR> - This flag keeps mod_rewrite from applying the usual URI escaping - rules to the result of a rewrite. Ordinarily, special characters - (such as '%', '$', ';', and so on) will be escaped into their - hexcode equivalents ('%25', '%24', and '%3B', respectively); this - flag prevents this from being done. This allows percent symbols - to appear in the output, as in - <pre> + for making backreferences where the <strong>N</strong>th group can + be used on the RHS of a RewriteRule with <code>$</code><strong>N</strong>) + +<strong>Anchors:</strong> + <strong><code>^</code></strong> Start of line anchor + <strong><code>$</code></strong> End of line anchor + +<strong>Escaping:</strong> + <strong><code>\</code></strong>char escape that particular char + (for instance to specify the chars "<code>.[]()</code>" <em>etc.</em>) +</pre> + </td> + </tr> + </table> + + <p>For more information about regular expressions either have + a look at your local regex(3) manpage or its + <code>src/regex/regex.3</code> copy in the Apache 1.3 + distribution. If you are interested in more detailed + information about regular expressions and their variants + (POSIX regex, Perl regex, <em>etc.</em>) have a look at the + following dedicated book on this topic:</p> + + <blockquote> + <em>Mastering Regular Expressions</em><br /> + Jeffrey E.F. Friedl<br /> + Nutshell Handbook Series<br /> + O'Reilly & Associates, Inc. 1997<br /> + ISBN 1-56592-257-3<br /> + </blockquote> + + <p>Additionally in mod_rewrite the NOT character + ('<code>!</code>') is a possible pattern prefix. This gives + you the ability to negate a pattern; to say, for instance: + ``<em>if the current URL does <strong>NOT</strong> match this + pattern</em>''. This can be used for exceptional cases, where + it is easier to match the negative pattern, or as a last + default rule.</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Notice:</strong> 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 <code>$N</code> in the substitution + string!</td> + </tr> + </table> + + <p><a id="rhs" 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</p> + + <ol> + <li>back-references <code>$N</code> to the RewriteRule + pattern</li> + + <li>back-references <code>%N</code> to the last matched + RewriteCond pattern</li> + + <li>server-variables as in rule condition test-strings + (<code>%{VARNAME}</code>)</li> + + <li><a href="#mapfunc">mapping-function</a> calls + (<code>${mapname:key|default}</code>)</li> + </ol> + Back-references are <code>$</code><strong>N</strong> + (<strong>N</strong>=0..9) identifiers which will be replaced + by the contents of the <strong>N</strong>th group of the + matched <em>Pattern</em>. The server-variables are the same + as for the <em>TestString</em> of a <code>RewriteCond</code> + directive. The mapping-functions come from the + <code>RewriteMap</code> 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 <strong>completely + replaced</strong> by the <em>Substitution</em> and the + rewriting process goes on until there are no more rules + unless explicitly terminated by a + <code><strong>L</strong></code> flag - see below.</p> + + <p>There is a special substitution string named + '<code>-</code>' which means: <strong>NO + substitution</strong>! Sounds silly? No, it is useful to + provide rewriting rules which <strong>only</strong> match + some URLs but do no substitution, <em>e.g.</em>, in + conjunction with the <strong>C</strong> (chain) flag to be + able to have more than one pattern to be applied before a + substitution occurs.</p> + + <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="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Note</strong>: There is a special feature: + When you prefix a substitution field with + <code>http://</code><em>thishost</em>[<em>:thisport</em>] + then <strong>mod_rewrite</strong> 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.</td> + </tr> + </table> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Remember:</strong> An unconditional external + redirect to your own server will not work with the prefix + <code>http://thishost</code> because of this feature. To + achieve such a self-redirect, you have to use the + <strong>R</strong>-flag (see below).</td> + </tr> + </table> + + <p>Additionally you can set special flags for + <em>Substitution</em> by appending</p> + + <blockquote> + <strong><code>[</code><em>flags</em><code>]</code></strong> + </blockquote> + as the third argument to the <code>RewriteRule</code> + directive. <em>Flags</em> is a comma-separated list of the + following flags: + + <ul> + <li> + '<strong><code>redirect|R</code> + [=<em>code</em>]</strong>' (force <a id="redirect" + name="redirect"><strong>r</strong>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 + <em>code</em> 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: + <code>temp</code> (default), <code>permanent</code>, + <code>seeother</code>. Use it for rules which should + canonicalize the URL and give it back to the client, + <em>e.g.</em>, translate ``<code>/~</code>'' into + ``<code>/u/</code>'' or always append a slash to + <code>/u/</code><em>user</em>, etc.<br /> + + + <p><strong>Note:</strong> 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>, rewriting + continues. 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> + + <li>'<strong><code>forbidden|F</code></strong>' (force URL + to be <strong>f</strong>orbidden)<br /> + This forces the current URL to be forbidden, + <em>i.e.</em>, it immediately sends back a HTTP response of + 403 (FORBIDDEN). Use this flag in conjunction with + appropriate RewriteConds to conditionally block some + URLs.</li> + + <li>'<strong><code>gone|G</code></strong>' (force URL to be + <strong>g</strong>one)<br /> + This forces the current URL to be gone, <em>i.e.</em>, it + immediately sends back a HTTP response of 410 (GONE). Use + this flag to mark pages which no longer exist as gone.</li> + + <li> + '<strong><code>proxy|P</code></strong>' (force + <strong>p</strong>roxy)<br /> + This flag forces the substitution part to be internally + forced as a proxy request and immediately (<em>i.e.</em>, + rewriting rule processing stops here) put through the <a + href="mod_proxy.html">proxy module</a>. You have to make + sure that the substitution string is a valid URI + (<em>e.g.</em>, typically starting with + <code>http://</code><em>hostname</em>) 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 <a + href="mod_proxy.html#proxypass">ProxyPass</a> directive, + to map some remote stuff into the namespace of the local + server. + + <p>Notice: To use this functionality make sure you have + the proxy module compiled into your Apache server + program. If you don't know please check whether + <code>mod_proxy.c</code> is part of the ``<code>httpd + -l</code>'' output. If yes, this functionality is + available to mod_rewrite. If not, then you first have to + rebuild the ``<code>httpd</code>'' program with mod_proxy + enabled.</p> + </li> + + <li>'<strong><code>last|L</code></strong>' + (<strong>l</strong>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. For example, use it to rewrite the root-path URL + ('<code>/</code>') to a real one, <em>e.g.</em>, + '<code>/e/www/</code>'.</li> + + <li>'<strong><code>next|N</code></strong>' + (<strong>n</strong>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, <em>i.e.</em>, + to immediately go to the top of the loop.<br /> + <strong>But be careful not to create an infinite + loop!</strong></li> + + <li>'<strong><code>chain|C</code></strong>' + (<strong>c</strong>hained with next rule)<br /> + This flag chains the current rule with the next rule + (which itself can be chained with the following rule, + <em>etc.</em>). This has the following effect: if a rule + matches, then processing continues as usual, <em>i.e.</em>, + the flag has no effect. If the rule does + <strong>not</strong> match, then all following chained + rules are skipped. For instance, use it to remove the + ``<code>.www</code>'' part inside a per-directory rule set + when you let an external redirect happen (where the + ``<code>.www</code>'' part should not to occur!).</li> + + <li> + '<strong><code>type|T</code></strong>=<em>MIME-type</em>' + (force MIME <strong>t</strong>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 <code>mod_alias</code> directive + <code>ScriptAlias</code> which internally forces all files + inside the mapped directory to have a MIME type of + ``<code>application/x-httpd-cgi</code>''.</li> + + <li> + '<strong><code>nosubreq|NS</code></strong>' (used only if + <strong>n</strong>o internal + <strong>s</strong>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 <code>mod_include</code> tries to find out + information about possible directory default files + (<code>index.xxx</code>). 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> + + <li>'<strong><code>nocase|NC</code></strong>' + (<strong>n</strong>o <strong>c</strong>ase)<br /> + This makes the <em>Pattern</em> case-insensitive, + <em>i.e.</em>, there is no difference between 'A-Z' and + 'a-z' when <em>Pattern</em> is matched against the current + URL.</li> + + <li>'<strong><code>qsappend|QSA</code></strong>' + (<strong>q</strong>uery <strong>s</strong>tring + <strong>a</strong>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.</li> + + <li> + '<strong><code>noescape|NE</code></strong>' + (<strong>n</strong>o URI <strong>e</strong>scaping of + output)<br /> + This flag keeps mod_rewrite from applying the usual URI + escaping rules to the result of a rewrite. Ordinarily, + special characters (such as '%', '$', ';', and so on) + will be escaped into their hexcode equivalents ('%25', + '%24', and '%3B', respectively); this flag prevents this + from being done. This allows percent symbols to appear in + the output, as in +<pre> RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] - </pre> - which would turn '<code>/foo/zed</code>' into a safe request - for '<code>/bar?arg=P1=zed</code>'. - <TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> - <TR><TD> - <STRONG>Notice:</STRONG> The <code>noescape</code> flag is only available - with Apache 1.3.20 and later versions. - </TD></TR> - </TABLE> -<P> -<LI>'<STRONG><CODE>passthrough|PT</CODE></STRONG>' (<STRONG>p</STRONG>ass <STRONG>t</STRONG>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 <CODE>RewriteRule</CODE> directives by - <CODE>Alias</CODE>, <CODE>ScriptAlias</CODE>, <CODE>Redirect</CODE>, <EM>etc.</EM> directives - from other URI-to-filename translators. A trivial example to show the - semantics: - If you want to rewrite <CODE>/abc</CODE> to <CODE>/def</CODE> via the rewriting - engine of <CODE>mod_rewrite</CODE> and then <CODE>/def</CODE> to <CODE>/ghi</CODE> - with <CODE>mod_alias</CODE>: - <PRE> + +</pre> + which would turn '<code>/foo/zed</code>' into a safe + request for '<code>/bar?arg=P1=zed</code>'. + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Notice:</strong> The + <code>noescape</code> flag is only available with + Apache 1.3.20 and later versions.</td> + </tr> + </table> + </li> + + <li> + '<strong><code>passthrough|PT</code></strong>' + (<strong>p</strong>ass <strong>t</strong>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 + <code>RewriteRule</code> directives by + <code>Alias</code>, <code>ScriptAlias</code>, + <code>Redirect</code>, <em>etc.</em> directives from + other URI-to-filename translators. A trivial example to + show the semantics: If you want to rewrite + <code>/abc</code> to <code>/def</code> via the rewriting + engine of <code>mod_rewrite</code> and then + <code>/def</code> to <code>/ghi</code> with + <code>mod_alias</code>: +<pre> RewriteRule ^/abc(.*) /def$1 [PT] Alias /def /ghi - </PRE> - If you omit the <CODE>PT</CODE> flag then <CODE>mod_rewrite</CODE> - will do its job fine, <EM>i.e.</EM>, it rewrites <CODE>uri=/abc/...</CODE> to - <CODE>filename=/def/...</CODE> as a full API-compliant URI-to-filename - translator should do. Then <CODE>mod_alias</CODE> comes and tries to do a - URI-to-filename transition which will not work. - <P> - Note: <STRONG>You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators</STRONG>. The - typical example is the use of <CODE>mod_alias</CODE> and - <CODE>mod_rewrite</CODE>.. -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<font size=-1> - <STRONG>Note - For Apache hackers:</STRONG><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 a hook in Apache version 2.0. -</FONT> -</TD></TR> -</TABLE> -<P> -<LI>'<STRONG><CODE>skip|S</CODE></STRONG>=<EM>num</EM>' (<STRONG>s</STRONG>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 - <CODE>skip=N</CODE> where N is the number of rules in the else-clause. - (This is <STRONG>not</STRONG> the same as the 'chain|C' flag!) -<P> -<LI>'<STRONG><CODE>env|E=</CODE></STRONG><EM>VAR</EM>:<EM>VAL</EM>' (set <STRONG>e</STRONG>nvironment variable)<BR> - This forces an environment variable named <EM>VAR</EM> to be set to the - value <EM>VAL</EM>, where <EM>VAL</EM> can contain regexp backreferences - <CODE>$N</CODE> and <CODE>%N</CODE> which will be expanded. You can use this flag - more than once to set more than one variable. The variables can be later - dereferenced in many situations, but usually from - within XSSI (via <CODE><!--#echo var="VAR"--></CODE>) or CGI (<EM>e.g.</EM> - <CODE>$ENV{'VAR'}</CODE>). Additionally you can dereference it in a - following RewriteCond pattern via <CODE>%{ENV:VAR}</CODE>. Use this to strip - but remember information from URLs. -</UL> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note:</STRONG> Never forget that <EM>Pattern</EM> is applied to a complete URL -in per-server configuration files. <STRONG>But in per-directory configuration -files, the per-directory prefix (which always is the same for a specific -directory!) is automatically <EM>removed</EM> for the pattern matching and -automatically <EM>added</EM> after the substitution has been done.</STRONG> 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 -``<CODE>http://</CODE>'' then the directory prefix will <STRONG>not</STRONG> be added and an -external redirect or proxy throughput (if flag <STRONG>P</STRONG> is used!) is forced! -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note:</STRONG> To enable the rewriting engine for per-directory configuration files -you need to set ``<CODE>RewriteEngine On</CODE>'' in these files <STRONG>and</STRONG> -``<CODE>Options FollowSymLinks</CODE>'' must be enabled. If your administrator has -disabled override of <CODE>FollowSymLinks</CODE> 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> -<STRONG>Inside per-server configuration (<CODE>httpd.conf</CODE>)<BR> -for request ``<CODE>GET /somepath/pathinfo</CODE>'':</STRONG><BR> - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD> -<PRE> -<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> + +</pre> + If you omit the <code>PT</code> flag then + <code>mod_rewrite</code> will do its job fine, + <em>i.e.</em>, it rewrites <code>uri=/abc/...</code> to + <code>filename=/def/...</code> as a full API-compliant + URI-to-filename translator should do. Then + <code>mod_alias</code> comes and tries to do a + URI-to-filename transition which will not work. + + <p>Note: <strong>You have to use this flag if you want to + intermix directives of different modules which contain + URL-to-filename translators</strong>. The typical example + is the use of <code>mod_alias</code> and + <code>mod_rewrite</code>..</p> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><font size="-1"><strong>Note - For Apache + hackers:</strong><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 a hook in + Apache version 2.0.</font> </td> + </tr> + </table> + </li> + + <li>'<strong><code>skip|S</code></strong>=<em>num</em>' + (<strong>s</strong>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 + <code>skip=N</code> where N is the number of rules in the + else-clause. (This is <strong>not</strong> the same as the + 'chain|C' flag!)</li> + + <li> + '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>' + (set <strong>e</strong>nvironment variable)<br /> + This forces an environment variable named <em>VAR</em> to + be set to the value <em>VAL</em>, where <em>VAL</em> can + contain regexp backreferences <code>$N</code> and + <code>%N</code> which will be expanded. You can use this + flag more than once to set more than one variable. The + variables can be later dereferenced in many situations, but + usually from within XSSI (via <code><!--#echo + var="VAR"--></code>) or CGI (<em>e.g.</em> + <code>$ENV{'VAR'}</code>). Additionally you can dereference + it in a following RewriteCond pattern via + <code>%{ENV:VAR}</code>. Use this to strip but remember + information from URLs.</li> + </ul> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td> + <strong>Note:</strong> Never forget that + <em>Pattern</em> is applied to a complete URL in + per-server configuration files. <strong>But in + per-directory configuration files, the per-directory + prefix (which always is the same for a specific + directory!) is automatically <em>removed</em> for the + pattern matching and automatically <em>added</em> after + the substitution has been done.</strong> 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 ``<code>http://</code>'' then the directory + prefix will <strong>not</strong> be added and an + external redirect or proxy throughput (if flag + <strong>P</strong> is used!) is forced!</p> + </td> + </tr> + </table> + + <table width="70%" border="0" bgcolor="#E0E0F0" + cellspacing="0" cellpadding="10"> + <tr> + <td><strong>Note:</strong> To enable the rewriting engine + for per-directory configuration files you need to set + ``<code>RewriteEngine On</code>'' in these files + <strong>and</strong> ``<code>Options + FollowSymLinks</code>'' must be enabled. If your + administrator has disabled override of + <code>FollowSymLinks</code> 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> + + <p><strong>Inside per-server configuration + (<code>httpd.conf</code>)<br /> + for request ``<code>GET + /somepath/pathinfo</code>'':</strong><br /> + </p> + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td> +<pre> +<strong>Given Rule</strong> <strong>Resulting Substitution</strong> ---------------------------------------------- ---------------------------------- ^/somepath(.*) otherpath$1 not supported, because invalid! @@ -1821,23 +1955,25 @@ for request ``<CODE>GET /somepath/pathinfo</CODE>'':</STRONG><BR> ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy -</PRE> -</TD> -</TR> -</TABLE> - -<P> -<STRONG>Inside per-directory configuration for <CODE>/somepath</CODE><BR> -(<EM>i.e.</EM>, file <CODE>.htaccess</CODE> in dir <CODE>/physical/path/to/somepath</CODE> containing -<CODE>RewriteBase /somepath</CODE>)<BR> for -request ``<CODE>GET /somepath/localpath/pathinfo</CODE>'':</STRONG><BR> - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD> -<PRE> -<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> +</pre> + </td> + </tr> + </table> + + <p><strong>Inside per-directory configuration for + <code>/somepath</code><br /> + (<em>i.e.</em>, file <code>.htaccess</code> in dir + <code>/physical/path/to/somepath</code> containing + <code>RewriteBase /somepath</code>)<br /> + for request ``<code>GET + /somepath/localpath/pathinfo</code>'':</strong><br /> + </p> + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td> +<pre> +<strong>Given Rule</strong> <strong>Resulting Substitution</strong> ---------------------------------------------- ---------------------------------- ^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo @@ -1869,90 +2005,86 @@ request ``<CODE>GET /somepath/localpath/pathinfo</CODE>'':</STRONG><BR> ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy -</PRE> -</TD> -</TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> -<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>/path/to/file/map.txt</CODE>. Then we only have to add the -following lines to the Apache server configuration file: - -<BLOCKQUOTE> -<PRE> +</pre> + </td> + </tr> + </table> + + <p><strong>Example:</strong></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>/path/to/file/map.txt</code>. Then we only have to + add the following lines to the Apache server configuration + file:</p> + + <blockquote> +<pre> RewriteLog /path/to/file/rewrite.log RewriteMap real-to-user txt:/path/to/file/map.txt RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -</PRE> -</BLOCKQUOTE> - -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Miscelleneous">Miscellaneous</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<H2><A NAME="EnvVar">Environment Variables</A></H2> - -This module keeps track of two additional (non-standard) CGI/SSI environment -variables named <CODE>SCRIPT_URL</CODE> and <CODE>SCRIPT_URI</CODE>. These contain -the <EM>logical</EM> Web-view to the current resource, while the standard CGI/SSI -variables <CODE>SCRIPT_NAME</CODE> and <CODE>SCRIPT_FILENAME</CODE> contain the -<EM>physical</EM> System-view. - -<P> -Notice: These variables hold the URI/URL <EM>as they were initially -requested</EM>, <EM>i.e.</EM>, <EM>before</EM> any rewriting. This is -important because the rewriting process is primarily used to rewrite logical -URLs to physical pathnames. - -<P> -<STRONG>Example:</STRONG> - -<BLOCKQUOTE> -<PRE> +</pre> + </blockquote> + </blockquote> + <hr noshade="noshade" size="1" /> + + <center> + <h1><a id="Miscelleneous" + name="Miscelleneous">Miscellaneous</a></h1> + </center> + <hr noshade="noshade" size="1" /> + + <h2><a id="EnvVar" name="EnvVar">Environment + Variables</a></h2> + This module keeps track of two additional (non-standard) + CGI/SSI environment variables named <code>SCRIPT_URL</code> + and <code>SCRIPT_URI</code>. These contain the + <em>logical</em> Web-view to the current resource, while the + standard CGI/SSI variables <code>SCRIPT_NAME</code> and + <code>SCRIPT_FILENAME</code> contain the <em>physical</em> + System-view. + + <p>Notice: These variables hold the URI/URL <em>as they were + initially requested</em>, <em>i.e.</em>, <em>before</em> any + rewriting. This is important because the rewriting process is + primarily used to rewrite logical URLs to physical + pathnames.</p> + + <p><strong>Example:</strong></p> + + <blockquote> +<pre> SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html SCRIPT_FILENAME=/u/rse/.www/index.html SCRIPT_URL=/u/rse/ SCRIPT_URI=http://en1.engelschall.com/u/rse/ -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<H2><A NAME="Solutions">Practical Solutions</A></H2> - -We also have an <a href="../misc/rewriteguide.html">URL Rewriting -Guide</a> available, which provides a collection of practical solutions -for URL-based problems. There you can find real-life rulesets and -additional information about mod_rewrite. +</pre> + </blockquote> + <hr noshade="noshade" size="1" /> + + <h2><a id="Solutions" name="Solutions">Practical + Solutions</a></h2> + We also have an <a href="../misc/rewriteguide.html">URL + Rewriting Guide</a> available, which provides a collection of + practical solutions for URL-based problems. There you can + find real-life rulesets and additional information about + mod_rewrite. <!--#include virtual="footer.html" --> + </blockquote> + <!-- page indentation --> + <!--/%hypertext --> + </body> +</html> -<!--#include virtual="footer.html" --> -</BLOCKQUOTE><!-- page indentation --> -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_setenvif.html b/docs/manual/mod/mod_setenvif.html index 6190d7f968..6716965bf7 100644 --- a/docs/manual/mod/mod_setenvif.html +++ b/docs/manual/mod/mod_setenvif.html @@ -1,352 +1,276 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_setenvif</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_setenvif</H1> - <P> - This module provides the ability to set environment variables based - upon attributes of the request. - </P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_setenvif.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> setenvif_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later. -</P> - - <H2>Summary</H2> - <P> - The <SAMP>mod_setenvif</SAMP> module allows you to set environment - variables according to whether different aspects of the request - match regular expressions you specify. These environment variables - can be used by other parts of the server to make decisions about - actions to be taken. - </P> - <P>The directives are considered in the order they appear in the - configuration files. So more complex sequences can be used, such - as this example, which sets <CODE>netscape</CODE> if the browser - is mozilla but not MSIE. - <BLOCKQUOTE><PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_setenvif</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_setenvif</h1> + + <p>This module provides the ability to set environment + variables based upon attributes of the request.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_setenvif.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + setenvif_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.3 and later.</p> + + <h2>Summary</h2> + + <p>The <samp>mod_setenvif</samp> module allows you to set + environment variables according to whether different aspects of + the request match regular expressions you specify. These + environment variables can be used by other parts of the server + to make decisions about actions to be taken.</p> + + <p>The directives are considered in the order they appear in + the configuration files. So more complex sequences can be used, + such as this example, which sets <code>netscape</code> if the + browser is mozilla but not MSIE.</p> + + <blockquote> +<pre> BrowserMatch ^Mozilla netscape BrowserMatch MSIE !netscape - </PRE></BLOCKQUOTE> - </P> - - <p>For additional information, we provide a document on - <a href="../env.html">Environment Variables in Apache</a>.</p> - - <H2>Directives</H2> - <UL> - <LI><A HREF="#BrowserMatch">BrowserMatch</A> - </LI> - <LI><A HREF="#BrowserMatchNoCase">BrowserMatchNoCase</A> - </LI> - <LI><A HREF="#SetEnvIf">SetEnvIf</A> - </LI> - <LI><A HREF="#SetEnvIfNoCase">SetEnvIfNoCase</A> - </LI> - </UL> - - <HR> <!-- the HR is part of the directive description --> - <H2><A NAME="BrowserMatch">BrowserMatch directive</A></H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> BrowserMatch <EM>regex - env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>value</em>]] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <i>none</i> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> FileInfo - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2 - this directive was found in the now-obsolete mod_browser module) - </P> - <P> - The BrowserMatch directive defines environment variables based on the - <SAMP>User-Agent</SAMP> HTTP request header field. The first argument - should be a POSIX.2 extended regular expression (similar to an - <SAMP>egrep</SAMP>-style regex). The rest of the arguments give the - names of variables to set, and optionally values to which they should - be set. These take the form of - </P> - <OL> - <LI><SAMP><EM>varname</EM></SAMP>, or - </LI> - <LI><SAMP>!<EM>varname</EM></SAMP>, or - </LI> - <LI><SAMP><EM>varname</EM>=<EM>value</EM></SAMP> - </LI> - </OL> - <P> - 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 <SAMP><EM>value</EM></SAMP>. If a - <SAMP>User-Agent</SAMP> string matches more than one entry, they will - be merged. Entries are processed in the order in which they appear, - and later entries can override earlier ones. - </P> - <P> - For example: - </P> - <PRE> + +</pre> + </blockquote> + <br /> + <br /> + + + <p>For additional information, we provide a document on <a + href="../env.html">Environment Variables in Apache</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#BrowserMatch">BrowserMatch</a></li> + + <li><a href="#BrowserMatchNoCase">BrowserMatchNoCase</a></li> + + <li><a href="#SetEnvIf">SetEnvIf</a></li> + + <li><a href="#SetEnvIfNoCase">SetEnvIfNoCase</a></li> + </ul> + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="BrowserMatch" name="BrowserMatch">BrowserMatch + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> BrowserMatch <em>regex + env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <i>none</i><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_setenvif<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)</p> + + <p>The BrowserMatch directive defines environment variables + based on the <samp>User-Agent</samp> HTTP request header field. + The first argument should be a POSIX.2 extended regular + expression (similar to an <samp>egrep</samp>-style regex). The + rest of the arguments give the names of variables to set, and + optionally values to which they should be set. These take the + form of</p> + + <ol> + <li><samp><em>varname</em></samp>, or</li> + + <li><samp>!<em>varname</em></samp>, or</li> + + <li><samp><em>varname</em>=<em>value</em></samp></li> + </ol> + + <p>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 + <samp><em>value</em></samp>. If a <samp>User-Agent</samp> + string matches more than one entry, they will be merged. + Entries are processed in the order in which they appear, and + later entries can override earlier ones.</p> + + <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> - Note that the regular expression string is - <STRONG>case-sensitive</STRONG>. For case-INsensitive matching, see - the - <A - HREF="#BrowserMatchNoCase" - ><SAMP>BrowserMatchNoCase</SAMP></A> - directive. - </P> - <P> - The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP> - directives are special cases of the - <A - HREF="#SetEnvIf" - ><SAMP>SetEnvIf</SAMP></A> - and - <A - HREF="#SetEnvIfNoCase" - ><SAMP>SetEnvIfNoCase</SAMP></A> - directives. The following two lines have the same effect: - </P> - <PRE> + +</pre> + + <p>Note that the regular expression string is + <strong>case-sensitive</strong>. For case-INsensitive matching, + see the <a + href="#BrowserMatchNoCase"><samp>BrowserMatchNoCase</samp></a> + directive.</p> + + <p>The <samp>BrowserMatch</samp> and + <samp>BrowserMatchNoCase</samp> directives are special cases of + the <a href="#SetEnvIf"><samp>SetEnvIf</samp></a> and <a + href="#SetEnvIfNoCase"><samp>SetEnvIfNoCase</samp></a> + directives. The following two lines have the same effect:</p> +<pre> BrowserMatchNoCase Robot is_a_robot SetEnvIfNoCase User-Agent Robot is_a_robot - </PRE> - - <HR> <!-- the HR is part of the directive description --> - <H2> - <A NAME="BrowserMatchNoCase">BrowserMatchNoCase directive - </A> - </H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> BrowserMatchNoCase <EM>regex - env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>value</em>]] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> FileInfo - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2 - this directive was found in the now-obsolete mod_browser module) - </P> - <P> - The <SAMP>BrowserMatchNoCase</SAMP> directive is semantically identical to - the - <A - HREF="#BrowserMatch" - ><SAMP>BrowserMatch</SAMP></A> - directive. However, it provides for case-insensitive matching. For - example: - </P> - <PRE> + +</pre> + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="BrowserMatchNoCase" + name="BrowserMatchNoCase">BrowserMatchNoCase directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> BrowserMatchNoCase + <em>regex env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>none</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_setenvif<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)</p> + + <p>The <samp>BrowserMatchNoCase</samp> directive is + semantically identical to the <a + href="#BrowserMatch"><samp>BrowserMatch</samp></a> directive. + However, it provides for case-insensitive matching. For + example:</p> +<pre> BrowserMatchNoCase mac platform=macintosh BrowserMatchNoCase win platform=windows - </PRE> - <P> - The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP> - directives are special cases of the - <A - HREF="#SetEnvIf" - ><SAMP>SetEnvIf</SAMP></A> - and - <A - HREF="#SetEnvIfNoCase" - ><SAMP>SetEnvIfNoCase</SAMP></A> - directives. The following two lines have the same effect: - </P> - <PRE> + +</pre> + + <p>The <samp>BrowserMatch</samp> and + <samp>BrowserMatchNoCase</samp> directives are special cases of + the <a href="#SetEnvIf"><samp>SetEnvIf</samp></a> and <a + href="#SetEnvIfNoCase"><samp>SetEnvIfNoCase</samp></a> + directives. The following two lines have the same effect:</p> +<pre> BrowserMatchNoCase Robot is_a_robot SetEnvIfNoCase User-Agent Robot is_a_robot - </PRE> - - <HR> <!-- the HR is part of the directive description --> - <H2> - <A NAME="SetEnvIf">SetEnvIf directive - </A> - </H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> SetEnvIf <EM> attribute regex - env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>value</em>]] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> FileInfo - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above; the - Request_Protocol keyword and environment-variable matching are only - available with 1.3.7 and later - </P> - <P> - The <SAMP>SetEnvIf</SAMP> directive defines environment variables - based on attributes of the request. These attributes can be the - values of various HTTP request header fields (see - <a href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a> - for more information about these), or of other aspects of the request, - including the following: - </P> - <UL> - <LI><SAMP>Remote_Host</SAMP> - the hostname (if available) of the - client making the request - </LI> - <LI><SAMP>Remote_Addr</SAMP> - the IP address of the client making - the request - </LI> - <LI><SAMP>Remote_User</SAMP> - the authenticated username (if - available) - </LI> - <LI><SAMP>Request_Method</SAMP> - the name of the method being used - (<SAMP>GET</SAMP>, <SAMP>POST</SAMP>, <EM>et cetera</EM>) - </LI> - <LI><SAMP>Request_Protocol</SAMP> - the name and version of the protocol - with which the request was made (<EM>e.g.</EM>, "HTTP/0.9", "HTTP/1.1", - <EM>etc.</EM>) - </LI> - <LI><SAMP>Request_URI</SAMP> - the portion of the URL following the - scheme and host portion - </LI> - </UL> - <P> - Some of the more commonly used request header field names include - <SAMP>Host</SAMP>, <SAMP>User-Agent</SAMP>, and <SAMP>Referer</SAMP>. - </P> - <P> - If the <EM>attribute</EM> name doesn't match any of the special keywords, - nor any of the request's header field names, it is tested as the name - of an environment variable in the list of those associated with the request. - This allows <CODE>SetEnvIf</CODE> directives to test against the result - of prior matches. - </P> - <BLOCKQUOTE> - <STRONG>Only those environment variables defined by earlier - <CODE>SetEnvIf[NoCase]</CODE> directives are available for testing in - this manner. 'Earlier' means that they were defined at a broader scope - (such as server-wide) or previously in the current directive's - scope.</STRONG> - </BLOCKQUOTE> - <P> - <EM>attribute</EM> may be a regular expression when used to match a request header. - If <EM>attribute</EM> is a regular expression and it doesn't match any of the - request's header names, then <EM>attribute</EM> is not tested against the request's - environment variable list. - </P> - <P> - Example: - </P> - <PRE> + +</pre> + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="SetEnvIf" name="SetEnvIf">SetEnvIf + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> SetEnvIf <em>attribute + regex env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>none</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_setenvif<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3 and + above; the Request_Protocol keyword and environment-variable + matching are only available with 1.3.7 and later</p> + + <p>The <samp>SetEnvIf</samp> directive defines environment + variables based on attributes of the request. These attributes + can be the values of various HTTP request header fields (see <a + href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a> + for more information about these), or of other aspects of the + request, including the following:</p> + + <ul> + <li><samp>Remote_Host</samp> - the hostname (if available) of + the client making the request</li> + + <li><samp>Remote_Addr</samp> - the IP address of the client + making the request</li> + + <li><samp>Remote_User</samp> - the authenticated username (if + available)</li> + + <li><samp>Request_Method</samp> - the name of the method + being used (<samp>GET</samp>, <samp>POST</samp>, <em>et + cetera</em>)</li> + + <li><samp>Request_Protocol</samp> - the name and version of + the protocol with which the request was made (<em>e.g.</em>, + "HTTP/0.9", "HTTP/1.1", <em>etc.</em>)</li> + + <li><samp>Request_URI</samp> - the portion of the URL + following the scheme and host portion</li> + </ul> + + <p>Some of the more commonly used request header field names + include <samp>Host</samp>, <samp>User-Agent</samp>, and + <samp>Referer</samp>.</p> + + <p>If the <em>attribute</em> name doesn't match any of the + special keywords, nor any of the request's header field names, + it is tested as the name of an environment variable in the list + of those associated with the request. This allows + <code>SetEnvIf</code> directives to test against the result of + prior matches.</p> + + <blockquote> + <strong>Only those environment variables defined by earlier + <code>SetEnvIf[NoCase]</code> directives are available for + testing in this manner. 'Earlier' means that they were + defined at a broader scope (such as server-wide) or + previously in the current directive's scope.</strong> + </blockquote> + + <p><em>attribute</em> may be a regular expression when used to + match a request header. If <em>attribute</em> is a regular + expression and it doesn't match any of the request's header + names, then <em>attribute</em> is not tested against the + request's environment variable list.</p> + + <p>Example:</p> +<pre> SetEnvIf Request_URI "\.gif$" object_is_image=gif SetEnvIf Request_URI "\.jpg$" object_is_image=jpg SetEnvIf Request_URI "\.xbm$" object_is_image=xbm @@ -356,79 +280,59 @@ REL="Help" SetEnvIf object_is_image xbm XBIT_PROCESSING=1 : SetEnvIf ^TS* ^[a-z].* HAVE_TS - </PRE> - <P> - The first three will set the environment variable <SAMP>object_is_image</SAMP> if the - request was for an image file, and the fourth sets - <SAMP>intra_site_referral</SAMP> if the referring page was somewhere - on the <SAMP>www.mydomain.com</SAMP> Web site. - </P> - <P> - The last example will set environment variable <SAMP>HAVE_TS</SAMP> if the request - contains any headers that begin with "TS" whose values begins with any character - in the set [a-z]. - </P> - <HR> <!-- the HR is part of the directive description --> - <H2> - <A NAME="SetEnvIfNoCase">SetEnvIfNoCase directive - </A> - </H2> - <P> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> SetEnvIfNoCase <EM> attribute regex - env-variable</em>[=<em>value</em>] [<em>env-variable</em>[=<em>value</em>]] ... - <BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <EM>none</EM> - <BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess - <BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> FileInfo - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base - <BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_setenvif - <BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above - </P> - <P> - The <SAMP>SetEnvIfNoCase</SAMP> is semantically identical to the - <A - HREF="#SetEnvIf" - ><SAMP>SetEnvIf</SAMP></A> - directive, and differs only in that the regular expression matching is - performed in a case-insensitive manner. For example: - </P> - <PRE> + +</pre> + + <p>The first three will set the environment variable + <samp>object_is_image</samp> if the request was for an image + file, and the fourth sets <samp>intra_site_referral</samp> if + the referring page was somewhere on the + <samp>www.mydomain.com</samp> Web site.</p> + + <p>The last example will set environment variable + <samp>HAVE_TS</samp> if the request contains any headers that + begin with "TS" whose values begins with any character in the + set [a-z].</p> + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="SetEnvIfNoCase" name="SetEnvIfNoCase">SetEnvIfNoCase + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> SetEnvIfNoCase + <em>attribute regex env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>none</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_setenvif<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3 and + above</p> + + <p>The <samp>SetEnvIfNoCase</samp> is semantically identical to + the <a href="#SetEnvIf"><samp>SetEnvIf</samp></a> directive, + and differs only in that the regular expression matching is + performed in a case-insensitive manner. For example:</p> +<pre> SetEnvIfNoCase Host Apache\.Org site=apache - </PRE> - <P> - This will cause the <SAMP>site</SAMP> environment variable to be set to - "<SAMP>apache</SAMP>" if the HTTP request header field - <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>, - <SAMP>apache.org</SAMP>, or any other combination. - </P> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> + +</pre> + + <p>This will cause the <samp>site</samp> environment variable + to be set to "<samp>apache</samp>" if the HTTP request header + field <samp>Host:</samp> was included and contained + <samp>Apache.Org</samp>, <samp>apache.org</samp>, or any other + combination.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_so.html b/docs/manual/mod/mod_so.html index aef279aeec..98c97b9f5e 100644 --- a/docs/manual/mod/mod_so.html +++ b/docs/manual/mod/mod_so.html @@ -1,192 +1,185 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_so</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_so</H1> - -<p>This module provides for loading of executable code and modules into the -server at start-up or restart time.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base (Windows); Optional (Unix) -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_so.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> so_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later. -</P> - - -<H2>Summary</H2> - -<P>On selected operating systems this module can be used to load modules -into Apache at runtime via the <A HREF="../dso.html">Dynamic Shared -Object</A> (DSO) mechanism, rather than requiring a recompilation. - -<P> -On Unix, the loaded code typically comes from shared object files -(usually with <SAMP>.so</SAMP> extension), on Windows this may either -the <SAMP>.so</SAMP> or <SAMP>.dll</SAMP> extension. This module is -only available in Apache 1.3 and up. - -<p>In previous releases, the functionality of this module was provided -for Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll -was used in beta release 1.3b1 through 1.3b5. mod_so combines these -two modules into a single module for all operating systems. - -<P><STRONG> Warning: Apache 1.3 modules cannot be directly used with - Apache 2.0 - the module must be modified to dynamically load or - compile into Apache 2.0</STRONG>.</P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#loadfile">LoadFile</A> -<LI><A HREF="#loadmodule">LoadModule</A> -</UL> - -<H2><A NAME="creating">Creating Loadable Modules for Windows</A></H2> - -<P><STRONG>Note: the module name format changed for Windows with Apache - 1.3.15 and 2.0 - the modules are now named as mod_foo.so</STRONG>. - While mod_so still loads modules with ApacheModuleFoo.dll names, the - new naming convention is preferred; if you are converting your loadable - module for 2.0, please fix the name to this 2.0 convention.</P> - -<P>The Apache module API is unchanged between the Unix and Windows - versions. Many modules will run on Windows with no or little change - from Unix, although others rely on aspects of the Unix architecture - which are not present in Windows, and will not work.</P> - -<P>When a module does work, it can be added to the server in one of two - ways. As with Unix, it can be compiled into the server. Because Apache - for Windows does not have the <CODE>Configure</CODE> program of Apache - for Unix, the module's source file must be added to the ApacheCore - project file, and its symbols must be added to the - <CODE>os\win32\modules.c</CODE> file.</P> - -<P>The second way is to compile the module as a DLL, a shared library - that can be loaded into the server at runtime, using the - <CODE><A HREF="#loadmodule">LoadModule</A></CODE> - directive. These module DLLs can be distributed and run on any Apache - for Windows installation, without recompilation of the server.</P> - -<P>To create a module DLL, a small change is necessary to the module's - source file: The module record must be exported from the DLL (which - will be created later; see below). To do this, add the <CODE - >AP_MODULE_DECLARE_DATA</CODE> (defined in the Apache header files) - to your module's module record definition. For example, if your module - has:</P> -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_so</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_so</h1> + + <p>This module provides for loading of executable code and + modules into the server at start-up or restart time.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base (Windows); + Optional (Unix)<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_so.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + so_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.3 and later.</p> + + <h2>Summary</h2> + + <p>On selected operating systems this module can be used to + load modules into Apache at runtime via the <a + href="../dso.html">Dynamic Shared Object</a> (DSO) mechanism, + rather than requiring a recompilation.</p> + + <p>On Unix, the loaded code typically comes from shared object + files (usually with <samp>.so</samp> extension), on Windows + this may either the <samp>.so</samp> or <samp>.dll</samp> + extension. This module is only available in Apache 1.3 and + up.</p> + + <p>In previous releases, the functionality of this module was + provided for Unix by mod_dld, and for Windows by mod_dll. On + Windows, mod_dll was used in beta release 1.3b1 through 1.3b5. + mod_so combines these two modules into a single module for all + operating systems.</p> + + <p><strong>Warning: Apache 1.3 modules cannot be directly used + with Apache 2.0 - the module must be modified to dynamically + load or compile into Apache 2.0</strong>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#loadfile">LoadFile</a></li> + + <li><a href="#loadmodule">LoadModule</a></li> + </ul> + + <h2><a id="creating" name="creating">Creating Loadable Modules + for Windows</a></h2> + + <p><strong>Note: the module name format changed for Windows + with Apache 1.3.15 and 2.0 - the modules are now named as + mod_foo.so</strong>. While mod_so still loads modules with + ApacheModuleFoo.dll names, the new naming convention is + preferred; if you are converting your loadable module for 2.0, + please fix the name to this 2.0 convention.</p> + + <p>The Apache module API is unchanged between the Unix and + Windows versions. Many modules will run on Windows with no or + little change from Unix, although others rely on aspects of the + Unix architecture which are not present in Windows, and will + not work.</p> + + <p>When a module does work, it can be added to the server in + one of two ways. As with Unix, it can be compiled into the + server. Because Apache for Windows does not have the + <code>Configure</code> program of Apache for Unix, the module's + source file must be added to the ApacheCore project file, and + its symbols must be added to the + <code>os\win32\modules.c</code> file.</p> + + <p>The second way is to compile the module as a DLL, a shared + library that can be loaded into the server at runtime, using + the <code><a href="#loadmodule">LoadModule</a></code> + directive. These module DLLs can be distributed and run on any + Apache for Windows installation, without recompilation of the + server.</p> + + <p>To create a module DLL, a small change is necessary to the + module's source file: The module record must be exported from + the DLL (which will be created later; see below). To do this, + add the <code>AP_MODULE_DECLARE_DATA</code> (defined in the + Apache header files) to your module's module record definition. + For example, if your module has:</p> +<pre> module foo_module; -</PRE> -<P>Replace the above with:</P> -<PRE> +</pre> + + <p>Replace the above with:</p> +<pre> module AP_MODULE_DECLARE_DATA foo_module; -</PRE> -<P>Note that this will only be activated on Windows, so the module can - continue to be used, unchanged, with Unix if needed. Also, if you are - familiar with <CODE>.DEF</CODE> files, you can export the module - record with that method instead.</P> - -<P>Now, create a DLL containing your module. You will need to link this - against the libhttpd.lib export library that is created when the - libhttpd.dll shared library is compiled. You may also have to change - the compiler settings to ensure that the Apache header files are - correctly located. You can find this library in your server root's - modules directory. It is best to grab an existing module .dsp file - from the tree to assure the build environment is configured correctly, - or alternately compare the compiler and link options to your .dsp.</P> - -<P>This should create a DLL version of your module. Now simply place it - in the <SAMP>modules</SAMP> directory of your server root, and use - the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to - load it.</P> - -<HR> - -<H2><A NAME="loadfile">LoadFile</A> directive</H2> -<!--%plaintext <?INDEX {\tt LoadFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename</em> - [<em>filename</em>] ...<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_so<P> - -The LoadFile directive links in the named object files or libraries -when the server is started or restarted; this is used to load -additional code which may be required for some module to -work. <EM>Filename</EM> is either an absolute path or relative to <A -HREF="core.html#serverroot">ServerRoot</A>.<P><HR> - -<H2><A NAME="loadmodule">LoadModule</A> directive</H2> -<!--%plaintext <?INDEX {\tt LoadModule} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_so<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, and is -listed as the <a href="module-dict.html#ModuleIdentifier">Module -Identifier</a> in the module documentation. Example: -<BLOCKQUOTE><CODE> -LoadModule status_module modules/mod_status.so -</CODE></BLOCKQUOTE> - -<P>loads the named module from the modules subdirectory of the - ServerRoot.<P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + + <p>Note that this will only be activated on Windows, so the + module can continue to be used, unchanged, with Unix if needed. + Also, if you are familiar with <code>.DEF</code> files, you can + export the module record with that method instead.</p> + + <p>Now, create a DLL containing your module. You will need to + link this against the libhttpd.lib export library that is + created when the libhttpd.dll shared library is compiled. You + may also have to change the compiler settings to ensure that + the Apache header files are correctly located. You can find + this library in your server root's modules directory. It is + best to grab an existing module .dsp file from the tree to + assure the build environment is configured correctly, or + alternately compare the compiler and link options to your + .dsp.</p> + + <p>This should create a DLL version of your module. Now simply + place it in the <samp>modules</samp> directory of your server + root, and use the <code><a + href="#loadmodule">LoadModule</a></code> directive to load + it.</p> + <hr /> + + <h2><a id="loadfile" name="loadfile">LoadFile</a> + directive</h2> + <!--%plaintext <?INDEX {\tt LoadFile} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> LoadFile + <em>filename</em> [<em>filename</em>] ...<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_so + + <p>The LoadFile directive links in the named object files or + libraries when the server is started or restarted; this is used + to load additional code which may be required for some module + to work. <em>Filename</em> is either an absolute path or + relative to <a href="core.html#serverroot">ServerRoot</a>.</p> + <hr /> + + <h2><a id="loadmodule" name="loadmodule">LoadModule</a> + directive</h2> + <!--%plaintext <?INDEX {\tt LoadModule} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> LoadModule <em>module + filename</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_so + + <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, and is listed as the <a + href="module-dict.html#ModuleIdentifier">Module Identifier</a> + in the module documentation. Example:</p> + + <blockquote> + <code>LoadModule status_module modules/mod_status.so</code> + </blockquote> + + <p>loads the named module from the modules subdirectory of the + ServerRoot.</p> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> diff --git a/docs/manual/mod/mod_speling.html b/docs/manual/mod/mod_speling.html index cc294cdcee..f194f68926 100644 --- a/docs/manual/mod/mod_speling.html +++ b/docs/manual/mod/mod_speling.html @@ -1,137 +1,126 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_speling</TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Module mod_speling</H1> - <P> - This module attempts to correct misspellings of URLs that users - might have entered, by ignoring capitalization and by allowing up to - one misspelling.</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_speling.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> speling_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later. Available as an External module in Apache 1.1 and later. -</P> - - - <H2>Summary</H2> - <P> - Requests to documents sometimes cannot be served by the core apache - server because the request was misspelled or miscapitalized. This - module addresses this problem by trying to find a matching document, - even after all other modules gave up. It does its work by comparing - each document name in the requested directory against the requested - document name <STRONG>without regard to case</STRONG>, and allowing - <STRONG>up to one misspelling</STRONG> (character insertion / omission - / transposition or wrong character). A list is built with all document - names which were matched using this strategy. - </P> - <P> - If, after scanning the directory, - <UL> - <LI>no matching document was found, Apache will proceed as usual - and return a "document not found" error. - <LI>only one document is found that "almost" matches the request, - then it is returned in the form of a redirection response. - <LI>more than one document with a close match was found, then - the list of the matches is returned to the client, and the client - can select the correct candidate. - </UL> - </P> - - <H2>Directives</H2> - - <UL> - <LI><A HREF="#checkspelling">CheckSpelling</A> - </UL> - - <HR> <!-- the HR is part of the directive description --> - <H2><A NAME="checkspelling">CheckSpelling</A> directive</H2> - <!--%plaintext <?INDEX {\tt CheckSpelling} directive> --> - <A - HREF="directive-dict.html#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> CheckSpelling on|off<BR> - <A - HREF="directive-dict.html#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> <CODE>CheckSpelling Off</CODE><BR> - <A - HREF="directive-dict.html#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> server config, virtual host, - directory, .htaccess<BR> - <A - HREF="directive-dict.html#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> Options - <BR> - <A - HREF="directive-dict.html#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> Base<BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_speling<BR> - <A - HREF="directive-dict.html#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> CheckSpelling was available as a - separately - available module for Apache 1.1, but was limited to miscapitalizations. - As of Apache 1.3, it is part of the Apache distribution. Prior to - Apache 1.3.2, the <SAMP>CheckSpelling</SAMP> directive was only available - in the "server" and "virtual host" contexts. - <P> - This directive enables or disables the spelling module. When enabled, - keep in mind that - </P> - <UL> - <LI>the directory scan which is necessary for the spelling - correction will have an impact on the server's performance - when many spelling corrections have to be performed at the same time. - </LI> - <LI>the document trees should not contain sensitive files which could - be matched inadvertently by a spelling "correction". - </LI> - <LI>the module is unable to correct misspelled user names - (as in <CODE>http://my.host/~apahce/</CODE>), just file names or - directory names. - </LI> - <LI>spelling corrections apply strictly to existing files, so a request for - the <SAMP><Location /status></SAMP> may get incorrectly treated - as the negotiated file "<SAMP>/stats.html</SAMP>". - </LI> - </UL> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_speling</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_speling</h1> + + <p>This module attempts to correct misspellings of URLs that + users might have entered, by ignoring capitalization and by + allowing up to one misspelling.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_speling.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + speling_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.3 and later. Available as an External module in Apache + 1.1 and later.</p> + + <h2>Summary</h2> + + <p>Requests to documents sometimes cannot be served by the core + apache server because the request was misspelled or + miscapitalized. This module addresses this problem by trying to + find a matching document, even after all other modules gave up. + It does its work by comparing each document name in the + requested directory against the requested document name + <strong>without regard to case</strong>, and allowing + <strong>up to one misspelling</strong> (character insertion / + omission / transposition or wrong character). A list is built + with all document names which were matched using this + strategy.</p> + + <p>If, after scanning the directory,</p> + + <ul> + <li>no matching document was found, Apache will proceed as + usual and return a "document not found" error.</li> + + <li>only one document is found that "almost" matches the + request, then it is returned in the form of a redirection + response.</li> + + <li>more than one document with a close match was found, then + the list of the matches is returned to the client, and the + client can select the correct candidate.</li> + </ul> + <br /> + <br /> + + + <h2>Directives</h2> + + <ul> + <li><a href="#checkspelling">CheckSpelling</a></li> + </ul> + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="checkspelling" + name="checkspelling">CheckSpelling</a> directive</h2> + <!--%plaintext <?INDEX {\tt CheckSpelling} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CheckSpelling + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>CheckSpelling + Off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> Options <br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_speling<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> CheckSpelling + was available as a separately available module for Apache 1.1, + but was limited to miscapitalizations. As of Apache 1.3, it is + part of the Apache distribution. Prior to Apache 1.3.2, the + <samp>CheckSpelling</samp> directive was only available in the + "server" and "virtual host" contexts. + + <p>This directive enables or disables the spelling module. When + enabled, keep in mind that</p> + + <ul> + <li>the directory scan which is necessary for the spelling + correction will have an impact on the server's performance + when many spelling corrections have to be performed at the + same time.</li> + + <li>the document trees should not contain sensitive files + which could be matched inadvertently by a spelling + "correction".</li> + + <li>the module is unable to correct misspelled user names (as + in <code>http://my.host/~apahce/</code>), just file names or + directory names.</li> + + <li>spelling corrections apply strictly to existing files, so + a request for the <samp><Location /status></samp> may + get incorrectly treated as the negotiated file + "<samp>/stats.html</samp>".</li> + </ul> + <!--#include virtual="footer.html" --> + </body> +</html> diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html index 8ea9d83dbe..8510691fae 100644 --- a/docs/manual/mod/mod_status.html +++ b/docs/manual/mod/mod_status.html @@ -1,96 +1,90 @@ -<!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" -> - -<!--#include virtual="header.html" --> - -<blockquote><strong>Warning:</strong> -This document has not been updated to take into account changes -made in the 2.0 version of the Apache HTTP Server. Some of the -information may still be relevant, but please use it -with care. -</blockquote> - -<H1 ALIGN="CENTER">Module mod_status</H1> - -<p>This module provides information on server activity and -performance.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_status.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> status_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.1 and later. -</P> - - -<H2>Summary</H2> - -<p>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> - -<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>Directives</h2> - -<ul> -<li><a href="#extendedstatus">ExtendedStatus</a></li> -</ul> - - -<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> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <blockquote> + <strong>Warning:</strong> This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. + </blockquote> + + <h1 align="CENTER">Module mod_status</h1> + + <p>This module provides information on server activity and + performance.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_status.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + status_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.1 and later.</p> + + <h2>Summary</h2> + + <p>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> + + <p>The details given are:</p> + + <ul> + <li>The number of children serving requests</li> + + <li>The number of idle children</li> + + <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> + + <li>A total number of accesses and byte count served (*)</li> + + <li>The time the server was started/restarted and the time it + has been running for</li> + + <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> + + <li>The current percentage CPU used by each child and in + total by Apache (*)</li> + + <li>The current hosts and requests being processed (*)</li> + </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>Directives</h2> + + <ul> + <li><a href="#extendedstatus">ExtendedStatus</a></li> + </ul> + + <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 @@ -98,76 +92,66 @@ domain add this code to your <CODE>access.conf</CODE> configuration file 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>. - -<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> - -<H2><A NAME="extendedstatus">ExtendedStatus directive</A></H2> -<!--%plaintext <?INDEX {\tt ExtendedStatus} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ExtendedStatus On|Off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ExtendedStatus Off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config <BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> - <A - HREF="directive-dict.html#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> mod_status<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> ExtendedStatus is only available - in Apache 1.3.2 and later. - -<P> -This directive controls whether the server keeps track of extended -status information for each request. This is only useful if the status module -is enabled on the server. -</P> -<P> -This setting applies to the entire server, and cannot be enabled or -disabled on a virtualhost-by-virtualhost basis. -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</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> + + <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.</p> + + <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>. + + <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 /> + + <h2><a id="extendedstatus" name="extendedstatus">ExtendedStatus + directive</a></h2> + <!--%plaintext <?INDEX {\tt ExtendedStatus} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ExtendedStatus + On|Off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>ExtendedStatus + Off</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config <br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_status<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> ExtendedStatus + is only available in Apache 1.3.2 and later. + + <p>This directive controls whether the server keeps track of + extended status information for each request. This is only + useful if the status module is enabled on the server.</p> + + <p>This setting applies to the entire server, and cannot be + enabled or disabled on a virtualhost-by-virtualhost basis.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_suexec.html b/docs/manual/mod/mod_suexec.html index 0910999f1a..862a9a6fec 100644 --- a/docs/manual/mod/mod_suexec.html +++ b/docs/manual/mod/mod_suexec.html @@ -1,95 +1,75 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_suexec</TITLE> -</HEAD> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_suexec</H1> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> -<P> -This module provides support for <A HREF="../suexec.html"> -running CGI scripts as a specified User and Group</A>. -</P> + <title>Apache module mod_suexec</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_suexec.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> suexec_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 2.0 and later. -</P> + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> -<h2>Summary</h2> + <h1 align="CENTER">Module mod_suexec</h1> -<p>This module allows CGI scripts to run as a specified user and Group.</p> + <p>This module provides support for <a + href="../suexec.html">running CGI scripts as a specified User + and Group</a>.</p> -<H2>Directives</H2> -<UL> - <LI><A HREF="#suexecusergroup">SuexecUserGroup</A> -</UL> + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mod_suexec.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + suexec_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 2.0 and later.</p> -<H2><A NAME="suexecusergroup">SuexecUserGroup directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SuexecUserGroup <EM>User Group</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_suexec<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SuexecUserGroup is only available in 2.0 and later.</P> -<P> -The <CODE>SuexecUserGroup</CODE> directive allows you to specify a user and -group for CGI programs to run as. Non-CGI requests are still processes -with the user specified in the User directive. This directive replaces -using the User and Group directives inside of VirtualHosts. -</P> -<HR> + <h2>Summary</h2> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 2.0 -</H3> + <p>This module allows CGI scripts to run as a specified user + and Group.</p> -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + <h2>Directives</h2> + + <ul> + <li><a href="#suexecusergroup">SuexecUserGroup</a></li> + </ul> + + <h2><a id="suexecusergroup" + name="suexecusergroup">SuexecUserGroup directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> SuexecUserGroup + <em>User Group</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> None<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_suexec<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> SuexecUserGroup + is only available in 2.0 and later.</p> + + <p>The <code>SuexecUserGroup</code> directive allows you to + specify a user and group for CGI programs to run as. Non-CGI + requests are still processes with the user specified in the + User directive. This directive replaces using the User and + Group directives inside of VirtualHosts.</p> + <hr /> + + <h3 align="CENTER">Apache HTTP Server Version 2.0</h3> + <a href="./"><img src="../images/index.gif" alt="Index" /></a> + <a href="../"><img src="../images/home.gif" alt="Home" /></a> + </body> +</html> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_unique_id.html b/docs/manual/mod/mod_unique_id.html index 812f26a675..edc9611193 100644 --- a/docs/manual/mod/mod_unique_id.html +++ b/docs/manual/mod/mod_unique_id.html @@ -1,205 +1,204 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_unique_id</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_unique_id</H1> - -<p>This module provides an environment variable with a unique identifier -for each request.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_unique_id.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> unique_id_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later. -</P> - -<h2>Summary</h2> - -<p>This module provides a magic token for each request which is guaranteed -to be unique across "all" requests under very specific conditions. -The unique identifier is even unique across multiple machines in a -properly configured cluster of machines. The environment variable -<CODE>UNIQUE_ID</CODE> is set to the identifier for each request. -Unique identifiers are useful for various reasons which are beyond the -scope of this document.</p> - -<h2>Directives</h2> - -<p>This module has no directives.</p> - - -<H2>Theory</H2> - -<P> -First a brief recap of how the Apache server works on Unix machines. -This feature currently isn't supported on Windows NT. On Unix machines, -Apache creates several children, the children process requests one at -a time. Each child can serve multiple requests in its lifetime. For the -purpose of this discussion, the children don't share any data -with each other. We'll refer to the children as httpd processes. - -<P> -Your website has one or more machines under your administrative control, -together we'll call them a cluster of machines. Each machine can -possibly run multiple instances of Apache. All of these collectively -are considered "the universe", and with certain assumptions we'll -show that in this universe we can generate unique identifiers for each -request, without extensive communication between machines in the cluster. - -<P> -The machines in your cluster should satisfy these requirements. -(Even if you have only one machine you should synchronize its clock -with NTP.) - -<UL> -<LI>The machines' times are synchronized via NTP or other network time - protocol. - -<LI>The machines' hostnames all differ, such that the module can do a - hostname lookup on the hostname and receive a different IP address - for each machine in the cluster. -</UL> - -<P> -As far as operating system assumptions go, we assume that pids (process -ids) fit in 32-bits. If the operating system uses more than 32-bits -for a pid, the fix is trivial but must be performed in the code. - -<P> -Given those assumptions, at a single point in time we can identify -any httpd process on any machine in the cluster from all other httpd -processes. The machine's IP address and the pid of the httpd process -are sufficient to do this. So in order to generate unique identifiers -for requests we need only distinguish between different points in time. - -<P> -To distinguish time we will use a Unix timestamp (seconds since January -1, 1970 UTC), and a 16-bit counter. The timestamp has only one second -granularity, so the counter is used to represent up to 65536 values -during a single second. The quadruple <EM>( ip_addr, pid, time_stamp, -counter )</EM> is sufficient to enumerate 65536 requests per second per -httpd process. There are issues however with pid reuse over -time, and the counter is used to alleviate this issue. - -<P> -When an httpd child is created, the counter is initialized with ( -current microseconds divided by 10 ) modulo 65536 (this formula was -chosen to eliminate some variance problems with the low order bits of -the microsecond timers on some systems). When a unique identifier is -generated, the time stamp used is the time the request arrived at the -web server. The counter is incremented every time an identifier is -generated (and allowed to roll over). - -<P> -The kernel generates a pid for each process as it forks the process, and -pids are allowed to roll over (they're 16-bits on many Unixes, but newer -systems have expanded to 32-bits). So over time the same pid will be -reused. However unless it is reused within the same second, it does not -destroy the uniqueness of our quadruple. That is, we assume the system -does not spawn 65536 processes in a one second interval (it may even be -32768 processes on some Unixes, but even this isn't likely to happen). - -<P> -Suppose that time repeats itself for some reason. That is, suppose that -the system's clock is screwed up and it revisits a past time (or it is -too far forward, is reset correctly, and then revisits the future time). -In this case we can easily show that we can get pid and time stamp reuse. -The choice of initializer for the counter is intended to help defeat this. -Note that we really want a random number to initialize the counter, -but there aren't any readily available numbers on most systems (<EM>i.e.</EM>, you -can't use rand() because you need to seed the generator, and can't seed -it with the time because time, at least at one second resolution, has -repeated itself). This is not a perfect defense. - -<P> -How good a defense is it? Suppose that one of your machines serves -at most 500 requests per second (which is a very reasonable upper bound -at this writing, because systems generally do more than just shovel out -static files). To do that it will require a number of children which -depends on how many concurrent clients you have. But we'll be pessimistic -and suppose that a single child is able to serve 500 requests per second. -There are 1000 possible starting counter values such that two sequences -of 500 requests overlap. So there is a 1.5% chance that if time (at one -second resolution) repeats itself this child will repeat a counter value, -and uniqueness will be broken. This was a very pessimistic example, -and with real world values it's even less likely to occur. If your -system is such that it's still likely to occur, then perhaps you should -make the counter 32 bits (by editing the code). - -<P> -You may be concerned about the clock being "set back" during summer -daylight savings. However this isn't an issue because the times used here -are UTC, which "always" go forward. Note that x86 based Unixes may need -proper configuration for this to be true -- they should be configured to -assume that the motherboard clock is on UTC and compensate appropriately. -But even still, if you're running NTP then your UTC time will be correct -very shortly after reboot. - -<P> -The <CODE>UNIQUE_ID</CODE> environment variable is constructed by -encoding the 112-bit (32-bit IP address, 32 bit pid, 32 bit time stamp, -16 bit counter) quadruple using the alphabet <CODE>[A-Za-z0-9@-]</CODE> -in a manner similar to MIME base64 encoding, producing 19 characters. -The MIME base64 alphabet is actually <CODE>[A-Za-z0-9+/]</CODE> however -<CODE>+</CODE> and <CODE>/</CODE> need to be specially encoded in URLs, -which makes them less desirable. All values are encoded in network -byte ordering so that the encoding is comparable across architectures of -different byte ordering. The actual ordering of the encoding is: time -stamp, IP address, pid, counter. This ordering has a purpose, but it -should be emphasized that applications should not dissect the encoding. -Applications should treat the entire encoded <CODE>UNIQUE_ID</CODE> as an -opaque token, which can be compared against other <CODE>UNIQUE_ID</CODE>s -for equality only. - -<P> -The ordering was chosen such that it's possible to change the encoding -in the future without worrying about collision with an existing database -of <CODE>UNIQUE_ID</CODE>s. The new encodings should also keep the time -stamp as the first element, and can otherwise use the same alphabet and -bit length. Since the time stamps are essentially an increasing sequence, -it's sufficient to have a <EM>flag second</EM> in which all machines in the -cluster stop serving and request, and stop using the old encoding format. -Afterwards they can resume requests and begin issuing the new encodings. - -<P> -This we believe is a relatively portable solution to this problem. It can -be extended to multithreaded systems like Windows NT, and can grow with -future needs. The identifiers generated have essentially an infinite -life-time because future identifiers can be made longer as required. -Essentially no communication is required between machines in the cluster -(only NTP synchronization is required, which is low overhead), and no -communication between httpd processes is required (the communication is -implicit in the pid value assigned by the kernel). In very specific -situations the identifier can be shortened, but more information needs -to be assumed (for example the 32-bit IP address is overkill for any -site, but there is no portable shorter replacement for it). - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_unique_id</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_unique_id</h1> + + <p>This module provides an environment variable with a unique + identifier for each request.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_unique_id.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + unique_id_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.3 and later.</p> + + <h2>Summary</h2> + + <p>This module provides a magic token for each request which is + guaranteed to be unique across "all" requests under very + specific conditions. The unique identifier is even unique + across multiple machines in a properly configured cluster of + machines. The environment variable <code>UNIQUE_ID</code> is + set to the identifier for each request. Unique identifiers are + useful for various reasons which are beyond the scope of this + document.</p> + + <h2>Directives</h2> + + <p>This module has no directives.</p> + + <h2>Theory</h2> + + <p>First a brief recap of how the Apache server works on Unix + machines. This feature currently isn't supported on Windows NT. + On Unix machines, Apache creates several children, the children + process requests one at a time. Each child can serve multiple + requests in its lifetime. For the purpose of this discussion, + the children don't share any data with each other. We'll refer + to the children as httpd processes.</p> + + <p>Your website has one or more machines under your + administrative control, together we'll call them a cluster of + machines. Each machine can possibly run multiple instances of + Apache. All of these collectively are considered "the + universe", and with certain assumptions we'll show that in this + universe we can generate unique identifiers for each request, + without extensive communication between machines in the + cluster.</p> + + <p>The machines in your cluster should satisfy these + requirements. (Even if you have only one machine you should + synchronize its clock with NTP.)</p> + + <ul> + <li>The machines' times are synchronized via NTP or other + network time protocol.</li> + + <li>The machines' hostnames all differ, such that the module + can do a hostname lookup on the hostname and receive a + different IP address for each machine in the cluster.</li> + </ul> + + <p>As far as operating system assumptions go, we assume that + pids (process ids) fit in 32-bits. If the operating system uses + more than 32-bits for a pid, the fix is trivial but must be + performed in the code.</p> + + <p>Given those assumptions, at a single point in time we can + identify any httpd process on any machine in the cluster from + all other httpd processes. The machine's IP address and the pid + of the httpd process are sufficient to do this. So in order to + generate unique identifiers for requests we need only + distinguish between different points in time.</p> + + <p>To distinguish time we will use a Unix timestamp (seconds + since January 1, 1970 UTC), and a 16-bit counter. The timestamp + has only one second granularity, so the counter is used to + represent up to 65536 values during a single second. The + quadruple <em>( ip_addr, pid, time_stamp, counter )</em> is + sufficient to enumerate 65536 requests per second per httpd + process. There are issues however with pid reuse over time, and + the counter is used to alleviate this issue.</p> + + <p>When an httpd child is created, the counter is initialized + with ( current microseconds divided by 10 ) modulo 65536 (this + formula was chosen to eliminate some variance problems with the + low order bits of the microsecond timers on some systems). When + a unique identifier is generated, the time stamp used is the + time the request arrived at the web server. The counter is + incremented every time an identifier is generated (and allowed + to roll over).</p> + + <p>The kernel generates a pid for each process as it forks the + process, and pids are allowed to roll over (they're 16-bits on + many Unixes, but newer systems have expanded to 32-bits). So + over time the same pid will be reused. However unless it is + reused within the same second, it does not destroy the + uniqueness of our quadruple. That is, we assume the system does + not spawn 65536 processes in a one second interval (it may even + be 32768 processes on some Unixes, but even this isn't likely + to happen).</p> + + <p>Suppose that time repeats itself for some reason. That is, + suppose that the system's clock is screwed up and it revisits a + past time (or it is too far forward, is reset correctly, and + then revisits the future time). In this case we can easily show + that we can get pid and time stamp reuse. The choice of + initializer for the counter is intended to help defeat this. + Note that we really want a random number to initialize the + counter, but there aren't any readily available numbers on most + systems (<em>i.e.</em>, you can't use rand() because you need + to seed the generator, and can't seed it with the time because + time, at least at one second resolution, has repeated itself). + This is not a perfect defense.</p> + + <p>How good a defense is it? Suppose that one of your machines + serves at most 500 requests per second (which is a very + reasonable upper bound at this writing, because systems + generally do more than just shovel out static files). To do + that it will require a number of children which depends on how + many concurrent clients you have. But we'll be pessimistic and + suppose that a single child is able to serve 500 requests per + second. There are 1000 possible starting counter values such + that two sequences of 500 requests overlap. So there is a 1.5% + chance that if time (at one second resolution) repeats itself + this child will repeat a counter value, and uniqueness will be + broken. This was a very pessimistic example, and with real + world values it's even less likely to occur. If your system is + such that it's still likely to occur, then perhaps you should + make the counter 32 bits (by editing the code).</p> + + <p>You may be concerned about the clock being "set back" during + summer daylight savings. However this isn't an issue because + the times used here are UTC, which "always" go forward. Note + that x86 based Unixes may need proper configuration for this to + be true -- they should be configured to assume that the + motherboard clock is on UTC and compensate appropriately. But + even still, if you're running NTP then your UTC time will be + correct very shortly after reboot.</p> + + <p>The <code>UNIQUE_ID</code> environment variable is + constructed by encoding the 112-bit (32-bit IP address, 32 bit + pid, 32 bit time stamp, 16 bit counter) quadruple using the + alphabet <code>[A-Za-z0-9@-]</code> in a manner similar to MIME + base64 encoding, producing 19 characters. The MIME base64 + alphabet is actually <code>[A-Za-z0-9+/]</code> however + <code>+</code> and <code>/</code> need to be specially encoded + in URLs, which makes them less desirable. All values are + encoded in network byte ordering so that the encoding is + comparable across architectures of different byte ordering. The + actual ordering of the encoding is: time stamp, IP address, + pid, counter. This ordering has a purpose, but it should be + emphasized that applications should not dissect the encoding. + Applications should treat the entire encoded + <code>UNIQUE_ID</code> as an opaque token, which can be + compared against other <code>UNIQUE_ID</code>s for equality + only.</p> + + <p>The ordering was chosen such that it's possible to change + the encoding in the future without worrying about collision + with an existing database of <code>UNIQUE_ID</code>s. The new + encodings should also keep the time stamp as the first element, + and can otherwise use the same alphabet and bit length. Since + the time stamps are essentially an increasing sequence, it's + sufficient to have a <em>flag second</em> in which all machines + in the cluster stop serving and request, and stop using the old + encoding format. Afterwards they can resume requests and begin + issuing the new encodings.</p> + + <p>This we believe is a relatively portable solution to this + problem. It can be extended to multithreaded systems like + Windows NT, and can grow with future needs. The identifiers + generated have essentially an infinite life-time because future + identifiers can be made longer as required. Essentially no + communication is required between machines in the cluster (only + NTP synchronization is required, which is low overhead), and no + communication between httpd processes is required (the + communication is implicit in the pid value assigned by the + kernel). In very specific situations the identifier can be + shortened, but more information needs to be assumed (for + example the 32-bit IP address is overkill for any site, but + there is no portable shorter replacement for it). + <!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html index 98894962c8..68f398d4f3 100644 --- a/docs/manual/mod/mod_userdir.html +++ b/docs/manual/mod/mod_userdir.html @@ -1,139 +1,122 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_userdir</H1> - -<p>This module provides for user-specific directories.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Base -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_userdir.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> userdir_module -</P> - -<h2>Directives</h2> - - -<UL> -<LI><A HREF="#userdir">UserDir</A> -</UL> -<HR> - -<H2><A NAME="userdir">UserDir</A> directive</H2> -<!--%plaintext <?INDEX {\tt UserDir} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> UserDir <EM>directory-filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>UserDir public_html</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_userdir<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> All forms except the <CODE>UserDir -public_html</CODE> form are only available in Apache 1.1 or above. Use -of the <SAMP>enabled</SAMP> keyword, or <SAMP>disabled</SAMP> with a -list of usernames, is only available in Apache 1.3 and 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-filename</EM> is one of the following: -</P> -<UL> - <LI>The name of a directory or a pattern such as those shown below. - </LI> - <LI>The keyword <SAMP>disabled</SAMP>. This turns off <EM>all</EM> - username-to-directory translations except those explicitly named with - the <SAMP>enabled</SAMP> keyword (see below). - </LI> - <LI>The keyword <SAMP>disabled</SAMP> followed by a space-delimited - list of usernames. Usernames that appear in such a list will - <EM>never</EM> have directory translation performed, even if they - appear in an <SAMP>enabled</SAMP> clause. - </LI> - <LI>The keyword <SAMP>enabled</SAMP> followed by a space-delimited list - of usernames. These usernames will have directory translation - performed even if a global disable is in effect, but not if they also - appear in a <SAMP>disabled</SAMP> clause. - </LI> -</UL> -<P> -If neither the <SAMP>enabled</SAMP> nor the <SAMP>disabled</SAMP> -keywords appear in the <SAMP>Userdir</SAMP> directive, the argument is -treated as a filename pattern, and is used to turn the name into a -directory specification. A request for -<CODE>http://www.foo.com/~bob/one/two.html</CODE> will be translated to: -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_userdir</h1> + + <p>This module provides for user-specific directories.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_userdir.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + userdir_module</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#userdir">UserDir</a></li> + </ul> + <hr /> + + <h2><a id="userdir" name="userdir">UserDir</a> directive</h2> + <!--%plaintext <?INDEX {\tt UserDir} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> UserDir + <em>directory-filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>UserDir + public_html</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Base<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_userdir<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> All forms except + the <code>UserDir public_html</code> form are only available in + Apache 1.1 or above. Use of the <samp>enabled</samp> keyword, + or <samp>disabled</samp> with a list of usernames, is only + available in Apache 1.3 and 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-filename</em> is one of the + following:</p> + + <ul> + <li>The name of a directory or a pattern such as those shown + below.</li> + + <li>The keyword <samp>disabled</samp>. This turns off + <em>all</em> username-to-directory translations except those + explicitly named with the <samp>enabled</samp> keyword (see + below).</li> + + <li>The keyword <samp>disabled</samp> followed by a + space-delimited list of usernames. Usernames that appear in + such a list will <em>never</em> have directory translation + performed, even if they appear in an <samp>enabled</samp> + clause.</li> + + <li>The keyword <samp>enabled</samp> followed by a + space-delimited list of usernames. These usernames will have + directory translation performed even if a global disable is + in effect, but not if they also appear in a + <samp>disabled</samp> clause.</li> + </ul> + + <p>If neither the <samp>enabled</samp> nor the + <samp>disabled</samp> keywords appear in the + <samp>Userdir</samp> directive, the argument is treated as a + filename pattern, and is used to turn the name into a directory + specification. A request for + <code>http://www.foo.com/~bob/one/two.html</code> will be + translated to:</p> +<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> +</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> -<BLOCKQUOTE> - <STRONG> - Be careful when using this directive; for instance, - <SAMP>"UserDir ./"</SAMP> would map - <SAMP>"/~root"</SAMP> to - <SAMP>"/"</SAMP> - which is probably undesirable. If you are - running Apache 1.3 or above, it is strongly recommended that your - configuration include a - "<SAMP>UserDir disabled root</SAMP>" declaration. - 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> -</BLOCKQUOTE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + <br /> + <br /> + + + <blockquote> + <strong>Be careful when using this directive; for instance, + <samp>"UserDir ./"</samp> would map + <samp>"/~root"</samp> to <samp>"/"</samp> - which is probably + undesirable. If you are running Apache 1.3 or above, it is + strongly recommended that your configuration include a + "<samp>UserDir disabled root</samp>" declaration. + 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> + </blockquote> + <!--#include virtual="footer.html" --> + </body> +</html> diff --git a/docs/manual/mod/mod_usertrack.html b/docs/manual/mod/mod_usertrack.html index c8fe14e480..22d46b3cfe 100644 --- a/docs/manual/mod/mod_usertrack.html +++ b/docs/manual/mod/mod_usertrack.html @@ -1,90 +1,80 @@ -<!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" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_usertrack</H1> - -<p>This module uses cookies to provide for a <em>clickstream</em> log of user -activity on a site.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_usertrack.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> usertrack_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Known as mod_cookies prior to -Apache 1.3. -</P> - -<h2>Summary</h2> - -<p>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.</p> - -<H2>Directives</H2> - -<UL> -<li><a href="#cookiedomain">CookieDomain</a></li> -<LI><A HREF="#cookieexpires">CookieExpires</A> -<LI><A HREF="#cookiename">CookieName</A> -<li><a href="#cookiestyle">CookieStyle</a></li> -<LI><A HREF="#cookietracking">CookieTracking</A> -</UL> - -<H2>Logging</H2> - -<p>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 multiple log files. 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> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <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"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_usertrack</h1> + + <p>This module uses cookies to provide for a + <em>clickstream</em> log of user activity on a site.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_usertrack.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + usertrack_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Known as + mod_cookies prior to Apache 1.3.</p> -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>Summary</h2> -<H2>2-digit or 4-digit dates for cookies?</H2> + <p>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.</p> -(the following is from message -<022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> in -the new-httpd archives) + <h2>Directives</h2> -<P> + <ul> + <li><a href="#cookiedomain">CookieDomain</a></li> -<PRE> + <li><a href="#cookieexpires">CookieExpires</a></li> + + <li><a href="#cookiename">CookieName</a></li> + + <li><a href="#cookiestyle">CookieStyle</a></li> + + <li><a href="#cookietracking">CookieTracking</a></li> + </ul> + + <h2>Logging</h2> + + <p>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 multiple log files. The cookie itself is logged by + using the text <tt>%{cookie}n</tt> in the log file format. For + example:</p> +<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>2-digit or 4-digit dates for cookies?</h2> + (the following is from message + <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> + in the new-httpd archives) +<pre> From: "Christian Allen" <christian@sane.com> Subject: Re: Apache Y2K bug in mod_usertrack.c Date: Tue, 30 Jun 1998 11:41:56 -0400 @@ -115,184 +105,139 @@ Summary: Mozilla 3.x and up understands two digit dates up until "37" form, but also understands 4-digit years, which can probably reach up until 9999. Your best bet for sending a long-life cookie is to send it for some time late in the year "37". -</PRE> - -<hr> - -<h2><a name="cookiedomain">CookieDomain</a> directive</h2> -<a - href="directive-dict.html#Syntax" - rel="Help" -><b>Syntax:</b></a> CookieDomain <i>domain</i><br> -<a - href="directive-dict.html#Context" - rel="Help" -><b>Context:</b></a> server config, virtual host, directory, .htaccess<br> -<a - href="directive-dict.html#Status" - rel="Help" -><b>Status:</b></a> optional<br> -<a - href="directive-dict.html#Module" - rel="Help" -><b>Module:</b></a> mod_usertrack - -<p> -This directive controls the setting of the domain to which the -tracking cookie applies. If not present, no domain is included -in the cookie header field. -</p> -<p> -The domain string <b>must</b> begin with a dot, and <b>must</b> -include at least one embedded dot. That is, ".foo.com" is legal, -but "foo.bar.com" and ".com" are not. -</p> - -<HR> - -<H2><A NAME="cookieexpires">CookieExpires</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieExpires <EM>expiry-period</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> -<b>1.3.20 and earlier:</b> server config, virtual host; -<b>1.3.21 and later:</b> server config, virtual host, directory, .htaccess<br> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_usertrack<P> - -When used, this directive sets an expiry time on the cookie generated -by the usertrack module. The <EM>expiry-period</EM> 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. If the expiry time is in any format other than one -number indicating the number of seconds, it must be enclosed by -double quotes. - -<P>If this directive is not used, cookies last only for the current -browser session.</P> - -<HR> -<H2><A NAME="cookiename">CookieName</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieName <EM>token</EM> -<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>Apache</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_usertrack -<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3.7 and later -<P> -This directive allows you to change the name of the cookie this module -uses for its tracking purposes. By default the cookie is named -"<CODE>Apache</CODE>". -</P> -<P> -You must specify a valid cookie name; results are unpredictable if -you use a name containing unusual characters. Valid characters -include A-Z, a-z, 0-9, "_", and "-". -</P> - -<hr> - -<h2><a name="cookiestyle">CookieStyle</a> directive</h2> -<a - href="directive-dict.html#Syntax" - rel="Help" -><b>Syntax:</b></a> CookieStyle <i>Netscape|Cookie|Cookie2|RFC2109|RFC2965</i><br> -<a - href="directive-dict.html#Context" - rel="Help" -><b>Context:</b></a> server config, virtual host, directory, .htaccess<br> -<a - href="directive-dict.html#Status" - rel="Help" -><b>Status:</b></a> optional<br> -<a - href="directive-dict.html#Module" - rel="Help" -><b>Module:</b></a> mod_usertrack - -<p> -This directive controls the format of the cookie header field. -The three formats allowed are: -</p> -<ul> - <li><b>Netscape</b>, which is the original but now deprecated - syntax. This is the default, and the syntax Apache has - historically used.</li> - <li><b>Cookie</b> or <b>RFC2109</b>, which is the syntax that - superseded the Netscape syntax.</li> - <li><b>Cookie2</b> or <b>RFC2965</b>, which is the most current - cookie syntax.</li> -</ul> - -<p> -Not all clients can understand all of these formats. but you should use -the newest one that is generally acceptable to your users' browsers. -</p> - -<hr> -<H2><A NAME="cookietracking">CookieTracking</A> directive</H2> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CookieTracking on|off<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, -.htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> optional<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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. - - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + <hr /> + + <h2><a id="cookiedomain" name="cookiedomain">CookieDomain</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><b>Syntax:</b></a> CookieDomain <i>domain</i><br /> + <a href="directive-dict.html#Context" + rel="Help"><b>Context:</b></a> server config, virtual host, + directory, .htaccess<br /> + <a href="directive-dict.html#Status" + rel="Help"><b>Status:</b></a> optional<br /> + <a href="directive-dict.html#Module" + rel="Help"><b>Module:</b></a> mod_usertrack + + <p>This directive controls the setting of the domain to which + the tracking cookie applies. If not present, no domain is + included in the cookie header field.</p> + + <p>The domain string <b>must</b> begin with a dot, and + <b>must</b> include at least one embedded dot. That is, + ".foo.com" is legal, but "foo.bar.com" and ".com" are not.</p> + <hr /> + + <h2><a id="cookieexpires" + name="cookieexpires">CookieExpires</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CookieExpires + <em>expiry-period</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> <b>1.3.20 and + earlier:</b> server config, virtual host; <b>1.3.21 and + later:</b> server config, virtual host, directory, + .htaccess<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> optional<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_usertrack + + <p>When used, this directive sets an expiry time on the cookie + generated by the usertrack module. The <em>expiry-period</em> + 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. If the expiry + time is in any format other than one number indicating the + number of seconds, it must be enclosed by double quotes.</p> + + <p>If this directive is not used, cookies last only for the + current browser session.</p> + <hr /> + + <h2><a id="cookiename" name="cookiename">CookieName</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CookieName + <em>token</em> <br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>Apache</em> <br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> optional<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_usertrack <br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 1.3.7 and + later + + <p>This directive allows you to change the name of the cookie + this module uses for its tracking purposes. By default the + cookie is named "<code>Apache</code>".</p> + + <p>You must specify a valid cookie name; results are + unpredictable if you use a name containing unusual characters. + Valid characters include A-Z, a-z, 0-9, "_", and "-".</p> + <hr /> + + <h2><a id="cookiestyle" name="cookiestyle">CookieStyle</a> + directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><b>Syntax:</b></a> CookieStyle + <i>Netscape|Cookie|Cookie2|RFC2109|RFC2965</i><br /> + <a href="directive-dict.html#Context" + rel="Help"><b>Context:</b></a> server config, virtual host, + directory, .htaccess<br /> + <a href="directive-dict.html#Status" + rel="Help"><b>Status:</b></a> optional<br /> + <a href="directive-dict.html#Module" + rel="Help"><b>Module:</b></a> mod_usertrack + + <p>This directive controls the format of the cookie header + field. The three formats allowed are:</p> + + <ul> + <li><b>Netscape</b>, which is the original but now deprecated + syntax. This is the default, and the syntax Apache has + historically used.</li> + + <li><b>Cookie</b> or <b>RFC2109</b>, which is the syntax that + superseded the Netscape syntax.</li> + + <li><b>Cookie2</b> or <b>RFC2965</b>, which is the most + current cookie syntax.</li> + </ul> + + <p>Not all clients can understand all of these formats. but you + should use the newest one that is generally acceptable to your + users' browsers.</p> + <hr /> + + <h2><a id="cookietracking" + name="cookietracking">CookieTracking</a> directive</h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CookieTracking + on|off<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host, directory, .htaccess<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> FileInfo<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> optional<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> 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. <!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mod_vhost_alias.html b/docs/manual/mod/mod_vhost_alias.html index 8051209073..1a6e6cc980 100644 --- a/docs/manual/mod/mod_vhost_alias.html +++ b/docs/manual/mod/mod_vhost_alias.html @@ -1,345 +1,340 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_vhost_alias</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Module mod_vhost_alias</H1> - -<P> -This module provides support for <A -HREF="../vhosts/mass.html">dynamically configured mass virtual -hosting</A>. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_vhost_alias.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> vhost_alias_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3.7 and later. -</P> - -<h2>Summary</h2> - -<p>This module creates dynamically configured virtual hosts, by -allowing the IP address and/or the <code>Host:</code> header of the -HTTP request to be used as part of the pathname to determine what -files to serve. This allows for easy use of a huge number of virtual -hosts with similar configurations.</p> - -<H2>Directives</H2> -<UL> - <LI><A HREF="#virtualdocumentroot">VirtualDocumentRoot</A> - <LI><A HREF="#virtualdocumentrootip">VirtualDocumentRootIP</A> - <LI><A HREF="#virtualscriptalias">VirtualScriptAlias</A> - <LI><A HREF="#virtualscriptaliasip">VirtualScriptAliasIP</A> -</UL> - -<p>See also: <a href="core.html#usecanonicalname">UseCanonicalName</a>.</p> - - -<H2>Directory Name Interpolation</H2> - -<P> -All the directives in this module interpolate a string into a -pathname. The interpolated string (henceforth called the "name") may -be either the server name (see the -<A HREF="core.html#usecanonicalname"><CODE>UseCanonicalName</CODE></A> -directive for details on how this is determined) or the IP address of -the virtual host on the server in dotted-quad format. The -interpolation is controlled by specifiers inspired by -<CODE>printf</CODE> which have a number of formats: -<DL> - <DT><CODE>%%</CODE> - <DD>insert a <CODE>%</CODE> - <DT><CODE>%p</CODE> - <DD>insert the port number of the virtual host - <DT><CODE>%N.M</CODE> - <DD>insert (part of) the name -</DL> -</P> - -<P> -<CODE>N</CODE> and <CODE>M</CODE> are used to specify substrings of -the name. <CODE>N</CODE> selects from the dot-separated components of -the name, and <CODE>M</CODE> selects characters within whatever -<CODE>N</CODE> has selected. <CODE>M</CODE> is optional and defaults -to zero if it isn't present; the dot must be present if and only if -<CODE>M</CODE> is present. The interpretation is as follows: -<DL> - <DT><CODE>0</CODE> - <DD>the whole name - <DT><CODE>1</CODE> - <DD>the first part - <DT><CODE>2</CODE> - <DD>the second part - <DT><CODE>-1</CODE> - <DD>the last part - <DT><CODE>-2</CODE> - <DD>the penultimate part - <DT><CODE>2+</CODE> - <DD>the second and all subsequent parts - <DT><CODE>-2+</CODE> - <DD>the penultimate and all preceding parts - <DT><CODE>1+</CODE> and <CODE>-1+</CODE> - <DD>the same as <CODE>0</CODE> -</DL> -If <CODE>N</CODE> or <CODE>M</CODE> is greater than the number of -parts available a single underscore is interpolated. -</P> - -<H3>Examples</H3> - -<P> -For simple name-based virtual hosts you might use the following -directives in your server configuration file: -<PRE> - UseCanonicalName Off - VirtualDocumentRoot /usr/local/apache/vhosts/%0 -</PRE> -A request for <CODE>http://www.example.com/directory/file.html</CODE> -will be satisfied by the file -<CODE>/usr/local/apache/vhosts/www.example.com/directory/file.html</CODE>. -</P> - -<P> -For a very large number of virtual hosts it is a good idea to arrange -the files to reduce the size of the <CODE>vhosts</CODE> directory. To -do this you might use the following in your configuration file: -<PRE> - UseCanonicalName Off - VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2 -</PRE> -A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> -will be satisfied by the file -<CODE>/usr/local/apache/vhosts/isp.com/e/x/a/example/directory/file.html</CODE>. -A more even spread of files can be achieved by hashing from the end of -the name, for example: -<PRE> - VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2 -</PRE> -The example request would come from -<CODE>/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html</CODE>. -Alternatively you might use: -<PRE> - VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+ -</PRE> -The example request would come from -<CODE>/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html</CODE>. -</P> - -<P> -For IP-based virtual hosting you might use the following in your -configuration file: -<PRE> - UseCanonicalName DNS - VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs - VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin -</PRE> -A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> -would be satisfied by the file -<CODE>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</CODE> if -the IP address of <CODE>www.example.com</CODE> were 10.20.30.40. -A request for <CODE>http://www.example.isp.com/cgi-bin/script.pl</CODE> -would be satisfied by executing the program -<CODE>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</CODE>. -</P> - -<P> -If you want to include the <CODE>.</CODE> character in a -<CODE>VirtualDocumentRoot</CODE> directive, but it clashes with a -<CODE>%</CODE> directive, you can work around the problem in the -following way: -<PRE> - VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0 -</PRE> -A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> -will be satisfied by the file -<CODE>/usr/local/apache/vhosts/example.isp/directory/file.html</CODE>. -</P> - -<P> -The <A HREF="mod_log_config.html#formats">LogFormat directives</A> -<CODE>%V</CODE> and <CODE>%A</CODE> are useful in conjunction with -this module. -</P> - -<HR> - - -<H2><A NAME="virtualdocumentroot">VirtualDocumentRoot directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualDocumentRoot <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualDocumentRoot is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualDocumentRoot</CODE> directive allows you to determine -where Apache will find your documents based on the value of the server -name. The result of expanding <EM>interpolated-directory</EM> is used -as the root of the document tree in a similar manner to the -<A HREF="core.html#documentroot"><CODE>DocumentRoot</CODE></A> -directive's argument. If <EM>interpolated-directory</EM> is -<CODE>none</CODE> then <CODE>VirtaulDocumentRoot</CODE> is turned off. -This directive cannot be used in the same context as -<A HREF="#virtualdocumentrootip"><CODE>VirtualDocumentRootIP</CODE></A>. -</P> -<HR> - -<H2><A NAME="virtualdocumentrootip">VirtualDocumentRootIP directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualDocumentRootIP <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualDocumentRootIP is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualDocumentRootIP</CODE> directive is like the -<A HREF="#virtualdocumentroot"><CODE>VirtualDocumentRoot</CODE></A> directive, -except that it uses the IP address of the server end of the connection -instead of the server name. -</P> -<HR> - -<H2><A NAME="virtualscriptalias">VirtualScriptAlias directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualScriptAlias <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualScriptAlias is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualScriptAlias</CODE> directive allows you to determine -where Apache will find CGI scripts in a similar manner to -<A HREF="#virtualdocumentroot"><CODE>VirtualDocumentRoot</CODE></A> -does for other documents. It matches requests for URIs starting -<CODE>/cgi-bin/</CODE>, much like -<CODE><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> /cgi-bin/</CODE> -would. -</P> -<HR> - -<H2><A NAME="virtualscriptaliasip">VirtualScriptAliasIP directive</A></H2> -<P> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> VirtualScriptAliasIP <EM>interpolated-directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> None<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> VirtualScriptAliasIP is only available in 1.3.7 and later.</P> -<P> -The <CODE>VirtualScriptAliasIP</CODE> directive is like the -<A HREF="#virtualscriptalias"><CODE>VirtualScriptAlias</CODE></A> directive, -except that it uses the IP address of the server end of the connection -instead of the server name. -</P> -<HR> - -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.3 -</H3> - -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> - -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_vhost_alias</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_vhost_alias</h1> + + <p>This module provides support for <a + href="../vhosts/mass.html">dynamically configured mass virtual + hosting</a>.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_vhost_alias.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + vhost_alias_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 1.3.7 and later.</p> + + <h2>Summary</h2> + + <p>This module creates dynamically configured virtual hosts, by + allowing the IP address and/or the <code>Host:</code> header of + the HTTP request to be used as part of the pathname to + determine what files to serve. This allows for easy use of a + huge number of virtual hosts with similar configurations.</p> + + <h2>Directives</h2> + + <ul> + <li><a + href="#virtualdocumentroot">VirtualDocumentRoot</a></li> + + <li><a + href="#virtualdocumentrootip">VirtualDocumentRootIP</a></li> + + <li><a href="#virtualscriptalias">VirtualScriptAlias</a></li> + + <li><a + href="#virtualscriptaliasip">VirtualScriptAliasIP</a></li> + </ul> + + <p>See also: <a + href="core.html#usecanonicalname">UseCanonicalName</a>.</p> + + <h2>Directory Name Interpolation</h2> + + <p>All the directives in this module interpolate a string into + a pathname. The interpolated string (henceforth called the + "name") may be either the server name (see the <a + href="core.html#usecanonicalname"><code>UseCanonicalName</code></a> + directive for details on how this is determined) or the IP + address of the virtual host on the server in dotted-quad + format. The interpolation is controlled by specifiers inspired + by <code>printf</code> which have a number of formats:</p> + + <dl> + <dt><code>%%</code></dt> + + <dd>insert a <code>%</code></dd> + + <dt><code>%p</code></dt> + + <dd>insert the port number of the virtual host</dd> + + <dt><code>%N.M</code></dt> + + <dd>insert (part of) the name</dd> + </dl> + <br /> + <br /> + + + <p><code>N</code> and <code>M</code> are used to specify + substrings of the name. <code>N</code> selects from the + dot-separated components of the name, and <code>M</code> + selects characters within whatever <code>N</code> has selected. + <code>M</code> is optional and defaults to zero if it isn't + present; the dot must be present if and only if <code>M</code> + is present. The interpretation is as follows:</p> + + <dl> + <dt><code>0</code></dt> + + <dd>the whole name</dd> + + <dt><code>1</code></dt> + + <dd>the first part</dd> + + <dt><code>2</code></dt> + + <dd>the second part</dd> + + <dt><code>-1</code></dt> + + <dd>the last part</dd> + + <dt><code>-2</code></dt> + + <dd>the penultimate part</dd> + + <dt><code>2+</code></dt> + + <dd>the second and all subsequent parts</dd> + + <dt><code>-2+</code></dt> + + <dd>the penultimate and all preceding parts</dd> + + <dt><code>1+</code> and <code>-1+</code></dt> + + <dd>the same as <code>0</code></dd> + </dl> + If <code>N</code> or <code>M</code> is greater than the number + of parts available a single underscore is interpolated. <br /> + <br /> + + + <h3>Examples</h3> + + <p>For simple name-based virtual hosts you might use the + following directives in your server configuration file:</p> +<pre> + UseCanonicalName Off + VirtualDocumentRoot /usr/local/apache/vhosts/%0 +</pre> + A request for + <code>http://www.example.com/directory/file.html</code> will be + satisfied by the file + <code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>. + <br /> + <br /> + + + <p>For a very large number of virtual hosts it is a good idea + to arrange the files to reduce the size of the + <code>vhosts</code> directory. To do this you might use the + following in your configuration file:</p> +<pre> + UseCanonicalName Off + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2 +</pre> + A request for + <code>http://www.example.isp.com/directory/file.html</code> + will be satisfied by the file + <code>/usr/local/apache/vhosts/isp.com/e/x/a/example/directory/file.html</code>. + A more even spread of files can be achieved by hashing from the + end of the name, for example: +<pre> + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2 +</pre> + The example request would come from + <code>/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html</code>. + Alternatively you might use: +<pre> + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+ +</pre> + The example request would come from + <code>/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html</code>. + <br /> + <br /> + + + <p>For IP-based virtual hosting you might use the following in + your configuration file:</p> +<pre> + UseCanonicalName DNS + VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs + VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin +</pre> + A request for + <code>http://www.example.isp.com/directory/file.html</code> + would be satisfied by the file + <code>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</code> + if the IP address of <code>www.example.com</code> were + 10.20.30.40. A request for + <code>http://www.example.isp.com/cgi-bin/script.pl</code> would + be satisfied by executing the program + <code>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</code>. + <br /> + <br /> + + + <p>If you want to include the <code>.</code> character in a + <code>VirtualDocumentRoot</code> directive, but it clashes with + a <code>%</code> directive, you can work around the problem in + the following way:</p> +<pre> + VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0 +</pre> + A request for + <code>http://www.example.isp.com/directory/file.html</code> + will be satisfied by the file + <code>/usr/local/apache/vhosts/example.isp/directory/file.html</code>. + <br /> + <br /> + + + <p>The <a href="mod_log_config.html#formats">LogFormat + directives</a> <code>%V</code> and <code>%A</code> are useful + in conjunction with this module.</p> + <hr /> + + <h2><a id="virtualdocumentroot" + name="virtualdocumentroot">VirtualDocumentRoot + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> VirtualDocumentRoot + <em>interpolated-directory</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> None<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + VirtualDocumentRoot is only available in 1.3.7 and later.</p> + + <p>The <code>VirtualDocumentRoot</code> directive allows you to + determine where Apache will find your documents based on the + value of the server name. The result of expanding + <em>interpolated-directory</em> is used as the root of the + document tree in a similar manner to the <a + href="core.html#documentroot"><code>DocumentRoot</code></a> + directive's argument. If <em>interpolated-directory</em> is + <code>none</code> then <code>VirtaulDocumentRoot</code> is + turned off. This directive cannot be used in the same context + as <a + href="#virtualdocumentrootip"><code>VirtualDocumentRootIP</code></a>.</p> + <hr /> + + <h2><a id="virtualdocumentrootip" + name="virtualdocumentrootip">VirtualDocumentRootIP + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> VirtualDocumentRootIP + <em>interpolated-directory</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> None<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + VirtualDocumentRootIP is only available in 1.3.7 and later.</p> + + <p>The <code>VirtualDocumentRootIP</code> directive is like the + <a + href="#virtualdocumentroot"><code>VirtualDocumentRoot</code></a> + directive, except that it uses the IP address of the server end + of the connection instead of the server name.</p> + <hr /> + + <h2><a id="virtualscriptalias" + name="virtualscriptalias">VirtualScriptAlias directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> VirtualScriptAlias + <em>interpolated-directory</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> None<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + VirtualScriptAlias is only available in 1.3.7 and later.</p> + + <p>The <code>VirtualScriptAlias</code> directive allows you to + determine where Apache will find CGI scripts in a similar + manner to <a + href="#virtualdocumentroot"><code>VirtualDocumentRoot</code></a> + does for other documents. It matches requests for URIs starting + <code>/cgi-bin/</code>, much like <code><a + href="mod_alias.html#scriptalias">ScriptAlias</a> + /cgi-bin/</code> would.</p> + <hr /> + + <h2><a id="virtualscriptaliasip" + name="virtualscriptaliasip">VirtualScriptAliasIP + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> VirtualScriptAliasIP + <em>interpolated-directory</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> None<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Extension<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + VirtualScriptAliasIP is only available in 1.3.7 and later.</p> + + <p>The <code>VirtualScriptAliasIP</code> directive is like the + <a + href="#virtualscriptalias"><code>VirtualScriptAlias</code></a> + directive, except that it uses the IP address of the server end + of the connection instead of the server name.</p> + <hr /> + + <h3 align="CENTER">Apache HTTP Server Version 1.3</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/docs/manual/mod/module-dict.html b/docs/manual/mod/module-dict.html index 7d99828e81..5e7cadb821 100644 --- a/docs/manual/mod/module-dict.html +++ b/docs/manual/mod/module-dict.html @@ -1,144 +1,123 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Definitions of terms used to describe Apache modules - </TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Terms Used to Describe Apache Modules</H1> - - <P> - Each Apache module is described using a common format that looks - like this: - </P> - <DL> - <DD><A - HREF="#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> <EM>status</EM> - <BR> - <A - HREF="#SourceFile" - REL="Help" - ><STRONG>Source File:</STRONG></A> <EM>source-file</EM> - <BR> - <A - HREF="#ModuleIdentifier" - REL="Help" - ><STRONG>Module Identifier:</STRONG></A> <EM>module-identifier</EM> - <BR> - <A - HREF="#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM> - </DD> - </DL> - <P> - Each of the attributes, complete with values where possible, are - described in this document. - </P> - - <H2>Module Terms</H2> - <UL> - <LI><A HREF="#Status">Status</A> - </LI> - <LI><A HREF="#SourceFile">Source File</A> - </LI> - <LI><A HREF="#ModuleIdentifier">Module Identifier</A> - </LI> - <LI><A HREF="#Compatibility">Compatibility</A> - </LI> - </UL> - - <HR> - <H2><A NAME="Status">Status</A></H2> - <P> - This indicates how tightly bound into the Apache Web server the - module is; in other words, you may need to recompile the server in - order to gain access to the module and its functionality. Possible - values for this attribute are: - </P> - <DL> - <DT><STRONG>MPM</STRONG> - </DT> - <DD>A module with status "MPM" is a <a - href="../mpm.html">Multi-Processing Module</a>. Unlike the other - types of modules, Apache must have one and only one MPM in use at - any time. This type of module is responsible for basic request - handling and dispatching. - <P> - </P> - <DT><STRONG>Base</STRONG> - </DT> - <DD>A module labeled as having "Base" status is compiled - and loaded into the server by default, and is therefore normally - available unless you have taken steps to remove the module from your - configuration. - <P> - </P> - </DD> - <DT><STRONG>Extension</STRONG> - </DT> - <DD>A module with "Extension" status is not normally - compiled and loaded into the server. To enable the module and its - functionality, you may need to change the server build - configuration files and re-compile Apache. - <P> - </P> - </DD> - <DT><STRONG>Experimental</STRONG> - </DT> - <DD>"Experimental" status indicates that the module is - available as part of the Apache kit, but you are on your own if you - try to use it. The module is being documented for completeness, - and is not necessarily supported. - <P> - </P> - </DD> - <DT><STRONG>External</STRONG> - </DT> - <DD>Modules which are not included with the base Apache - distribution ("third-party modules") may use the - "External" status. We are not responsible for, nor do we - support such modules. - <P> - </P> - </DD> - </DL> - - <HR> - <H2><A NAME="SourceFile">Source File</A></H2> - <P> - This quite simply lists the name of the source file which contains - the code for the module. This is also the name used by the <A - HREF="core.html#ifmodule"><CODE><IfModule></CODE></A> - directive. - </P> - - <HR> - <H2><A NAME="ModuleIdentifier">Module Identifier</A></H2> - <P> - This is a string which identifies the module for use in the <A - HREF="mod_so.html#loadmodule">LoadModule</A> directive when - dynamically loading modules. In particular, it is the name - of the external variable of type module in the source file. - </P> - - <HR> - <H2><A NAME="Compatibility">Compatibility</A></H2> - <P> - If the module was not part of the original Apache version 2 - distribution, the version in which it was introduced should be listed - here. - </P> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Definitions of terms used to describe Apache + modules</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Terms Used to Describe Apache Modules</h1> + + <p>Each Apache module is described using a common format that + looks like this:</p> + + <dl> + <dd><a href="#Status" rel="Help"><strong>Status:</strong></a> + <em>status</em><br /> + <a href="#SourceFile" rel="Help"><strong>Source + File:</strong></a> <em>source-file</em><br /> + <a href="#ModuleIdentifier" rel="Help"><strong>Module + Identifier:</strong></a> <em>module-identifier</em><br /> + <a href="#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + <em>compatibility notes</em></dd> + </dl> + + <p>Each of the attributes, complete with values where possible, + are described in this document.</p> + + <h2>Module Terms</h2> + + <ul> + <li><a href="#Status">Status</a></li> + + <li><a href="#SourceFile">Source File</a></li> + + <li><a href="#ModuleIdentifier">Module Identifier</a></li> + + <li><a href="#Compatibility">Compatibility</a></li> + </ul> + <hr /> + + <h2><a id="Status" name="Status">Status</a></h2> + + <p>This indicates how tightly bound into the Apache Web server + the module is; in other words, you may need to recompile the + server in order to gain access to the module and its + functionality. Possible values for this attribute are:</p> + + <dl> + <dt><strong>MPM</strong></dt> + + <dd>A module with status "MPM" is a <a + href="../mpm.html">Multi-Processing Module</a>. Unlike the + other types of modules, Apache must have one and only one MPM + in use at any time. This type of module is responsible for + basic request handling and dispatching.</dd> + + <dt><strong>Base</strong></dt> + + <dd>A module labeled as having "Base" status is compiled and + loaded into the server by default, and is therefore normally + available unless you have taken steps to remove the module + from your configuration.</dd> + + <dt><strong>Extension</strong></dt> + + <dd>A module with "Extension" status is not normally compiled + and loaded into the server. To enable the module and its + functionality, you may need to change the server build + configuration files and re-compile Apache.</dd> + + <dt><strong>Experimental</strong></dt> + + <dd>"Experimental" status indicates that the module is + available as part of the Apache kit, but you are on your own + if you try to use it. The module is being documented for + completeness, and is not necessarily supported.</dd> + + <dt><strong>External</strong></dt> + + <dd>Modules which are not included with the base Apache + distribution ("third-party modules") may use the "External" + status. We are not responsible for, nor do we support such + modules.</dd> + </dl> + <hr /> + + <h2><a id="SourceFile" name="SourceFile">Source File</a></h2> + + <p>This quite simply lists the name of the source file which + contains the code for the module. This is also the name used by + the <a + href="core.html#ifmodule"><code><IfModule></code></a> + directive.</p> + <hr /> + + <h2><a id="ModuleIdentifier" name="ModuleIdentifier">Module + Identifier</a></h2> + + <p>This is a string which identifies the module for use in the + <a href="mod_so.html#loadmodule">LoadModule</a> directive when + dynamically loading modules. In particular, it is the name of + the external variable of type module in the source file.</p> + <hr /> + + <h2><a id="Compatibility" + name="Compatibility">Compatibility</a></h2> + + <p>If the module was not part of the original Apache version 2 + distribution, the version in which it was introduced should be + listed here.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/module-dict.html.en b/docs/manual/mod/module-dict.html.en index 7d99828e81..5e7cadb821 100644 --- a/docs/manual/mod/module-dict.html.en +++ b/docs/manual/mod/module-dict.html.en @@ -1,144 +1,123 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Definitions of terms used to describe Apache modules - </TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Terms Used to Describe Apache Modules</H1> - - <P> - Each Apache module is described using a common format that looks - like this: - </P> - <DL> - <DD><A - HREF="#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> <EM>status</EM> - <BR> - <A - HREF="#SourceFile" - REL="Help" - ><STRONG>Source File:</STRONG></A> <EM>source-file</EM> - <BR> - <A - HREF="#ModuleIdentifier" - REL="Help" - ><STRONG>Module Identifier:</STRONG></A> <EM>module-identifier</EM> - <BR> - <A - HREF="#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM> - </DD> - </DL> - <P> - Each of the attributes, complete with values where possible, are - described in this document. - </P> - - <H2>Module Terms</H2> - <UL> - <LI><A HREF="#Status">Status</A> - </LI> - <LI><A HREF="#SourceFile">Source File</A> - </LI> - <LI><A HREF="#ModuleIdentifier">Module Identifier</A> - </LI> - <LI><A HREF="#Compatibility">Compatibility</A> - </LI> - </UL> - - <HR> - <H2><A NAME="Status">Status</A></H2> - <P> - This indicates how tightly bound into the Apache Web server the - module is; in other words, you may need to recompile the server in - order to gain access to the module and its functionality. Possible - values for this attribute are: - </P> - <DL> - <DT><STRONG>MPM</STRONG> - </DT> - <DD>A module with status "MPM" is a <a - href="../mpm.html">Multi-Processing Module</a>. Unlike the other - types of modules, Apache must have one and only one MPM in use at - any time. This type of module is responsible for basic request - handling and dispatching. - <P> - </P> - <DT><STRONG>Base</STRONG> - </DT> - <DD>A module labeled as having "Base" status is compiled - and loaded into the server by default, and is therefore normally - available unless you have taken steps to remove the module from your - configuration. - <P> - </P> - </DD> - <DT><STRONG>Extension</STRONG> - </DT> - <DD>A module with "Extension" status is not normally - compiled and loaded into the server. To enable the module and its - functionality, you may need to change the server build - configuration files and re-compile Apache. - <P> - </P> - </DD> - <DT><STRONG>Experimental</STRONG> - </DT> - <DD>"Experimental" status indicates that the module is - available as part of the Apache kit, but you are on your own if you - try to use it. The module is being documented for completeness, - and is not necessarily supported. - <P> - </P> - </DD> - <DT><STRONG>External</STRONG> - </DT> - <DD>Modules which are not included with the base Apache - distribution ("third-party modules") may use the - "External" status. We are not responsible for, nor do we - support such modules. - <P> - </P> - </DD> - </DL> - - <HR> - <H2><A NAME="SourceFile">Source File</A></H2> - <P> - This quite simply lists the name of the source file which contains - the code for the module. This is also the name used by the <A - HREF="core.html#ifmodule"><CODE><IfModule></CODE></A> - directive. - </P> - - <HR> - <H2><A NAME="ModuleIdentifier">Module Identifier</A></H2> - <P> - This is a string which identifies the module for use in the <A - HREF="mod_so.html#loadmodule">LoadModule</A> directive when - dynamically loading modules. In particular, it is the name - of the external variable of type module in the source file. - </P> - - <HR> - <H2><A NAME="Compatibility">Compatibility</A></H2> - <P> - If the module was not part of the original Apache version 2 - distribution, the version in which it was introduced should be listed - here. - </P> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Definitions of terms used to describe Apache + modules</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Terms Used to Describe Apache Modules</h1> + + <p>Each Apache module is described using a common format that + looks like this:</p> + + <dl> + <dd><a href="#Status" rel="Help"><strong>Status:</strong></a> + <em>status</em><br /> + <a href="#SourceFile" rel="Help"><strong>Source + File:</strong></a> <em>source-file</em><br /> + <a href="#ModuleIdentifier" rel="Help"><strong>Module + Identifier:</strong></a> <em>module-identifier</em><br /> + <a href="#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> + <em>compatibility notes</em></dd> + </dl> + + <p>Each of the attributes, complete with values where possible, + are described in this document.</p> + + <h2>Module Terms</h2> + + <ul> + <li><a href="#Status">Status</a></li> + + <li><a href="#SourceFile">Source File</a></li> + + <li><a href="#ModuleIdentifier">Module Identifier</a></li> + + <li><a href="#Compatibility">Compatibility</a></li> + </ul> + <hr /> + + <h2><a id="Status" name="Status">Status</a></h2> + + <p>This indicates how tightly bound into the Apache Web server + the module is; in other words, you may need to recompile the + server in order to gain access to the module and its + functionality. Possible values for this attribute are:</p> + + <dl> + <dt><strong>MPM</strong></dt> + + <dd>A module with status "MPM" is a <a + href="../mpm.html">Multi-Processing Module</a>. Unlike the + other types of modules, Apache must have one and only one MPM + in use at any time. This type of module is responsible for + basic request handling and dispatching.</dd> + + <dt><strong>Base</strong></dt> + + <dd>A module labeled as having "Base" status is compiled and + loaded into the server by default, and is therefore normally + available unless you have taken steps to remove the module + from your configuration.</dd> + + <dt><strong>Extension</strong></dt> + + <dd>A module with "Extension" status is not normally compiled + and loaded into the server. To enable the module and its + functionality, you may need to change the server build + configuration files and re-compile Apache.</dd> + + <dt><strong>Experimental</strong></dt> + + <dd>"Experimental" status indicates that the module is + available as part of the Apache kit, but you are on your own + if you try to use it. The module is being documented for + completeness, and is not necessarily supported.</dd> + + <dt><strong>External</strong></dt> + + <dd>Modules which are not included with the base Apache + distribution ("third-party modules") may use the "External" + status. We are not responsible for, nor do we support such + modules.</dd> + </dl> + <hr /> + + <h2><a id="SourceFile" name="SourceFile">Source File</a></h2> + + <p>This quite simply lists the name of the source file which + contains the code for the module. This is also the name used by + the <a + href="core.html#ifmodule"><code><IfModule></code></a> + directive.</p> + <hr /> + + <h2><a id="ModuleIdentifier" name="ModuleIdentifier">Module + Identifier</a></h2> + + <p>This is a string which identifies the module for use in the + <a href="mod_so.html#loadmodule">LoadModule</a> directive when + dynamically loading modules. In particular, it is the name of + the external variable of type module in the source file.</p> + <hr /> + + <h2><a id="Compatibility" + name="Compatibility">Compatibility</a></h2> + + <p>If the module was not part of the original Apache version 2 + distribution, the version in which it was introduced should be + listed here.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mpm_common.html b/docs/manual/mod/mpm_common.html index 39c629e7fa..bc414cee85 100644 --- a/docs/manual/mod/mpm_common.html +++ b/docs/manual/mod/mpm_common.html @@ -1,771 +1,696 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache MPM Common Directives</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Multi-Processing Module Common Directives</H1> - -<P>This file documents directives that are implemented by more -than one multi-processing module (MPM). -</P> - -<H2>Directives</H2> -<UL> -<li><a href="#connectionstatus">ConnectionStatus</a></li> -<li><a href="#coredumpdirectory">CoreDumpDirectory</a></li> -<li><a href="#group">Group</a></li> -<li><a href="#pidfile">PidFile</a></li> -<li><a href="#listen">Listen</a></li> -<li><a href="#listenbacklog">ListenBacklog</a></li> -<li><a href="#lockfile">LockFile</a></li> -<li><a href="#maxclients">MaxClients</a></li> -<li><a href="#maxrequestsperchild">MaxRequestsPerChild</a></li> -<li><a href="#maxsparethreads">MaxSpareThreads</a></li> -<li><a href="#maxthreadsperchild">MaxThreadsPerChild</a></li> -<li><a href="#minsparethreads">MinSpareThreads</a></li> -<li><a href="#numservers">NumServers</a></li> -<li><a href="#scoreboardfile">ScoreBoardFile</a></li> -<li><a href="#sendbuffersize">SendBufferSize</a></li> -<li><a href="#startservers">StartServers</a></li> -<li><a href="#startthreads">StartThreads</a></li> -<li><a href="#threadsperchild">ThreadsPerChild</a></li> -<li><a href="#user">User</a></li> -</UL> -<HR> - -<H2><A NAME="connectionstatus">ConnectionStatus directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - ConnectionStatus on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <CODE>ConnectionStatus on</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> perchild</p> - -<p>Whether or not to maintain status information on current -connections. If this is off then mod_status will not work properly.</p> - -<hr> - -<H2><A NAME="coredumpdirectory">CoreDumpDirectory directive</A></H2> -<!--%plaintext <?INDEX {\tt CoreDumpDirectory} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> CoreDumpDirectory <EM>directory</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> the same location as ServerRoot<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p> - -<p>This controls the directory to which Apache attempts to switch -before dumping core. The default is in the <A -HREF="core.html#serverroot">ServerRoot</A> directory, however since -this should not be writable by the user the server runs as, core dumps -won't normally get written. If you want a core dump for debugging, -you can use this directive to place it in a different location.<P><HR> - - -<H2><A NAME="group">Group directive</A></H2> -<!--%plaintext <?INDEX {\tt Group} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Group <EM>unix-group</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>Group #-1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork</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< is no longer -supported. To implement the <A HREF="../suexec.html">suEXEC wrapper</A> -with Apache 2.0, use the <A HREF=mod_suexec.html#suexecusergroup> -SuexecUserGroup</A> directive. - -SECURITY: See <A HREF="#user">User</A> for a discussion of the security -considerations.<P><HR> - -<H2><A NAME="pidfile">PidFile directive</A></H2> -<!--%plaintext <?INDEX {\tt PidFile} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> PidFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>PidFile logs/httpd.pid</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p> - -<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="core.html#serverroot">ServerRoot</A>.</p> - -<p>It is often useful to be able to send the server a signal, so that -it closes and then reopens its <A -HREF="core.html#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> - -<p>The PidFile is subject to the same warnings about log file placement and -<A HREF="../misc/security_tips.html#serverroot">security</A>.</p> - -<p><hr> - -<H2><A NAME="listen">Listen directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> -Listen [<EM>IP-address</EM>:]<EM>port number</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p> - - -<P>The Listen directive instructs Apache to listen to only specific IP -addresses or ports; by default it responds to requests on all IP -interfaces, but only on the port given by the <CODE><A -HREF="core.html#port">Port</A></CODE> directive.</P> - -<p>The Listen directive tells -the server to accept incoming requests on the specified port or -address-and-port combination. If only a port number is specified, -the server listens to the given port on all interfaces, -instead of the port given by the <TT>Port</TT> directive. If an IP -address is given as well as a port, the server will listen on the -given port and interface. <P> - -Note that you may still require a <TT>Port</TT> directive so -that URLs that Apache generates that point to your server still -work.<P> - -Multiple Listen directives may be used -to specify a number of addresses and ports to listen to. The server -will respond to requests from any of the listed addresses and -ports. -<P> - -For example, to make the server accept connections on both port -80 and port 8000, use: -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache MPM Common Directives</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module Common + Directives</h1> + + <p>This file documents directives that are implemented by more + than one multi-processing module (MPM).</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#connectionstatus">ConnectionStatus</a></li> + + <li><a href="#coredumpdirectory">CoreDumpDirectory</a></li> + + <li><a href="#group">Group</a></li> + + <li><a href="#pidfile">PidFile</a></li> + + <li><a href="#listen">Listen</a></li> + + <li><a href="#listenbacklog">ListenBacklog</a></li> + + <li><a href="#lockfile">LockFile</a></li> + + <li><a href="#maxclients">MaxClients</a></li> + + <li><a + href="#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a href="#maxsparethreads">MaxSpareThreads</a></li> + + <li><a href="#maxthreadsperchild">MaxThreadsPerChild</a></li> + + <li><a href="#minsparethreads">MinSpareThreads</a></li> + + <li><a href="#numservers">NumServers</a></li> + + <li><a href="#scoreboardfile">ScoreBoardFile</a></li> + + <li><a href="#sendbuffersize">SendBufferSize</a></li> + + <li><a href="#startservers">StartServers</a></li> + + <li><a href="#startthreads">StartThreads</a></li> + + <li><a href="#threadsperchild">ThreadsPerChild</a></li> + + <li><a href="#user">User</a></li> + </ul> + <hr /> + + <h2><a id="connectionstatus" + name="connectionstatus">ConnectionStatus directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ConnectionStatus + on|off<br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>ConnectionStatus + on</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> perchild</p> + + <p>Whether or not to maintain status information on current + connections. If this is off then mod_status will not work + properly.</p> + <hr /> + + <h2><a id="coredumpdirectory" + name="coredumpdirectory">CoreDumpDirectory directive</a></h2> + <!--%plaintext <?INDEX {\tt CoreDumpDirectory} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> CoreDumpDirectory + <em>directory</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> the same location as + ServerRoot<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork, mpm_winnt</p> + + <p>This controls the directory to which Apache attempts to + switch before dumping core. The default is in the <a + href="core.html#serverroot">ServerRoot</a> directory, however + since this should not be writable by the user the server runs + as, core dumps won't normally get written. If you want a core + dump for debugging, you can use this directive to place it in a + different location.</p> + <hr /> + + <h2><a id="group" name="group">Group directive</a></h2> + <!--%plaintext <?INDEX {\tt Group} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Group + <em>unix-group</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>Group + #-1</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork</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</dt> + + <dd>Refers to the given group by name.</dd> + + <dt># followed by a group number.</dt> + + <dd>Refers to a group by its number.</dd> + </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> + + <p>Special note: Use of this directive in <VirtualHost< + is no longer supported. To implement the <a + href="../suexec.html">suEXEC wrapper</a> with Apache 2.0, use + the <a + href="mod_suexec.html#suexecusergroup">SuexecUserGroup</a> + directive. SECURITY: See <a href="#user">User</a> for a + discussion of the security considerations.</p> + <hr /> + + <h2><a id="pidfile" name="pidfile">PidFile directive</a></h2> + <!--%plaintext <?INDEX {\tt PidFile} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> PidFile + <em>filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>PidFile + logs/httpd.pid</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork, mpm_winnt</p> + + <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="core.html#serverroot">ServerRoot</a>.</p> + + <p>It is often useful to be able to send the server a signal, + so that it closes and then reopens its <a + href="core.html#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> + + <p>The PidFile is subject to the same warnings about log file + placement and <a + href="../misc/security_tips.html#serverroot">security</a>.</p> + <hr /> + + <h2><a id="listen" name="listen">Listen directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> Listen + [<em>IP-address</em>:]<em>port number</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork, mpm_winnt</p> + + <p>The Listen directive instructs Apache to listen to only + specific IP addresses or ports; by default it responds to + requests on all IP interfaces, but only on the port given by + the <code><a href="core.html#port">Port</a></code> + directive.</p> + + <p>The Listen directive tells the server to accept incoming + requests on the specified port or address-and-port combination. + If only a port number is specified, the server listens to the + given port on all interfaces, instead of the port given by the + <tt>Port</tt> directive. If an IP address is given as well as a + port, the server will listen on the given port and + interface.</p> + + <p>Note that you may still require a <tt>Port</tt> directive so + that URLs that Apache generates that point to your server still + work.</p> + + <p>Multiple Listen directives may be used to specify a number + of addresses and ports to listen to. The server will respond to + requests from any of the listed addresses and ports.</p> + + <p>For example, to make the server accept connections on both + port 80 and port 8000, use:</p> +<pre> Listen 80 Listen 8000 -</PRE> - -To make the server accept connections on two specified -interfaces and port numbers, use -<PRE> +</pre> + To make the server accept connections on two specified + interfaces and port numbers, use +<pre> Listen 192.170.2.1:80 Listen 192.170.2.5:8000 -</PRE> - -<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="http://www.apache.org/info/known_bugs.html#listenbug">Known Bugs</A> -</P> -<HR> - -<H2><A NAME="listenbacklog">ListenBacklog directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ListenBacklog <EM>backlog</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ListenBacklog 511</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</p> - -<P>The maximum length of the queue of pending connections. Generally no -tuning is needed or desired, however on some systems it is desirable -to increase this when under a TCP SYN flood attack. See -the backlog parameter to the <CODE>listen(2)</CODE> system call. - -<P>This will often be limited to a smaller number by the operating -system. This varies from OS to OS. Also note that many OSes do not -use exactly what is specified as the backlog, but use a number based on -(but normally larger than) what is set. -<HR> - -<H2><A NAME="lockfile">LockFile directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LockFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>LockFile logs/accept.lock</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork</p> - -<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 <STRONG>the lockfile -must be stored on a local disk</STRONG>. The PID of the main -server process is automatically appended to the filename. <P> - -<p><STRONG>SECURITY:</STRONG> It is best to avoid putting this file in a -world writable directory such as <CODE>/var/tmp</CODE> because someone -could create a denial of service attack and prevent the server from -starting by creating a lockfile with the same name as the one the -server will try to create.</p> - -<hr> - -<H2><A NAME="maxclients">MaxClients directive</A></H2> -<!--%plaintext <?INDEX {\tt MaxClients} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxClients <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxClients 8</code> (with threads) -<code>MaxClients 256</code> (no threads)<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, prefork</p> - -<P>The MaxClients directive sets the limit on the number of child -processes that will be created to serve requests. When the server is -built without threading, no more than this number of clients can be -served simultaneously. To configure more than 256 clients, you must -edit the <code>HARD_SERVER_LIMIT</code> entry in -<code>mpm_default.h</code> and recompile. - -<P>Any connection attempts over the MaxClients limit will normally -be queued, up to a number based on the <A HREF="#listenbacklog"> -ListenBacklog</A> directive. Once a child process is freed at the -end of a different request, the connection will then be serviced.</p> - -<p>When the server is compiled with threading, then the maximum number -of simultaneous requests that can be served is obtained from the value -of this directive multiplied by <a -href="#threadsperchild">ThreadsPerChild</a>.</p> - -<HR> - -<H2><A NAME="maxrequestsperchild">MaxRequestsPerChild directive</A></H2> -<!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxRequestsPerChild <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxRequestsPerChild 10000</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, prefork, perchild, mpm_winnt</p> - -<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><STRONG>NOTE:</STRONG> For <EM>KeepAlive</EM> requests, only the first -request is counted towards this limit. In effect, it changes the -behavior to limit the number of <EM>connections</EM> per child. - -<P><HR> - - -<H2><A NAME="maxsparethreads">MaxSpareThreads directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxSpareThreads <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxSpareThreads 10 (Perchild) or 500 (threaded) </CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild</p> - -<P>Maximum number of idle threads. Different MPMs deal with this directive -differently. Perchild monitor the number of idle threads on a -per-child basis. If there are too many idle threads in that child, the server -will begin to kill threads within that child.</P> -<P>threaded deals with idle threads on a server-wide basis. If there are -too many idle threads in the server then child processes are killed -until the number of idle threads is less than this number.</p> - -<p>See also <A HREF="#minsparethreads">MinSpareThreads</A> and -<A HREF="#startservers">StartServers</A>. - -<P><HR> - -<H2><A NAME="maxthreadsperchild">MaxThreadsPerChild directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxThreadsPerChild <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxThreadsPerChild 64</code> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild</p> - -<P>Maximum number of threads per child. For MPMs with a variable -number of threads per child, this directive sets the maximum number of -threads that will be created in each child process. To increase this -value beyond its default, it is necessary to change the value of -the compile-time define <code>HARD_THREAD_LIMIT</code> and recompile -the server.</p> - -<P><HR> - -<H2><A NAME="minsparethreads">MinSpareThreads directive</A></H2> -<!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MinSpareServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxSpareThreads 5 (Perchild) or 250 (threaded) </CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild</p> - -<P>Minimum number of idle threads to handle request spikes. Different MPMs -deal with this directive differently. Perchild monitor the number -of idle threads on a per-child basis. If there aren't enough idle threads in -that child, the server will begin to create new threads within that child. -</P> -<P>threaded deals with idle threads on a server-wide basis. If there -aren't enough idle threads in the server then child processes are created -until the number of idle threads is greater than number.</p> - -See also <A HREF="#maxsparethreads">MaxSpareThreads</A> and -<A HREF="#startservers">StartServers</A>.<P><HR> - - -<H2><A NAME="numservers">NumServers directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> NumServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>NumServers 2</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> perchild</p> - -<p>Number of children alive at the same time. MPMs that use this directive -do not dynamically create new child processes so this number should be -large enough to handle the requests for the entire site.</p> - -<hr> - -<H2><A NAME="scoreboardfile">ScoreBoardFile directive</A></H2> -<!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ScoreBoardFile <EM>filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ScoreBoardFile logs/apache_status</CODE> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -></a> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork</p> - -<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> - -<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> - -<p><STRONG>See Also</STRONG>: -<A HREF="../stopping.html">Stopping and Restarting Apache</A></P> - - -<P><HR> - -<H2><A NAME="sendbuffersize">SendBufferSize directive</A></H2> -<!--%plaintext <?INDEX {\tt SendBufferSize} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> SendBufferSize <EM>bytes</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork, mpm_winnt</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 (<EM>i.e.</EM>, 100ms or so, such as transcontinental -fast pipes) - -<P><HR> - -<H2><A NAME="startservers">StartServers directive</A></H2> -<!--%plaintext <?INDEX {\tt StartServers} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> StartServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>StartServers 5</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, prefork</p> - -<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> - -<P>See also <A HREF="#minsparethreads">MinSpareThreads</A> and -<A HREF="#maxsparethreads">MaxSpareThreads</A>.<P><HR> - - -<H2><A NAME="startthreads">StartThreads directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> StartThreads <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>StartThreads 5</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> perchild</p> - -<p>Number of threads each child creates on startup. As the number of threads -is dynamically controlled depending on the load, there is usually little -reason to adjust this parameter.</p> - -<hr> - -<H2><A NAME="threadsperchild">ThreadsPerChild</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> ThreadsPerChild <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>ThreadsPerChild 50</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, mpm_winnt</p> - -<P>This directive sets the number of threads created by each child -process. The child creates these threads at startup and never creates -more. if using an MPM like mpmt_winnt, where there is only one child process, -this number should be high enough to handle the entire load of the server. -If using an MPM like threaded, where there are multiple child processes, -the total number of threads should be high enough to handle the common load -on the server.</p> - -<p><hr> - - -<H2><A NAME="user">User directive</A></H2> -<!--%plaintext <?INDEX {\tt User} directive> --> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> User <EM>unix-userid</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>User #-1</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> threaded, perchild, prefork</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. -For example mod_proxy's cache, when enabled, must be accessible to this user -(see <A HREF="mod_proxy.html">mod_proxy's</A> <CODE>CacheRoot</CODE> -directive).<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> is no longer -supported. To configure your server for <A HREF="mod_suexec.html"> -suexec</A> use <A HREF="mod_suexec.html#suexecusergroup">SuexecUserGroup</A>. - -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> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +</pre> + + <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="http://www.apache.org/info/known_bugs.html#listenbug">Known + Bugs</a></p> + <hr /> + + <h2><a id="listenbacklog" name="listenbacklog">ListenBacklog + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ListenBacklog + <em>backlog</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>ListenBacklog + 511</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork, mpm_winnt</p> + + <p>The maximum length of the queue of pending connections. + Generally no tuning is needed or desired, however on some + systems it is desirable to increase this when under a TCP SYN + flood attack. See the backlog parameter to the + <code>listen(2)</code> system call.</p> + + <p>This will often be limited to a smaller number by the + operating system. This varies from OS to OS. Also note that + many OSes do not use exactly what is specified as the backlog, + but use a number based on (but normally larger than) what is + set.</p> + <hr /> + + <h2><a id="lockfile" name="lockfile">LockFile + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> LockFile + <em>filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>LockFile + logs/accept.lock</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork</p> + + <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 + <strong>the lockfile must be stored on a local disk</strong>. + The PID of the main server process is automatically appended to + the filename.</p> + + <p><strong>SECURITY:</strong> It is best to avoid putting this + file in a world writable directory such as + <code>/var/tmp</code> because someone could create a denial of + service attack and prevent the server from starting by creating + a lockfile with the same name as the one the server will try to + create.</p> + <hr /> + + <h2><a id="maxclients" name="maxclients">MaxClients + directive</a></h2> + <!--%plaintext <?INDEX {\tt MaxClients} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxClients + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MaxClients + 8</code> (with threads) <code>MaxClients 256</code> (no + threads)<br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, prefork</p> + + <p>The MaxClients directive sets the limit on the number of + child processes that will be created to serve requests. When + the server is built without threading, no more than this number + of clients can be served simultaneously. To configure more than + 256 clients, you must edit the <code>HARD_SERVER_LIMIT</code> + entry in <code>mpm_default.h</code> and recompile.</p> + + <p>Any connection attempts over the MaxClients limit will + normally be queued, up to a number based on the <a + href="#listenbacklog">ListenBacklog</a> directive. Once a child + process is freed at the end of a different request, the + connection will then be serviced.</p> + + <p>When the server is compiled with threading, then the maximum + number of simultaneous requests that can be served is obtained + from the value of this directive multiplied by <a + href="#threadsperchild">ThreadsPerChild</a>.</p> + <hr /> + + <h2><a id="maxrequestsperchild" + name="maxrequestsperchild">MaxRequestsPerChild + directive</a></h2> + <!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxRequestsPerChild + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>MaxRequestsPerChild 10000</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, prefork, + perchild, mpm_winnt</p> + + <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> + + <p>Setting MaxRequestsPerChild to a non-zero limit has two + beneficial effects:</p> + + <ul> + <li>it limits the amount of memory that process can consume + by (accidental) memory leakage;</li> + + <li>by giving processes a finite lifetime, it helps reduce + the number of processes when the server load reduces.</li> + </ul> + + <p><strong>NOTE:</strong> For <em>KeepAlive</em> requests, only + the first request is counted towards this limit. In effect, it + changes the behavior to limit the number of + <em>connections</em> per child.</p> + <hr /> + + <h2><a id="maxsparethreads" + name="maxsparethreads">MaxSpareThreads directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxSpareThreads + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MaxSpareThreads + 10 (Perchild) or 500 (threaded)</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild</p> + + <p>Maximum number of idle threads. Different MPMs deal with + this directive differently. Perchild monitor the number of idle + threads on a per-child basis. If there are too many idle + threads in that child, the server will begin to kill threads + within that child.</p> + + <p>threaded deals with idle threads on a server-wide basis. If + there are too many idle threads in the server then child + processes are killed until the number of idle threads is less + than this number.</p> + + <p>See also <a href="#minsparethreads">MinSpareThreads</a> and + <a href="#startservers">StartServers</a>.</p> + <hr /> + + <h2><a id="maxthreadsperchild" + name="maxthreadsperchild">MaxThreadsPerChild directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxThreadsPerChild + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> + <code>MaxThreadsPerChild 64</code> <a + href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild</p> + + <p>Maximum number of threads per child. For MPMs with a + variable number of threads per child, this directive sets the + maximum number of threads that will be created in each child + process. To increase this value beyond its default, it is + necessary to change the value of the compile-time define + <code>HARD_THREAD_LIMIT</code> and recompile the server.</p> + <hr /> + + <h2><a id="minsparethreads" + name="minsparethreads">MinSpareThreads directive</a></h2> + <!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MinSpareServers + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MaxSpareThreads + 5 (Perchild) or 250 (threaded)</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild</p> + + <p>Minimum number of idle threads to handle request spikes. + Different MPMs deal with this directive differently. Perchild + monitor the number of idle threads on a per-child basis. If + there aren't enough idle threads in that child, the server will + begin to create new threads within that child.</p> + + <p>threaded deals with idle threads on a server-wide basis. If + there aren't enough idle threads in the server then child + processes are created until the number of idle threads is + greater than number.</p> + See also <a href="#maxsparethreads">MaxSpareThreads</a> and <a + href="#startservers">StartServers</a>. + <hr /> + + <h2><a id="numservers" name="numservers">NumServers + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> NumServers + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>NumServers + 2</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> perchild</p> + + <p>Number of children alive at the same time. MPMs that use + this directive do not dynamically create new child processes so + this number should be large enough to handle the requests for + the entire site.</p> + <hr /> + + <h2><a id="scoreboardfile" name="scoreboardfile">ScoreBoardFile + directive</a></h2> + <!--%plaintext <?INDEX {\tt ScoreBoardFile} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ScoreBoardFile + <em>filename</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>ScoreBoardFile + logs/apache_status</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Compatibility" rel="Help"></a> <a + href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork</p> + + <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> + + <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> + + <p><strong>See Also</strong>: <a + href="../stopping.html">Stopping and Restarting Apache</a></p> + <hr /> + + <h2><a id="sendbuffersize" name="sendbuffersize">SendBufferSize + directive</a></h2> + <!--%plaintext <?INDEX {\tt SendBufferSize} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> SendBufferSize + <em>bytes</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork, mpm_winnt</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 (<em>i.e.</em>, 100ms or so, such as + transcontinental fast pipes) + <hr /> + + <h2><a id="startservers" name="startservers">StartServers + directive</a></h2> + <!--%plaintext <?INDEX {\tt StartServers} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> StartServers + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>StartServers + 5</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, prefork</p> + + <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> + + <p>See also <a href="#minsparethreads">MinSpareThreads</a> and + <a href="#maxsparethreads">MaxSpareThreads</a>.</p> + <hr /> + + <h2><a id="startthreads" name="startthreads">StartThreads + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> StartThreads + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>StartThreads + 5</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> perchild</p> + + <p>Number of threads each child creates on startup. As the + number of threads is dynamically controlled depending on the + load, there is usually little reason to adjust this + parameter.</p> + <hr /> + + <h2><a id="threadsperchild" + name="threadsperchild">ThreadsPerChild</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ThreadsPerChild + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>ThreadsPerChild + 50</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, mpm_winnt</p> + + <p>This directive sets the number of threads created by each + child process. The child creates these threads at startup and + never creates more. if using an MPM like mpmt_winnt, where + there is only one child process, this number should be high + enough to handle the entire load of the server. If using an MPM + like threaded, where there are multiple child processes, the + total number of threads should be high enough to handle the + common load on the server.</p> + <hr /> + + <h2><a id="user" name="user">User directive</a></h2> + <!--%plaintext <?INDEX {\tt User} directive> --> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> User + <em>unix-userid</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>User + #-1</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config, virtual + host<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> threaded, perchild, + prefork</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</dt> + + <dd>Refers to the given user by name.</dd> + + <dt># followed by a user number.</dt> + + <dd>Refers to a user by their number.</dd> + </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. For example mod_proxy's cache, when enabled, must be + accessible to this user (see <a + href="mod_proxy.html">mod_proxy's</a> <code>CacheRoot</code> + directive). + + <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> + + <p>Special note: Use of this directive in <VirtualHost> + is no longer supported. To configure your server for <a + href="mod_suexec.html">suexec</a> use <a + href="mod_suexec.html#suexecusergroup">SuexecUserGroup</a>. + 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> + + <p><!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/mpm_winnt.html b/docs/manual/mod/mpm_winnt.html index f4a90f03cf..7b8d24f5e7 100644 --- a/docs/manual/mod/mpm_winnt.html +++ b/docs/manual/mod/mpm_winnt.html @@ -1,59 +1,61 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache MPM pthread</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Multi-Processing Module mpm_winnt</H1> -<P> -This Multi-Processing Module is optimized for Windows NT. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> MPM -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mpm_winnt.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> mpm_winnt_module -</P> - -<H2>Summary</H2> - -<p>This Multi-Processing Module (MPM) is the default for -the Windows NT operating systems. It uses a single control -process which launches a single child process which in turn -creates threads to handle requests</p> - - -<H2>Directives</H2> -<UL> -<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> -<li><a href="mpm_common.html#pidfile">PidFile</a></li> -<li><a href="mpm_common.html#listen">Listen</a></li> -<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li> -<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> -<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> -<li><a href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li> -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache MPM pthread</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module mpm_winnt</h1> + + <p>This Multi-Processing Module is optimized for Windows + NT.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mpm_winnt.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mpm_winnt_module</p> + + <h2>Summary</h2> + + <p>This Multi-Processing Module (MPM) is the default for the + Windows NT operating systems. It uses a single control process + which launches a single child process which in turn creates + threads to handle requests</p> + + <h2>Directives</h2> + + <ul> + <li><a + href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> + + <li><a href="mpm_common.html#pidfile">PidFile</a></li> + + <li><a href="mpm_common.html#listen">Listen</a></li> + + <li><a + href="mpm_common.html#listenbacklog">ListenBacklog</a></li> + + <li><a + href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a + href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> + + <li><a + href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li> + </ul> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/perchild.html b/docs/manual/mod/perchild.html index 9c951d8605..2fca46d4be 100644 --- a/docs/manual/mod/perchild.html +++ b/docs/manual/mod/perchild.html @@ -1,170 +1,170 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache MPM perchild</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Multi-Processing Module perchild</H1> -<P> -This Multi-Processing Module allows for daemon processes serving requests -to be assigned a variety of different userids. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> MPM -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> perchild.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> mpm_perchild_module -</P> - -<H2>Summary</H2> - -<p>This Multi-Processing Module (MPM) implements a hybrid -multi-process, multi-threaded web server. A fixed number of processes -create threads to handle requests. Fluctuations in load are handled -by increasing or decreasing the number of threads in each process.</p> - -<p>A single control process launches the number of child processes -indicated by the <code>NumServers</code> directive at server startup. -Each child process creates threads as specified in the -<code>StartThreads</code> directive. The individual threads then -listen for connections and serve them when they arrive.</p> - -<p>Apache always tries to maintain a pool of <em>spare</em> or idle -server threads, which stand ready to serve incoming requests. In this -way, clients do not need to wait for new threads to be created. For -each child process, Apache assesses the number of idle threads and -creates or destroys threads to keep this number within the boundaries -specified by <code>MinSpareThreads</code> and -<code>MaxSpareThreads</code>. Since this process is very -self-regulating, it is rarely necessary to modify these directives -from their default values. The maximum number of clients that may be -served simultaneously is determined by multiplying the number -of server processes that will be created (<code>NumServers</code>) by -the maximum number of threads created in each process -(<code>MaxThreadsPerChild</code>).</p> - -<p>While the parent process is usually started as root under Unix in -order to bind to port 80, the child processes and threads are launched -by Apache as a less-privileged user. The <code>User</code> and -<code>Group</code> directives are used to set the privileges of the -Apache child processes. The child processes must be able to read all -the content that will be served, but should have as few privileges -beyond that as possible. In addition, unless <a -href="../suexec.html">suexec</a> is used, these directives also set -the privileges which will be inherited by CGI scripts.</p> - -<p><code>MaxRequestsPerChild</code> controls how frequently the server -recycles processes by killing old ones and launching new ones.</p> - -<p>See also: <a href="../bind.html">Setting which addresses and ports -Apache uses</a>.</p> - -<p>In addition it adds the extra ability to specify that specific processes -should serve requests under different userids. These processes can -then be associated with specific virtual hosts.</p> - -<!-- XXX: This desperately needs more explanation. --> - - -<H2>Directives</H2> -<UL> -<li><a href="#assignuserid">AssignUserID</a></li> -<li><a href="#childperuserid">ChildPerUserID</a></li> -<li><a href="mpm_common.html#connectionstatus">ConnectionStatus</a></li> -<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> -<li><a href="mpm_common.html#group">Group</a></li> -<li><a href="mpm_common.html#pidfile">PidFile</a></li> -<li><a href="mpm_common.html#listen">Listen</a></li> -<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li> -<li><a href="mpm_common.html#lockfile">LockFile</a></li> -<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> -<li><a href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li> -<li><a href="mpm_common.html#maxthreadsperchild">MaxThreadsPerChild</a></li> -<li><a href="mpm_common.html#minsparethreads">MinSpareThreads</a></li> -<li><a href="mpm_common.html#numservers">NumServers</a></li> -<li><a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> -<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> -<li><a href="mpm_common.html#startthreads">StartThreads</a></li> -<li><a href="mpm_common.html#user">User</a></li> -</UL> - -<hr> - -<H2><A NAME="assignuserid">AssignUserID directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> perchild</p> - -<p>Tie a virtual host to a specific child process.</p> - -<hr> - -<H2><A NAME="childperuserid">ChildPerUserID directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> MPM<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> perchild</p> - -<p>Specify a User and Group for a specific child process.</p> - - - - - -<!--#include virtual="footer.html" --> - -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache MPM perchild</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module perchild</h1> + + <p>This Multi-Processing Module allows for daemon processes + serving requests to be assigned a variety of different + userids.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> perchild.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mpm_perchild_module</p> + + <h2>Summary</h2> + + <p>This Multi-Processing Module (MPM) implements a hybrid + multi-process, multi-threaded web server. A fixed number of + processes create threads to handle requests. Fluctuations in + load are handled by increasing or decreasing the number of + threads in each process.</p> + + <p>A single control process launches the number of child + processes indicated by the <code>NumServers</code> directive at + server startup. Each child process creates threads as specified + in the <code>StartThreads</code> directive. The individual + threads then listen for connections and serve them when they + arrive.</p> + + <p>Apache always tries to maintain a pool of <em>spare</em> or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for new + threads to be created. For each child process, Apache assesses + the number of idle threads and creates or destroys threads to + keep this number within the boundaries specified by + <code>MinSpareThreads</code> and <code>MaxSpareThreads</code>. + Since this process is very self-regulating, it is rarely + necessary to modify these directives from their default values. + The maximum number of clients that may be served simultaneously + is determined by multiplying the number of server processes + that will be created (<code>NumServers</code>) by the maximum + number of threads created in each process + (<code>MaxThreadsPerChild</code>).</p> + + <p>While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + <code>User</code> and <code>Group</code> directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless <a + href="../suexec.html">suexec</a> is used, these directives also + set the privileges which will be inherited by CGI scripts.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> + + <p>In addition it adds the extra ability to specify that + specific processes should serve requests under different + userids. These processes can then be associated with specific + virtual hosts.</p> + <!-- XXX: This desperately needs more explanation. --> + + <h2>Directives</h2> + + <ul> + <li><a href="#assignuserid">AssignUserID</a></li> + + <li><a href="#childperuserid">ChildPerUserID</a></li> + + <li><a + href="mpm_common.html#connectionstatus">ConnectionStatus</a></li> + + <li><a + href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> + + <li><a href="mpm_common.html#group">Group</a></li> + + <li><a href="mpm_common.html#pidfile">PidFile</a></li> + + <li><a href="mpm_common.html#listen">Listen</a></li> + + <li><a + href="mpm_common.html#listenbacklog">ListenBacklog</a></li> + + <li><a href="mpm_common.html#lockfile">LockFile</a></li> + + <li><a + href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a + href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li> + + <li><a + href="mpm_common.html#maxthreadsperchild">MaxThreadsPerChild</a></li> + + <li><a + href="mpm_common.html#minsparethreads">MinSpareThreads</a></li> + + <li><a href="mpm_common.html#numservers">NumServers</a></li> + + <li><a + href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> + + <li><a + href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> + + <li><a + href="mpm_common.html#startthreads">StartThreads</a></li> + + <li><a href="mpm_common.html#user">User</a></li> + </ul> + <hr /> + + <h2><a id="assignuserid" name="assignuserid">AssignUserID + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> perchild</p> + + <p>Tie a virtual host to a specific child process.</p> + <hr /> + + <h2><a id="childperuserid" name="childperuserid">ChildPerUserID + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> perchild</p> + + <p>Specify a User and Group for a specific child process.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/prefork.html b/docs/manual/mod/prefork.html index eda56730d2..05b25c84d8 100644 --- a/docs/manual/mod/prefork.html +++ b/docs/manual/mod/prefork.html @@ -1,228 +1,230 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache MPM prefork</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Multi-Processing Module prefork</H1> -<P> -This Multi-Processing Module implements a non-threaded, pre-forking -web server. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> MPM -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> prefork.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> mpm_prefork_module -</P> - -<H2>Summary</H2> - -<p>This Multi-Processing Module (MPM) implements a non-threaded, -pre-forking web server which handles request in a manner very similar -to the default behavior of Apache 1.3 on Unix.</p> - -<p>A single control process is responsible for launching child -processes which listen for connections and serve them when they -arrive. Apache always tries to maintain several <em>spare</em> or -idle server processes, which stand ready to serve incoming requests. -In this way, clients do not need to wait for a new child processes to -be forked before their requests can be served.</p> - -<p>The <code>StartServers</code>, <code>MinSpareServers</code>, -<code>MaxSpareServers</code>, and <code>MaxClients</code> regulate how -the parent process creates children to serve requests. In general, -Apache is very self-regulating, so most sites do not need to adjust -these directives from their default values. Sites which need to serve -more than 256 simultaneous requests may need to increase -<code>MaxClients</code>, while sites with limited memory may need to -decrease <code>MaxClients</code> to keep the server from thrashing -(swapping memory to disk and back). More information about tuning -process creation is provided in the <a -href="../misc/perf-tuning.html">performance hints</a> documentation.</p> - -<p>While the parent process is usually started as root under Unix -in order to bind to port 80, the child processes are launched -by Apache as a less-privileged user. The <code>User</code> and -<code>Group</code> directives are used to set the privileges -of the Apache child processes. The child processes must -be able to read all the content that will be served, but -should have as few privileges beyond that as possible. -In addition, unless <a href="../suexec.html">suexec</a> is used, -these directives also set the privileges which will be inherited -by CGI scripts.</p> - -<p><code>MaxRequestsPerChild</code> controls how frequently the server -recycles processes by killing old ones and launching new ones.</p> - -<p>See also: <a href="../bind.html">Setting which addresses and ports -Apache uses</a>.</p> - -<H2>Directives</H2> -<UL> -<li><a href="#acceptmutex">AcceptMutex</a> -<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> -<li><a href="mpm_common.html#group">Group</a></li> -<li><a href="mpm_common.html#pidfile">PidFile</a></li> -<li><a href="mpm_common.html#listen">Listen</a></li> -<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li> -<li><a href="mpm_common.html#lockfile">LockFile</a></li> -<li><a href="mpm_common.html#maxclients">MaxClients</a></li> -<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> -<li><a href="#maxspareservers">MaxSpareServers</a></li> -<li><a href="#minspareservers">MinSpareServers</a></li> -<li><a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> -<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> -<li><a href="mpm_common.html#startservers">StartServers</a></li> -<li><a href="mpm_common.html#user">User</a></li> -</UL> - -<p><hr> - - -<H2><A NAME="AcceptMutex">AcceptMutex Directive</A></H2> -<p><A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> AcceptMutex default|<EM>method</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <code>AcceptMutex default</code><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> core</p> - -<p>The <code>AcceptMutex</code> directives sets the method that Apache -uses to serialize multiple children accepting requests on network -sockets. Prior to Apache 2.0, the method was selectable only at -compile time. The optimal method to use is highly architecture and -platform dependent. For further details, see the <a -href="../misc/perf-tuning.html">performance tuning</a> -documentation.</p> - -<p>If this directive is set to <code>default</code>, then the -compile-time selected default will be used. Other possible -methods are listed below. Note that not all methods are available -on all platforms. If a method is specified which is not available, -a message will be written to the error log listing the available -methods.</p> - -<dl> - -<dt><code>flock</code></dt> -<dd>uses the <code>flock(2)</code> system call to lock the -file defined by the <a href="mpm_common.html#lockfile">LockFile</a> -directive.</dd> - -<dt><code>fcntl</code></dt> -<dd>uses the <code>fnctl(2)</code> system call to lock the -file defined by the <a href="mpm_common.html#lockfile">LockFile</a> -directive.</dd> - -<dt><code>sysvsem</code></dt> -<dd>uses SySV-style semaphores to implement the mutex.</dd> - -<dt><code>proc_pthread</code></dt> -<dd>uses POSIX mutexes as implemented by the POSIX Threads (PThreads) -specification.</dd> - -</dl> - -<hr> - -<H2><A NAME="maxspareservers">MaxSpareServers directive</A></H2> -<!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MaxSpareServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MaxSpareServers 10</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> 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> - -<P> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="mpm_common.html#startservers">StartServers</A>.<P><HR> - -<H2><A NAME="minspareservers">MinSpareServers directive</A></H2> -<!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> MinSpareServers <EM>number</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>MinSpareServers 5</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> 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> - -This directive has no effect on Microsoft Windows. - -<P> - -See also <A HREF="#maxspareservers">MaxSpareServers</A> and -<A HREF="mpm_common.html#startservers">StartServers</A>. - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache MPM prefork</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module prefork</h1> + + <p>This Multi-Processing Module implements a non-threaded, + pre-forking web server.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> prefork.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mpm_prefork_module</p> + + <h2>Summary</h2> + + <p>This Multi-Processing Module (MPM) implements a + non-threaded, pre-forking web server which handles request in a + manner very similar to the default behavior of Apache 1.3 on + Unix.</p> + + <p>A single control process is responsible for launching child + processes which listen for connections and serve them when they + arrive. Apache always tries to maintain several <em>spare</em> + or idle server processes, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child processes to be forked before their requests can be + served.</p> + + <p>The <code>StartServers</code>, <code>MinSpareServers</code>, + <code>MaxSpareServers</code>, and <code>MaxClients</code> + regulate how the parent process creates children to serve + requests. In general, Apache is very self-regulating, so most + sites do not need to adjust these directives from their default + values. Sites which need to serve more than 256 simultaneous + requests may need to increase <code>MaxClients</code>, while + sites with limited memory may need to decrease + <code>MaxClients</code> to keep the server from thrashing + (swapping memory to disk and back). More information about + tuning process creation is provided in the <a + href="../misc/perf-tuning.html">performance hints</a> + documentation.</p> + + <p>While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes are + launched by Apache as a less-privileged user. The + <code>User</code> and <code>Group</code> directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless <a + href="../suexec.html">suexec</a> is used, these directives also + set the privileges which will be inherited by CGI scripts.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#acceptmutex">AcceptMutex</a></li> + + <li><a + href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> + + <li><a href="mpm_common.html#group">Group</a></li> + + <li><a href="mpm_common.html#pidfile">PidFile</a></li> + + <li><a href="mpm_common.html#listen">Listen</a></li> + + <li><a + href="mpm_common.html#listenbacklog">ListenBacklog</a></li> + + <li><a href="mpm_common.html#lockfile">LockFile</a></li> + + <li><a href="mpm_common.html#maxclients">MaxClients</a></li> + + <li><a + href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a href="#maxspareservers">MaxSpareServers</a></li> + + <li><a href="#minspareservers">MinSpareServers</a></li> + + <li><a + href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> + + <li><a + href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> + + <li><a + href="mpm_common.html#startservers">StartServers</a></li> + + <li><a href="mpm_common.html#user">User</a></li> + </ul> + <hr /> + + <h2><a id="AcceptMutex" name="AcceptMutex">AcceptMutex + Directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> AcceptMutex + default|<em>method</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>AcceptMutex + default</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core</p> + + <p>The <code>AcceptMutex</code> directives sets the method that + Apache uses to serialize multiple children accepting requests + on network sockets. Prior to Apache 2.0, the method was + selectable only at compile time. The optimal method to use is + highly architecture and platform dependent. For further + details, see the <a href="../misc/perf-tuning.html">performance + tuning</a> documentation.</p> + + <p>If this directive is set to <code>default</code>, then the + compile-time selected default will be used. Other possible + methods are listed below. Note that not all methods are + available on all platforms. If a method is specified which is + not available, a message will be written to the error log + listing the available methods.</p> + + <dl> + <dt><code>flock</code></dt> + + <dd>uses the <code>flock(2)</code> system call to lock the + file defined by the <a + href="mpm_common.html#lockfile">LockFile</a> directive.</dd> + + <dt><code>fcntl</code></dt> + + <dd>uses the <code>fnctl(2)</code> system call to lock the + file defined by the <a + href="mpm_common.html#lockfile">LockFile</a> directive.</dd> + + <dt><code>sysvsem</code></dt> + + <dd>uses SySV-style semaphores to implement the mutex.</dd> + + <dt><code>proc_pthread</code></dt> + + <dd>uses POSIX mutexes as implemented by the POSIX Threads + (PThreads) specification.</dd> + </dl> + <hr /> + + <h2><a id="maxspareservers" + name="maxspareservers">MaxSpareServers directive</a></h2> + <!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxSpareServers + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MaxSpareServers + 10</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> 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> + + <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> + + <p>See also <a href="#minspareservers">MinSpareServers</a> and + <a href="mpm_common.html#startservers">StartServers</a>.</p> + <hr /> + + <h2><a id="minspareservers" + name="minspareservers">MinSpareServers directive</a></h2> + <!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MinSpareServers + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MinSpareServers + 5</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> 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> + + <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> + + <p>This directive has no effect on Microsoft Windows.</p> + + <p>See also <a href="#maxspareservers">MaxSpareServers</a> and + <a href="mpm_common.html#startservers">StartServers</a>. + <!--#include virtual="footer.html" --> + </p> + </body> +</html> + diff --git a/docs/manual/mod/threaded.html b/docs/manual/mod/threaded.html index 0d00ff7cab..434cd40e53 100644 --- a/docs/manual/mod/threaded.html +++ b/docs/manual/mod/threaded.html @@ -1,105 +1,121 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache MPM threaded</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Multi-Processing Module threaded</H1> -<P> -This Multi-Processing Module implements a hybrid multi-threaded -multi-process web server. -</P> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> MPM -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> threaded.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> mpm_threaded_module -</P> - -<H2>Summary</H2> - -<p>This Multi-Processing Module (MPM) is the default for most unix-like -operating systems. It implements a hybrid -multi-process multi-threaded server. Each process has a fixed number -of threads. The server adjusts to handle load by increasing or -decreasing the number of processes.</p> - -<p>A single control process is responsible for launching child -processes. Each child process creates a fixed number of threads as -specified in the <code>ThreadsPerChild</code> directive. -The individual threads then listen for connections and -serve them when they arrive.</p> - -<p>Apache always tries to maintain a pool of <em>spare</em> or idle -server threads, which stand ready to serve incoming requests. In this -way, clients do not need to wait for a new threads or processes to be -created before their requests can be served. Apache assesses the -total number of idle threads in all processes, and forks or kills -processes to keep this number within the boundaries specified by -<code>MinSpareThreads</code> and <code>MaxSpareThreads</code>. -Since this process is very self-regulating, it is rarely necessary to -modify these directives from their default values. The maximum -number of clients that may be served simultaneously is determined -by multiplying the maximum number of server processes that -will be created (<code>MaxClients</code>) by the number of threads -created in each process (<code>ThreadsPerChild</code>).</p> - -<p>While the parent process is usually started as root under Unix in -order to bind to port 80, the child processes and threads are launched -by Apache as a less-privileged user. The <code>User</code> and -<code>Group</code> directives are used to set the privileges of the -Apache child processes. The child processes must be able to read all -the content that will be served, but should have as few privileges -beyond that as possible. In addition, unless <a -href="../suexec.html">suexec</a> is used, these directives also set -the privileges which will be inherited by CGI scripts.</p> - -<p><code>MaxRequestsPerChild</code> controls how frequently the server -recycles processes by killing old ones and launching new ones.</p> - -<p>See also: <a href="../bind.html">Setting which addresses and ports -Apache uses</a>.</p> - - -<H2>Directives</H2> -<UL> -<li><a href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> -<li><a href="mpm_common.html#group">Group</a></li> -<li><a href="mpm_common.html#pidfile">PidFile</a></li> -<li><a href="mpm_common.html#listen">Listen</a></li> -<li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li> -<li><a href="mpm_common.html#lockfile">LockFile</a></li> -<li><a href="mpm_common.html#maxclients">MaxClients</a></li> -<li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> -<li><a href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li> -<li><a href="mpm_common.html#minsparethreads">MinSpareThreads</a></li> -<li><a href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> -<li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> -<li><a href="mpm_common.html#startservers">StartServers</a></li> -<li><a href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li> -<li><a href="mpm_common.html#user">User</a></li> -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache MPM threaded</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module threaded</h1> + + <p>This Multi-Processing Module implements a hybrid + multi-threaded multi-process web server.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> threaded.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mpm_threaded_module</p> + + <h2>Summary</h2> + + <p>This Multi-Processing Module (MPM) is the default for most + unix-like operating systems. It implements a hybrid + multi-process multi-threaded server. Each process has a fixed + number of threads. The server adjusts to handle load by + increasing or decreasing the number of processes.</p> + + <p>A single control process is responsible for launching child + processes. Each child process creates a fixed number of threads + as specified in the <code>ThreadsPerChild</code> directive. The + individual threads then listen for connections and serve them + when they arrive.</p> + + <p>Apache always tries to maintain a pool of <em>spare</em> or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + threads or processes to be created before their requests can be + served. Apache assesses the total number of idle threads in all + processes, and forks or kills processes to keep this number + within the boundaries specified by <code>MinSpareThreads</code> + and <code>MaxSpareThreads</code>. Since this process is very + self-regulating, it is rarely necessary to modify these + directives from their default values. The maximum number of + clients that may be served simultaneously is determined by + multiplying the maximum number of server processes that will be + created (<code>MaxClients</code>) by the number of threads + created in each process (<code>ThreadsPerChild</code>).</p> + + <p>While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + <code>User</code> and <code>Group</code> directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless <a + href="../suexec.html">suexec</a> is used, these directives also + set the privileges which will be inherited by CGI scripts.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a + href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> + + <li><a href="mpm_common.html#group">Group</a></li> + + <li><a href="mpm_common.html#pidfile">PidFile</a></li> + + <li><a href="mpm_common.html#listen">Listen</a></li> + + <li><a + href="mpm_common.html#listenbacklog">ListenBacklog</a></li> + + <li><a href="mpm_common.html#lockfile">LockFile</a></li> + + <li><a href="mpm_common.html#maxclients">MaxClients</a></li> + + <li><a + href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a + href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li> + + <li><a + href="mpm_common.html#minsparethreads">MinSpareThreads</a></li> + + <li><a + href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> + + <li><a + href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> + + <li><a + href="mpm_common.html#startservers">StartServers</a></li> + + <li><a + href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li> + + <li><a href="mpm_common.html#user">User</a></li> + </ul> + <!--#include virtual="footer.html" --> + </body> +</html> + |