mirror of
https://github.com/apache/httpd.git
synced 2025-11-03 17:53:20 +03:00
74e009ce0a
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1330883 13f79535-47bb-0310-9956-ffa450edef68
533 lines
22 KiB
XML
533 lines
22 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<manualpage metafile="env.xml.meta">
|
|
|
|
<title>Environment Variables in Apache</title>
|
|
|
|
<summary>
|
|
<p>There are two kinds of environment variables that affect
|
|
the Apache HTTP Server.</p>
|
|
|
|
<p>First, there are the environment variables controlled by
|
|
the underlying operating system. These are set before the
|
|
server starts. They can be used in expansions in configuration
|
|
files, and can optionally be passed to CGI scripts and SSI
|
|
using the PassEnv directive.</p>
|
|
|
|
<p>Second, the Apache HTTP Server provides a mechanism for storing
|
|
information in named variables that are also 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>
|
|
</summary>
|
|
|
|
<section id="setting">
|
|
<title>Setting Environment Variables</title>
|
|
<related>
|
|
<modulelist>
|
|
<module>mod_cache</module>
|
|
<module>mod_env</module>
|
|
<module>mod_rewrite</module>
|
|
<module>mod_setenvif</module>
|
|
<module>mod_unique_id</module>
|
|
</modulelist>
|
|
<directivelist>
|
|
<directive module="mod_setenvif">BrowserMatch</directive>
|
|
<directive module="mod_setenvif">BrowserMatchNoCase</directive>
|
|
<directive module="mod_env">PassEnv</directive>
|
|
<directive module="mod_rewrite">RewriteRule</directive>
|
|
<directive module="mod_env">SetEnv</directive>
|
|
<directive module="mod_setenvif">SetEnvIf</directive>
|
|
<directive module="mod_setenvif">SetEnvIfNoCase</directive>
|
|
<directive module="mod_env">UnsetEnv</directive>
|
|
</directivelist>
|
|
</related>
|
|
|
|
<section id="basic-manipulation">
|
|
<title>Basic Environment Manipulation</title>
|
|
|
|
<p>The most basic way to set an environment variable in Apache
|
|
is using the unconditional <directive module="mod_env"
|
|
>SetEnv</directive> directive. Variables may also be passed from
|
|
the environment of the shell which started the server using the
|
|
<directive module="mod_env">PassEnv</directive> directive.</p>
|
|
|
|
</section>
|
|
<section id="conditional">
|
|
<title>Conditional Per-Request Settings</title>
|
|
|
|
<p>For additional flexibility, the directives provided by
|
|
<module>mod_setenvif</module> 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 <module>mod_rewrite</module>'s <directive
|
|
module="mod_rewrite">RewriteRule</directive> which uses the
|
|
<code>[E=...]</code> option to set environment variables.</p>
|
|
|
|
</section>
|
|
<section id="unique-identifiers">
|
|
<title>Unique Identifiers</title>
|
|
|
|
<p>Finally, <module>mod_unique_id</module> 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>
|
|
|
|
</section>
|
|
<section id="standard-cgi">
|
|
<title>Standard CGI Variables</title>
|
|
|
|
<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://www.ietf.org/rfc/rfc3875">CGI
|
|
specification</a>.</p>
|
|
|
|
</section>
|
|
<section id="caveats">
|
|
<title>Some Caveats</title>
|
|
|
|
<ul>
|
|
<li>It is not possible to override or change the standard CGI
|
|
variables using the environment manipulation directives.</li>
|
|
|
|
<li>When <program>suexec</program> 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>
|
|
|
|
<li>A special case are HTTP headers which are passed to CGI
|
|
scripts and the like via environment variables (see below).
|
|
They are converted to uppercase and only dashes are replaced with
|
|
underscores; if the header contains any other (invalid) character,
|
|
the whole header is silently dropped. See <a href="#fixheader">
|
|
below</a> for a workaround.</li>
|
|
|
|
<li>The <directive module="mod_env">SetEnv</directive> directive runs
|
|
late during request processing meaning that directives such as
|
|
<directive module="mod_setenvif">SetEnvIf</directive> and <directive
|
|
module="mod_rewrite">RewriteCond</directive> will not see the
|
|
variables set with it.</li>
|
|
</ul>
|
|
</section>
|
|
</section>
|
|
<section id="using">
|
|
<title>Using Environment Variables</title>
|
|
|
|
<related>
|
|
<modulelist>
|
|
<module>mod_authz_host</module>
|
|
<module>mod_cgi</module>
|
|
<module>mod_ext_filter</module>
|
|
<module>mod_headers</module>
|
|
<module>mod_include</module>
|
|
<module>mod_log_config</module>
|
|
<module>mod_rewrite</module>
|
|
</modulelist>
|
|
<directivelist>
|
|
<directive module="mod_access_compat">Allow</directive>
|
|
<directive module="mod_log_config">CustomLog</directive>
|
|
<directive module="mod_access_compat">Deny</directive>
|
|
<directive module="mod_ext_filter">ExtFilterDefine</directive>
|
|
<directive module="mod_headers">Header</directive>
|
|
<directive module="mod_log_config">LogFormat</directive>
|
|
<directive module="mod_rewrite">RewriteCond</directive>
|
|
<directive module="mod_rewrite">RewriteRule</directive>
|
|
</directivelist>
|
|
</related>
|
|
|
|
<section id="cgi-scripts">
|
|
<title>CGI Scripts</title>
|
|
|
|
<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>
|
|
|
|
</section>
|
|
<section id="ssi-pages">
|
|
<title>SSI Pages</title>
|
|
|
|
<p>Server-parsed (SSI) documents processed by
|
|
<module>mod_include</module>'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>
|
|
|
|
</section>
|
|
<section id="access-control">
|
|
<title>Access Control</title>
|
|
|
|
<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
|
|
<directive module="mod_setenvif">SetEnvIf</directive>, 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>
|
|
|
|
</section>
|
|
<section id="logging">
|
|
<title>Conditional Logging</title>
|
|
|
|
<p>Environment variables can be logged in the access log using
|
|
the <directive module="mod_log_config">LogFormat</directive>
|
|
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
|
|
<directive module="mod_log_config">CustomLog</directive>
|
|
directive. In combination with <directive module="mod_setenvif"
|
|
>SetEnvIf</directive> 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>
|
|
|
|
</section>
|
|
<section id="response-headers">
|
|
<title>Conditional Response Headers</title>
|
|
|
|
<p>The <directive module="mod_headers">Header</directive>
|
|
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>
|
|
|
|
</section>
|
|
|
|
<section id="external-filter">
|
|
<title>External Filter Activation</title>
|
|
|
|
<p>External filters configured by <module>mod_ext_filter</module>
|
|
using the <directive
|
|
module="mod_ext_filter">ExtFilterDefine</directive> directive can
|
|
by activated conditional on an environment variable using the
|
|
<code>disableenv=</code> and <code>enableenv=</code> options.</p>
|
|
</section>
|
|
|
|
<section id="url-rewriting">
|
|
<title>URL Rewriting</title>
|
|
|
|
<p>The <code>%{ENV:<em>variable</em>}</code> form of
|
|
<em>TestString</em> in the <directive module="mod_rewrite"
|
|
>RewriteCond</directive> allows <module>mod_rewrite</module>'s rewrite
|
|
engine to make decisions conditional on environment variables.
|
|
Note that the variables accessible in <module>mod_rewrite</module>
|
|
without the <code>ENV:</code> prefix are not actually environment
|
|
variables. Rather, they are variables special to
|
|
<module>mod_rewrite</module> which cannot be accessed from other
|
|
modules.</p>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="special">
|
|
<title>Special Purpose Environment Variables</title>
|
|
|
|
<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 <directive module="mod_setenvif"
|
|
>BrowserMatch</directive>, though <directive module="mod_env"
|
|
>SetEnv</directive> and <directive module="mod_env"
|
|
>PassEnv</directive> could also be used, for example.</p>
|
|
|
|
<section id="downgrade">
|
|
<title>downgrade-1.0</title>
|
|
|
|
<p>This forces the request to be treated as a HTTP/1.0 request
|
|
even if it was in a later dialect.</p>
|
|
|
|
</section>
|
|
<section id="force-gzip">
|
|
<title>force-gzip</title>
|
|
<p>If you have the <code>DEFLATE</code> filter activated, this
|
|
environment variable will ignore the accept-encoding setting of
|
|
your browser and will send compressed output unconditionally.</p>
|
|
</section>
|
|
<section id="force-no-vary">
|
|
<title>force-no-vary</title>
|
|
|
|
<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; setting this
|
|
variable can work around this problem. Setting this variable
|
|
also implies <strong>force-response-1.0</strong>.</p>
|
|
|
|
</section>
|
|
<section id="force-response">
|
|
<title>force-response-1.0</title>
|
|
|
|
<p>This forces an HTTP/1.0 response to clients making an HTTP/1.0
|
|
request. It was originally
|
|
implemented as a result of a problem with AOL's proxies. Some
|
|
HTTP/1.0 clients may not behave correctly when given an HTTP/1.1
|
|
response, and this can be used to interoperate with them.</p>
|
|
|
|
</section>
|
|
|
|
<section id="gzip-only-text-html">
|
|
<title>gzip-only-text/html</title>
|
|
|
|
<p>When set to a value of "1", this variable disables the
|
|
<code>DEFLATE</code> output filter provided by
|
|
<module>mod_deflate</module> for content-types other than
|
|
<code>text/html</code>. If you'd rather
|
|
use statically compressed files, <module>mod_negotiation</module>
|
|
evaluates the variable as well (not only for gzip, but for all
|
|
encodings that differ from "identity").</p>
|
|
</section>
|
|
|
|
<section id="no-gzip"><title>no-gzip</title>
|
|
|
|
<p>When set, the <code>DEFLATE</code> filter of
|
|
<module>mod_deflate</module> will be turned off and
|
|
<module>mod_negotiation</module> will refuse to deliver encoded
|
|
resources.</p>
|
|
|
|
</section>
|
|
|
|
<section id="no-cache"><title>no-cache</title>
|
|
<p><em>Available in versions 2.2.12 and later</em></p>
|
|
|
|
<p>When set, <module>mod_cache</module> will not save an otherwise
|
|
cacheable response. This environment variable does not influence
|
|
whether a response already in the cache will be served for the current
|
|
request.</p>
|
|
|
|
</section>
|
|
|
|
<section id="nokeepalive">
|
|
<title>nokeepalive</title>
|
|
|
|
<p>This disables <directive module="core">KeepAlive</directive>
|
|
when set.</p>
|
|
|
|
</section>
|
|
|
|
<section id="prefer-language"><title>prefer-language</title>
|
|
|
|
<p>This influences <module>mod_negotiation</module>'s behaviour. If
|
|
it contains a language tag (such as <code>en</code>, <code>ja</code>
|
|
or <code>x-klingon</code>), <module>mod_negotiation</module> tries
|
|
to deliver a variant with that language. If there's no such variant,
|
|
the normal <a href="content-negotiation.html">negotiation</a> process
|
|
applies.</p>
|
|
|
|
</section>
|
|
|
|
<section id="redirect-carefully">
|
|
<title>redirect-carefully</title>
|
|
|
|
<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>
|
|
|
|
</section>
|
|
|
|
<section id="suppress-error-charset">
|
|
<title>suppress-error-charset</title>
|
|
|
|
<p><em>Available in versions after 2.0.54</em></p>
|
|
|
|
<p>When Apache issues a redirect in response to a client request,
|
|
the response includes some actual text to be displayed in case
|
|
the client can't (or doesn't) automatically follow the redirection.
|
|
Apache ordinarily labels this text according to the character set
|
|
which it uses, which is ISO-8859-1.</p>
|
|
|
|
<p> However, if the redirection is to a page that uses a different
|
|
character set, some broken browser versions will try to use the
|
|
character set from the redirection text rather than the actual page.
|
|
This can result in Greek, for instance, being incorrectly rendered.</p>
|
|
|
|
<p>Setting this environment variable causes Apache to omit the character
|
|
set for the redirection text, and these broken browsers will then correctly
|
|
use that of the destination page.</p>
|
|
|
|
<note type="warning">
|
|
<title>Security note</title>
|
|
|
|
<p>Sending error pages without a specified character set may
|
|
allow a cross-site-scripting attack for existing browsers (MSIE)
|
|
which do not follow the HTTP/1.1 specification and attempt to
|
|
"guess" the character set from the content. Such browsers can
|
|
be easily fooled into using the UTF-7 character set, and UTF-7
|
|
content from input data (such as the request-URI) will not be
|
|
escaped by the usual escaping mechanisms designed to prevent
|
|
cross-site-scripting attacks.</p>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="proxy"><title>force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked,
|
|
proxy-sendcl, proxy-chain-auth, proxy-interim-response, proxy-initial-not-pooled</title>
|
|
|
|
<p>These directives alter the protocol behavior of
|
|
<module>mod_proxy</module>. See the <module>mod_proxy</module> and <module>mod_proxy_http</module>
|
|
documentation for more details.</p>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="examples">
|
|
<title>Examples</title>
|
|
|
|
<section id="fixheader">
|
|
<title>Passing broken headers to CGI scripts</title>
|
|
|
|
<p>Starting with version 2.4, Apache is more strict about how HTTP
|
|
headers are converted to environment variables in <module>mod_cgi
|
|
</module> and other modules: Previously any invalid characters
|
|
in header names were simply translated to underscores. This allowed
|
|
for some potential cross-site-scripting attacks via header injection
|
|
(see <a href="http://events.ccc.de/congress/2007/Fahrplan/events/2212.en.html">
|
|
Unusual Web Bugs</a>, slide 19/20).</p>
|
|
|
|
<p>If you have to support a client which sends broken headers and
|
|
which can't be fixed, a simple workaround involving <module>mod_setenvif
|
|
</module> and <module>mod_header</module> allows you to still accept
|
|
these headers:</p>
|
|
|
|
<highlight language="config">
|
|
#
|
|
# The following works around a client sending a broken Accept_Encoding
|
|
# header.
|
|
#
|
|
SetEnvIfNoCase ^Accept.Encoding$ ^(.*)$ fix_accept_encoding=$1
|
|
RequestHeader set Accept-Encoding %{fix_accept_encoding}e env=fix_accept_encoding
|
|
</highlight>
|
|
|
|
</section>
|
|
|
|
<section id="misbehaving">
|
|
<title>Changing protocol behavior with misbehaving clients</title>
|
|
|
|
<p>Earlier versions recommended that the following lines be included in
|
|
httpd.conf to deal with known client problems. Since the affected clients
|
|
are no longer seen in the wild, this configuration is likely no-longer
|
|
necessary.</p>
|
|
<highlight language="config">
|
|
#
|
|
# 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 understand 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
|
|
</highlight>
|
|
|
|
</section>
|
|
<section id="no-img-log">
|
|
<title>Do not log requests for images in the access log</title>
|
|
|
|
<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>
|
|
|
|
<highlight language="config">
|
|
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
|
|
</highlight>
|
|
|
|
</section>
|
|
<section id="image-theft">
|
|
<title>Prevent "Image Theft"</title>
|
|
|
|
<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 <code>/web/images</code>.</p>
|
|
|
|
<highlight language="config">
|
|
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>
|
|
</highlight>
|
|
|
|
<p>For more information about this technique, see the
|
|
"<a href="http://www.serverwatch.com/tutorials/article.php/1132731"
|
|
>Keeping Your Images from Adorning Other Sites</a>"
|
|
tutorial on ServerWatch.</p>
|
|
</section>
|
|
</section>
|
|
</manualpage>
|