docs/manual/env.html

	env.html revision c8f9b27f3551ad0a3520a0f6246940bf7255828d
55cf6e01272ec475edea32aa9b7923de2d36cb42Christian Maeder<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<HTML>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<HEAD>
b43458b4d81f7451112cecbd757f3a05216e7088Kristina Sojakova<TITLE>Environment Variables in Apache</TITLE>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova</HEAD>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova
98890889ffb2e8f6f722b00e265a211f13b5a861Corneliu-Claudiu Prodescu<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<BODY
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova BGCOLOR="#FFFFFF"
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova TEXT="#000000"
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova LINK="#0000FF"
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova VLINK="#000080"
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova ALINK="#FF0000"
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<!--#include virtual="header.html" -->
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<h1 align="center">Environment Variables in Apache</h1>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
b2e01ef1b5d4c7a62260eb792291e8e1b10e545bIulia Ignatov<p>Many operating systems provide a facility for storage and
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakovatransmission of information called environment variables.  Apache uses
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakovaenvironment variables in many ways to control operations and to
9f85afecbd79b3df5a0bb17bd28cd0b288dc3213Kristina Sojakovacommunicate with other programs like CGI scripts.  This document
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovaexplains some of the ways to use environment variables in Apache.</p>
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakova
b2e01ef1b5d4c7a62260eb792291e8e1b10e545bIulia Ignatov<ul>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<li><a href="#setting">Setting Environment Variables</a><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<li><a href="#using">Using Environment Variables</a><br>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<li><a href="#special">Special Purpose Environment Variables</a><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<li><a href="#examples">Examples</a><br>
d71bb9deea089887b4fd829c5b766e7e4de9f204Kristina Sojakova</ul>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<hr>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<h2><a name="setting">Setting Environment Variables</a></h2>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<table border="1">
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<tr><td valign="top">
b43458b4d81f7451112cecbd757f3a05216e7088Kristina Sojakova<strong>Related Modules</strong><br><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<a href="mod/mod_env.html">mod_env</a><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<a href="mod/mod_rewrite.html">mod_rewrite</a><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<a href="mod/mod_setenvif.html">mod_setenvif</a><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<a href="mod/mod_unique_id.html">mod_unique_id</a><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova</td><td valign="top">
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<strong>Related Directives</strong><br><br>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<A HREF="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</A><br>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<A HREF="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A><br>
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<A HREF="mod/mod_env.html#passenv">PassEnv</A><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<A HREF="mod/mod_env.html#setenv">SetEnv</A><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<A HREF="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</A><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<A HREF="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova</td></tr></table>
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<p>The most basic way to set an environment variable in Apache is
b43458b4d81f7451112cecbd757f3a05216e7088Kristina Sojakovausing the unconditional <code>SetEnv</code> directive.  Variables
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovamay also be passed from the environment when Apache is started
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovausing the <code>PassEnv</code> directive.</p>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<p>The directives provided by mod_setenvif allow environment variables
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovato be set on a per-request basis based on characteristics of particular
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovarequests.  For example, a variable could be set only when a specific
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovabrowser (User-Agent) is making a request, or only when a specific
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina SojakovaReferer header is found.  Even more flexibility is available through the
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovamod_rewrite's <code>RewriteRule</code> which uses the
abd5fc85dc7e19b1614890182436940e922963a4Kristina Sojakova<code>[E=...]</code> option to set environment variables.</p>
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakova
14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova<p>Finally, mod_unique_id sets the environment variable
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<code>UNIQUE_ID</code> for each request to a value which is guaranteed
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakovato be unique across "all" requests under very specific conditions.</p>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<hr>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<h2><a name="using">Using Environment Variables</a></h2>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova<table border=1><tr><td valign="top">
abd5fc85dc7e19b1614890182436940e922963a4Kristina Sojakova<strong>Related Modules</strong><br><br>
ccaa75089b23c0f043cdbd4001cba4e076ca4fd3Kristina Sojakova
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder<a href="mod/mod_access.html">mod_access</a><br>
80d2ec8f37d5ddec13c14b17b1bab01e9c94630aChristian Maeder<a href="mod/mod_cgi.html">mod_cgi</a><br>
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder<a href="mod/mod_include.html">mod_include</a><br>
d71bb9deea089887b4fd829c5b766e7e4de9f204Kristina Sojakova<a href="mod/mod_log_config.html">mod_log_config</a><br>
168d206b4e5fd436c98239a1b6629c651f54c8eeKristina Sojakova<a href="mod/mod_rewrite.html">mod_rewrite</a><br>
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder</td><td valign="top">
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<strong>Related Directives</strong><br><br>
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova
d2786879b4733fd4886a5b654f7c6de1d234f638Kristina Sojakova<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>
abd5fc85dc7e19b1614890182436940e922963a4Kristina Sojakova<a href="mod/mod_log_config.html#customlog-conditional">CustomLog
b3bacd257ffcdd346b70ab690f03b28ad5f33fdcKristina Sojakova(conditional)</a><br>
b3bacd257ffcdd346b70ab690f03b28ad5f33fdcKristina Sojakova<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder<a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
b3bacd257ffcdd346b70ab690f03b28ad5f33fdcKristina Sojakova<A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
b3bacd257ffcdd346b70ab690f03b28ad5f33fdcKristina Sojakova<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder
b3bacd257ffcdd346b70ab690f03b28ad5f33fdcKristina Sojakova</td></tr></table>
d71bb9deea089887b4fd829c5b766e7e4de9f204Kristina Sojakova
abd5fc85dc7e19b1614890182436940e922963a4Kristina Sojakova<p>One of the primary uses of environment variables is to communicate
168d206b4e5fd436c98239a1b6629c651f54c8eeKristina Sojakovainformation to CGI scripts.  In addition to all environment variables
80d2ec8f37d5ddec13c14b17b1bab01e9c94630aChristian Maederset within Apache, CGI scripts are provided with a set of
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovameta-information about the request as provided for in the <a
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovahref="misc/FAQ.html#cgi-spec">CGI specification</a>.  If you are using
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakova<a href="suexec.html">Suexec</a> to execute CGI scripts under
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovadifferent userids, note that the environment will be cleaned down to a
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovaset of <em>safe</em> environment variables before the CGI script is
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovaexecuted.  The set of safe environment variables is defined at
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovacompile time in <code>suexec.c</code>.
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakova</p>
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakova
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakova<p>Server-parsed (SSI) documents processed by mod_include's
abd5fc85dc7e19b1614890182436940e922963a4Kristina Sojakova<code>server-parsed</code> handler can print environment variables
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovausing the <code>echo</code> element, and can use environment variables
e8dd447a2aa5fbac10668749dfe4142c05ec3d7dKristina Sojakovain flow control elements.
5e35940c3516ccea02caa0450d2b075de0106fa5Kristina Sojakova</p>
5e35940c3516ccea02caa0450d2b075de0106fa5Kristina Sojakova
5e35940c3516ccea02caa0450d2b075de0106fa5Kristina Sojakova<p>Access to the server can be controlled based on the value of
2cb6df4f21c52732336579a79f7e5d28299b3500Iulia Ignatovenvironment variables using the <code>allow from env=</code> and
2cb6df4f21c52732336579a79f7e5d28299b3500Iulia Ignatov<code>deny from env=</code></a> directives.  In combination with
b2e01ef1b5d4c7a62260eb792291e8e1b10e545bIulia Ignatov<code>SetEnvIf</code>, this allows for flexible control of access to
b2e01ef1b5d4c7a62260eb792291e8e1b10e545bIulia Ignatovthe server based on characteristics of the client.  For example, you
can use these directives to deny access to a particular browser
(User-Agent).
</p>

<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>

<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_browser.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 &quot;Image Theft&quot;</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
    &lt;Directory /web/images&gt;
       Order Deny,Allow
       Deny from all
       Allow from env=local_referal
    &lt;/Directory&gt;
</pre>

<p>For more information about this technique, see the ApacheToday
tutorial &quot;<a
href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">Keeping
Your Images from Adorning Other Sites</a>&quot;.</p>

<!--#include virtual="footer.html" -->
</BODY>
</HTML>