mirror of
https://github.com/apache/httpd.git
synced 2025-06-01 23:21:45 +03:00
fe687a82c8
Submitted by: Vincent de Lau <vincent@delau.nl> git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96211 13f79535-47bb-0310-9956-ffa450edef68
295 lines
18 KiB
Plaintext
295 lines
18 KiB
Plaintext
<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
This file is generated from xml source: DO NOT EDIT
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
--><title>Environment Variables in Apache- Apache HTTP Server</title><link href="./style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="./images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Environment Variables in Apache</h1>
|
|
<p>The Apache HTTP Server provides a mechanism for storing
|
|
information in named variables that are called <em>environment
|
|
variables</em>. This information can be used to control various
|
|
operations such as logging or access control. The variables are
|
|
also used as a mechanism to communicate with external programs
|
|
such as CGI scripts. This document discusses different ways to
|
|
manipulate and use these variables.</p>
|
|
|
|
<p>Although these variables are referred to as <em>environment
|
|
variables</em>, they are not the same as the environment
|
|
variables controlled by the underlying operating system.
|
|
Instead, these variables are stored and manipulated in an
|
|
internal Apache structure. They only become actual operating
|
|
system environment variables when they are provided to CGI
|
|
scripts and Server Side Include scripts. If you wish to
|
|
manipulate the operating system environment under which the
|
|
server itself runs, you must use the standard environment
|
|
manipulation mechanisms provided by your operating system
|
|
shell.</p>
|
|
<ul><li><a href="#setting">Setting Environment Variables</a><ul><li><a href="#basic-manipulation">Basic Environment Manipulation</a></li><li><a href="#conditional">Conditional Per-Request Settings</a></li><li><a href="#unique-identifiers">Unique Identifiers</a></li><li><a href="#standard-cgi">Standard CGI Variables</a></li><li><a href="#caveats">Some Caveats</a></li></ul></li><li><a href="#using">Using Environment Variables</a><ul><li><a href="#cgi-scripts">CGI Scripts</a></li><li><a href="#ssi-pages">SSI Pages</a></li><li><a href="#access-control">Access Control</a></li><li><a href="#logging">Conditional Logging</a></li><li><a href="#response-headers">Conditional Response Headers</a></li><li><a href="#url-rewriting">URL Rewriting</a></li></ul></li><li><a href="#special">Special Purpose Environment Variables</a><ul><li><a href="#downgrade">downgrade-1.0</a></li><li><a href="#force-no-vary">force-no-vary</a></li><li><a href="#force-response">force-response-1.0</a></li><li><a href="#nokeepalive">nokeepalive</a></li><li><a href="#redirect-carefully">redirect-carefully</a></li></ul></li><li><a href="#examples">Examples</a><ul><li><a href="#misbehaving">Changing protocol behavior with misbehaving clients</a></li><li><a href="#no-img-log">Do not log requests for images in the access log</a></li><li><a href="#image-theft">Prevent "Image Theft"</a></li></ul></li></ul><hr/><h2><a name="setting">Setting Environment Variables</a></h2>
|
|
|
|
<table border="1"><tr><td valign="top"><strong>Related Modules</strong><br/><br/><code><a href="./mod/mod_env.html">mod_env</a></code>, <br/><code><a href="./mod/mod_rewrite.html">mod_rewrite</a></code>, <br/><code><a href="./mod/mod_setenvif.html">mod_setenvif</a></code>, <br/><code><a href="./mod/mod_unique_id.html">mod_unique_id</a></code><br/></td><td valign="top"><strong>Related Directives</strong><br/><br/><a href="./mod/mod_setenvif.html#browsermatch" class="directive"><code class="directive">BrowserMatch</code></a><br/><a href="./mod/mod_setenvif.html#browsermatchnocase" class="directive"><code class="directive">BrowserMatchNoCase</code></a><br/><a href="./mod/mod_env.html#passenv" class="directive"><code class="directive">PassEnv</code></a><br/><a href="./mod/mod_rewrite.html#rewriterule" class="directive"><code class="directive">RewriteRule</code></a><br/><a href="./mod/mod_env.html#setenv" class="directive"><code class="directive">SetEnv</code></a><br/><a href="./mod/mod_setenvif.html#setenvif" class="directive"><code class="directive">SetEnvIf</code></a><br/><a href="./mod/mod_setenvif.html#setenvifnocase" class="directive"><code class="directive">SetEnvIfNoCase</code></a><br/><a href="./mod/mod_env.html.html#unsetenv" class="directive"><code class="directive">UnsetEnv</code></a><br/></td></tr></table>
|
|
|
|
<h3><a name="basic-manipulation">Basic Environment Manipulation</a></h3>
|
|
|
|
|
|
<p>The most basic way to set an environment variable in Apache
|
|
is using the unconditional <a href="./mod/mod_env.html#setenv" class="directive"><code class="directive">SetEnv</code></a> directive. Variables may also be passed from
|
|
the environment of the shell which started the server using the
|
|
<a href="./mod/mod_env.html#passenv" class="directive"><code class="directive">PassEnv</code></a> directive.</p>
|
|
|
|
|
|
<h3><a name="conditional">Conditional Per-Request Settings</a></h3>
|
|
|
|
|
|
<p>For additional flexibility, the directives provided by
|
|
mod_setenvif allow environment variables to be set on a
|
|
per-request basis, conditional on characteristics of particular
|
|
requests. For example, a variable could be set only when a
|
|
specific browser (User-Agent) is making a request, or only when
|
|
a specific Referer [sic] header is found. Even more flexibility
|
|
is available through the mod_rewrite's <a href="./mod/mod_rewrite.html#rewriterule" class="directive"><code class="directive">RewriteRule</code></a> which uses the
|
|
<code>[E=...]</code> option to set environment variables.</p>
|
|
|
|
|
|
<h3><a name="unique-identifiers">Unique Identifiers</a></h3>
|
|
|
|
|
|
<p>Finally, mod_unique_id sets the environment variable
|
|
<code>UNIQUE_ID</code> for each request to a value which is
|
|
guaranteed to be unique across "all" requests under very
|
|
specific conditions.</p>
|
|
|
|
|
|
<h3><a name="standard-cgi">Standard CGI Variables</a></h3>
|
|
|
|
|
|
<p>In addition to all environment variables set within the
|
|
Apache configuration and passed from the shell, CGI scripts and
|
|
SSI pages are provided with a set of environment variables
|
|
containing meta-information about the request as required by
|
|
the <a href="http://cgi-spec.golux.com/">CGI
|
|
specification</a>.</p>
|
|
|
|
|
|
<h3><a name="caveats">Some Caveats</a></h3>
|
|
|
|
|
|
<ul>
|
|
<li>It is not possible to override or change the standard CGI
|
|
variables using the environment manipulation directives.</li>
|
|
|
|
<li>When <a href="suexec.html">suexec</a> is used to launch
|
|
CGI scripts, the environment will be cleaned down to a set of
|
|
<em>safe</em> variables before CGI scripts are launched. The
|
|
list of <em>safe</em> variables is defined at compile-time in
|
|
<code>suexec.c</code>.</li>
|
|
|
|
<li>For portability reasons, the names of environment
|
|
variables may contain only letters, numbers, and the
|
|
underscore character. In addition, the first character may
|
|
not be a number. Characters which do not match this
|
|
restriction will be replaced by an underscore when passed to
|
|
CGI scripts and SSI pages.</li>
|
|
</ul>
|
|
|
|
<h2><a name="using">Using Environment Variables</a></h2>
|
|
|
|
|
|
<table border="1"><tr><td valign="top"><strong>Related Modules</strong><br/><br/><code><a href="./mod/mod_access.html">mod_access</a></code>, <br/><code><a href="./mod/mod_cgi.html">mod_cgi</a></code>, <br/><code><a href="./mod/mod_headers.html">mod_headers</a></code>, <br/><code><a href="./mod/mod_include.html">mod_include</a></code>, <br/><code><a href="./mod/mod_log_config.html">mod_log_config</a></code>, <br/><code><a href="./mod/mod_rewrite.html">mod_rewrite</a></code><br/></td><td valign="top"><strong>Related Directives</strong><br/><br/><a href="./mod/mod_access.html#allow" class="directive"><code class="directive">Allow</code></a><br/><a href="./mod/mod_log_config.html#customlog" class="directive"><code class="directive">CustomLog</code></a><br/><a href="./mod/mod_access.html#deny" class="directive"><code class="directive">Deny</code></a><br/><a href="./mod/mod_headers.html#header" class="directive"><code class="directive">Header</code></a><br/><a href="./mod/mod_log_config.html#logformat" class="directive"><code class="directive">LogFormat</code></a><br/><a href="./mod/mod_rewrite.html#rewritecond" class="directive"><code class="directive">RewriteCond</code></a><br/><a href="./mod/mod_rewrite.html#rewriterule" class="directive"><code class="directive">RewriteRule</code></a><br/></td></tr></table>
|
|
|
|
<h3><a name="cgi-scripts">CGI Scripts</a></h3>
|
|
|
|
|
|
<p>One of the primary uses of environment variables is to
|
|
communicate information to CGI scripts. As discussed above, the
|
|
environment passed to CGI scripts includes standard
|
|
meta-information about the request in addition to any variables
|
|
set within the Apache configuration. For more details, see the
|
|
<a href="howto/cgi.html">CGI tutorial</a>.</p>
|
|
|
|
|
|
<h3><a name="ssi-pages">SSI Pages</a></h3>
|
|
|
|
|
|
<p>Server-parsed (SSI) documents processed by mod_include's
|
|
<code>INCLUDES</code> filter can print environment variables
|
|
using the <code>echo</code> element, and can use environment
|
|
variables in flow control elements to makes parts of a page
|
|
conditional on characteristics of a request. Apache also
|
|
provides SSI pages with the standard CGI environment variables
|
|
as discussed above. For more details, see the <a href="howto/ssi.html">SSI tutorial</a>.</p>
|
|
|
|
|
|
<h3><a name="access-control">Access Control</a></h3>
|
|
|
|
|
|
<p>Access to the server can be controlled based on the value of
|
|
environment variables using the <code>allow from env=</code>
|
|
and <code>deny from env=</code> directives. In combination with
|
|
<a href="./mod/mod_setenvif.html#setenvif" class="directive"><code class="directive">SetEnvIf</code></a>, this
|
|
allows for flexible control of access to the server based on
|
|
characteristics of the client. For example, you can use these
|
|
directives to deny access to a particular browser (User-Agent).
|
|
</p>
|
|
|
|
|
|
<h3><a name="logging">Conditional Logging</a></h3>
|
|
|
|
|
|
<p>Environment variables can be logged in the access log using
|
|
the <a href="./mod/mod_log_config.html#logformat" class="directive"><code class="directive">LogFormat</code></a>
|
|
option <code>%e</code>. In addition, the decision on whether
|
|
or not to log requests can be made based on the status of
|
|
environment variables using the conditional form of the
|
|
<a href="./mod/mod_log_config.html#customlog" class="directive"><code class="directive">CustomLog</code></a>
|
|
directive. In combination with <a href="./mod/mod_setenvif.html#setenvif" class="directive"><code class="directive">SetEnvIf</code></a> this allows for flexible control of which
|
|
requests are logged. For example, you can choose not to log
|
|
requests for filenames ending in <code>gif</code>, or you can
|
|
choose to only log requests from clients which are outside your
|
|
subnet.</p>
|
|
|
|
|
|
<h3><a name="response-headers">Conditional Response Headers</a></h3>
|
|
|
|
|
|
<p>The <a href="./mod/mod_headers.html#header" class="directive"><code class="directive">Header</code></a>
|
|
directive can use the presence or
|
|
absence of an environment variable to determine whether or not
|
|
a certain HTTP header will be placed in the response to the
|
|
client. This allows, for example, a certain response header to
|
|
be sent only if a corresponding header is received in the
|
|
request from the client.</p>
|
|
|
|
|
|
<h3><a name="url-rewriting">URL Rewriting</a></h3>
|
|
|
|
|
|
<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in
|
|
the <a href="./mod/mod_rewrite.html#rewritecond" class="directive"><code class="directive">RewriteCond</code></a>
|
|
allows mod_rewrite's rewrite
|
|
engine to make decisions conditional on environment variables.
|
|
Note that the variables accessible in mod_rewrite without the
|
|
<code>ENV:</code> prefix are not actually environment
|
|
variables. Rather, they are variables special to mod_rewrite
|
|
which cannot be accessed from other modules.</p>
|
|
|
|
<h2><a name="special">Special Purpose Environment Variables</a></h2>
|
|
|
|
|
|
<p>Interoperability problems have led to the introduction of
|
|
mechanisms to modify the way Apache behaves when talking to
|
|
particular clients. To make these mechanisms as flexible as
|
|
possible, they are invoked by defining environment variables,
|
|
typically with <a href="./mod/mod_setenvif.html#browsermatch" class="directive"><code class="directive">BrowserMatch</code></a>,
|
|
though <a href="./mod/mod_env.html#setenv" class="directive"><code class="directive">SetEnv</code></a> and
|
|
<a href="./mod/mod_env.html#passenv" class="directive"><code class="directive">PassEnv</code></a> could also be used,
|
|
for example.</p>
|
|
|
|
<h3><a name="downgrade">downgrade-1.0</a></h3>
|
|
|
|
|
|
<p>This forces the request to be treated as a HTTP/1.0 request
|
|
even if it was in a later dialect.</p>
|
|
|
|
|
|
<h3><a name="force-no-vary">force-no-vary</a></h3>
|
|
|
|
|
|
<p>This causes any <code>Vary</code> fields to be removed from
|
|
the response header before it is sent back to the client. Some
|
|
clients don't interpret this field correctly (see the <a href="misc/known_client_problems.html">known client
|
|
problems</a> page); setting this variable can work around this
|
|
problem. Setting this variable also implies
|
|
<strong>force-response-1.0</strong>.</p>
|
|
|
|
|
|
<h3><a name="force-response">force-response-1.0</a></h3>
|
|
|
|
|
|
<p>This forces an HTTP/1.0 response when set. It was originally
|
|
implemented as a result of a problem with AOL's proxies. Some
|
|
clients may not behave correctly when given an HTTP/1.1
|
|
response, and this can be used to interoperate with them.</p>
|
|
|
|
|
|
<h3><a name="nokeepalive">nokeepalive</a></h3>
|
|
|
|
|
|
<p>This disables <a href="./mod/core.html#keepalive" class="directive"><code class="directive">KeepAlive</code></a> when set.</p>
|
|
|
|
|
|
<h3><a name="redirect-carefully">redirect-carefully</a></h3>
|
|
|
|
|
|
<p>This forces the server to be more careful when sending a redirect
|
|
to the client. This is typically used when a client has a known
|
|
problem handling redirects. This was originally implemented as a
|
|
result of a problem with Microsoft's WebFolders software which has
|
|
a problem handling redirects on directory resources via DAV
|
|
methods.</p>
|
|
|
|
|
|
<h2><a name="examples">Examples</a></h2>
|
|
|
|
|
|
<h3><a name="misbehaving">Changing protocol behavior with misbehaving clients</a></h3>
|
|
|
|
|
|
<p>We recommend that the following lines be included in
|
|
httpd.conf to deal with known client problems.</p>
|
|
<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><pre>
|
|
#
|
|
# The following directives modify normal HTTP response behavior.
|
|
# The first directive disables keepalive for Netscape 2.x and browsers that
|
|
# spoof it. There are known problems with these browser implementations.
|
|
# The second directive is for Microsoft Internet Explorer 4.0b2
|
|
# which has a broken HTTP/1.1 implementation and does not properly
|
|
# support keepalive when it is used on 301 or 302 (redirect) responses.
|
|
#
|
|
BrowserMatch "Mozilla/2" nokeepalive
|
|
BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
|
|
|
|
#
|
|
# The following directive disables HTTP/1.1 responses to browsers which
|
|
# are in violation of the HTTP/1.0 spec by not being able to grok a
|
|
# basic 1.1 response.
|
|
#
|
|
BrowserMatch "RealPlayer 4\.0" force-response-1.0
|
|
BrowserMatch "Java/1\.0" force-response-1.0
|
|
BrowserMatch "JDK/1\.0" force-response-1.0</pre></code></td></tr></table></blockquote>
|
|
|
|
|
|
<h3><a name="no-img-log">Do not log requests for images in the access log</a></h3>
|
|
|
|
|
|
<p>This example keeps requests for images from appearing in the
|
|
access log. It can be easily modified to prevent logging of
|
|
particular directories, or to prevent logging of requests
|
|
coming from particular hosts.</p>
|
|
<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><pre>
|
|
SetEnvIf Request_URI \.gif image-request
|
|
SetEnvIf Request_URI \.jpg image-request
|
|
SetEnvIf Request_URI \.png image-request
|
|
CustomLog logs/access_log common env=!image-request</pre></code></td></tr></table></blockquote>
|
|
|
|
|
|
<h3><a name="image-theft">Prevent "Image Theft"</a></h3>
|
|
|
|
|
|
<p>This example shows how to keep people not on your server
|
|
from using images on your server as inline-images on their
|
|
pages. This is not a recommended configuration, but it can work
|
|
in limited circumstances. We assume that all your images are in
|
|
a directory called /web/images.</p>
|
|
<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code><pre>
|
|
SetEnvIf Referer "^http://www.example.com/" local_referal
|
|
# Allow browsers that do not send Referer info
|
|
SetEnvIf Referer "^$" local_referal
|
|
<Directory /web/images>
|
|
Order Deny,Allow
|
|
Deny from all
|
|
Allow from env=local_referal
|
|
</Directory></pre></code></td></tr></table></blockquote>
|
|
|
|
<p>For more information about this technique, see the
|
|
ApacheToday tutorial " <a href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
|
|
Keeping Your Images from Adorning Other Sites</a>".</p>
|
|
|
|
</blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img src="./images/index.gif" alt="Index"/></a><a href="./"><img src="./images/home.gif" alt="Home"/></a></body></html> |