env.html revision cb1cb317c196e6a7bc786b8686e72720ba87fcea
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes BGCOLOR="#FFFFFF"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes TEXT="#000000"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes LINK="#0000FF"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes VLINK="#000080"
0662ed52e814f8f08ef0e09956413a792584eddffuankg ALINK="#FF0000"
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<!--#include virtual="header.html" -->
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<h1 align="center">Environment Variables in Apache</h1>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>The Apache HTTP Server provides a mechanism for storing information
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesin named variables that are called <em>environment variables</em>.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis information can be used to control various operations such as
99e93b940fa004264fbf50595399b5fbfbd91537fuankglogging or access control. The variables are also used as a mechanism
99e93b940fa004264fbf50595399b5fbfbd91537fuankgto communicate with external programs such as CGI scripts. This
99e93b940fa004264fbf50595399b5fbfbd91537fuankgdocument discusses different ways to manipulate and use these
99e93b940fa004264fbf50595399b5fbfbd91537fuankgvariables.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>Although these variables are referred to as <em>environment
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesvariables</em>, they are not the same as the environment variables
bb2b38cd44b032118359afbc743efbea12f48e61bnicholescontrolled by the underlying operating system. Instead, these
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesvariables are stored and manipulated in an internal Apache structure.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThey only become actual operating system environment variables when
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthey are provided to CGI scripts and Server Side Include scripts. If
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesyou wish to manipulate the operating system environment under which
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe server itself runs, you must use the standard environment
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmanipulation mechanisms provided by your operating system shell.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<li><a href="#setting">Setting Environment Variables</a></li>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<li><a href="#using">Using Environment Variables</a></li>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<li><a href="#special">Special Purpose Environment Variables</a></li>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<h2><a name="setting">Setting Environment Variables</a></h2>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<a href="mod/mod_setenvif.html">mod_setenvif</a><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<a href="mod/mod_unique_id.html">mod_unique_id</a><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>The most basic way to set an environment variable in Apache is
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesusing the unconditional <code>SetEnv</code> directive. Variables
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmay also be passed from the environment of the shell which started
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe server using the <code>PassEnv</code> directive.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>For additional flexibility, the directives provided by mod_setenvif
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesallow environment variables to be set on a per-request basis,
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesconditional on characteristics of particular requests. For example, a
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgvariable could be set only when a specific browser (User-Agent) is
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmaking a request, or only when a specific Referer [sic] header is
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesfound. Even more flexibility is available through the mod_rewrite's
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>RewriteRule</code> which uses the <code>[E=...]</code> option to
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesset environment variables.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>Finally, mod_unique_id sets the environment variable
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>UNIQUE_ID</code> for each request to a value which is guaranteed
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesto be unique across "all" requests under very specific conditions.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>In addition to all environment variables set within the Apache
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesconfiguration and passed from the shell, CGI scripts and SSI pages are
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesprovided with a set of environment variables containing
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmeta-information about the request as required by the <a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeshref="misc/FAQ.html#cgi-spec">CGI specification</a>.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<li>It is not possible to override or change the standard CGI
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgvariables using the environment manipulation directives.</li>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<li>When <a href="suexec.html">suexec</a> is used to launch CGI
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesscripts, the environment will be cleaned down to a set of
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<em>safe</em> variables before CGI scripts are launched. The list of
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<em>safe</em> variables is defined at compile-time in
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<li>For portability reasons, the names of environment variables
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmay contain only letters, numbers, and the underscore character.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesIn addition, the first character may not be a number. Characters
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeswhich do not match this restriction will be replaced by an
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgunderscore when passed to CGI scripts and SSI pages.</li>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<h2><a name="using">Using Environment Variables</a></h2>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<a href="mod/mod_log_config.html">mod_log_config</a><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<a href="mod/mod_headers.html#Header">Header</a><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>One of the primary uses of environment variables is to communicate
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesinformation to CGI scripts. As discussed above, the environment
ac7985784d08a3655291f24f711812b4d8b1cbcffuankgpassed to CGI scripts includes standard meta-information about the request
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesin addition to any variables set within the Apache configuration.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesFor more details, see the <a href="howto/cgi.html">CGI tutorial</a>.
3c937b528ca923d5b51e63def9f888af4a77bb40bnicholes<p>Server-parsed (SSI) documents processed by mod_include's
06509499ae5b6676db799057108433170a23ed28fuankg<code>INCLUDES</code> filter can print environment variables
3c937b528ca923d5b51e63def9f888af4a77bb40bnicholesusing the <code>echo</code> element, and can use environment variables
f7d723f1ad88ed006c6caf4c2c6604b7c59dd172bnicholesin flow control elements to makes parts of a page conditional on
3c937b528ca923d5b51e63def9f888af4a77bb40bnicholescharacteristics of a request. Apache also provides SSI pages with the
3c937b528ca923d5b51e63def9f888af4a77bb40bnicholesstandard CGI environment variables as discussed above. For more
1569fefafbfcbc266c7d712eb068e58847c217b7fuankgdetails, see the <a href="howto/ssi.html">SSI tutorial</a>.
ef06a12023b00bdbe0b983192e4afdbdb21139e3fuankg<p>Access to the server can be controlled based on the value of
b4a00883f358625923365ca1560c96edec172a52sfenvironment variables using the <code>allow from env=</code> and
1f145fc8204dbb305cfbfe658a2b9518d5a79b3abnicholes<code>deny from env=</code></a> directives. In combination with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>SetEnvIf</code>, this allows for flexible control of access to
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe server based on characteristics of the client. For example, you
99e93b940fa004264fbf50595399b5fbfbd91537fuankgcan use these directives to deny access to a particular browser
99e93b940fa004264fbf50595399b5fbfbd91537fuankg(User-Agent).
b0827492bc89f04870db952fa9b940e76c975489bnicholes<p>Environment variables can be logged in the access log using the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>LogFormat</code> option <code>%e</code>. In addition, the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesdecision on whether or not to log requests can be made based on the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesstatus of environment variables using the conditional form of the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>CustomLog</code> directive. In combination with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>SetEnvIf</code> this allows for flexible control of which
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesrequests are logged. For example, you can choose not to log requests
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesfor filenames ending in <code>gif</code>, or you can choose to only
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeslog requests from clients which are outside your subnet.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>The <code>Header</code> directive can use the presence or absence
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesof an environment variable to determine whether or not a certain
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesHTTP header will be placed in the response to the client.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis allows, for example, a certain response header to be sent
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesonly if a corresponding header is received in the request from
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthe client.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesdecisions conditional on environment variables. Note that the
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesvariables accessible in mod_rewrite without the <code>ENV:</code>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesprefix are not actually environment variables. Rather, they
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesare variables special to mod_rewrite which cannot be accessed from
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesother modules.</p>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg<H2><a name="special">Special Purpose Environment Variables</a></H2>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesInteroperability problems have led to the introduction of
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesmechanisms to modify the way Apache behaves when talking to particular
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesclients. To make these mechanisms as flexible as possible, they
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesare invoked by defining environment variables, typically with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_setenvif.html#browsermatch">BrowserMatch</A>, though
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis forces the request to be treated as a HTTP/1.0 request even if it
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeswas in a later dialect.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis causes any <CODE>Vary</CODE> fields to be removed from the response
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesheader before it is sent back to the client. Some clients don't
ac7985784d08a3655291f24f711812b4d8b1cbcffuankginterpret this field correctly (see the
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg<A HREF="misc/known_client_problems.html">known client problems</A>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholespage); setting this variable can work around this problem. Setting
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesthis variable also implies <STRONG>force-response-1.0</STRONG>.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis forces an HTTP/1.0 response when set. It was originally implemented as a
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesresult of a problem with AOL's proxies. Some clients may not behave correctly
bb2b38cd44b032118359afbc743efbea12f48e61bnicholeswhen given an HTTP/1.1 response, and this can be used to interoperate with
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesThis disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set.
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<h3>Changing protocol behavior with misbehaving clients</h3>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes<p>We recommend that the following lines be included in httpd.conf
bb2b38cd44b032118359afbc743efbea12f48e61bnicholesto deal with known client problems.</p>
bb2b38cd44b032118359afbc743efbea12f48e61bnicholes# The following directives modify normal HTTP response behavior.
0662ed52e814f8f08ef0e09956413a792584eddffuankg# The first directive disables keepalive for Netscape 2.x and browsers that
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg# spoof it. There are known problems with these browser implementations.
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg# The second directive is for Microsoft Internet Explorer 4.0b2
SetEnvIf Referer "^http://www.example.com/" local_referal
<!--#include virtual="footer.html" -->