env.html.en revision 0c3dc632b26c26dfcf43200fb58e7eaf61dd5245
71da3cca78eea6010f89b139ecadb79e6d213c4fnd<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
71da3cca78eea6010f89b139ecadb79e6d213c4fnd BGCOLOR="#FFFFFF"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd TEXT="#000000"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd LINK="#0000FF"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd VLINK="#000080"
71da3cca78eea6010f89b139ecadb79e6d213c4fnd ALINK="#FF0000"
f4c310fd2555c6faca1f980f00b161eadb089023gstein<!--#include virtual="header.html" -->
f4c310fd2555c6faca1f980f00b161eadb089023gstein<h1 align="center">Environment Variables in Apache</h1>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>Many operating systems provide a facility for storage and
f4c310fd2555c6faca1f980f00b161eadb089023gsteintransmission of information called environment variables. Apache uses
f4c310fd2555c6faca1f980f00b161eadb089023gsteinenvironment variables in many ways to control operations and to
1b21d7b3d97def358b2e923655edeb16613a1c31gsteincommunicate with other programs like CGI scripts. This document
952023a04a2f9d51553babd9094fb857f1c97548trawickexplains some of the ways to use environment variables in Apache.</p>
1b21d7b3d97def358b2e923655edeb16613a1c31gstein<li><a href="#setting">Setting Environment Variables</a></li>
1b21d7b3d97def358b2e923655edeb16613a1c31gstein<li><a href="#using">Using Environment Variables</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="#special">Special Purpose Environment Variables</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<h2><a name="setting">Setting Environment Variables</a></h2>
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm<li><a href="mod/mod_rewrite.html">mod_rewrite</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="mod/mod_setenvif.html">mod_setenvif</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="mod/mod_unique_id.html">mod_unique_id</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><A HREF="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><A HREF="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><A HREF="mod/mod_env.html#passenv">PassEnv</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A></li>
5b03ba47ff7225cacb131f14b019332af27da960gstein<li><A HREF="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</A></li>
5b03ba47ff7225cacb131f14b019332af27da960gstein<li><A HREF="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A></li>
5b03ba47ff7225cacb131f14b019332af27da960gstein<li><A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A></li>
5b03ba47ff7225cacb131f14b019332af27da960gstein<p>The most basic way to set an environment variable in Apache is
5b03ba47ff7225cacb131f14b019332af27da960gsteinusing the unconditional <code>SetEnv</code> directive. Variables
5b03ba47ff7225cacb131f14b019332af27da960gsteinmay also be passed from the environment when Apache is started
5b03ba47ff7225cacb131f14b019332af27da960gstein<p>The directives provided by mod_setenvif allow environment variables
5b03ba47ff7225cacb131f14b019332af27da960gsteinto be set on a per-request basis based on characteristics of particular
5b03ba47ff7225cacb131f14b019332af27da960gsteinrequests. For example, a variable could be set only when a specific
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowebrowser (User-Agent) is making a request, or only when a specific
98e9c4a310bb623ff788680f88b6bd200ff36a24wroweReferer header is found. Even more flexibility is available through the
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>[E=...]</code> option to set environment variables.</p>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>Finally, mod_unique_id sets the environment variable
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>UNIQUE_ID</code> for each request to a value which is guaranteed
f4c310fd2555c6faca1f980f00b161eadb089023gsteinto be unique across "all" requests under very specific conditions.</p>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<h2><a name="using">Using Environment Variables</a></h2>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="mod/mod_include.html">mod_include</a></li>
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe<li><a href="mod/mod_log_config.html">mod_log_config</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="mod/mod_rewrite.html">mod_rewrite</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<LI><A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="mod/mod_log_config.html#customlog-conditional">CustomLog
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowe<LI><A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<li><a href="mod/mod_log_config.html#logformat">LogFormat</a></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<LI><A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<LI><A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A></li>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>One of the primary uses of environment variables is to communicate
f4c310fd2555c6faca1f980f00b161eadb089023gsteininformation to CGI scripts. In addition to all environment variables
6f15570e3adc0faf87bf55f70857028276fc9e32wroweset within Apache, CGI scripts are provided with a set of
6f15570e3adc0faf87bf55f70857028276fc9e32wrowemeta-information about the request as provided for in the <a
6f15570e3adc0faf87bf55f70857028276fc9e32wrowehref="misc/FAQ.html#cgi-spec">CGI specification</a>. If you are using
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe<a href="suexec.html">Suexec</a> to execute CGI scripts under
f4c310fd2555c6faca1f980f00b161eadb089023gsteindifferent userids, note that the environment will be cleaned down to a
6f15570e3adc0faf87bf55f70857028276fc9e32wroweset of <em>safe</em> environment variables before the CGI script is
f4c310fd2555c6faca1f980f00b161eadb089023gsteinexecuted. The set of safe environment variables is defined at
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>Server-parsed (SSI) documents processed by mod_include's
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>server-parsed</code> handler can print environment variables
98e9c4a310bb623ff788680f88b6bd200ff36a24wroweusing the <code>echo</code> element, and can use environment variables
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowein flow control elements.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>Access to the server can be controlled based on the value of
f4c310fd2555c6faca1f980f00b161eadb089023gsteinenvironment variables using the <code>allow from env=</code> and
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>deny from env=</code></a> directives. In combination with
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>SetEnvIf</code>, this allows for flexible control of access to
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowethe server based on characteristics of the client. For example, you
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowecan use these directives to deny access to a particular browser
f4c310fd2555c6faca1f980f00b161eadb089023gstein(User-Agent).
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>Environment variables can be logged in the access log using the
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>LogFormat</code> option <code>%e</code>. In addition, the
f4c310fd2555c6faca1f980f00b161eadb089023gsteindecision on whether or not to log requests can be made based on the
f4c310fd2555c6faca1f980f00b161eadb089023gsteinstatus of environment variables using the conditional form of the
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>SetEnvIf</code> this allows for flexible control of which
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowerequests are logged. For example, you can choose not to log requests
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowefor filenames ending in <code>gif</code>, or you can choose to only
f4c310fd2555c6faca1f980f00b161eadb089023gsteinlog requests from clients which are outside your subnet.
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
f4c310fd2555c6faca1f980f00b161eadb089023gstein<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
f4c310fd2555c6faca1f980f00b161eadb089023gsteindecisions conditional on environment variables.
98e9c4a310bb623ff788680f88b6bd200ff36a24wrowe<H2><a name="special">Special Purpose Environment Variables</a></H2>
f4c310fd2555c6faca1f980f00b161eadb089023gsteinInteroperability problems have led to the introduction of
f4c310fd2555c6faca1f980f00b161eadb089023gsteinmechanisms to modify the way Apache behaves when talking to particular
f4c310fd2555c6faca1f980f00b161eadb089023gsteinclients. To make these mechanisms as flexible as possible, they
f4c310fd2555c6faca1f980f00b161eadb089023gsteinare invoked by defining environment variables, typically with
f4c310fd2555c6faca1f980f00b161eadb089023gstein<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though
f4c310fd2555c6faca1f980f00b161eadb089023gstein<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for
f4c310fd2555c6faca1f980f00b161eadb089023gsteinThis forces the request to be treated as a HTTP/1.0 request even if it
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwas in a later dialect.
f4c310fd2555c6faca1f980f00b161eadb089023gsteinThis causes any <CODE>Vary</CODE> fields to be removed from the response
91644a5f4d3e992dc208304b50e80bbb236fca89trawickheader before it is sent back to the client. Some clients don't
8b99f2a316c5e2fa6ab208206fdd7fc2bfc4a921dougminterpret this field correctly (see the
f4c310fd2555c6faca1f980f00b161eadb089023gstein<A HREF="misc/known_client_problems.html">known client problems</A>
f4c310fd2555c6faca1f980f00b161eadb089023gsteinpage); setting this variable can work around this problem. Setting
f4c310fd2555c6faca1f980f00b161eadb089023gsteinthis variable also implies <STRONG>force-response-1.0</STRONG>.
6f15570e3adc0faf87bf55f70857028276fc9e32wroweThis forces an HTTP/1.0 response when set. It was originally implemented as a
f4c310fd2555c6faca1f980f00b161eadb089023gsteinresult of a problem with AOL's proxies. Some clients may not behave correctly
f4c310fd2555c6faca1f980f00b161eadb089023gsteinwhen given an HTTP/1.1 response, and this can be used to interoperate with
f4c310fd2555c6faca1f980f00b161eadb089023gsteinThis disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set.
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe<h3>Changing protocol behavior with misbehaving clients</h3>
f4c310fd2555c6faca1f980f00b161eadb089023gstein<p>We recommend that the following lines be included in httpd.conf
48f35e10f195dd594d75738fc536bb885eda537cgsteinto deal with known client problems.</p>
48f35e10f195dd594d75738fc536bb885eda537cgstein# The following directives modify normal HTTP response behavior.
48f35e10f195dd594d75738fc536bb885eda537cgstein# The first directive disables keepalive for Netscape 2.x and browsers that
48f35e10f195dd594d75738fc536bb885eda537cgstein# spoof it. There are known problems with these browser implementations.
48f35e10f195dd594d75738fc536bb885eda537cgstein# The second directive is for Microsoft Internet Explorer 4.0b2
48f35e10f195dd594d75738fc536bb885eda537cgstein# which has a broken HTTP/1.1 implementation and does not properly
48f35e10f195dd594d75738fc536bb885eda537cgstein# support keepalive when it is used on 301 or 302 (redirect) responses.
48f35e10f195dd594d75738fc536bb885eda537cgsteinBrowserMatch "Mozilla/2" nokeepalive
48f35e10f195dd594d75738fc536bb885eda537cgsteinBrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
48f35e10f195dd594d75738fc536bb885eda537cgstein# The following directive disables HTTP/1.1 responses to browsers which
48f35e10f195dd594d75738fc536bb885eda537cgstein# are in violation of the HTTP/1.0 spec by not being able to grok a
24efed0910118b762a4eb84830875d4714b8d315ianh# basic 1.1 response.
48f35e10f195dd594d75738fc536bb885eda537cgsteinBrowserMatch "RealPlayer 4\.0" force-response-1.0
48f35e10f195dd594d75738fc536bb885eda537cgsteinBrowserMatch "Java/1\.0" force-response-1.0
48f35e10f195dd594d75738fc536bb885eda537cgsteinBrowserMatch "JDK/1\.0" force-response-1.0
77c2148c53e0a4a20a80af735caa4e0e6bd448e0gstein<h3>Do not log requests for images in the access log</h3>
77c2148c53e0a4a20a80af735caa4e0e6bd448e0gstein<p>This example keeps requests for images from appearing
77c2148c53e0a4a20a80af735caa4e0e6bd448e0gsteinin the access log. It can be easily modified to prevent logging
48f35e10f195dd594d75738fc536bb885eda537cgsteinof particular directories, or to prevent logging of requests
48f35e10f195dd594d75738fc536bb885eda537cgsteincoming from particular hosts.</p>
48f35e10f195dd594d75738fc536bb885eda537cgstein SetEnvIf Request_URI \.gif image-request
48f35e10f195dd594d75738fc536bb885eda537cgstein SetEnvIf Request_URI \.jpg image-request
48f35e10f195dd594d75738fc536bb885eda537cgstein SetEnvIf Request_URI \.png image-request
48f35e10f195dd594d75738fc536bb885eda537cgstein<p>This example shows how to keep people not on your server from using
f4c310fd2555c6faca1f980f00b161eadb089023gsteinimages on your server as inline-images on their pages. This is not
f4c310fd2555c6faca1f980f00b161eadb089023gsteina recommended configuration, but it can work in limited
f4c310fd2555c6faca1f980f00b161eadb089023gsteincircumstances. We assume that all your images are in a directory
f4c310fd2555c6faca1f980f00b161eadb089023gstein SetEnvIf Referer "^http://www.example.com/" local_referal
f4c310fd2555c6faca1f980f00b161eadb089023gstein # Allow browsers that do not send Referer info
f4c310fd2555c6faca1f980f00b161eadb089023gstein SetEnvIf Referer "^$" local_referal
f4c310fd2555c6faca1f980f00b161eadb089023gstein Order Deny,Allow
f4c310fd2555c6faca1f980f00b161eadb089023gstein Deny from all
f4c310fd2555c6faca1f980f00b161eadb089023gstein Allow from env=local_referal
f4c310fd2555c6faca1f980f00b161eadb089023gstein </Directory>
6f15570e3adc0faf87bf55f70857028276fc9e32wrowe<p>For more information about this technique, see the ApacheToday
6f15570e3adc0faf87bf55f70857028276fc9e32wrowetutorial "<a
f4c310fd2555c6faca1f980f00b161eadb089023gsteinhref="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">Keeping
f4c310fd2555c6faca1f980f00b161eadb089023gstein<!--#include virtual="footer.html" -->