granicus.if.org Git - apache/blob - docs/manual/env.html.en

   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
   7       --><title>Environment Variables in Apache - Apache HTTP Server</title><link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="./images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><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><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="./images/feather.gif" /></div><div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Environment Variables in Apache</h1>
   8     <p>The Apache HTTP Server provides a mechanism for storing
   9     information in named variables that are called <em>environment
  10     variables</em>. This information can be used to control various
  11     operations such as logging or access control. The variables are
  12     also used as a mechanism to communicate with external programs
  13     such as CGI scripts. This document discusses different ways to
  14     manipulate and use these variables.</p>
  15
  16     <p>Although these variables are referred to as <em>environment
  17     variables</em>, they are not the same as the environment
  18     variables controlled by the underlying operating system.
  19     Instead, these variables are stored and manipulated in an
  20     internal Apache structure. They only become actual operating
  21     system environment variables when they are provided to CGI
  22     scripts and Server Side Include scripts. If you wish to
  23     manipulate the operating system environment under which the
  24     server itself runs, you must use the standard environment
  25     manipulation mechanisms provided by your operating system
  26     shell.</p>
  27   </div><div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#setting">Setting Environment Variables</a></li><li><img alt="" src="./images/down.gif" /> <a href="#using">Using Environment Variables</a></li><li><img alt="" src="./images/down.gif" /> <a href="#special">Special Purpose Environment Variables</a></li><li><img alt="" src="./images/down.gif" /> <a href="#examples">Examples</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div><div class="section"><h2><a name="setting" id="setting">Setting Environment Variables</a></h2>
  28
  29     <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>
  30
  31     <h3><a name="basic-manipulation" id="basic-manipulation">Basic Environment Manipulation</a></h3>
  32
  33
  34         <p>The most basic way to set an environment variable in Apache
  35         is using the unconditional <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> directive. Variables may also be passed from
  36         the environment of the shell which started the server using the
  37         <code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code> directive.</p>
  38
  39
  40     <h3><a name="conditional" id="conditional">Conditional Per-Request Settings</a></h3>
  41
  42
  43         <p>For additional flexibility, the directives provided by
  44         mod_setenvif allow environment variables to be set on a
  45         per-request basis, conditional on characteristics of particular
  46         requests. For example, a variable could be set only when a
  47         specific browser (User-Agent) is making a request, or only when
  48         a specific Referer [sic] header is found. Even more flexibility
  49         is available through the mod_rewrite's <code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> which uses the
  50         <code>[E=...]</code> option to set environment variables.</p>
  51
  52
  53     <h3><a name="unique-identifiers" id="unique-identifiers">Unique Identifiers</a></h3>
  54
  55
  56         <p>Finally, mod_unique_id sets the environment variable
  57         <code>UNIQUE_ID</code> for each request to a value which is
  58         guaranteed to be unique across "all" requests under very
  59         specific conditions.</p>
  60
  61
  62     <h3><a name="standard-cgi" id="standard-cgi">Standard CGI Variables</a></h3>
  63
  64
  65         <p>In addition to all environment variables set within the
  66         Apache configuration and passed from the shell, CGI scripts and
  67         SSI pages are provided with a set of environment variables
  68         containing meta-information about the request as required by
  69         the <a href="http://cgi-spec.golux.com/">CGI
  70         specification</a>.</p>
  71
  72
  73     <h3><a name="caveats" id="caveats">Some Caveats</a></h3>
  74
  75
  76         <ul>
  77           <li>It is not possible to override or change the standard CGI
  78           variables using the environment manipulation directives.</li>
  79
  80           <li>When <a href="suexec.html">suexec</a> is used to launch
  81           CGI scripts, the environment will be cleaned down to a set of
  82           <em>safe</em> variables before CGI scripts are launched. The
  83           list of <em>safe</em> variables is defined at compile-time in
  84           <code>suexec.c</code>.</li>
  85
  86           <li>For portability reasons, the names of environment
  87           variables may contain only letters, numbers, and the
  88           underscore character. In addition, the first character may
  89           not be a number. Characters which do not match this
  90           restriction will be replaced by an underscore when passed to
  91           CGI scripts and SSI pages.</li>
  92         </ul>
  93
  94   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div><div class="section"><h2><a name="using" id="using">Using Environment Variables</a></h2>
  95
  96
  97     <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_authz_host.html">mod_authz_host</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_authz_host.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_authz_host.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>
  98
  99     <h3><a name="cgi-scripts" id="cgi-scripts">CGI Scripts</a></h3>
 100
 101
 102         <p>One of the primary uses of environment variables is to
 103         communicate information to CGI scripts. As discussed above, the
 104         environment passed to CGI scripts includes standard
 105         meta-information about the request in addition to any variables
 106         set within the Apache configuration. For more details, see the
 107         <a href="howto/cgi.html">CGI tutorial</a>.</p>
 108
 109
 110     <h3><a name="ssi-pages" id="ssi-pages">SSI Pages</a></h3>
 111
 112
 113         <p>Server-parsed (SSI) documents processed by mod_include's
 114         <code>INCLUDES</code> filter can print environment variables
 115         using the <code>echo</code> element, and can use environment
 116         variables in flow control elements to makes parts of a page
 117         conditional on characteristics of a request. Apache also
 118         provides SSI pages with the standard CGI environment variables
 119         as discussed above. For more details, see the <a href="howto/ssi.html">SSI tutorial</a>.</p>
 120
 121
 122     <h3><a name="access-control" id="access-control">Access Control</a></h3>
 123
 124
 125         <p>Access to the server can be controlled based on the value of
 126         environment variables using the <code>allow from env=</code>
 127         and <code>deny from env=</code> directives. In combination with
 128         <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>, this
 129         allows for flexible control of access to the server based on
 130         characteristics of the client. For example, you can use these
 131         directives to deny access to a particular browser (User-Agent).
 132         </p>
 133
 134
 135     <h3><a name="logging" id="logging">Conditional Logging</a></h3>
 136
 137
 138         <p>Environment variables can be logged in the access log using
 139         the <code class="directive"><a href="./mod/mod_log_config.html#logformat">LogFormat</a></code>
 140         option <code>%e</code>. In addition, the decision on whether
 141         or not to log requests can be made based on the status of
 142         environment variables using the conditional form of the
 143         <code class="directive"><a href="./mod/mod_log_config.html#customlog">CustomLog</a></code>
 144         directive. In combination with <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> this allows for flexible control of which
 145         requests are logged. For example, you can choose not to log
 146         requests for filenames ending in <code>gif</code>, or you can
 147         choose to only log requests from clients which are outside your
 148         subnet.</p>
 149
 150
 151     <h3><a name="response-headers" id="response-headers">Conditional Response Headers</a></h3>
 152
 153
 154         <p>The <code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code>
 155         directive can use the presence or
 156         absence of an environment variable to determine whether or not
 157         a certain HTTP header will be placed in the response to the
 158         client. This allows, for example, a certain response header to
 159         be sent only if a corresponding header is received in the
 160         request from the client.</p>
 161
 162
 163
 164     <h3><a name="external-filter" id="external-filter">External Filter Activation</a></h3>
 165
 166
 167         <p>External filters configured by <code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code>
 168         using the <code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code> directive can
 169         by activated conditional on an environment variable using the
 170         <code>disableenv=</code> and <code>enableenv=</code> options.</p>
 171
 172
 173     <h3><a name="url-rewriting" id="url-rewriting">URL Rewriting</a></h3>
 174
 175
 176         <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in
 177         the <code class="directive"><a href="./mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
 178         allows mod_rewrite's rewrite
 179         engine to make decisions conditional on environment variables.
 180         Note that the variables accessible in mod_rewrite without the
 181         <code>ENV:</code> prefix are not actually environment
 182         variables. Rather, they are variables special to mod_rewrite
 183         which cannot be accessed from other modules.</p>
 184
 185   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div><div class="section"><h2><a name="special" id="special">Special Purpose Environment Variables</a></h2>
 186
 187
 188         <p>Interoperability problems have led to the introduction of
 189         mechanisms to modify the way Apache behaves when talking to
 190         particular clients. To make these mechanisms as flexible as
 191         possible, they are invoked by defining environment variables,
 192         typically with <code class="directive"><a href="./mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code>,
 193         though <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> and
 194         <code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code> could also be used,
 195         for example.</p>
 196
 197     <h3><a name="downgrade" id="downgrade">downgrade-1.0</a></h3>
 198
 199
 200         <p>This forces the request to be treated as a HTTP/1.0 request
 201         even if it was in a later dialect.</p>
 202
 203
 204     <h3><a name="force-no-vary" id="force-no-vary">force-no-vary</a></h3>
 205
 206
 207         <p>This causes any <code>Vary</code> fields to be removed from
 208         the response header before it is sent back to the client. Some
 209         clients don't interpret this field correctly (see the <a href="misc/known_client_problems.html">known client
 210         problems</a> page); setting this variable can work around this
 211         problem. Setting this variable also implies
 212         <strong>force-response-1.0</strong>.</p>
 213
 214
 215     <h3><a name="force-response" id="force-response">force-response-1.0</a></h3>
 216
 217
 218       <p>This forces an HTTP/1.0 response to clients making an HTTP/1.0
 219       request. It was originally
 220       implemented as a result of a problem with AOL's proxies. Some
 221       HTTP/1.0 clients may not behave correctly when given an HTTP/1.1
 222       response, and this can be used to interoperate with them.</p>
 223
 224
 225
 226     <h3><a name="gzip-only-text-html" id="gzip-only-text-html">gzip-only-text/html</a></h3>
 227
 228
 229         <p>When set to a value of "1", this variable disables the DEFLATE
 230         output filter provided by <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> for
 231         content-types other than <code>text/html</code>.</p>
 232
 233
 234     <h3><a name="nogzip" id="nogzip">nogzip</a></h3>
 235
 236         <p>When set, the <code>DEFLATE</code> filter of
 237         <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will be turned off.</p>
 238
 239
 240
 241     <h3><a name="nokeepalive" id="nokeepalive">nokeepalive</a></h3>
 242
 243
 244         <p>This disables <code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> when set.</p>
 245
 246
 247     <h3><a name="redirect-carefully" id="redirect-carefully">redirect-carefully</a></h3>
 248
 249
 250         <p>This forces the server to be more careful when sending a redirect
 251         to the client.  This is typically used when a client has a known
 252         problem handling redirects.  This was originally implemented as a
 253         result of a problem with Microsoft's WebFolders software which has
 254         a problem handling redirects on directory resources via DAV
 255         methods.</p>
 256
 257
 258
 259    <h3><a name="suppress-error-charset" id="suppress-error-charset">suppress-error-charset</a></h3>
 260
 261
 262     <p><em>Available in versions after 2.0.40</em></p>
 263
 264     <p>When Apache issues a redirect in response to a client request,
 265     the response includes some actual text to be displayed in case
 266     the client can't (or doesn't) automatically follow the redirection.
 267     Apache ordinarily labels this text according to the character set
 268     which it uses, which is ISO-8859-1.</p>
 269     <p> However, if the redirection is to a page that uses a different
 270     character set, some broken browser versions will try to use the
 271     character set from the redirection text rather than the actual page.
 272     This can result in Greek, for instance, being incorrectly rendered.</p>
 273     <p>Setting this environment variable causes Apache to omit the character
 274     set for the redirection text, and these broken browsers will then correctly
 275     use that of the destination page.</p>
 276
 277
 278
 279   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div><div class="section"><h2><a name="examples" id="examples">Examples</a></h2>
 280
 281
 282     <h3><a name="misbehaving" id="misbehaving">Changing protocol behavior with misbehaving clients</a></h3>
 283
 284
 285         <p>We recommend that the following lines be included in
 286         httpd.conf to deal with known client problems.</p>
 287 <div class="example"><pre>
 288 #
 289 # The following directives modify normal HTTP response behavior.
 290 # The first directive disables keepalive for Netscape 2.x and browsers that
 291 # spoof it. There are known problems with these browser implementations.
 292 # The second directive is for Microsoft Internet Explorer 4.0b2
 293 # which has a broken HTTP/1.1 implementation and does not properly
 294 # support keepalive when it is used on 301 or 302 (redirect) responses.
 295 #
 296 BrowserMatch "Mozilla/2" nokeepalive
 297 BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
 298
 299 #
 300 # The following directive disables HTTP/1.1 responses to browsers which
 301 # are in violation of the HTTP/1.0 spec by not being able to grok a
 302 # basic 1.1 response.
 303 #
 304 BrowserMatch "RealPlayer 4\.0" force-response-1.0
 305 BrowserMatch "Java/1\.0" force-response-1.0
 306 BrowserMatch "JDK/1\.0" force-response-1.0</pre></div>
 307
 308
 309     <h3><a name="no-img-log" id="no-img-log">Do not log requests for images in the access log</a></h3>
 310
 311
 312         <p>This example keeps requests for images from appearing in the
 313         access log. It can be easily modified to prevent logging of
 314         particular directories, or to prevent logging of requests
 315         coming from particular hosts.</p>
 316     <div class="example"><pre>
 317 SetEnvIf Request_URI \.gif image-request
 318 SetEnvIf Request_URI \.jpg image-request
 319 SetEnvIf Request_URI \.png image-request
 320 CustomLog logs/access_log common env=!image-request</pre></div>
 321
 322
 323     <h3><a name="image-theft" id="image-theft">Prevent "Image Theft"</a></h3>
 324
 325
 326         <p>This example shows how to keep people not on your server
 327         from using images on your server as inline-images on their
 328         pages. This is not a recommended configuration, but it can work
 329         in limited circumstances. We assume that all your images are in
 330         a directory called /web/images.</p>
 331     <div class="example"><pre>
 332 SetEnvIf Referer "^http://www.example.com/" local_referal
 333 # Allow browsers that do not send Referer info
 334 SetEnvIf Referer "^$" local_referal
 335 &lt;Directory /web/images&gt;
 336    Order Deny,Allow
 337    Deny from all
 338    Allow from env=local_referal
 339 &lt;/Directory&gt;</pre></div>
 340
 341         <p>For more information about this technique, see the
 342         ApacheToday tutorial " <a href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
 343     Keeping Your Images from Adorning Other Sites</a>".</p>
 344
 345   </div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><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></body></html>