| <!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>Many operating systems provide a facility for storage and |
| transmission of information called environment variables. Apache uses |
| environment variables in many ways to control operations and to |
| communicate with other programs like CGI scripts. This document |
| explains some of the ways to use environment variables in Apache.</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="misc/FAQ.html#cgi-spec">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_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_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>server-parsed</code> handler 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>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> |
| |
| <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> |
| |
| <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 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">Keeping |
| Your Images from Adorning Other Sites</a>".</p> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |