env.html revision 2b3d9d9ea2b368cce27c9693b6ac263b4f101b4c
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<TITLE>Special Purpose Environment Variables</TITLE>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
3726777f47ac4bba3e21b075905959bbea47e72eerikabele BGCOLOR="#FFFFFF"
3726777f47ac4bba3e21b075905959bbea47e72eerikabele TEXT="#000000"
3726777f47ac4bba3e21b075905959bbea47e72eerikabele LINK="#0000FF"
3726777f47ac4bba3e21b075905959bbea47e72eerikabele VLINK="#000080"
3726777f47ac4bba3e21b075905959bbea47e72eerikabele ALINK="#FF0000"
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd<!--#include virtual="header.html" -->
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<p>Many operating systems provide a facility for storage and
3726777f47ac4bba3e21b075905959bbea47e72eerikabeletransmission of information called environment variables. Apache uses
4489f0b54d190e8ac29906e1071bbad6c49de17endenvironment variables in many ways to control operations and to
3726777f47ac4bba3e21b075905959bbea47e72eerikabelecommunicate with other programs like CGI scripts. This document
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleexplains some of the ways to use environment variables in Apache.</p>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<li><a href="#setting">Setting Environment Variables</a></li>
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd<li><a href="#special">Special Purpose Environment Variables</a></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<h2><a name="setting">Setting Environment Variables</a></h2>
4489f0b54d190e8ac29906e1071bbad6c49de17end<li><a href="mod/mod_unique_id.html">mod_unique_id</a></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<li><A HREF="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</A></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<li><A HREF="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<li><A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<li><A HREF="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</A></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<li><A HREF="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A></li>
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>The most basic way to set an environment variable in Apache is
4489f0b54d190e8ac29906e1071bbad6c49de17endusing the unconditional <code>SetEnv</code> directive. Variables
4489f0b54d190e8ac29906e1071bbad6c49de17endmay also be passed from the environment when Apache is started
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>The directives provided by mod_setenvif allow environment variables
4489f0b54d190e8ac29906e1071bbad6c49de17endto be set on a per-request basis based on characteristics of particular
4489f0b54d190e8ac29906e1071bbad6c49de17endrequests. For example, a variable could be set only when a specific
4489f0b54d190e8ac29906e1071bbad6c49de17endbrowser (User-Agent) is making a request, or only when a specific
4489f0b54d190e8ac29906e1071bbad6c49de17endReferer header is found. Even more flexibility is available through the
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>[E=...]</code> option to set environment variables.</p>
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>Finally, mod_unique_id sets the environment variable
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>UNIQUE_ID</code> for each request to a value which is guaranteed
4489f0b54d190e8ac29906e1071bbad6c49de17endto be unique across "all" requests under very specific conditions.</p>
e0471b26427a7310358a7a3a835bd146072e4c29nd<li><a href="mod/mod_log_config.html">mod_log_config</a></li>
e0471b26427a7310358a7a3a835bd146072e4c29nd<LI><A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A></li>
e0471b26427a7310358a7a3a835bd146072e4c29nd<li><a href="mod/mod_log_config.html#customlog-conditional">CustomLog
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<LI><A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A></li>
3c56725151a46fef84ce376d709b5339da28e10fnd<li><a href="mod/mod_log_config.html#logformat">LogFormat</a></li>
3c56725151a46fef84ce376d709b5339da28e10fnd<LI><A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A></li>
3c56725151a46fef84ce376d709b5339da28e10fnd<LI><A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A></li>
e0471b26427a7310358a7a3a835bd146072e4c29nd<p>One of the primary uses of environment variables is to communicate
e0471b26427a7310358a7a3a835bd146072e4c29ndinformation to CGI scripts. In addition to all environment variables
4489f0b54d190e8ac29906e1071bbad6c49de17endset within Apache, CGI scripts are provided with a set of
4489f0b54d190e8ac29906e1071bbad6c49de17endmeta-information about the request as provided for in the <a
4489f0b54d190e8ac29906e1071bbad6c49de17endhref="misc/FAQ.html#cgi-spec">CGI specification</a>. If you are using
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<a href="suexec.html">Suexec</a> to execute CGI scripts under
3c56725151a46fef84ce376d709b5339da28e10fnddifferent userids, note that the environment will be cleaned down to a
3c56725151a46fef84ce376d709b5339da28e10fndset of <em>safe</em> environment variables before the CGI script is
3c56725151a46fef84ce376d709b5339da28e10fndexecuted. The set of safe environment variables is defined at
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>Server-parsed (SSI) documents processed by mod_include's
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>server-parsed</code> handler can print environment variables
4489f0b54d190e8ac29906e1071bbad6c49de17endusing the <code>echo</code> element, and can use environment variables
4489f0b54d190e8ac29906e1071bbad6c49de17endin flow control elements.
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>Access to the server can be controlled based on the value of
4489f0b54d190e8ac29906e1071bbad6c49de17endenvironment variables using the <code>allow from env=</code> and
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>deny from env=</code></a> directives. In combination with
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>SetEnvIf</code>, this allows for flexible control of access to
4489f0b54d190e8ac29906e1071bbad6c49de17endthe server based on characteristics of the client. For example, you
4489f0b54d190e8ac29906e1071bbad6c49de17endcan use these directives to deny access to a particular browser
4489f0b54d190e8ac29906e1071bbad6c49de17end(User-Agent).
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>Environment variables can be logged in the access log using the
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>LogFormat</code> option <code>%e</code>. In addition, the
4489f0b54d190e8ac29906e1071bbad6c49de17enddecision on whether or not to log requests can be made based on the
4489f0b54d190e8ac29906e1071bbad6c49de17endstatus of environment variables using the conditional form of the
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>SetEnvIf</code> this allows for flexible control of which
4489f0b54d190e8ac29906e1071bbad6c49de17endrequests are logged. For example, you can choose not to log requests
4489f0b54d190e8ac29906e1071bbad6c49de17endfor filenames ending in <code>gif</code>, or you can choose to only
4489f0b54d190e8ac29906e1071bbad6c49de17endlog requests from clients which are outside your subnet.
4489f0b54d190e8ac29906e1071bbad6c49de17end<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
4489f0b54d190e8ac29906e1071bbad6c49de17end<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
4489f0b54d190e8ac29906e1071bbad6c49de17enddecisions conditional on environment variables.
e0471b26427a7310358a7a3a835bd146072e4c29nd<H2><a name="special">Special Purpose Environment Variables</a></H2>
e0471b26427a7310358a7a3a835bd146072e4c29ndInteroperability problems have led to the introduction of
e0471b26427a7310358a7a3a835bd146072e4c29ndmechanisms to modify the way Apache behaves when talking to particular
e0471b26427a7310358a7a3a835bd146072e4c29ndclients. To make these mechanisms as flexible as possible, they
e0471b26427a7310358a7a3a835bd146072e4c29ndare invoked by defining environment variables, typically with
e0471b26427a7310358a7a3a835bd146072e4c29nd<A HREF="mod/mod_browser.html#browsermatch">BrowserMatch</A>, though
e0471b26427a7310358a7a3a835bd146072e4c29nd<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for
4489f0b54d190e8ac29906e1071bbad6c49de17endThis forces the request to be treated as a HTTP/1.0 request even if it
3726777f47ac4bba3e21b075905959bbea47e72eerikabelewas in a later dialect.
e0471b26427a7310358a7a3a835bd146072e4c29ndThis causes any <CODE>Vary</CODE> fields to be removed from the response
e0471b26427a7310358a7a3a835bd146072e4c29ndheader before it is sent back to the client. Some clients don't
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleinterpret this field correctly (see the
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<A HREF="misc/known_client_problems.html">known client problems</A>
e0471b26427a7310358a7a3a835bd146072e4c29ndpage); setting this variable can work around this problem. Setting
e0471b26427a7310358a7a3a835bd146072e4c29ndthis variable also implies <STRONG>force-response-1.0</STRONG>.
3c56725151a46fef84ce376d709b5339da28e10fndThis forces an HTTP/1.0 response when set. It was originally implemented as a
3c56725151a46fef84ce376d709b5339da28e10fndresult of a problem with AOL's proxies. Some clients may not behave correctly
3726777f47ac4bba3e21b075905959bbea47e72eerikabelewhen given an HTTP/1.1 response, and this can be used to interoperate with
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleThis disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set.
e0471b26427a7310358a7a3a835bd146072e4c29nd<h3>Changing protocol behavior with misbehaving clients</h3>
e0471b26427a7310358a7a3a835bd146072e4c29nd<p>We recommend that the following lines be included in httpd.conf
e0471b26427a7310358a7a3a835bd146072e4c29ndto deal with known client problems.</p>
e0471b26427a7310358a7a3a835bd146072e4c29nd# The following directives modify normal HTTP response behavior.
3c56725151a46fef84ce376d709b5339da28e10fnd# The first directive disables keepalive for Netscape 2.x and browsers that
3c56725151a46fef84ce376d709b5339da28e10fnd# spoof it. There are known problems with these browser implementations.
e0471b26427a7310358a7a3a835bd146072e4c29nd# The second directive is for Microsoft Internet Explorer 4.0b2
3c56725151a46fef84ce376d709b5339da28e10fnd# which has a broken HTTP/1.1 implementation and does not properly
e0471b26427a7310358a7a3a835bd146072e4c29nd# support keepalive when it is used on 301 or 302 (redirect) responses.
e0471b26427a7310358a7a3a835bd146072e4c29ndBrowserMatch "Mozilla/2" nokeepalive
e0471b26427a7310358a7a3a835bd146072e4c29ndBrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
3c56725151a46fef84ce376d709b5339da28e10fnd# The following directive disables HTTP/1.1 responses to browsers which
e0471b26427a7310358a7a3a835bd146072e4c29nd# are in violation of the HTTP/1.0 spec by not being able to grok a
4489f0b54d190e8ac29906e1071bbad6c49de17end# basic 1.1 response.
4489f0b54d190e8ac29906e1071bbad6c49de17endBrowserMatch "RealPlayer 4\.0" force-response-1.0
3c56725151a46fef84ce376d709b5339da28e10fndBrowserMatch "Java/1\.0" force-response-1.0
e0471b26427a7310358a7a3a835bd146072e4c29ndBrowserMatch "JDK/1\.0" force-response-1.0
3726777f47ac4bba3e21b075905959bbea47e72eerikabele<h3>Do not log requests for images in the access log</h3>
e0471b26427a7310358a7a3a835bd146072e4c29nd<p>This example keeps requests for images from appearing
e0471b26427a7310358a7a3a835bd146072e4c29ndin the access log. It can be easily modified to prevent logging
e0471b26427a7310358a7a3a835bd146072e4c29ndof particular directories, or to prevent logging of requests
3726777f47ac4bba3e21b075905959bbea47e72eerikabelecoming from particular hosts.</p>
3726777f47ac4bba3e21b075905959bbea47e72eerikabele SetEnvIf Request_URI \.gif image-request
3726777f47ac4bba3e21b075905959bbea47e72eerikabele SetEnvIf Request_URI \.jpg image-request
e0471b26427a7310358a7a3a835bd146072e4c29nd SetEnvIf Request_URI \.png image-request
e0471b26427a7310358a7a3a835bd146072e4c29nd<p>This example shows how to keep people not on your server from using
e0471b26427a7310358a7a3a835bd146072e4c29ndimages on your server as inline-images on their pages. This is not
e0471b26427a7310358a7a3a835bd146072e4c29nda recommended configuration, but it can work in limited
e0471b26427a7310358a7a3a835bd146072e4c29ndcircumstances. We assume that all your images are in a directory
e0471b26427a7310358a7a3a835bd146072e4c29nd SetEnvIf Referer "^http://www.example.com/" local_referal
e0471b26427a7310358a7a3a835bd146072e4c29nd # Allow browsers that do not send Referer info
e0471b26427a7310358a7a3a835bd146072e4c29nd SetEnvIf Referer "^$" local_referal
e0471b26427a7310358a7a3a835bd146072e4c29nd Order Deny,Allow
e0471b26427a7310358a7a3a835bd146072e4c29nd Deny from all
e0471b26427a7310358a7a3a835bd146072e4c29nd Allow from env=local_referal
e0471b26427a7310358a7a3a835bd146072e4c29nd </Directory>
e0471b26427a7310358a7a3a835bd146072e4c29nd<p>For more information about this technique, see the ApacheToday
e0471b26427a7310358a7a3a835bd146072e4c29ndtutorial "<a
e0471b26427a7310358a7a3a835bd146072e4c29ndhref="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">Keeping
e0471b26427a7310358a7a3a835bd146072e4c29nd<!--#include virtual="footer.html" -->