| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta name="generator" content="HTML Tidy, see www.w3.org" /> |
| |
| <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 id="setting" 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="http://cgi-spec.golux.com/">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 id="using" 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> 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 id="special" 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> |
| |
| <h2>redirect-carefully</h2> |
| |
| <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> |
| |
| <hr /> |
| <h2><a id="examples" 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> |
| |