env.html revision c8f9b27f3551ad0a3520a0f6246940bf7255828d
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj BGCOLOR="#FFFFFF"
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj TEXT="#000000"
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj LINK="#0000FF"
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj VLINK="#000080"
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj ALINK="#FF0000"
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<!--#include virtual="header.html" -->
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<h1 align="center">Environment Variables in Apache</h1>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>Many operating systems provide a facility for storage and
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjtransmission of information called environment variables. Apache uses
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjenvironment variables in many ways to control operations and to
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjcommunicate with other programs like CGI scripts. This document
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjexplains some of the ways to use environment variables in Apache.</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<li><a href="#setting">Setting Environment Variables</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<li><a href="#using">Using Environment Variables</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<li><a href="#special">Special Purpose Environment Variables</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<h2><a name="setting">Setting Environment Variables</a></h2>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<a href="mod/mod_setenvif.html">mod_setenvif</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<a href="mod/mod_unique_id.html">mod_unique_id</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>The most basic way to set an environment variable in Apache is
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjusing the unconditional <code>SetEnv</code> directive. Variables
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjmay also be passed from the environment when Apache is started
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>The directives provided by mod_setenvif allow environment variables
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjto be set on a per-request basis based on characteristics of particular
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjrequests. For example, a variable could be set only when a specific
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjbrowser (User-Agent) is making a request, or only when a specific
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjReferer header is found. Even more flexibility is available through the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjmod_rewrite's <code>RewriteRule</code> which uses the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>[E=...]</code> option to set environment variables.</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>Finally, mod_unique_id sets the environment variable
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>UNIQUE_ID</code> for each request to a value which is guaranteed
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjto be unique across "all" requests under very specific conditions.</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<h2><a name="using">Using Environment Variables</a></h2>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<a href="mod/mod_log_config.html">mod_log_config</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<a href="mod/mod_log_config.html#customlog-conditional">CustomLog
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>One of the primary uses of environment variables is to communicate
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjinformation to CGI scripts. In addition to all environment variables
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjset within Apache, CGI scripts are provided with a set of
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjmeta-information about the request as provided for in the <a
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjhref="misc/FAQ.html#cgi-spec">CGI specification</a>. If you are using
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<a href="suexec.html">Suexec</a> to execute CGI scripts under
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjdifferent userids, note that the environment will be cleaned down to a
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjset of <em>safe</em> environment variables before the CGI script is
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjexecuted. The set of safe environment variables is defined at
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>Server-parsed (SSI) documents processed by mod_include's
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>server-parsed</code> handler can print environment variables
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjusing the <code>echo</code> element, and can use environment variables
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjin flow control elements.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>Access to the server can be controlled based on the value of
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjenvironment variables using the <code>allow from env=</code> and
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>deny from env=</code></a> directives. In combination with
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>SetEnvIf</code>, this allows for flexible control of access to
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjthe server based on characteristics of the client. For example, you
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjcan use these directives to deny access to a particular browser
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj(User-Agent).
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>Environment variables can be logged in the access log using the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>LogFormat</code> option <code>%e</code>. In addition, the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjdecision on whether or not to log requests can be made based on the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjstatus of environment variables using the conditional form of the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>CustomLog</code> directive. In combination with
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>SetEnvIf</code> this allows for flexible control of which
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjrequests are logged. For example, you can choose not to log requests
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjfor filenames ending in <code>gif</code>, or you can choose to only
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjlog requests from clients which are outside your subnet.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjdecisions conditional on environment variables. Note that the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjvariables accessible in mod_rewrite without the <code>ENV:</code>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjprefix are not actually environment variables. Rather, they
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjare variables special to mod_rewrite which cannot be accessed from
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjother modules.</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<H2><a name="special">Special Purpose Environment Variables</a></H2>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjInteroperability problems have led to the introduction of
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjmechanisms to modify the way Apache behaves when talking to particular
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjclients. To make these mechanisms as flexible as possible, they
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjare invoked by defining environment variables, typically with
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjThis forces the request to be treated as a HTTP/1.0 request even if it
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjwas in a later dialect.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjThis causes any <CODE>Vary</CODE> fields to be removed from the response
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjheader before it is sent back to the client. Some clients don't
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjinterpret this field correctly (see the
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<A HREF="misc/known_client_problems.html">known client problems</A>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjpage); setting this variable can work around this problem. Setting
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjthis variable also implies <STRONG>force-response-1.0</STRONG>.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjThis forces an HTTP/1.0 response when set. It was originally implemented as a
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjresult of a problem with AOL's proxies. Some clients may not behave correctly
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjwhen given an HTTP/1.1 response, and this can be used to interoperate with
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjThis disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<h3>Changing protocol behavior with misbehaving clients</h3>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>We recommend that the following lines be included in httpd.conf
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjto deal with known client problems.</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# The following directives modify normal HTTP response behavior.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# The first directive disables keepalive for Netscape 2.x and browsers that
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# spoof it. There are known problems with these browser implementations.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# The second directive is for Microsoft Internet Explorer 4.0b2
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# which has a broken HTTP/1.1 implementation and does not properly
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# support keepalive when it is used on 301 or 302 (redirect) responses.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjBrowserMatch "Mozilla/2" nokeepalive
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjBrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# The following directive disables HTTP/1.1 responses to browsers which
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# are in violation of the HTTP/1.0 spec by not being able to grok a
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj# basic 1.1 response.
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjBrowserMatch "RealPlayer 4\.0" force-response-1.0
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjBrowserMatch "Java/1\.0" force-response-1.0
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjBrowserMatch "JDK/1\.0" force-response-1.0
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<h3>Do not log requests for images in the access log</h3>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>This example keeps requests for images from appearing
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjin the access log. It can be easily modified to prevent logging
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjof particular directories, or to prevent logging of requests
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjcoming from particular hosts.</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj SetEnvIf Request_URI \.gif image-request
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj SetEnvIf Request_URI \.jpg image-request
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj SetEnvIf Request_URI \.png image-request
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>This example shows how to keep people not on your server from using
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjimages on your server as inline-images on their pages. This is not
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonja recommended configuration, but it can work in limited
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjcircumstances. We assume that all your images are in a directory
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj SetEnvIf Referer "^http://www.example.com/" local_referal
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj # Allow browsers that do not send Referer info
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj SetEnvIf Referer "^$" local_referal
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj Order Deny,Allow
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj Deny from all
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj Allow from env=local_referal
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj </Directory>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<p>For more information about this technique, see the ApacheToday
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjtutorial "<a
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjhref="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">Keeping
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonjYour Images from Adorning Other Sites</a>".</p>
d04ccbb3f3163ae5962a8b7465d9796bff6ca434carlsonj<!--#include virtual="footer.html" -->