env.html revision 17bc0e8f2e3816e25bc8fd3fadf39357340aebd0
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
bd3f5647b96d378d9c75c954e3f13582af32c643sf <meta name="generator" content="HTML Tidy, see www.w3.org" />
9e430d18dde58791589bd699416c8319560dd067jim <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
d03c146b3cdb757b2e7cb85881df1088558293a7covener <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
d03c146b3cdb757b2e7cb85881df1088558293a7covener <!--#include virtual="header.html" -->
28cfe7f444531a5faf01669fac53a0e3280bf902covener <h1 align="center">Environment Variables in Apache</h1>
bf2c5978346829f62a64d3f2106a3cc08782b86csf <p>The Apache HTTP Server provides a mechanism for storing
bf2c5978346829f62a64d3f2106a3cc08782b86csf information in named variables that are called <em>environment
bf2c5978346829f62a64d3f2106a3cc08782b86csf variables</em>. This information can be used to control various
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf operations such as logging or access control. The variables are
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf also used as a mechanism to communicate with external programs
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf such as CGI scripts. This document discusses different ways to
855d6aa9f641cd160ee4265824a3ad3d06231c76covener manipulate and use these variables.</p>
855d6aa9f641cd160ee4265824a3ad3d06231c76covener <p>Although these variables are referred to as <em>environment
855d6aa9f641cd160ee4265824a3ad3d06231c76covener variables</em>, they are not the same as the environment
ca8584db70d0ff4d85cbfd912573688c41be27cfjailletc variables controlled by the underlying operating system.
ca8584db70d0ff4d85cbfd912573688c41be27cfjailletc Instead, these variables are stored and manipulated in an
ca8584db70d0ff4d85cbfd912573688c41be27cfjailletc internal Apache structure. They only become actual operating
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf system environment variables when they are provided to CGI
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf scripts and Server Side Include scripts. If you wish to
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf manipulate the operating system environment under which the
7f40ab64e74b7d1057b5ee6abc349e32e74b1b4cjim server itself runs, you must use the standard environment
7f40ab64e74b7d1057b5ee6abc349e32e74b1b4cjim manipulation mechanisms provided by your operating system
7f40ab64e74b7d1057b5ee6abc349e32e74b1b4cjim shell.</p>
f6b9c755a0b793e8a3a3aebd327ca20a86478117sf <li><a href="#setting">Setting Environment Variables</a></li>
132ee6ac1c26d6e8953836316ba50734eefab47bsf <li><a href="#using">Using Environment Variables</a></li>
4f517d09c93a552f177f49ff97e93aa44eb127ebcovener <h2><a id="setting" name="setting">Setting Environment
cc45ee60ddfb8380b3703455098475eb72625ca8jim <a href="mod/mod_unique_id.html">mod_unique_id</a><br />
46e5dfe0899face9346d6711e4f2ba873d526991sf <td valign="top"><strong>Related Directives</strong><br />
aee831691bb9ecd96dea63d35bc8bdd21c0f0b1fsf href="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</a><br />
aee831691bb9ecd96dea63d35bc8bdd21c0f0b1fsf href="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br />
79ccc75d7de4e14e5add1fa73aaabda0f5d33fe6trawick <a href="mod/mod_env.html#passenv">PassEnv</a><br />
79ccc75d7de4e14e5add1fa73aaabda0f5d33fe6trawick href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br />
fc1459657a1fde206a847f9028930725d715f8b4trawick href="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</a><br />
e758971371df73b097609b2fd62bc14ad935e096trawick href="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</a><br />
e758971371df73b097609b2fd62bc14ad935e096trawick <a href="mod/mod_env.html#unsetenv">UnsetEnv</a><br />
e39eb98e3ad3fbf5c34b2fa1d16861f95143e22esf <p>The most basic way to set an environment variable in Apache
d6fc66efa723db8b3ee5e9fd32579bed884e4e58sf is using the unconditional <code>SetEnv</code> directive.
d6fc66efa723db8b3ee5e9fd32579bed884e4e58sf Variables may also be passed from the environment of the shell
d6fc66efa723db8b3ee5e9fd32579bed884e4e58sf directive.</p>
f00cb80197f824c3ff00dd4fdff3b2c267a519d1kbrand <p>For additional flexibility, the directives provided by
85eacfc96a04547ef25aabbc06440039715084c2jorton mod_setenvif allow environment variables to be set on a
85eacfc96a04547ef25aabbc06440039715084c2jorton per-request basis, conditional on characteristics of particular
85eacfc96a04547ef25aabbc06440039715084c2jorton requests. For example, a variable could be set only when a
1d8d7e58e1d31d7b6fb7a518e09649a4dbb315e9trawick specific browser (User-Agent) is making a request, or only when
1d8d7e58e1d31d7b6fb7a518e09649a4dbb315e9trawick a specific Referer [sic] header is found. Even more flexibility
1d8d7e58e1d31d7b6fb7a518e09649a4dbb315e9trawick is available through the mod_rewrite's <code>RewriteRule</code>
f34da68471f256dca0ff770257c3e1f982f74cf1trawick which uses the <code>[E=...]</code> option to set environment
f34da68471f256dca0ff770257c3e1f982f74cf1trawick variables.</p>
8b645fd3c950da73513b546366c7cfa7476c5c06jim <p>Finally, mod_unique_id sets the environment variable
8b645fd3c950da73513b546366c7cfa7476c5c06jim <code>UNIQUE_ID</code> for each request to a value which is
193f0bb6057d67593ed652fbf58f043def51c642jim guaranteed to be unique across "all" requests under very
193f0bb6057d67593ed652fbf58f043def51c642jim specific conditions.</p>
68ba377fc3b124baa759662077c48077ebadb186minfrin <p>In addition to all environment variables set within the
68ba377fc3b124baa759662077c48077ebadb186minfrin Apache configuration and passed from the shell, CGI scripts and
00566fb187849626180724394a21ddcd28419fb2minfrin SSI pages are provided with a set of environment variables
00566fb187849626180724394a21ddcd28419fb2minfrin containing meta-information about the request as required by
57db302f0875a6c93a79333b8941cea4c1827272jim <li>It is not possible to override or change the standard CGI
57db302f0875a6c93a79333b8941cea4c1827272jim variables using the environment manipulation directives.</li>
92b1631880b0bf43fe8b2663a03c8571eb04e433jim <li>When <a href="suexec.html">suexec</a> is used to launch
92b1631880b0bf43fe8b2663a03c8571eb04e433jim CGI scripts, the environment will be cleaned down to a set of
92b1631880b0bf43fe8b2663a03c8571eb04e433jim <em>safe</em> variables before CGI scripts are launched. The
89225e8e84d38b07a8335922497997e83d872e75jim list of <em>safe</em> variables is defined at compile-time in
78f94f1d06c4e6828ce04d618221e0fcecb57849humbedooh <li>For portability reasons, the names of environment
78f94f1d06c4e6828ce04d618221e0fcecb57849humbedooh variables may contain only letters, numbers, and the
78f94f1d06c4e6828ce04d618221e0fcecb57849humbedooh underscore character. In addition, the first character may
f5e28c78424d2f71c61ba457009f100bba38bc68chrisd not be a number. Characters which do not match this
f5e28c78424d2f71c61ba457009f100bba38bc68chrisd restriction will be replaced by an underscore when passed to
f5e28c78424d2f71c61ba457009f100bba38bc68chrisd CGI scripts and SSI pages.</li>
985a4368b93c3e9171a57897ad9454c8dbf4cdf6jorton <td valign="top"><strong>Related Modules</strong><br />
109e2a09790de3fb315d36d6232a14ab66c8eb0ahumbedooh <a href="mod/mod_headers.html">mod_headers</a><br />
109e2a09790de3fb315d36d6232a14ab66c8eb0ahumbedooh <a href="mod/mod_include.html">mod_include</a><br />
4be250c774bdac977eef29a02183ca78de29fb41rjung <a href="mod/mod_log_config.html">mod_log_config</a><br />
12b5dc9afa1844df5ac8acab98fb538432a2fa1crjung <td valign="top"><strong>Related Directives</strong><br />
74e7a30182af5e68f14ccb8d57918b22b982db8bhumbedooh href="mod/mod_log_config.html#customlog">CustomLog</a><br />
10961a2f60207cb873d889bb28b1f0ef707a4311humbedooh <a href="mod/mod_headers.html#Header">Header</a><br />
10961a2f60207cb873d889bb28b1f0ef707a4311humbedooh href="mod/mod_log_config.html#logformat">LogFormat</a><br />
0448378b899e8df0c060360f17c0af692adf17bchumbedooh href="mod/mod_rewrite.html#RewriteCond">RewriteCond</a><br />
60a765cccbd3f3b5997b65b0034220c79f78369etrawick href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br />
91654e263480f0fdc2a03d782ff23f8dad07cf79humbedooh <p>One of the primary uses of environment variables is to
91814c869ca39ce45dfe147307d2a831cac6ecbehumbedooh communicate information to CGI scripts. As discussed above, the
91654e263480f0fdc2a03d782ff23f8dad07cf79humbedooh environment passed to CGI scripts includes standard
79c5787b92ac5f0e1cc82393816c77a006399316trawick meta-information about the request in addition to any variables
79c5787b92ac5f0e1cc82393816c77a006399316trawick set within the Apache configuration. For more details, see the
79c5787b92ac5f0e1cc82393816c77a006399316trawick <p>Server-parsed (SSI) documents processed by mod_include's
79c5787b92ac5f0e1cc82393816c77a006399316trawick <code>INCLUDES</code> filter can print environment variables
79c5787b92ac5f0e1cc82393816c77a006399316trawick using the <code>echo</code> element, and can use environment
79c5787b92ac5f0e1cc82393816c77a006399316trawick variables in flow control elements to makes parts of a page
12b987b969f03ef98d9175a53d849ab62f5684fecovener conditional on characteristics of a request. Apache also
12b987b969f03ef98d9175a53d849ab62f5684fecovener provides SSI pages with the standard CGI environment variables
099c357f282d4aebf2b32264f7dce6ffc0497c37sf as discussed above. For more details, see the <a
50f8c80eb4d3989ebf3f1341aeef4d2d302af162sf <p>Access to the server can be controlled based on the value of
4bb0a88a01fb7b494bb02a8b881b5eab0308bda6sf environment variables using the <code>allow from env=</code>
50f8c80eb4d3989ebf3f1341aeef4d2d302af162sf and <code>deny from env=</code> directives. In combination with
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton <code>SetEnvIf</code>, this allows for flexible control of
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton access to the server based on characteristics of the client.
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton For example, you can use these directives to deny access to a
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton particular browser (User-Agent).</p>
e81785da447b469da66f218b3f0244aab507958djorton <p>Environment variables can be logged in the access log using
3e4e54d4e3fc0123c63d57aa84ac7ad7a8c73ff8jorton the <code>LogFormat</code> option <code>%e</code>. In addition,
3e4e54d4e3fc0123c63d57aa84ac7ad7a8c73ff8jorton the decision on whether or not to log requests can be made
3e4e54d4e3fc0123c63d57aa84ac7ad7a8c73ff8jorton based on the status of environment variables using the
459eaf0826f995b73a0dc066f59ea10d2824e72dsf conditional form of the <code>CustomLog</code> directive. In
459eaf0826f995b73a0dc066f59ea10d2824e72dsf combination with <code>SetEnvIf</code> this allows for flexible
459eaf0826f995b73a0dc066f59ea10d2824e72dsf control of which requests are logged. For example, you can
459eaf0826f995b73a0dc066f59ea10d2824e72dsf choose not to log requests for filenames ending in
53e9b27aba029b18be814df40bcf6f0428771d1efuankg <code>gif</code>, or you can choose to only log requests from
53e9b27aba029b18be814df40bcf6f0428771d1efuankg clients which are outside your subnet.</p>
6bb524f1895f30265a1431afc460977d391cb36bsf <p>The <code>Header</code> directive can use the presence or
6bb524f1895f30265a1431afc460977d391cb36bsf absence of an environment variable to determine whether or not
ca61ccd0c306c2c72df153688ba1b49f3eceed80sf a certain HTTP header will be placed in the response to the
6bb524f1895f30265a1431afc460977d391cb36bsf client. This allows, for example, a certain response header to
e6dd71992459d05a676b98b7963423dc5dc1e24aminfrin be sent only if a corresponding header is received in the
e6dd71992459d05a676b98b7963423dc5dc1e24aminfrin request from the client.</p>
23f1535d6a60817d2846bac0aea230ea475d7dccminfrin <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in
23f1535d6a60817d2846bac0aea230ea475d7dccminfrin the <code>RewriteCond</code> allows mod_rewrite's rewrite
23f1535d6a60817d2846bac0aea230ea475d7dccminfrin engine to make decisions conditional on environment variables.
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung Note that the variables accessible in mod_rewrite without the
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung variables. Rather, they are variables special to mod_rewrite
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung which cannot be accessed from other modules.</p>
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung <h2><a id="special" name="special">Special Purpose Environment
6249dfa569d3b4f1f539665b979a80c6e335d93etrawick <p>Interoperability problems have led to the introduction of
0827cb14e550f6f65018431c22c2c913631c8f25kbrand mechanisms to modify the way Apache behaves when talking to
6249dfa569d3b4f1f539665b979a80c6e335d93etrawick particular clients. To make these mechanisms as flexible as
ae600ca541efc686b34f8b1f21bd3d0741d37674covener possible, they are invoked by defining environment variables,
6249dfa569d3b4f1f539665b979a80c6e335d93etrawick typically with <a
cfa64348224b66dd1c9979b809406c4d15b1c137fielding href="mod/mod_setenvif.html#browsermatch">BrowserMatch</a>,
74499a117b3b2cd9666715a14f90c0e5d1a4ee8ajim though <a href="mod/mod_env.html#setenv">SetEnv</a> and <a
cfa64348224b66dd1c9979b809406c4d15b1c137fielding href="mod/mod_env.html#passenv">PassEnv</a> could also be used,
74499a117b3b2cd9666715a14f90c0e5d1a4ee8ajim for example.</p>
74499a117b3b2cd9666715a14f90c0e5d1a4ee8ajim <p>This forces the request to be treated as a HTTP/1.0 request
cfa64348224b66dd1c9979b809406c4d15b1c137fielding even if it was in a later dialect.</p>
href="misc/known_client_problems.html">known client
# The first directive disables keepalive for Netscape 2.x and browsers that
SetEnvIf Referer "^http://www.example.com/" local_referal
<!--#include virtual="footer.html" -->