diff options
| author | Rich Bowen <rbowen@apache.org> | 2001-09-22 18:53:20 +0000 |
|---|---|---|
| committer | Rich Bowen <rbowen@apache.org> | 2001-09-22 18:53:20 +0000 |
| commit | 1bf05b9838e25403ff49e68c7ce8e26af90b6bd5 (patch) | |
| tree | 8d0f0997663688543686f0dea197117a28730949 /docs/manual/env.html | |
| parent | 64670c57ff3c8a851b66d37a4c9d1fe730e57c48 (diff) | |
| download | httpd-1bf05b9838e25403ff49e68c7ce8e26af90b6bd5.tar.gz | |
Ran w3c tidy on these as 'tidy -mi -asxml' to get xhtml. Please verify,
in particular, the non-english files, to make sure I did not screw
anything up. They look fine to me.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91112 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs/manual/env.html')
| -rw-r--r-- | docs/manual/env.html | 583 |
1 files changed, 298 insertions, 285 deletions
diff --git a/docs/manual/env.html b/docs/manual/env.html index 6e75559385..8224f9768b 100644 --- a/docs/manual/env.html +++ b/docs/manual/env.html @@ -1,268 +1,283 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<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> - -<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> - -<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 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 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></a> 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 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> - - -<hr> - -<h2><a 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> - +<!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> + + <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> + + <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> + <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> # # The following directives modify normal HTTP response behavior. @@ -285,13 +300,12 @@ 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> + <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 @@ -299,14 +313,13 @@ coming from particular hosts.</p> CustomLog logs/access_log 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> + <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 @@ -318,11 +331,11 @@ called /web/images.</p> </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">Keeping -Your Images from Adorning Other Sites</a>".</p> + <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> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> |