mirror of
https://github.com/apache/httpd.git
synced 2025-10-31 19:10:37 +03:00
61be6d5644
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89388 13f79535-47bb-0310-9956-ffa450edef68
329 lines
12 KiB
Plaintext
329 lines
12 KiB
Plaintext
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Environment Variables in Apache</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
<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></li>
|
|
<li><a href="#using">Using Environment Variables</a></li>
|
|
<li><a href="#special">Special Purpose Environment Variables</a></li>
|
|
<li><a href="#examples">Examples</a></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>
|
|
|
|
<a href="mod/mod_env.html">mod_env</a><br>
|
|
<a href="mod/mod_rewrite.html">mod_rewrite</a><br>
|
|
<a href="mod/mod_setenvif.html">mod_setenvif</a><br>
|
|
<a href="mod/mod_unique_id.html">mod_unique_id</a><br>
|
|
|
|
</td><td valign="top">
|
|
<strong>Related Directives</strong><br><br>
|
|
|
|
<A HREF="mod/mod_setenvif.html#BrowserMatch">BrowserMatch</A><br>
|
|
<A HREF="mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A><br>
|
|
<A HREF="mod/mod_env.html#passenv">PassEnv</A><br>
|
|
<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
|
|
<A HREF="mod/mod_env.html#setenv">SetEnv</A><br>
|
|
<A HREF="mod/mod_setenvif.html#SetEnvIf">SetEnvIf</A><br>
|
|
<A HREF="mod/mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A><br>
|
|
<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
|
|
</td></tr></table>
|
|
|
|
<h3>Basic Environment Manipulation</h3>
|
|
|
|
<p>The most basic way to set an environment variable in Apache is
|
|
using the unconditional <code>SetEnv</code> directive. Variables
|
|
may also be passed from the environment of the shell which started
|
|
the server using the <code>PassEnv</code> directive.</p>
|
|
|
|
<h3>Conditional Per-Request Settings</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
|
|
<code>RewriteRule</code> which uses the <code>[E=...]</code> option to
|
|
set environment variables.</p>
|
|
|
|
<h3>Unique Identifiers</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>Standard CGI Variables</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="misc/FAQ.html#cgi-spec">CGI specification</a>.</p>
|
|
|
|
<h3>Some Caveats</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>
|
|
|
|
|
|
<hr>
|
|
|
|
<h2><a name="using">Using Environment Variables</a></h2>
|
|
|
|
<table border=1><tr><td valign="top">
|
|
<strong>Related Modules</strong><br><br>
|
|
|
|
<a href="mod/mod_access.html">mod_access</a><br>
|
|
<a href="mod/mod_cgi.html">mod_cgi</a><br>
|
|
<a href="mod/mod_headers.html">mod_headers</a><br>
|
|
<a href="mod/mod_include.html">mod_include</a><br>
|
|
<a href="mod/mod_log_config.html">mod_log_config</a><br>
|
|
<a href="mod/mod_rewrite.html">mod_rewrite</a><br>
|
|
|
|
</td><td valign="top">
|
|
<strong>Related Directives</strong><br><br>
|
|
|
|
<A HREF="mod/mod_access.html#allow">Allow</A><br>
|
|
<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>
|
|
<A HREF="mod/mod_access.html#deny">Deny</A><br>
|
|
<a href="mod/mod_headers.html#Header">Header</a><br>
|
|
<a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
|
|
<A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
|
|
<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
|
|
|
|
</td></tr></table>
|
|
|
|
<h3>CGI Scripts</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>SSI Pages</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>Access Control</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></a> directives. In combination with
|
|
<code>SetEnvIf</code>, 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>Conditional Logging</h3>
|
|
|
|
<p>Environment variables can be logged in the access log using the
|
|
<code>LogFormat</code> 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
|
|
<code>CustomLog</code> directive. In combination with
|
|
<code>SetEnvIf</code> 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>Conditional Response Headers</h3>
|
|
|
|
<p>The <code>Header</code> 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>URL Rewriting</h3>
|
|
|
|
<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
|
|
<code>RewriteCond</code> 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>
|
|
|
|
<hr>
|
|
|
|
<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">BrowserMatch</A>, though
|
|
<A HREF="mod/mod_env.html#setenv">SetEnv</A> and
|
|
<A HREF="mod/mod_env.html#passenv">PassEnv</A> could also be used, for
|
|
example.
|
|
</P>
|
|
|
|
<H2>downgrade-1.0</H2>
|
|
<P>
|
|
This forces the request to be treated as a HTTP/1.0 request even if it
|
|
was in a later dialect.
|
|
</P>
|
|
|
|
<H2>force-no-vary</H2>
|
|
<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>
|
|
|
|
<H2>force-response-1.0</H2>
|
|
<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>
|
|
|
|
<H2>nokeepalive</H2>
|
|
<P>
|
|
This disables <A HREF="mod/core.html#keepalive">KeepAlive</A> when set.
|
|
</P>
|
|
|
|
|
|
<hr>
|
|
|
|
<h2><a name="examples">Examples</a></h2>
|
|
|
|
<h3>Changing protocol behavior with misbehaving clients</h3>
|
|
|
|
<p>We recommend that the following lines be included in httpd.conf
|
|
to deal with known client problems.</p>
|
|
|
|
<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>
|
|
|
|
<h3>Do not log requests for images in the access log</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>
|
|
|
|
<pre>
|
|
SetEnvIf Request_URI \.gif image-request
|
|
SetEnvIf Request_URI \.jpg image-request
|
|
SetEnvIf Request_URI \.png image-request
|
|
CustomLog logs/access_log env=!image-request
|
|
</pre>
|
|
|
|
<h3>Prevent "Image Theft"</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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|