diff options
| -rw-r--r-- | docs/manual/env.html.en | 571 | ||||
| -rw-r--r-- | docs/manual/env.xml | 353 | ||||
| -rw-r--r-- | docs/manual/filter.html.en | 79 | ||||
| -rw-r--r-- | docs/manual/filter.xml | 67 | ||||
| -rw-r--r-- | docs/manual/handler.html.en | 167 | ||||
| -rw-r--r-- | docs/manual/handler.xml | 145 |
6 files changed, 901 insertions, 481 deletions
diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en index 6b0b273479..73fd74493b 100644 --- a/docs/manual/env.html.en +++ b/docs/manual/env.html.en @@ -1,20 +1,8 @@ -<!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>Environment Variables in Apache</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">Environment Variables in Apache</h1> - +<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Environment Variables in Apache- Apache HTTP Server</title><link href="./style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="./images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Environment Variables in Apache</h1> <p>The Apache HTTP Server provides a mechanism for storing information in named variables that are called <em>environment variables</em>. This information can be used to control various @@ -22,7 +10,7 @@ also used as a mechanism to communicate with external programs such as CGI scripts. This document discusses different ways to manipulate and use these variables.</p> - + <p>Although these variables are referred to as <em>environment variables</em>, they are not the same as the environment variables controlled by the underlying operating system. @@ -34,260 +22,219 @@ server itself runs, you must use the standard environment manipulation mechanisms provided by your operating system shell.</p> - - <ul> - <li><a href="#setting">Setting Environment Variables</a></li> - - <li><a href="#using">Using Environment Variables</a></li> - - <li><a href="#special">Special Purpose Environment - Variables</a></li> - - <li><a href="#examples">Examples</a></li> - </ul> - <hr /> - - <h2><a id="setting" name="setting">Setting Environment - Variables</a></h2> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_env.html">mod_env</a><br /> - <a href="mod/mod_rewrite.html">mod_rewrite</a><br /> - <a href="mod/mod_setenvif.html">mod_setenvif</a><br /> - <a href="mod/mod_unique_id.html">mod_unique_id</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a - href="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</a><br /> - <a - href="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br /> - <a href="mod/mod_env.html#passenv">PassEnv</a><br /> - <a - href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br /> - <a href="mod/mod_env.html#setenv">SetEnv</a><br /> - <a - href="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</a><br /> - <a - href="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</a><br /> - <a href="mod/mod_env.html#unsetenv">UnsetEnv</a><br /> - </td> - </tr> - </table> - - <h3>Basic Environment Manipulation</h3> - - <p>The most basic way to set an environment variable in Apache - is using the unconditional <code>SetEnv</code> directive. - Variables may also be passed from the environment of the shell - which started the server using the <code>PassEnv</code> - directive.</p> - - <h3>Conditional Per-Request Settings</h3> - - <p>For additional flexibility, the directives provided by - mod_setenvif allow environment variables to be set on a - per-request basis, conditional on characteristics of particular - requests. For example, a variable could be set only when a - specific browser (User-Agent) is making a request, or only when - a specific Referer [sic] header is found. Even more flexibility - is available through the mod_rewrite's <code>RewriteRule</code> - which uses the <code>[E=...]</code> option to set environment - variables.</p> - - <h3>Unique Identifiers</h3> - - <p>Finally, mod_unique_id sets the environment variable - <code>UNIQUE_ID</code> for each request to a value which is - guaranteed to be unique across "all" requests under very - specific conditions.</p> - - <h3>Standard CGI Variables</h3> - - <p>In addition to all environment variables set within the - Apache configuration and passed from the shell, CGI scripts and - SSI pages are provided with a set of environment variables - containing meta-information about the request as required by - the <a href="http://cgi-spec.golux.com/">CGI - specification</a>.</p> - - <h3>Some Caveats</h3> - - <ul> - <li>It is not possible to override or change the standard CGI - variables using the environment manipulation directives.</li> - - <li>When <a href="suexec.html">suexec</a> is used to launch - CGI scripts, the environment will be cleaned down to a set of - <em>safe</em> variables before CGI scripts are launched. The - list of <em>safe</em> variables is defined at compile-time in - <code>suexec.c</code>.</li> - - <li>For portability reasons, the names of environment - variables may contain only letters, numbers, and the - underscore character. In addition, the first character may - not be a number. Characters which do not match this - restriction will be replaced by an underscore when passed to - CGI scripts and SSI pages.</li> - </ul> - <hr /> - - <h2><a id="using" name="using">Using Environment - Variables</a></h2> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_access.html">mod_access</a><br /> - <a href="mod/mod_cgi.html">mod_cgi</a><br /> - <a href="mod/mod_headers.html">mod_headers</a><br /> - <a href="mod/mod_include.html">mod_include</a><br /> - <a href="mod/mod_log_config.html">mod_log_config</a><br /> - <a href="mod/mod_rewrite.html">mod_rewrite</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a href="mod/mod_access.html#allow">Allow</a><br /> - <a - href="mod/mod_log_config.html#customlog">CustomLog</a><br /> - <a href="mod/mod_access.html#deny">Deny</a><br /> - <a href="mod/mod_headers.html#Header">Header</a><br /> - <a - href="mod/mod_log_config.html#logformat">LogFormat</a><br /> - <a - href="mod/mod_rewrite.html#RewriteCond">RewriteCond</a><br /> - <a - href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br /> - </td> - </tr> - </table> - - <h3>CGI Scripts</h3> - - <p>One of the primary uses of environment variables is to - communicate information to CGI scripts. As discussed above, the - environment passed to CGI scripts includes standard - meta-information about the request in addition to any variables - set within the Apache configuration. For more details, see the - <a href="howto/cgi.html">CGI tutorial</a>.</p> - - <h3>SSI Pages</h3> - - <p>Server-parsed (SSI) documents processed by mod_include's - <code>INCLUDES</code> filter can print environment variables - using the <code>echo</code> element, and can use environment - variables in flow control elements to makes parts of a page - conditional on characteristics of a request. Apache also - provides SSI pages with the standard CGI environment variables - as discussed above. For more details, see the <a - href="howto/ssi.html">SSI tutorial</a>.</p> - - <h3>Access Control</h3> - - <p>Access to the server can be controlled based on the value of - environment variables using the <code>allow from env=</code> - and <code>deny from env=</code> directives. In combination with - <code>SetEnvIf</code>, this allows for flexible control of - access to the server based on characteristics of the client. - For example, you can use these directives to deny access to a - particular browser (User-Agent).</p> - - <h3>Conditional Logging</h3> - - <p>Environment variables can be logged in the access log using - the <code>LogFormat</code> option <code>%e</code>. In addition, - the decision on whether or not to log requests can be made - based on the status of environment variables using the - conditional form of the <code>CustomLog</code> directive. In - combination with <code>SetEnvIf</code> this allows for flexible - control of which requests are logged. For example, you can - choose not to log requests for filenames ending in - <code>gif</code>, or you can choose to only log requests from - clients which are outside your subnet.</p> - - <h3>Conditional Response Headers</h3> - - <p>The <code>Header</code> directive can use the presence or - absence of an environment variable to determine whether or not - a certain HTTP header will be placed in the response to the - client. This allows, for example, a certain response header to - be sent only if a corresponding header is received in the - request from the client.</p> - - <h3>URL Rewriting</h3> - - <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in - the <code>RewriteCond</code> allows mod_rewrite's rewrite - engine to make decisions conditional on environment variables. - Note that the variables accessible in mod_rewrite without the - <code>ENV:</code> prefix are not actually environment - variables. Rather, they are variables special to mod_rewrite - which cannot be accessed from other modules.</p> - <hr /> - - <h2><a id="special" name="special">Special Purpose Environment - Variables</a></h2> - - <p>Interoperability problems have led to the introduction of - mechanisms to modify the way Apache behaves when talking to - particular clients. To make these mechanisms as flexible as - possible, they are invoked by defining environment variables, - typically with <a - href="mod/mod_setenvif.html#browsermatch">BrowserMatch</a>, - though <a href="mod/mod_env.html#setenv">SetEnv</a> and <a - href="mod/mod_env.html#passenv">PassEnv</a> could also be used, - for example.</p> - - <h2>downgrade-1.0</h2> - - <p>This forces the request to be treated as a HTTP/1.0 request - even if it was in a later dialect.</p> - - <h2>force-no-vary</h2> - - <p>This causes any <code>Vary</code> fields to be removed from - the response header before it is sent back to the client. Some - clients don't interpret this field correctly (see the <a - href="misc/known_client_problems.html">known client - problems</a> page); setting this variable can work around this - problem. Setting this variable also implies - <strong>force-response-1.0</strong>.</p> - - <h2>force-response-1.0</h2> - - <p>This forces an HTTP/1.0 response when set. It was originally - implemented as a result of a problem with AOL's proxies. Some - clients may not behave correctly when given an HTTP/1.1 - response, and this can be used to interoperate with them.</p> - - <h2>nokeepalive</h2> - - <p>This disables <a - href="mod/core.html#keepalive">KeepAlive</a> when set.</p> - - <h2>redirect-carefully</h2> - - <p>This forces the server to be more careful when sending a redirect - to the client. This is typically used when a client has a known - problem handling redirects. This was originally implemented as a - result of a problem with Microsoft's WebFolders software which has - a problem handling redirects on directory resources via DAV - methods.</p> - - <hr /> - <h2><a id="examples" name="examples">Examples</a></h2> - - <h3>Changing protocol behavior with misbehaving clients</h3> - - <p>We recommend that the following lines be included in - httpd.conf to deal with known client problems.</p> -<pre> + <ul><li><a href="#setting">Setting Environment Variables</a><ul><li><a href="#basic-manipulation">Basic Environment Manipulation</a></li><li><a href="#conditional">Conditional Per-Request Settings</a></li><li><a href="#unique-identifiers">Unique Identifiers</a></li><li><a href="#standard-cgi">Standard CGI Variables</a></li><li><a href="#caveats">Some Caveats</a></li></ul></li><li><a href="#using">Using Environment Variables</a><ul><li><a href="#cgi-scripts">CGI Scripts</a></li><li><a href="#ssi-pages">SSI Pages</a></li><li><a href="#access-control">Access Control</a></li><li><a href="#logging">Conditional Logging</a></li><li><a href="#response-headers">Conditional Response Headers</a></li><li><a href="#url-rewriting">URL Rewriting</a></li></ul></li><li><a href="#special">Special Purpose Environment Variables</a><ul><li><a href="#downgrade">downgrade-1.0</a></li><li><a href="#force-no-vary">force-no-vary</a></li><li><a href="#force-response">force-response-1.0</a></li><li><a href="#nokeepalive">nokeepalive</a></li><li><a href="#redirect-carefully">redirect-carefully</a></li></ul></li><li><a href="#examples">Examples</a><ul><li><a href="#misbehaving">Changing protocol behavior with misbehaving clients</a></li><li><a href="#no-img-log">Do not log requests for images in the access log</a></li><li><a href="#image-theft">Prevent "Image Theft"</a></li></ul></li></ul><hr/><h2><a name="setting">Setting Environment Variables</a></h2> + + <table border="1"><tr><td valign="top"><strong>Related Modules</strong><br/><br/><code><a href="./mod/mod_env.html">mod_env</a></code>, <br/><code><a href="./mod/mod_rewrite.html">mod_rewrite</a></code>, <br/><code><a href="./mod/mod_setenvif.html">mod_setenvif</a></code>, <br/><code><a href="./mod/mod_unique_id.html">mod_unique_id</a></code><br/></td><td valign="top"><strong>Related Directives</strong><br/><br/><a href="./mod/mod_setenvif.html#browsermatch" class="directive"><code class="directive">BrowserMatch</code></a><br/><a href="./mod/mod_setenvif.html#browsermatchnocase" class="directive"><code class="directive">BrowserMatchNoCase</code></a><br/><a href="./mod/mod_env.html#passenv" class="directive"><code class="directive">PassEnv</code></a><br/><a href="./mod/mod_rewrite.html#rewriterule" class="directive"><code class="directive">RewriteRule</code></a><br/><a href="./mod/mod_env.html#setenv" class="directive"><code class="directive">SetEnv</code></a><br/><a href="./mod/mod_setenvif.html#setenvif" class="directive"><code class="directive">SetEnvIf</code></a><br/><a href="./mod/mod_setenvif.html#setenvifnocase" class="directive"><code class="directive">SetEnvIfNoCase</code></a><br/><a href="./mod/mod_env.html.html#unsetenv" class="directive"><code class="directive">UnsetEnv</code></a><br/></td></tr></table> + + <h3><a name="basic-manipulation">Basic Environment Manipulation</a></h3> + + + <p>The most basic way to set an environment variable in Apache + is using the unconditional <a href="./mod/mod_env.html#setenv" class="directive"><code class="directive">SetEnv</code></a> directive. Variables may also be passed from + the environment of the shell which started the server using the + <a href="./mod/mod_env.html#passenv" class="directive"><code class="directive">PassEnv</code></a> directive.</p> + + + <h3><a name="conditional">Conditional Per-Request Settings</a></h3> + + + <p>For additional flexibility, the directives provided by + mod_setenvif allow environment variables to be set on a + per-request basis, conditional on characteristics of particular + requests. For example, a variable could be set only when a + specific browser (User-Agent) is making a request, or only when + a specific Referer [sic] header is found. Even more flexibility + is available through the mod_rewrite's <a href="./mod/mod_rewrite.html#rewriterule" class="directive"><code class="directive">RewriteRule</code></a> which uses the + <code>[E=...]</code> option to set environment variables.</p> + + + <h3><a name="unique-identifiers">Unique Identifiers</a></h3> + + + <p>Finally, mod_unique_id sets the environment variable + <code>UNIQUE_ID</code> for each request to a value which is + guaranteed to be unique across "all" requests under very + specific conditions.</p> + + + <h3><a name="standard-cgi">Standard CGI Variables</a></h3> + + + <p>In addition to all environment variables set within the + Apache configuration and passed from the shell, CGI scripts and + SSI pages are provided with a set of environment variables + containing meta-information about the request as required by + the <a href="http://cgi-spec.golux.com/">CGI + specification</a>.</p> + + + <h3><a name="caveats">Some Caveats</a></h3> + + + <ul> + <li>It is not possible to override or change the standard CGI + variables using the environment manipulation directives.</li> + + <li>When <a href="suexec.html">suexec</a> is used to launch + CGI scripts, the environment will be cleaned down to a set of + <em>safe</em> variables before CGI scripts are launched. The + list of <em>safe</em> variables is defined at compile-time in + <code>suexec.c</code>.</li> + + <li>For portability reasons, the names of environment + variables may contain only letters, numbers, and the + underscore character. In addition, the first character may + not be a number. Characters which do not match this + restriction will be replaced by an underscore when passed to + CGI scripts and SSI pages.</li> + </ul> + + <h2><a name="using">Using Environment Variables</a></h2> + + + <table border="1"><tr><td valign="top"><strong>Related Modules</strong><br/><br/><code><a href="./mod/mod_access.html">mod_access</a></code>, <br/><code><a href="./mod/mod_cgi.html">mod_cgi</a></code>, <br/><code><a href="./mod/mod_headers.html">mod_headers</a></code>, <br/><code><a href="./mod/mod_include.html">mod_include</a></code>, <br/><code><a href="./mod/mod_log_config.html">mod_log_config</a></code>, <br/><code><a href="./mod/mod_rewrite.html">mod_rewrite</a></code><br/></td><td valign="top"><strong>Related Directives</strong><br/><br/><a href="./mod/mod_access.html#allow" class="directive"><code class="directive">Allow</code></a><br/><a href="./mod/mod_log_config.html#customlog" class="directive"><code class="directive">CustomLog</code></a><br/><a href="./mod/mod_access.html#deny" class="directive"><code class="directive">Deny</code></a><br/><a href="./mod/mod_headers.html#header" class="directive"><code class="directive">Header</code></a><br/><a href="./mod/mod_log_config.html#logformat" class="directive"><code class="directive">LogFormat</code></a><br/><a href="./mod/mod_rewrite.html#rewritecond" class="directive"><code class="directive">RewriteCond</code></a><br/><a href="./mod/mod_rewrite.html#rewriterule" class="directive"><code class="directive">RewriteRule</code></a><br/></td></tr></table> + + <h3><a name="cgi-scripts">CGI Scripts</a></h3> + + + <p>One of the primary uses of environment variables is to + communicate information to CGI scripts. As discussed above, the + environment passed to CGI scripts includes standard + meta-information about the request in addition to any variables + set within the Apache configuration. For more details, see the + <a href="howto/cgi.html">CGI tutorial</a>.</p> + + + <h3><a name="ssi-pages">SSI Pages</a></h3> + + + <p>Server-parsed (SSI) documents processed by mod_include's + <code>INCLUDES</code> filter can print environment variables + using the <code>echo</code> element, and can use environment + variables in flow control elements to makes parts of a page + conditional on characteristics of a request. Apache also + provides SSI pages with the standard CGI environment variables + as discussed above. For more details, see the <a href="howto/ssi.html">SSI tutorial</a>.</p> + + + <h3><a name="access-control">Access Control</a></h3> + + + <p>Access to the server can be controlled based on the value of + environment variables using the <code>allow from env=</code> + and <code>deny from env=</code> directives. In combination with + <a href="./mod/mod_setenvif.html#setenvif" class="directive"><code class="directive">SetEnvIf</code></a>, this + allows for flexible control of access to the server based on + characteristics of the client. For example, you can use these + directives to deny access to a particular browser (User-Agent). + </p> + + + <h3><a name="logging">Conditional Logging</a></h3> + + + <p>Environment variables can be logged in the access log using + the <a href="./mod/mod_log_config.html#logformat" class="directive"><code class="directive">LogFormat</code></a> + option <code>%e</code>. In addition, the decision on whether + or not to log requests can be made based on the status of + environment variables using the conditional form of the + <a href="./mod/mod_log_config.html#customlog" class="directive"><code class="directive">CustomLog</code></a> + directive. In combination with <a href="./mod/mod_setenvif.html#setenvif" class="directive"><code class="directive">SetEnvIf</code></a> this allows for flexible control of which + requests are logged. For example, you can choose not to log + requests for filenames ending in <code>gif</code>, or you can + choose to only log requests from clients which are outside your + subnet.</p> + + + <h3><a name="response-headers">Conditional Response Headers</a></h3> + + + <p>The <a href="./mod/mod_headers.html#header" class="directive"><code class="directive">Header</code></a> + directive can use the presence or + absence of an environment variable to determine whether or not + a certain HTTP header will be placed in the response to the + client. This allows, for example, a certain response header to + be sent only if a corresponding header is received in the + request from the client.</p> + + + <h3><a name="url-rewriting">URL Rewriting</a></h3> + + + <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in + the <a href="./mod/mod_rewrite.html#rewritecond" class="directive"><code class="directive">RewriteCond</code></a> + allows mod_rewrite's rewrite + engine to make decisions conditional on environment variables. + Note that the variables accessible in mod_rewrite without the + <code>ENV:</code> prefix are not actually environment + variables. Rather, they are variables special to mod_rewrite + which cannot be accessed from other modules.</p> + + <h2><a name="special">Special Purpose Environment Variables</a></h2> + + + <p>Interoperability problems have led to the introduction of + mechanisms to modify the way Apache behaves when talking to + particular clients. To make these mechanisms as flexible as + possible, they are invoked by defining environment variables, + typically with <a href="./mod/mod_setenvif.html#browsermatch" class="directive"><code class="directive">BrowserMatch</code></a>, + though <a href="./mod/mod_env.html#setenv" class="directive"><code class="directive">SetEnv</code></a> and + <a href="./mod/mod_env.html#passenv" class="directive"><code class="directive">PassEnv</code></a> could also be used, + for example.</p> + + <h3><a name="downgrade">downgrade-1.0</a></h3> + + + <p>This forces the request to be treated as a HTTP/1.0 request + even if it was in a later dialect.</p> + + + <h3><a name="force-no-vary">force-no-vary</a></h3> + + + <p>This causes any <code>Vary</code> fields to be removed from + the response header before it is sent back to the client. Some + clients don't interpret this field correctly (see the <a href="misc/known_client_problems.html">known client + problems</a> page); setting this variable can work around this + problem. Setting this variable also implies + <strong>force-response-1.0</strong>.</p> + + + <h3><a name="force-response">force-response-1.0</a></h3> + + + <p>This forces an HTTP/1.0 response when set. It was originally + implemented as a result of a problem with AOL's proxies. Some + clients may not behave correctly when given an HTTP/1.1 + response, and this can be used to interoperate with them.</p> + + + <h3><a name="nokeepalive">nokeepalive</a></h3> + + + <p>This disables <a href="./mod/core.html#keepalive" class="directive"><code class="directive">KeepAlive</code></a> when set.</p> + + + <h3><a name="redirect-carefully">redirect-carefully</a></h3> + + + <p>This forces the server to be more careful when sending a redirect + to the client. This is typically used when a client has a known + problem handling redirects. This was originally implemented as a + result of a problem with Microsoft's WebFolders software which has + a problem handling redirects on directory resources via DAV + methods.</p> + + + <h2><a name="examples">Examples</a></h2> + + + <h3><a name="misbehaving">Changing protocol behavior with misbehaving clients</a></h3> + + + <p>We recommend that the following lines be included in + httpd.conf to deal with known client problems.</p> +<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><pre> # # The following directives modify normal HTTP response behavior. # The first directive disables keepalive for Netscape 2.x and browsers that @@ -306,45 +253,43 @@ BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 # BrowserMatch "RealPlayer 4\.0" force-response-1.0 BrowserMatch "Java/1\.0" force-response-1.0 -BrowserMatch "JDK/1\.0" force-response-1.0 -</pre> - - <h3>Do not log requests for images in the access log</h3> - - <p>This example keeps requests for images from appearing in the - access log. It can be easily modified to prevent logging of - particular directories, or to prevent logging of requests - coming from particular hosts.</p> -<pre> - SetEnvIf Request_URI \.gif image-request - SetEnvIf Request_URI \.jpg image-request - SetEnvIf Request_URI \.png image-request - CustomLog logs/access_log common env=!image-request -</pre> - - <h3>Prevent "Image Theft"</h3> - - <p>This example shows how to keep people not on your server - from using images on your server as inline-images on their - pages. This is not a recommended configuration, but it can work - in limited circumstances. We assume that all your images are in - a directory called /web/images.</p> -<pre> - SetEnvIf Referer "^http://www.example.com/" local_referal - # Allow browsers that do not send Referer info - SetEnvIf Referer "^$" local_referal - <Directory /web/images> - Order Deny,Allow - Deny from all - Allow from env=local_referal - </Directory> -</pre> - - <p>For more information about this technique, see the - ApacheToday tutorial " <a - href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS"> +BrowserMatch "JDK/1\.0" force-response-1.0</pre></code></td></tr></table></blockquote> + + + <h3><a name="no-img-log">Do not log requests for images in the access log</a></h3> + + + <p>This example keeps requests for images from appearing in the + access log. It can be easily modified to prevent logging of + particular directories, or to prevent logging of requests + coming from particular hosts.</p> + <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><pre> +SetEnvIf Request_URI \.gif image-request +SetEnvIf Request_URI \.jpg image-request +SetEnvIf Request_URI \.png image-request +CustomLog logs/access_log common env=!image-request</pre></code></td></tr></table></blockquote> + + + <h3><a name="image-theft">Prevent "Image Theft"</a></h3> + + + <p>This example shows how to keep people not on your server + from using images on your server as inline-images on their + pages. This is not a recommended configuration, but it can work + in limited circumstances. We assume that all your images are in + a directory called /web/images.</p> + <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><pre> +SetEnvIf Referer "^http://www.example.com/" local_referal +# Allow browsers that do not send Referer info +SetEnvIf Referer "^$" local_referal +<Directory /web/images> + Order Deny,Allow + Deny from all + Allow from env=local_referal +</Directory></pre></code></td></tr></table></blockquote> + + <p>For more information about this technique, see the + ApacheToday tutorial " <a href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS"> Keeping Your Images from Adorning Other Sites</a>".</p> - <!--#include virtual="footer.html" --> - </body> -</html> - + + </blockquote><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>
\ No newline at end of file diff --git a/docs/manual/env.xml b/docs/manual/env.xml new file mode 100644 index 0000000000..263e3527dc --- /dev/null +++ b/docs/manual/env.xml @@ -0,0 +1,353 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?> + +<manualpage> + <relativepath href="."/> + + <title>Environment Variables in Apache</title> + + <summary> + <p>The Apache HTTP Server provides a mechanism for storing + information in named variables that are called <em>environment + variables</em>. This information can be used to control various + operations such as logging or access control. The variables are + also used as a mechanism to communicate with external programs + such as CGI scripts. This document discusses different ways to + manipulate and use these variables.</p> + + <p>Although these variables are referred to as <em>environment + variables</em>, they are not the same as the environment + variables controlled by the underlying operating system. + Instead, these variables are stored and manipulated in an + internal Apache structure. They only become actual operating + system environment variables when they are provided to CGI + scripts and Server Side Include scripts. If you wish to + manipulate the operating system environment under which the + server itself runs, you must use the standard environment + manipulation mechanisms provided by your operating system + shell.</p> + </summary> + + <section id="setting"> + <title>Setting Environment Variables</title> + <related> + <modulelist> + <module>mod_env</module> + <module>mod_rewrite</module> + <module>mod_setenvif</module> + <module>mod_unique_id</module> + </modulelist> + <directivelist> + <directive module="mod_setenvif">BrowserMatch</directive> + <directive module="mod_setenvif">BrowserMatchNoCase</directive> + <directive module="mod_env">PassEnv</directive> + <directive module="mod_rewrite">RewriteRule</directive> + <directive module="mod_env">SetEnv</directive> + <directive module="mod_setenvif">SetEnvIf</directive> + <directive module="mod_setenvif">SetEnvIfNoCase</directive> + <directive module="mod_env.html">UnsetEnv</directive> + </directivelist> + </related> + + <section id="basic-manipulation"> + <title>Basic Environment Manipulation</title> + + <p>The most basic way to set an environment variable in Apache + is using the unconditional <directive module="mod_env" + >SetEnv</directive> directive. Variables may also be passed from + the environment of the shell which started the server using the + <directive module="mod_env">PassEnv</directive> directive.</p> + + </section> + <section id="conditional"> + <title>Conditional Per-Request Settings</title> + + <p>For additional flexibility, the directives provided by + mod_setenvif allow environment variables to be set on a + per-request basis, conditional on characteristics of particular + requests. For example, a variable could be set only when a + specific browser (User-Agent) is making a request, or only when + a specific Referer [sic] header is found. Even more flexibility + is available through the mod_rewrite's <directive + module="mod_rewrite">RewriteRule</directive> which uses the + <code>[E=...]</code> option to set environment variables.</p> + + </section> + <section id="unique-identifiers"> + <title>Unique Identifiers</title> + + <p>Finally, mod_unique_id sets the environment variable + <code>UNIQUE_ID</code> for each request to a value which is + guaranteed to be unique across "all" requests under very + specific conditions.</p> + + </section> + <section id="standard-cgi"> + <title>Standard CGI Variables</title> + + <p>In addition to all environment variables set within the + Apache configuration and passed from the shell, CGI scripts and + SSI pages are provided with a set of environment variables + containing meta-information about the request as required by + the <a href="http://cgi-spec.golux.com/">CGI + specification</a>.</p> + + </section> + <section id="caveats"> + <title>Some Caveats</title> + + <ul> + <li>It is not possible to override or change the standard CGI + variables using the environment manipulation directives.</li> + + <li>When <a href="suexec.html">suexec</a> is used to launch + CGI scripts, the environment will be cleaned down to a set of + <em>safe</em> variables before CGI scripts are launched. The + list of <em>safe</em> variables is defined at compile-time in + <code>suexec.c</code>.</li> + + <li>For portability reasons, the names of environment + variables may contain only letters, numbers, and the + underscore character. In addition, the first character may + not be a number. Characters which do not match this + restriction will be replaced by an underscore when passed to + CGI scripts and SSI pages.</li> + </ul> + </section> + </section> + <section id="using"> + <title>Using Environment Variables</title> + + <related> + <modulelist> + <module>mod_access</module> + <module>mod_cgi</module> + <module>mod_headers</module> + <module>mod_include</module> + <module>mod_log_config</module> + <module>mod_rewrite</module> + </modulelist> + <directivelist> + <directive module="mod_access">Allow</directive> + <directive module="mod_log_config">CustomLog</directive> + <directive module="mod_access">Deny</directive> + <directive module="mod_headers">Header</directive> + <directive module="mod_log_config">LogFormat</directive> + <directive module="mod_rewrite">RewriteCond</directive> + <directive module="mod_rewrite">RewriteRule</directive> + </directivelist> + </related> + + <section id="cgi-scripts"> + <title>CGI Scripts</title> + + <p>One of the primary uses of environment variables is to + communicate information to CGI scripts. As discussed above, the + environment passed to CGI scripts includes standard + meta-information about the request in addition to any variables + set within the Apache configuration. For more details, see the + <a href="howto/cgi.html">CGI tutorial</a>.</p> + + </section> + <section id="ssi-pages"> + <title>SSI Pages</title> + + <p>Server-parsed (SSI) documents processed by mod_include's + <code>INCLUDES</code> filter can print environment variables + using the <code>echo</code> element, and can use environment + variables in flow control elements to makes parts of a page + conditional on characteristics of a request. Apache also + provides SSI pages with the standard CGI environment variables + as discussed above. For more details, see the <a + href="howto/ssi.html">SSI tutorial</a>.</p> + + </section> + <section id="access-control"> + <title>Access Control</title> + + <p>Access to the server can be controlled based on the value of + environment variables using the <code>allow from env=</code> + and <code>deny from env=</code> directives. In combination with + <directive module="mod_setenvif">SetEnvIf</directive>, this + allows for flexible control of access to the server based on + characteristics of the client. For example, you can use these + directives to deny access to a particular browser (User-Agent). + </p> + + </section> + <section id="logging"> + <title>Conditional Logging</title> + + <p>Environment variables can be logged in the access log using + the <directive module="mod_log_config">LogFormat</directive> + option <code>%e</code>. In addition, the decision on whether + or not to log requests can be made based on the status of + environment variables using the conditional form of the + <directive module="mod_log_config">CustomLog</directive> + directive. In combination with <directive module="mod_setenvif" + >SetEnvIf</directive> this allows for flexible control of which + requests are logged. For example, you can choose not to log + requests for filenames ending in <code>gif</code>, or you can + choose to only log requests from clients which are outside your + subnet.</p> + + </section> + <section id="response-headers"> + <title>Conditional Response Headers</title> + + <p>The <directive module="mod_headers">Header</directive> + directive can use the presence or + absence of an environment variable to determine whether or not + a certain HTTP header will be placed in the response to the + client. This allows, for example, a certain response header to + be sent only if a corresponding header is received in the + request from the client.</p> + + </section> + <section id="url-rewriting"> + <title>URL Rewriting</title> + + <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in + the <directive module="mod_rewrite">RewriteCond</directive> + allows mod_rewrite's rewrite + engine to make decisions conditional on environment variables. + Note that the variables accessible in mod_rewrite without the + <code>ENV:</code> prefix are not actually environment + variables. Rather, they are variables special to mod_rewrite + which cannot be accessed from other modules.</p> + </section> + </section> + + <section id="special"> + <title>Special Purpose Environment Variables</title> + + <p>Interoperability problems have led to the introduction of + mechanisms to modify the way Apache behaves when talking to + particular clients. To make these mechanisms as flexible as + possible, they are invoked by defining environment variables, + typically with <directive module="mod_setenvif">BrowserMatch</directive>, + though <directive module="mod_env">SetEnv</directive> and + <directive module="mod_env">PassEnv</directive> could also be used, + for example.</p> + + <section id="downgrade"> + <title>downgrade-1.0</title> + + <p>This forces the request to be treated as a HTTP/1.0 request + even if it was in a later dialect.</p> + + </section> + <section id="force-no-vary"> + <title>force-no-vary</title> + + <p>This causes any <code>Vary</code> fields to be removed from + the response header before it is sent back to the client. Some + clients don't interpret this field correctly (see the <a + href="misc/known_client_problems.html">known client + problems</a> page); setting this variable can work around this + problem. Setting this variable also implies + <strong>force-response-1.0</strong>.</p> + + </section> + <section id="force-response"> + <title>force-response-1.0</title> + + <p>This forces an HTTP/1.0 response when set. It was originally + implemented as a result of a problem with AOL's proxies. Some + clients may not behave correctly when given an HTTP/1.1 + response, and this can be used to interoperate with them.</p> + + </section> + <section id="nokeepalive"> + <title>nokeepalive</title> + + <p>This disables <directive module="core">KeepAlive</directive> when set.</p> + + </section> + <section id="redirect-carefully"> + <title>redirect-carefully</title> + + <p>This forces the server to be more careful when sending a redirect + to the client. This is typically used when a client has a known + problem handling redirects. This was originally implemented as a + result of a problem with Microsoft's WebFolders software which has + a problem handling redirects on directory resources via DAV + methods.</p> + + </section> + </section> + + <section id="examples"> + <title>Examples</title> + + <section id="misbehaving"> + <title>Changing protocol behavior with misbehaving clients</title> + + <p>We recommend that the following lines be included in + httpd.conf to deal with known client problems.</p> +<example><pre> +# +# The following directives modify normal HTTP response behavior. +# The first directive disables keepalive for Netscape 2.x and browsers that +# spoof it. There are known problems with these browser implementations. +# The second directive is for Microsoft Internet Explorer 4.0b2 +# which has a broken HTTP/1.1 implementation and does not properly +# support keepalive when it is used on 301 or 302 (redirect) responses. +# +BrowserMatch "Mozilla/2" nokeepalive +BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 + +# +# The following directive disables HTTP/1.1 responses to browsers which +# are in violation of the HTTP/1.0 spec by not being able to grok a +# basic 1.1 response. +# +BrowserMatch "RealPlayer 4\.0" force-response-1.0 +BrowserMatch "Java/1\.0" force-response-1.0 +BrowserMatch "JDK/1\.0" force-response-1.0</pre></example> + + </section> + <section id="no-img-log"> + <title>Do not log requests for images in the access log</title> + + <p>This example keeps requests for images from appearing in the + access log. It can be easily modified to prevent logging of + particular directories, or to prevent logging of requests + coming from particular hosts.</p> + <example><pre> +SetEnvIf Request_URI \.gif image-request +SetEnvIf Request_URI \.jpg image-request +SetEnvIf Request_URI \.png image-request +CustomLog logs/access_log common env=!image-request</pre></example> + + </section> + <section id="image-theft"> + <title>Prevent "Image Theft"</title> + + <p>This example shows how to keep people not on your server + from using images on your server as inline-images on their + pages. This is not a recommended configuration, but it can work + in limited circumstances. We assume that all your images are in + a directory called /web/images.</p> + <example><pre> +SetEnvIf Referer "^http://www.example.com/" local_referal +# Allow browsers that do not send Referer info +SetEnvIf Referer "^$" local_referal +<Directory /web/images> + Order Deny,Allow + Deny from all + Allow from env=local_referal +</Directory></pre></example> + + <p>For more information about this technique, see the + ApacheToday tutorial " <a + href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS"> + Keeping Your Images from Adorning Other Sites</a>".</p> + </section> + </section> +</manualpage> + + + + diff --git a/docs/manual/filter.html.en b/docs/manual/filter.html.en index 85c460ab38..75689e4963 100644 --- a/docs/manual/filter.html.en +++ b/docs/manual/filter.html.en @@ -1,47 +1,13 @@ -<!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>Filters - Apache HTTPD</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">Filters</h1> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_deflate.html">mod_deflate</a><br /> - <a href="mod/mod_ext_filter.html">mod_ext_filter</a><br /> - <a href="mod/mod_include.html">mod_include</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a - href="mod/mod_mime.html#addinputfilter">AddInputFilter</a><br /> - <a - href="mod/mod_mime.html#addoutputfilter">AddOutputFilter</a><br /> - <a - href="mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a><br /> - <a - href="mod/mod_ext_filter.html#extfilteroptions">ExtFilterOptions</a><br /> - <a - href="mod/core.html#setinputfilter">SetInputFilter</a><br /> - <a - href="mod/core.html#setoutputfilter">SetOutputFilter</a><br /> - </td> - </tr> - </table> - +<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Filters- Apache HTTP Server</title><link href="./style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="./images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Filters</h1> + <p>This document describes the use of filters in Apache.</p> + <ul><li><a href="#filters">Filters</a></li></ul><hr/><h2><a name="filters">Filters</a></h2> + + <table border="1"><tr><td valign="top"><strong>Related Modules</strong><br/><br/><code><a href="./mod/mod_deflate.html">mod_deflate</a></code>, <br/><code><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code>, <br/><code><a href="./mod/mod_include.html">mod_include</a></code><br/></td><td valign="top"><strong>Related Directives</strong><br/><br/><a href="./mod/mod_mime.html#addinputfilter" class="directive"><code class="directive">AddInputFilter</code></a><br/><a href="./mod/mod_mime.html#addoutputfilter" class="directive"><code class="directive">AddOutputFilter</code></a><br/><a href="./mod/mod_ext_filter.html#extfilterdefine" class="directive"><code class="directive">ExtFilterDefine</code></a><br/><a href="./mod/mod_ext_filter.html#extfilteroptions" class="directive"><code class="directive">ExtFilterOptions</code></a><br/><a href="./mod/core.html.html#setinputfilter" class="directive"><code class="directive">SetInputFilter</code></a><br/><a href="./mod/core.html.html#setoutputfilter" class="directive"><code class="directive">SetOutputFilter</code></a><br/></td></tr></table> + <p>A <em>filter</em> is a process that is applied to data that is sent or received by the server. Data sent by clients to the server is processed by <em>input filters</em> while data sent @@ -53,25 +19,18 @@ as chunking and byte-range request handling. In addition, modules can provide filters that are selectable using run-time configuration directives. The set of filters that apply to data - can be manipulated with the <code>SetInputFilter</code>, - <code>SetOutputFilter</code>, <code>AddInputFilter</code>, and - <code>AddOutputFilter</code> directives.</p> + can be manipulated with the <a href="./mod/core.html.html#setinputfilter" class="directive"><code class="directive">SetInputFilter</code></a>, <a href="./mod/core.html.html#setoutputfilter" class="directive"><code class="directive">SetOutputFilter</code></a>, <a href="./mod/mod_mime.html#addinputfilter" class="directive"><code class="directive">AddInputFilter</code></a>, and <a href="./mod/mod_mime.html#addoutputfilter" class="directive"><code class="directive">AddOutputFilter</code></a> directives.</p> <p>The following user-selectable filters are currently provided with the Apache HTTP Server distribution.</p> -<dl> -<dt>INCLUDES</dt> <dd>Server-Side Includes processing by <a -href="mod/mod_include.html">mod_include</a></dd> -<dt>DEFLATE</dt> <dd>Compress output before sending it to -the client using <a href="mod/mod_deflate.html">mod_deflate</a></dd> -</dl> + <dl> + <dt>INCLUDES</dt> + <dd>Server-Side Includes processing by <code><a href="./mod/mod_include.html">mod_include</a></code></dd> + <dt>DEFLATE</dt> + <dd>Compress output before sending it to the client using <code><a href="./mod/mod_include.html">mod_include</a></code></dd> + </dl> - <p>In addition, the module <a - href="mod/mod_ext_filter.html">mod_ext_filter</a> allows + <p>In addition, the module <code><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code> allows for external programs to be defined as filters.</p> - - <!--#include virtual="footer.html" --> - </body> -</html> - + </blockquote><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>
\ No newline at end of file diff --git a/docs/manual/filter.xml b/docs/manual/filter.xml new file mode 100644 index 0000000000..ba58529f66 --- /dev/null +++ b/docs/manual/filter.xml @@ -0,0 +1,67 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?> + +<manualpage> + <relativepath href="."/> + + <title>Filters</title> + + <summary> + <p>This document describes the use of filters in Apache.</p> + </summary> + + <section id="filters"> + <title>Filters</title> + <related> + <modulelist> + <module>mod_deflate</module> + <module>mod_ext_filter</module> + <module>mod_include</module> + </modulelist> + <directivelist> + <directive module="mod_mime">AddInputFilter</directive> + <directive module="mod_mime">AddOutputFilter</directive> + <directive module="mod_ext_filter">ExtFilterDefine</directive> + <directive module="mod_ext_filter">ExtFilterOptions</directive> + <directive module="core.html">SetInputFilter</directive> + <directive module="core.html">SetOutputFilter</directive> + </directivelist> + </related> + + <p>A <em>filter</em> is a process that is applied to data that + is sent or received by the server. Data sent by clients to the + server is processed by <em>input filters</em> while data sent + by the server to the client is processed by <em>output + filters</em>. Multiple filters can be applied to the data, and + the order of the filters can be explicitly specified.</p> + + <p>Filters are used internally by Apache to perform functions such + as chunking and byte-range request handling. In addition, modules + can provide filters that are selectable using run-time + configuration directives. The set of filters that apply to data + can be manipulated with the <directive module="core.html" + >SetInputFilter</directive>, <directive module="core.html" + >SetOutputFilter</directive>, <directive module="mod_mime" + >AddInputFilter</directive>, and <directive module="mod_mime" + >AddOutputFilter</directive> directives.</p> + + <p>The following user-selectable filters are currently provided + with the Apache HTTP Server distribution.</p> + + <dl> + <dt>INCLUDES</dt> + <dd>Server-Side Includes processing by <module>mod_include</module></dd> + <dt>DEFLATE</dt> + <dd>Compress output before sending it to the client using <module + >mod_include</module></dd> + </dl> + + <p>In addition, the module <module>mod_ext_filter</module> allows + for external programs to be defined as filters.</p> + </section> +</manualpage> + + + + diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en index f937095dcd..48648277e0 100644 --- a/docs/manual/handler.html.en +++ b/docs/manual/handler.html.en @@ -1,59 +1,13 @@ -<!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's Handler Use</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's Handler Use</h1> - - <ul> - <li><a href="#definition">What is a Handler</a></li> - - <li><a href="#examples">Examples</a></li> - - <li><a href="#programmer">Programmer's Note</a></li> - </ul> - <hr /> - - <h2><a id="definition" name="definition">What is a - Handler</a></h2> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_actions.html">mod_actions</a><br /> - <a href="mod/mod_asis.html">mod_asis</a><br /> - <a href="mod/mod_cgi.html">mod_cgi</a><br /> - <a href="mod/mod_imap.html">mod_imap</a><br /> - <a href="mod/mod_info.html">mod_info</a><br /> - <a href="mod/mod_mime.html">mod_mime</a><br /> - <a - href="mod/mod_negotiation.html">mod_negotiation</a><br /> - <a href="mod/mod_status.html">mod_status</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a href="mod/mod_actions.html#action">Action</a><br /> - <a - href="mod/mod_mime.html#addhandler">AddHandler</a><br /> - <a - href="mod/mod_mime.html#removehandler">RemoveHandler</a><br /> - <a - href="mod/mod_mime.html#sethandler">SetHandler</a><br /> - </td> - </tr> - </table> +<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Apache's Handler Use- Apache HTTP Server</title><link href="./style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="./images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache's Handler Use</h1> + <p>This document describes the use of Apache's Handlers.</p> + <ul><li><a href="#definition">What is a Handler</a></li><li><a href="#examples">Examples</a><ul><li><a href="#example1">Modifying static content using a CGI script</a></li><li><a href="#example2">Files with HTTP headers</a></li></ul></li><li><a href="#programmer">Programmer's Note</a></li></ul><hr/><h2><a name="definition">What is a Handler</a></h2> + + <table border="1"><tr><td valign="top"><strong>Related Modules</strong><br/><br/><code><a href="./mod/mod_actions.html">mod_actions</a></code>, <br/><code><a href="./mod/mod_asis.html">mod_asis</a></code>, <br/><code><a href="./mod/mod_cgi.html">mod_cgi</a></code>, <br/><code><a href="./mod/mod_imap.html">mod_imap</a></code>, <br/><code><a href="./mod/mod_info.html">mod_info</a></code>, <br/><code><a href="./mod/mod_mime.html">mod_mime</a></code>, <br/><code><a href="./mod/mod_negotiation.html">mod_negotiation</a></code>, <br/><code><a href="./mod/mod_status.html">mod_status</a></code><br/></td><td valign="top"><strong>Related Directives</strong><br/><br/><a href="./mod/mod_actions.html#action" class="directive"><code class="directive">Action</code></a><br/><a href="./mod/mod_mime.html#addhandler" class="directive"><code class="directive">AddHandler</code></a><br/><a href="./mod/mod_mime.html#removehandler" class="directive"><code class="directive">RemoveHandler</code></a><br/><a href="./mod/mod_mime.html#sethandler" class="directive"><code class="directive">SetHandler</code></a><br/></td></tr></table> + <p>A "handler" is an internal Apache representation of the action to be performed when a file is called. Generally, files @@ -66,13 +20,11 @@ can be specified without relation to file type. This is advantageous both because it is a more elegant solution, and because it also allows for both a type <strong>and</strong> a - handler to be associated with a file. (See also <a - href="mod/mod_mime.html#multipleext">Files with Multiple + handler to be associated with a file. (See also <a href="mod/mod_mime.html#multipleext">Files with Multiple Extensions</a>.)</p> <p>Handlers can either be built into the server or included in - a module, or they can be added with the <a - href="mod/mod_actions.html#action">Action</a> directive. The + a module, or they can be added with the <a href="./mod/mod_actions.html#action" class="directive"><code class="directive">Action</code></a> directive. The built-in handlers in the standard distribution are as follows:</p> @@ -82,61 +34,63 @@ default to handle static content. (core)</li> <li><strong>send-as-is</strong>: Send file with HTTP headers - as is. (<a href="mod/mod_asis.html">mod_asis</a>)</li> + as is. (<code><a href="./mod/mod_asis.html">mod_asis</a></code>)</li> <li><strong>cgi-script</strong>: Treat the file as a CGI - script. (<a href="mod/mod_cgi.html">mod_cgi</a>)</li> + script. (<code><a href="./mod/mod_cgi.html">mod_cgi</a></code>)</li> <li><strong>imap-file</strong>: Parse as an imagemap rule - file. (<a href="mod/mod_imap.html">mod_imap</a>)</li> + file. (<code><a href="./mod/mod_imap.html">mod_imap</a></code>)</li> <li><strong>server-info</strong>: Get the server's - configuration information. (<a - href="mod/mod_info.html">mod_info</a>)</li> + configuration information. (<code><a href="./mod/mod_info.html">mod_info</a></code>)</li> <li><strong>server-status</strong>: Get the server's status - report. (<a href="mod/mod_status.html">mod_status</a>)</li> + report. (<code><a href="./mod/mod_status.html">mod_status</a></code>)</li> <li><strong>type-map</strong>: Parse as a type map file for - content negotiation. (<a - href="mod/mod_negotiation.html">mod_negotiation</a>)</li> + content negotiation. (<code><a href="./mod/mod_negotiation.html">mod_negotiation</a></code>)</li> </ul> - <hr /> - - <h2><a id="examples" name="examples">Examples</a></h2> - - <h3>Modifying static content using a CGI script</h3> - - <p>The following directives will cause requests for files with - the <code>html</code> extension to trigger the launch of the - <code>footer.pl</code> CGI script.</p> -<pre> - Action add-footer /cgi-bin/footer.pl - AddHandler add-footer .html -</pre> - - <p>Then the CGI script is responsible for sending the - originally requested document (pointed to by the - <code>PATH_TRANSLATED</code> environment variable) and making - whatever modifications or additions are desired.</p> - - <h3>Files with HTTP headers</h3> - - <p>The following directives will enable the - <code>send-as-is</code> handler, which is used for files which - contain their own HTTP headers. All files in the - <code>/web/htdocs/asis/</code> directory will be processed by - the <code>send-as-is</code> handler, regardless of their - filename extensions.</p> -<pre> - <Directory /web/htdocs/asis> - SetHandler send-as-is - </Directory> -</pre> - <hr /> - - <h2><a id="programmer" name="programmer">Programmer's - Note</a></h2> + <h2><a name="examples">Examples</a></h2> + + + <h3><a name="example1">Modifying static content using a CGI script</a></h3> + + + <p>The following directives will cause requests for files with + the <code>html</code> extension to trigger the launch of the + <code>footer.pl</code> CGI script.</p> + + <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><code> + Action add-footer /cgi-bin/footer.pl<br> + AddHandler add-footer .html + </code></code></td></tr></table></blockquote> + + <p>Then the CGI script is responsible for sending the + originally requested document (pointed to by the + <code>PATH_TRANSLATED</code> environment variable) and making + whatever modifications or additions are desired.</p> + + + <h3><a name="example2">Files with HTTP headers</a></h3> + + + <p>The following directives will enable the + <code>send-as-is</code> handler, which is used for files which + contain their own HTTP headers. All files in the + <code>/web/htdocs/asis/</code> directory will be processed by + the <code>send-as-is</code> handler, regardless of their + filename extensions.</p> + + <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><code> + <Directory /web/htdocs/asis><br> + SetHandler send-as-is<br> + </Directory> + </code></code></td></tr></table></blockquote> + + + <h2><a name="programmer">Programmer's Note</a></h2> + <p>In order to implement the handler features, an addition has been made to the <a href="developer/API.html">Apache API</a> that @@ -154,7 +108,4 @@ type. While it is not necessary, the naming convention for handlers is to use a dash-separated word, with no slashes, so as to not invade the media type name-space.</p> - <!--#include virtual="footer.html" --> - </body> -</html> - + </blockquote><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>
\ No newline at end of file diff --git a/docs/manual/handler.xml b/docs/manual/handler.xml new file mode 100644 index 0000000000..3907bb4f20 --- /dev/null +++ b/docs/manual/handler.xml @@ -0,0 +1,145 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?> + +<manualpage> + <relativepath href="."/> + + <title>Apache's Handler Use</title> + + <summary> + <p>This document describes the use of Apache's Handlers.</p> + </summary> + + <section id="definition"> + <title>What is a Handler</title> + <related> + <modulelist> + <module>mod_actions</module> + <module>mod_asis</module> + <module>mod_cgi</module> + <module>mod_imap</module> + <module>mod_info</module> + <module>mod_mime</module> + <module>mod_negotiation</module> + <module>mod_status</module> + </modulelist> + <directivelist> + <directive module="mod_actions">Action</directive> + <directive module="mod_mime">AddHandler</directive> + <directive module="mod_mime">RemoveHandler</directive> + <directive module="mod_mime">SetHandler</directive> + </directivelist> + </related> + + + <p>A "handler" is an internal Apache representation of the + action to be performed when a file is called. Generally, files + have implicit handlers, based on the file type. Normally, all + files are simply served by the server, but certain file types + are "handled" separately.</p> + + <p>Apache 1.1 adds the ability to use handlers explicitly. + Based on either filename extensions or on location, handlers + can be specified without relation to file type. This is + advantageous both because it is a more elegant solution, and + because it also allows for both a type <strong>and</strong> a + handler to be associated with a file. (See also <a + href="mod/mod_mime.html#multipleext">Files with Multiple + Extensions</a>.)</p> + + <p>Handlers can either be built into the server or included in + a module, or they can be added with the <directive + module="mod_actions">Action</directive> directive. The + built-in handlers in the standard distribution are as + follows:</p> + + <ul> + <li><strong>default-handler</strong>: Send the file using the + <code>default_handler()</code>, which is the handler used by + default to handle static content. (core)</li> + + <li><strong>send-as-is</strong>: Send file with HTTP headers + as is. (<module>mod_asis</module>)</li> + + <li><strong>cgi-script</strong>: Treat the file as a CGI + script. (<module>mod_cgi</module>)</li> + + <li><strong>imap-file</strong>: Parse as an imagemap rule + file. (<module>mod_imap</module>)</li> + + <li><strong>server-info</strong>: Get the server's + configuration information. (<module>mod_info</module>)</li> + + <li><strong>server-status</strong>: Get the server's status + report. (<module>mod_status</module>)</li> + + <li><strong>type-map</strong>: Parse as a type map file for + content negotiation. (<module>mod_negotiation</module>)</li> + </ul> + </section> + <section id="examples"> + <title>Examples</title> + + <section id="example1"> + <title>Modifying static content using a CGI script</title> + + <p>The following directives will cause requests for files with + the <code>html</code> extension to trigger the launch of the + <code>footer.pl</code> CGI script.</p> + + <example><code> + Action add-footer /cgi-bin/footer.pl<br/> + AddHandler add-footer .html + </code></example> + + <p>Then the CGI script is responsible for sending the + originally requested document (pointed to by the + <code>PATH_TRANSLATED</code> environment variable) and making + whatever modifications or additions are desired.</p> + + </section> + <section id="example2"> + <title>Files with HTTP headers</title> + + <p>The following directives will enable the + <code>send-as-is</code> handler, which is used for files which + contain their own HTTP headers. All files in the + <code>/web/htdocs/asis/</code> directory will be processed by + the <code>send-as-is</code> handler, regardless of their + filename extensions.</p> + + <example><code> + <Directory /web/htdocs/asis><br/> + SetHandler send-as-is<br/> + </Directory> + </code></example> + + </section> + </section> + <section id="programmer"> + <title>Programmer's Note</title> + + <p>In order to implement the handler features, an addition has + been made to the <a href="developer/API.html">Apache API</a> that + you may wish to make use of. Specifically, a new record has + been added to the <code>request_rec</code> structure:</p> +<pre> + char *handler +</pre> + + <p>If you wish to have your module engage a handler, you need + only to set <code>r->handler</code> to the name of the + handler at any time prior to the <code>invoke_handler</code> + stage of the request. Handlers are implemented as they were + before, albeit using the handler name instead of a content + type. While it is not necessary, the naming convention for + handlers is to use a dash-separated word, with no slashes, so + as to not invade the media type name-space.</p> + </section> +</manualpage> + + + + + |