env.html.en revision 17bc0e8f2e3816e25bc8fd3fadf39357340aebd0
6de8046f8f7e07cd83895a528df25d977e502c76nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
7e79e8fd53348f9fc6e8009a4a2522425ab6f08ffielding "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <meta name="generator" content="HTML Tidy, see www.w3.org" />
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <!--#include virtual="header.html" -->
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <h1 align="center">Environment Variables in Apache</h1>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <p>The Apache HTTP Server provides a mechanism for storing
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding information in named variables that are called <em>environment
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh variables</em>. This information can be used to control various
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding operations such as logging or access control. The variables are
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding also used as a mechanism to communicate with external programs
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein such as CGI scripts. This document discusses different ways to
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein manipulate and use these variables.</p>
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein <p>Although these variables are referred to as <em>environment
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein variables</em>, they are not the same as the environment
1b21d7b3d97def358b2e923655edeb16613a1c31gstein variables controlled by the underlying operating system.
be3223a6a18d9a3a3cf7155d5430a5d92bcddceegstein Instead, these variables are stored and manipulated in an
1b21d7b3d97def358b2e923655edeb16613a1c31gstein internal Apache structure. They only become actual operating
1b21d7b3d97def358b2e923655edeb16613a1c31gstein system environment variables when they are provided to CGI
1b21d7b3d97def358b2e923655edeb16613a1c31gstein scripts and Server Side Include scripts. If you wish to
1b21d7b3d97def358b2e923655edeb16613a1c31gstein manipulate the operating system environment under which the
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein server itself runs, you must use the standard environment
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein manipulation mechanisms provided by your operating system
1b21d7b3d97def358b2e923655edeb16613a1c31gstein <li><a href="#setting">Setting Environment Variables</a></li>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li><a href="#using">Using Environment Variables</a></li>
cf8fe49d9d89cfa4b62cb2b1376ca6f25b81b362trawick <h2><a id="setting" name="setting">Setting Environment
8a3228198adb03e6996f7738c361a612777ecab6aaron <td valign="top"><strong>Related Modules</strong><br />
a7318397b355119d990d1f311b951dea2aafc53arbb <a href="mod/mod_unique_id.html">mod_unique_id</a><br />
cb9e6e5c78f5a1690214e9548250fc6af1fc73b5wrowe <td valign="top"><strong>Related Directives</strong><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</a><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <a href="mod/mod_env.html#passenv">PassEnv</a><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</a><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</a><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <a href="mod/mod_env.html#unsetenv">UnsetEnv</a><br />
8a3228198adb03e6996f7738c361a612777ecab6aaron <p>The most basic way to set an environment variable in Apache
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding is using the unconditional <code>SetEnv</code> directive.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Variables may also be passed from the environment of the shell
8a3228198adb03e6996f7738c361a612777ecab6aaron which started the server using the <code>PassEnv</code>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding directive.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>For additional flexibility, the directives provided by
8a3228198adb03e6996f7738c361a612777ecab6aaron mod_setenvif allow environment variables to be set on a
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding per-request basis, conditional on characteristics of particular
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding requests. For example, a variable could be set only when a
8a3228198adb03e6996f7738c361a612777ecab6aaron specific browser (User-Agent) is making a request, or only when
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding a specific Referer [sic] header is found. Even more flexibility
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding is available through the mod_rewrite's <code>RewriteRule</code>
8a3228198adb03e6996f7738c361a612777ecab6aaron which uses the <code>[E=...]</code> option to set environment
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding variables.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>Finally, mod_unique_id sets the environment variable
8a3228198adb03e6996f7738c361a612777ecab6aaron <code>UNIQUE_ID</code> for each request to a value which is
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding guaranteed to be unique across "all" requests under very
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding specific conditions.</p>
8a3228198adb03e6996f7738c361a612777ecab6aaron <p>In addition to all environment variables set within the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Apache configuration and passed from the shell, CGI scripts and
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding SSI pages are provided with a set of environment variables
8a3228198adb03e6996f7738c361a612777ecab6aaron containing meta-information about the request as required by
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li>It is not possible to override or change the standard CGI
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding variables using the environment manipulation directives.</li>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li>When <a href="suexec.html">suexec</a> is used to launch
8a3228198adb03e6996f7738c361a612777ecab6aaron CGI scripts, the environment will be cleaned down to a set of
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <em>safe</em> variables before CGI scripts are launched. The
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding list of <em>safe</em> variables is defined at compile-time in
8a3228198adb03e6996f7738c361a612777ecab6aaron <li>For portability reasons, the names of environment
8a3228198adb03e6996f7738c361a612777ecab6aaron variables may contain only letters, numbers, and the
8a3228198adb03e6996f7738c361a612777ecab6aaron underscore character. In addition, the first character may
8a3228198adb03e6996f7738c361a612777ecab6aaron not be a number. Characters which do not match this
8a3228198adb03e6996f7738c361a612777ecab6aaron restriction will be replaced by an underscore when passed to
8a3228198adb03e6996f7738c361a612777ecab6aaron CGI scripts and SSI pages.</li>
18b197c6ba1d5b8bb5b2fb372ef752f87e56912atrawick <td valign="top"><strong>Related Modules</strong><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe <a href="mod/mod_log_config.html">mod_log_config</a><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe <td valign="top"><strong>Related Directives</strong><br />
85c435ceda98eab940615e4466d9c5955252e745wrowe href="mod/mod_log_config.html#customlog">CustomLog</a><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe <a href="mod/mod_headers.html#Header">Header</a><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe href="mod/mod_log_config.html#logformat">LogFormat</a><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe href="mod/mod_rewrite.html#RewriteCond">RewriteCond</a><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br />
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe <p>One of the primary uses of environment variables is to
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe communicate information to CGI scripts. As discussed above, the
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe environment passed to CGI scripts includes standard
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe meta-information about the request in addition to any variables
b3edf21d591bfd0e64bbec0dda73c0e41d7ecdb6wrowe set within the Apache configuration. For more details, see the
76185d819b745e953dd2cd636fbdd515c333e4a4trawick <p>Server-parsed (SSI) documents processed by mod_include's
76185d819b745e953dd2cd636fbdd515c333e4a4trawick <code>INCLUDES</code> filter can print environment variables
76185d819b745e953dd2cd636fbdd515c333e4a4trawick using the <code>echo</code> element, and can use environment
76185d819b745e953dd2cd636fbdd515c333e4a4trawick variables in flow control elements to makes parts of a page
76185d819b745e953dd2cd636fbdd515c333e4a4trawick conditional on characteristics of a request. Apache also
76185d819b745e953dd2cd636fbdd515c333e4a4trawick provides SSI pages with the standard CGI environment variables
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm as discussed above. For more details, see the <a
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>Access to the server can be controlled based on the value of
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding environment variables using the <code>allow from env=</code>
f5fccb8eae1f1a5f212a5bda878479c281f36512trawick and <code>deny from env=</code> directives. In combination with
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm <code>SetEnvIf</code>, this allows for flexible control of
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm access to the server based on characteristics of the client.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding For example, you can use these directives to deny access to a
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh particular browser (User-Agent).</p>
76185d819b745e953dd2cd636fbdd515c333e4a4trawick <p>Environment variables can be logged in the access log using
76185d819b745e953dd2cd636fbdd515c333e4a4trawick the <code>LogFormat</code> option <code>%e</code>. In addition,
76185d819b745e953dd2cd636fbdd515c333e4a4trawick the decision on whether or not to log requests can be made
fa4e5ac791dd1c84df616b28d4ee9751efe9c64frbb based on the status of environment variables using the
fa4e5ac791dd1c84df616b28d4ee9751efe9c64frbb conditional form of the <code>CustomLog</code> directive. In
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh combination with <code>SetEnvIf</code> this allows for flexible
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm control of which requests are logged. For example, you can
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm choose not to log requests for filenames ending in
8a3228198adb03e6996f7738c361a612777ecab6aaron <code>gif</code>, or you can choose to only log requests from
066877f1a045103acfdd376d48cdd473c33f409bdougm clients which are outside your subnet.</p>
d521bfef0e1a65993d5e302628ac68a2c91a195ftrawick <p>The <code>Header</code> directive can use the presence or
20c85ca0d404e29972fb94c3d6236a264d1c77abstoddard absence of an environment variable to determine whether or not
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb a certain HTTP header will be placed in the response to the
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb client. This allows, for example, a certain response header to
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb be sent only if a corresponding header is received in the
8a3228198adb03e6996f7738c361a612777ecab6aaron request from the client.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in
061c3874622b67beff724876b9bd1b1f291f2eaafielding the <code>RewriteCond</code> allows mod_rewrite's rewrite
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb engine to make decisions conditional on environment variables.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Note that the variables accessible in mod_rewrite without the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <code>ENV:</code> prefix are not actually environment
8a3228198adb03e6996f7738c361a612777ecab6aaron variables. Rather, they are variables special to mod_rewrite
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb which cannot be accessed from other modules.</p>
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb <h2><a id="special" name="special">Special Purpose Environment
85c435ceda98eab940615e4466d9c5955252e745wrowe <p>Interoperability problems have led to the introduction of
8a3228198adb03e6996f7738c361a612777ecab6aaron mechanisms to modify the way Apache behaves when talking to
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding particular clients. To make these mechanisms as flexible as
2cfdca5be0c69f65b43a888d6d3da846489b8fa5rbb possible, they are invoked by defining environment variables,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding typically with <a
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_setenvif.html#browsermatch">BrowserMatch</a>,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding though <a href="mod/mod_env.html#setenv">SetEnv</a> and <a
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding href="mod/mod_env.html#passenv">PassEnv</a> could also be used,
8a3228198adb03e6996f7738c361a612777ecab6aaron for example.</p>
8a3228198adb03e6996f7738c361a612777ecab6aaron <p>This forces the request to be treated as a HTTP/1.0 request
8a3228198adb03e6996f7738c361a612777ecab6aaron even if it was in a later dialect.</p>
85c435ceda98eab940615e4466d9c5955252e745wrowe <p>This causes any <code>Vary</code> fields to be removed from
8a3228198adb03e6996f7738c361a612777ecab6aaron the response header before it is sent back to the client. Some
8a3228198adb03e6996f7738c361a612777ecab6aaron clients don't interpret this field correctly (see the <a
8a3228198adb03e6996f7738c361a612777ecab6aaron href="misc/known_client_problems.html">known client
8a3228198adb03e6996f7738c361a612777ecab6aaron problems</a> page); setting this variable can work around this
8a3228198adb03e6996f7738c361a612777ecab6aaron problem. Setting this variable also implies
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>This forces an HTTP/1.0 response when set. It was originally
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding implemented as a result of a problem with AOL's proxies. Some
8a3228198adb03e6996f7738c361a612777ecab6aaron clients may not behave correctly when given an HTTP/1.1
32c4bc04f89b16521718145dc731f750144d7b38wrowe response, and this can be used to interoperate with them.</p>
32c4bc04f89b16521718145dc731f750144d7b38wrowe href="mod/core.html#keepalive">KeepAlive</a> when set.</p>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <p>This forces the server to be more careful when sending a redirect
2b484455736f4c30447aa852764f53282cbeb5ddrbb to the client. This is typically used when a client has a known
c25e9633c29be3a5b74f0bf75079d54e5417115dwrowe problem handling redirects. This was originally implemented as a
85c435ceda98eab940615e4466d9c5955252e745wrowe result of a problem with Microsoft's WebFolders software which has
8a3228198adb03e6996f7738c361a612777ecab6aaron a problem handling redirects on directory resources via DAV
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding methods.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <h2><a id="examples" name="examples">Examples</a></h2>
85c435ceda98eab940615e4466d9c5955252e745wrowe <h3>Changing protocol behavior with misbehaving clients</h3>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>We recommend that the following lines be included in
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm# The following directives modify normal HTTP response behavior.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# The first directive disables keepalive for Netscape 2.x and browsers that
85c435ceda98eab940615e4466d9c5955252e745wrowe# spoof it. There are known problems with these browser implementations.
85c435ceda98eab940615e4466d9c5955252e745wrowe# The second directive is for Microsoft Internet Explorer 4.0b2
85c435ceda98eab940615e4466d9c5955252e745wrowe# which has a broken HTTP/1.1 implementation and does not properly
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# support keepalive when it is used on 301 or 302 (redirect) responses.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingBrowserMatch "Mozilla/2" nokeepalive
c57161db43fe4cf5a62758d7d0834675e59cad0astoddardBrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
0f57a69cc84c59eacda1179763ae42ca88f1a577wrowe# The following directive disables HTTP/1.1 responses to browsers which
0f57a69cc84c59eacda1179763ae42ca88f1a577wrowe# are in violation of the HTTP/1.0 spec by not being able to grok a
8a3228198adb03e6996f7738c361a612777ecab6aaron# basic 1.1 response.
ec727afb817df0e5202135278c0d2902923cc980stoddardBrowserMatch "RealPlayer 4\.0" force-response-1.0
2261031aa94be82d7e6b1b8c367afc1b282317f5ianhBrowserMatch "Java/1\.0" force-response-1.0
2261031aa94be82d7e6b1b8c367afc1b282317f5ianhBrowserMatch "JDK/1\.0" force-response-1.0
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <h3>Do not log requests for images in the access log</h3>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>This example keeps requests for images from appearing in the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding access log. It can be easily modified to prevent logging of
0f57a69cc84c59eacda1179763ae42ca88f1a577wrowe particular directories, or to prevent logging of requests
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding coming from particular hosts.</p>
8a3228198adb03e6996f7738c361a612777ecab6aaron SetEnvIf Request_URI \.gif image-request
8a3228198adb03e6996f7738c361a612777ecab6aaron SetEnvIf Request_URI \.jpg image-request
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding SetEnvIf Request_URI \.png image-request
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <p>This example shows how to keep people not on your server
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh from using images on your server as inline-images on their
8a3228198adb03e6996f7738c361a612777ecab6aaron pages. This is not a recommended configuration, but it can work
8a3228198adb03e6996f7738c361a612777ecab6aaron in limited circumstances. We assume that all your images are in
85c435ceda98eab940615e4466d9c5955252e745wrowe SetEnvIf Referer "^http://www.example.com/" local_referal
85c435ceda98eab940615e4466d9c5955252e745wrowe # Allow browsers that do not send Referer info
85c435ceda98eab940615e4466d9c5955252e745wrowe SetEnvIf Referer "^$" local_referal
8a3228198adb03e6996f7738c361a612777ecab6aaron Order Deny,Allow
8a3228198adb03e6996f7738c361a612777ecab6aaron Deny from all
8a3228198adb03e6996f7738c361a612777ecab6aaron Allow from env=local_referal
8a3228198adb03e6996f7738c361a612777ecab6aaron </Directory>
8a3228198adb03e6996f7738c361a612777ecab6aaron <p>For more information about this technique, see the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding ApacheToday tutorial " <a
85c435ceda98eab940615e4466d9c5955252e745wrowe href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Keeping Your Images from Adorning Other Sites</a>".</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <!--#include virtual="footer.html" -->