| <?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> |
| |
| <li>When the server looks up a path via an internal |
| <glossary ref="subrequest">subrequest</glossary> such as looking |
| for a <directive module="mod_dir" >DirectoryIndex</directive> |
| or generating a directory listing with <module>mod_autoindex</module>, |
| per-request environment variables are <em>not</em> inherited in the |
| subrequest. Additionally, |
| <directive module="mod_setenvif">SetEnvIf</directive> directives |
| are not separately evaluated in the subrequest due to the API phases |
| <module>mod_setenvif</module> takes action in.</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_authz_core">Require</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_headers</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> |
| Require 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> |