1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>Environment Variables in Apache - Apache HTTP Server</title>
9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
15 <p class="apache">Apache HTTP Server Version 2.0</p>
16 <img alt="" src="./images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
19 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Environment Variables in Apache</h1>
21 <p><span>Available Languages: </span><a href="./en/env.html" title="English"> en </a> |
22 <a href="./es/env.html" hreflang="es" rel="alternate" title="Español"> es </a> |
23 <a href="./fr/env.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
24 <a href="./ja/env.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
25 <a href="./ko/env.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
26 <a href="./tr/env.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
29 <p>The Apache HTTP Server provides a mechanism for storing
30 information in named variables that are called <em>environment
31 variables</em>. This information can be used to control various
32 operations such as logging or access control. The variables are
33 also used as a mechanism to communicate with external programs
34 such as CGI scripts. This document discusses different ways to
35 manipulate and use these variables.</p>
37 <p>Although these variables are referred to as <em>environment
38 variables</em>, they are not the same as the environment
39 variables controlled by the underlying operating system.
40 Instead, these variables are stored and manipulated in an
41 internal Apache structure. They only become actual operating
42 system environment variables when they are provided to CGI
43 scripts and Server Side Include scripts. If you wish to
44 manipulate the operating system environment under which the
45 server itself runs, you must use the standard environment
46 manipulation mechanisms provided by your operating system
49 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#setting">Setting Environment Variables</a></li>
50 <li><img alt="" src="./images/down.gif" /> <a href="#using">Using Environment Variables</a></li>
51 <li><img alt="" src="./images/down.gif" /> <a href="#special">Special Purpose Environment Variables</a></li>
52 <li><img alt="" src="./images/down.gif" /> <a href="#examples">Examples</a></li>
54 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
56 <h2><a name="setting" id="setting">Setting Environment Variables</a></h2>
58 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_env.html">mod_env</a></code></li><li><code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code></li><li><code class="module"><a href="./mod/mod_setenvif.html">mod_setenvif</a></code></li><li><code class="module"><a href="./mod/mod_unique_id.html">mod_unique_id</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code></li><li><code class="directive"><a href="./mod/mod_setenvif.html#browsermatchnocase">BrowserMatchNoCase</a></code></li><li><code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code></li><li><code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code></li><li><code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code></li><li><code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code></li><li><code class="directive"><a href="./mod/mod_setenvif.html#setenvifnocase">SetEnvIfNoCase</a></code></li><li><code class="directive"><a href="./mod/mod_env.html#unsetenv">UnsetEnv</a></code></li></ul></td></tr></table>
60 <h3><a name="basic-manipulation" id="basic-manipulation">Basic Environment Manipulation</a></h3>
63 <p>The most basic way to set an environment variable in Apache
64 is using the unconditional <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> directive. Variables may also be passed from
65 the environment of the shell which started the server using the
66 <code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code> directive.</p>
69 <h3><a name="conditional" id="conditional">Conditional Per-Request Settings</a></h3>
72 <p>For additional flexibility, the directives provided by
73 <code class="module"><a href="./mod/mod_setenvif.html">mod_setenvif</a></code> allow environment variables to be set
74 on a per-request basis, conditional on characteristics of particular
75 requests. For example, a variable could be set only when a
76 specific browser (User-Agent) is making a request, or only when
77 a specific Referer [sic] header is found. Even more flexibility
78 is available through the <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code>'s <code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> which uses the
79 <code>[E=...]</code> option to set environment variables.</p>
82 <h3><a name="unique-identifiers" id="unique-identifiers">Unique Identifiers</a></h3>
85 <p>Finally, <code class="module"><a href="./mod/mod_unique_id.html">mod_unique_id</a></code> sets the environment variable <code>UNIQUE_ID</code> for each request to a value which is
86 guaranteed to be unique across "all" requests under very
87 specific conditions.</p>
90 <h3><a name="standard-cgi" id="standard-cgi">Standard CGI Variables</a></h3>
93 <p>In addition to all environment variables set within the
94 Apache configuration and passed from the shell, CGI scripts and
95 SSI pages are provided with a set of environment variables
96 containing meta-information about the request as required by
97 the <a href="http://cgi-spec.golux.com/">CGI
98 specification</a>.</p>
101 <h3><a name="caveats" id="caveats">Some Caveats</a></h3>
105 <li>It is not possible to override or change the standard CGI
106 variables using the environment manipulation directives.</li>
108 <li>When <code class="program"><a href="./programs/suexec.html">suexec</a></code> is used to launch
109 CGI scripts, the environment will be cleaned down to a set of
110 <em>safe</em> variables before CGI scripts are launched. The
111 list of <em>safe</em> variables is defined at compile-time in
112 <code>suexec.c</code>.</li>
114 <li>For portability reasons, the names of environment
115 variables may contain only letters, numbers, and the
116 underscore character. In addition, the first character may
117 not be a number. Characters which do not match this
118 restriction will be replaced by an underscore when passed to
119 CGI scripts and SSI pages.</li>
121 <li>The <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> directive runs
122 late during request processing meaning that directives such as
123 <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> and <code class="directive"><a href="./mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> will not see the
124 variables set with it.</li>
127 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
128 <div class="section">
129 <h2><a name="using" id="using">Using Environment Variables</a></h2>
132 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_access.html">mod_access</a></code></li><li><code class="module"><a href="./mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code></li><li><code class="module"><a href="./mod/mod_headers.html">mod_headers</a></code></li><li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code></li><li><code class="module"><a href="./mod/mod_log_config.html">mod_log_config</a></code></li><li><code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_access.html#allow">Allow</a></code></li><li><code class="directive"><a href="./mod/mod_log_config.html#customlog">CustomLog</a></code></li><li><code class="directive"><a href="./mod/mod_access.html#deny">Deny</a></code></li><li><code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code></li><li><code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code></li><li><code class="directive"><a href="./mod/mod_log_config.html#logformat">LogFormat</a></code></li><li><code class="directive"><a href="./mod/mod_rewrite.html#rewritecond">RewriteCond</a></code></li><li><code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code></li></ul></td></tr></table>
134 <h3><a name="cgi-scripts" id="cgi-scripts">CGI Scripts</a></h3>
137 <p>One of the primary uses of environment variables is to
138 communicate information to CGI scripts. As discussed above, the
139 environment passed to CGI scripts includes standard
140 meta-information about the request in addition to any variables
141 set within the Apache configuration. For more details, see the
142 <a href="howto/cgi.html">CGI tutorial</a>.</p>
145 <h3><a name="ssi-pages" id="ssi-pages">SSI Pages</a></h3>
148 <p>Server-parsed (SSI) documents processed by <code class="module"><a href="./mod/mod_include.html">mod_include</a></code>'s
149 <code>INCLUDES</code> filter can print environment variables
150 using the <code>echo</code> element, and can use environment
151 variables in flow control elements to makes parts of a page
152 conditional on characteristics of a request. Apache also
153 provides SSI pages with the standard CGI environment variables
154 as discussed above. For more details, see the <a href="howto/ssi.html">SSI tutorial</a>.</p>
157 <h3><a name="access-control" id="access-control">Access Control</a></h3>
160 <p>Access to the server can be controlled based on the value of
161 environment variables using the <code>allow from env=</code>
162 and <code>deny from env=</code> directives. In combination with
163 <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>, this
164 allows for flexible control of access to the server based on
165 characteristics of the client. For example, you can use these
166 directives to deny access to a particular browser (User-Agent).
170 <h3><a name="logging" id="logging">Conditional Logging</a></h3>
173 <p>Environment variables can be logged in the access log using
174 the <code class="directive"><a href="./mod/mod_log_config.html#logformat">LogFormat</a></code>
175 option <code>%e</code>. In addition, the decision on whether
176 or not to log requests can be made based on the status of
177 environment variables using the conditional form of the
178 <code class="directive"><a href="./mod/mod_log_config.html#customlog">CustomLog</a></code>
179 directive. In combination with <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> this allows for flexible control of which
180 requests are logged. For example, you can choose not to log
181 requests for filenames ending in <code>gif</code>, or you can
182 choose to only log requests from clients which are outside your
186 <h3><a name="response-headers" id="response-headers">Conditional Response Headers</a></h3>
189 <p>The <code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code>
190 directive can use the presence or
191 absence of an environment variable to determine whether or not
192 a certain HTTP header will be placed in the response to the
193 client. This allows, for example, a certain response header to
194 be sent only if a corresponding header is received in the
195 request from the client.</p>
199 <h3><a name="external-filter" id="external-filter">External Filter Activation</a></h3>
202 <p>External filters configured by <code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code>
203 using the <code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code> directive can
204 by activated conditional on an environment variable using the
205 <code>disableenv=</code> and <code>enableenv=</code> options.</p>
208 <h3><a name="url-rewriting" id="url-rewriting">URL Rewriting</a></h3>
211 <p>The <code>%{ENV:<em>variable</em>}</code> form of
212 <em>TestString</em> in the <code class="directive"><a href="./mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> allows <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code>'s rewrite
213 engine to make decisions conditional on environment variables.
214 Note that the variables accessible in <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code>
215 without the <code>ENV:</code> prefix are not actually environment
216 variables. Rather, they are variables special to
217 <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code> which cannot be accessed from other
220 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
221 <div class="section">
222 <h2><a name="special" id="special">Special Purpose Environment Variables</a></h2>
225 <p>Interoperability problems have led to the introduction of
226 mechanisms to modify the way Apache behaves when talking to
227 particular clients. To make these mechanisms as flexible as
228 possible, they are invoked by defining environment variables,
229 typically with <code class="directive"><a href="./mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code>,
230 though <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> and
231 <code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code> could also be used,
234 <h3><a name="downgrade" id="downgrade">downgrade-1.0</a></h3>
237 <p>This forces the request to be treated as a HTTP/1.0 request
238 even if it was in a later dialect.</p>
241 <h3><a name="force-no-vary" id="force-no-vary">force-no-vary</a></h3>
244 <p>This causes any <code>Vary</code> fields to be removed from
245 the response header before it is sent back to the client. Some
246 clients don't interpret this field correctly (see the <a href="misc/known_client_problems.html">known client
247 problems</a> page); setting this variable can work around this
248 problem. Setting this variable also implies
249 <strong>force-response-1.0</strong>.</p>
252 <h3><a name="force-response" id="force-response">force-response-1.0</a></h3>
255 <p>This forces an HTTP/1.0 response to clients making an HTTP/1.0
256 request. It was originally
257 implemented as a result of a problem with AOL's proxies. Some
258 HTTP/1.0 clients may not behave correctly when given an HTTP/1.1
259 response, and this can be used to interoperate with them.</p>
263 <h3><a name="gzip-only-text-html" id="gzip-only-text-html">gzip-only-text/html</a></h3>
266 <p>When set to a value of "1", this variable disables the
267 <code>DEFLATE</code> output filter provided by
268 <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> for content-types other than
269 <code>text/html</code>.</p>
272 <h3><a name="no-gzip" id="no-gzip">no-gzip</a></h3>
274 <p>When set, the <code>DEFLATE</code> filter of
275 <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will be turned off.</p>
279 <h3><a name="nokeepalive" id="nokeepalive">nokeepalive</a></h3>
282 <p>This disables <code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code>
287 <h3><a name="prefer-language" id="prefer-language">prefer-language</a></h3>
289 <p>This influences <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code>'s behaviour. If
290 it contains a language tag (such as <code>en</code>, <code>ja</code>
291 or <code>x-klingon</code>), <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> tries
292 to deliver a variant with that language. If there's no such variant,
293 the normal <a href="content-negotiation.html">negotiation</a> process
298 <h3><a name="redirect-carefully" id="redirect-carefully">redirect-carefully</a></h3>
301 <p>This forces the server to be more careful when sending a redirect
302 to the client. This is typically used when a client has a known
303 problem handling redirects. This was originally implemented as a
304 result of a problem with Microsoft's WebFolders software which has
305 a problem handling redirects on directory resources via DAV
310 <h3><a name="suppress-error-charset" id="suppress-error-charset">suppress-error-charset</a></h3>
313 <p><em>Available in versions after 2.0.54</em></p>
315 <p>When Apache issues a redirect in response to a client request,
316 the response includes some actual text to be displayed in case
317 the client can't (or doesn't) automatically follow the redirection.
318 Apache ordinarily labels this text according to the character set
319 which it uses, which is ISO-8859-1.</p>
321 <p> However, if the redirection is to a page that uses a different
322 character set, some broken browser versions will try to use the
323 character set from the redirection text rather than the actual page.
324 This can result in Greek, for instance, being incorrectly rendered.</p>
326 <p>Setting this environment variable causes Apache to omit the character
327 set for the redirection text, and these broken browsers will then correctly
328 use that of the destination page.</p>
332 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
333 <div class="section">
334 <h2><a name="examples" id="examples">Examples</a></h2>
337 <h3><a name="misbehaving" id="misbehaving">Changing protocol behavior with misbehaving clients</a></h3>
340 <p>We recommend that the following lines be included in
341 httpd.conf to deal with known client problems.</p>
342 <div class="example"><pre>
344 # The following directives modify normal HTTP response behavior.
345 # The first directive disables keepalive for Netscape 2.x and browsers that
346 # spoof it. There are known problems with these browser implementations.
347 # The second directive is for Microsoft Internet Explorer 4.0b2
348 # which has a broken HTTP/1.1 implementation and does not properly
349 # support keepalive when it is used on 301 or 302 (redirect) responses.
351 BrowserMatch "Mozilla/2" nokeepalive
352 BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
355 # The following directive disables HTTP/1.1 responses to browsers which
356 # are in violation of the HTTP/1.0 spec by not being able to grok a
357 # basic 1.1 response.
359 BrowserMatch "RealPlayer 4\.0" force-response-1.0
360 BrowserMatch "Java/1\.0" force-response-1.0
361 BrowserMatch "JDK/1\.0" force-response-1.0</pre></div>
364 <h3><a name="no-img-log" id="no-img-log">Do not log requests for images in the access log</a></h3>
367 <p>This example keeps requests for images from appearing in the
368 access log. It can be easily modified to prevent logging of
369 particular directories, or to prevent logging of requests
370 coming from particular hosts.</p>
372 <div class="example"><p><code>
373 SetEnvIf Request_URI \.gif image-request<br />
374 SetEnvIf Request_URI \.jpg image-request<br />
375 SetEnvIf Request_URI \.png image-request<br />
376 CustomLog logs/access_log common env=!image-request
380 <h3><a name="image-theft" id="image-theft">Prevent "Image Theft"</a></h3>
383 <p>This example shows how to keep people not on your server
384 from using images on your server as inline-images on their
385 pages. This is not a recommended configuration, but it can work
386 in limited circumstances. We assume that all your images are in
387 a directory called /web/images.</p>
389 <div class="example"><p><code>
390 SetEnvIf Referer "^http://www\.example\.com/" local_referal<br />
391 # Allow browsers that do not send Referer info<br />
392 SetEnvIf Referer "^$" local_referal<br />
393 <Directory /web/images><br />
394 <span class="indent">
395 Order Deny,Allow<br />
397 Allow from env=local_referal
402 <p>For more information about this technique, see the
403 "<a href="http://www.serverwatch.com/tutorials/article.php/1132731">Keeping Your Images from Adorning Other Sites</a>" tutorial on
407 <div class="bottomlang">
408 <p><span>Available Languages: </span><a href="./en/env.html" title="English"> en </a> |
409 <a href="./es/env.html" hreflang="es" rel="alternate" title="Español"> es </a> |
410 <a href="./fr/env.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
411 <a href="./ja/env.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
412 <a href="./ko/env.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
413 <a href="./tr/env.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
414 </div><div id="footer">
415 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
416 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>