home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 November / PCWorld_2003-11_cd.bin / Komunik / apache / apache_2.0.47-win32-x86-no_ssl.msi / Data.Cab / F250515_env.html.en < prev    next >
Extensible Markup Language  |  2003-06-29  |  23KB  |  397 lines
  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
  4.         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  5.               This file is generated from xml source: DO NOT EDIT
  6.         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  7.       -->
  8. <title>Environment Variables in Apache - Apache HTTP Server</title>
  9. <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10. <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11. <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12. <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  13. <body id="manual-page"><div id="page-header">
  14. <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  15. <p class="apache">Apache HTTP Server Version 2.0</p>
  16. <img alt="" src="./images/feather.gif" /></div>
  17. <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
  18. <div id="path">
  19. <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Environment Variables in Apache</h1>
  20. <div class="toplang">
  21. <p><span>Available Languages: </span><a href="./en/env.html" title="English"> en </a> |
  22. <a href="./ja/env.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
  23. <a href="./ko/env.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
  24. </div>
  25.  
  26.     <p>The Apache HTTP Server provides a mechanism for storing
  27.     information in named variables that are called <em>environment
  28.     variables</em>. This information can be used to control various
  29.     operations such as logging or access control. The variables are
  30.     also used as a mechanism to communicate with external programs
  31.     such as CGI scripts. This document discusses different ways to
  32.     manipulate and use these variables.</p>
  33.  
  34.     <p>Although these variables are referred to as <em>environment
  35.     variables</em>, they are not the same as the environment
  36.     variables controlled by the underlying operating system.
  37.     Instead, these variables are stored and manipulated in an
  38.     internal Apache structure. They only become actual operating
  39.     system environment variables when they are provided to CGI
  40.     scripts and Server Side Include scripts. If you wish to
  41.     manipulate the operating system environment under which the
  42.     server itself runs, you must use the standard environment
  43.     manipulation mechanisms provided by your operating system
  44.     shell.</p>
  45.   </div>
  46. <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#setting">Setting Environment Variables</a></li>
  47. <li><img alt="" src="./images/down.gif" /> <a href="#using">Using Environment Variables</a></li>
  48. <li><img alt="" src="./images/down.gif" /> <a href="#special">Special Purpose Environment Variables</a></li>
  49. <li><img alt="" src="./images/down.gif" /> <a href="#examples">Examples</a></li>
  50. </ul></div>
  51. <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  52. <div class="section">
  53. <h2><a name="setting" id="setting">Setting Environment Variables</a></h2>
  54.     
  55.     <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_env.html">mod_env</a></code></li><li><code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code></li><li><code class="module"><a href="./mod/mod_setenvif.html">mod_setenvif</a></code></li><li><code class="module"><a href="./mod/mod_unique_id.html">mod_unique_id</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code></li><li><code class="directive"><a href="./mod/mod_setenvif.html#browsermatchnocase">BrowserMatchNoCase</a></code></li><li><code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code></li><li><code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code></li><li><code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code></li><li><code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code></li><li><code class="directive"><a href="./mod/mod_setenvif.html#setenvifnocase">SetEnvIfNoCase</a></code></li><li><code class="directive"><a href="./mod/mod_env.html#unsetenv">UnsetEnv</a></code></li></ul></td></tr></table>
  56.  
  57.     <h3><a name="basic-manipulation" id="basic-manipulation">Basic Environment Manipulation</a></h3>
  58.         
  59.  
  60.         <p>The most basic way to set an environment variable in Apache
  61.         is using the unconditional <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> directive. Variables may also be passed from
  62.         the environment of the shell which started the server using the
  63.         <code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code> directive.</p>
  64.  
  65.     
  66.     <h3><a name="conditional" id="conditional">Conditional Per-Request Settings</a></h3>
  67.         
  68.  
  69.         <p>For additional flexibility, the directives provided by
  70.         mod_setenvif allow environment variables to be set on a
  71.         per-request basis, conditional on characteristics of particular
  72.         requests. For example, a variable could be set only when a
  73.         specific browser (User-Agent) is making a request, or only when
  74.         a specific Referer [sic] header is found. Even more flexibility
  75.         is available through the mod_rewrite's <code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> which uses the 
  76.         <code>[E=...]</code> option to set environment variables.</p>
  77.  
  78.     
  79.     <h3><a name="unique-identifiers" id="unique-identifiers">Unique Identifiers</a></h3>
  80.         
  81.  
  82.         <p>Finally, mod_unique_id sets the environment variable
  83.         <code>UNIQUE_ID</code> for each request to a value which is
  84.         guaranteed to be unique across "all" requests under very
  85.         specific conditions.</p>
  86.  
  87.     
  88.     <h3><a name="standard-cgi" id="standard-cgi">Standard CGI Variables</a></h3>
  89.         
  90.  
  91.         <p>In addition to all environment variables set within the
  92.         Apache configuration and passed from the shell, CGI scripts and
  93.         SSI pages are provided with a set of environment variables
  94.         containing meta-information about the request as required by
  95.         the <a href="http://cgi-spec.golux.com/">CGI
  96.         specification</a>.</p>
  97.  
  98.     
  99.     <h3><a name="caveats" id="caveats">Some Caveats</a></h3>
  100.         
  101.  
  102.         <ul>
  103.           <li>It is not possible to override or change the standard CGI
  104.           variables using the environment manipulation directives.</li>
  105.  
  106.           <li>When <a href="suexec.html">suexec</a> is used to launch
  107.           CGI scripts, the environment will be cleaned down to a set of
  108.           <em>safe</em> variables before CGI scripts are launched. The
  109.           list of <em>safe</em> variables is defined at compile-time in
  110.           <code>suexec.c</code>.</li>
  111.  
  112.           <li>For portability reasons, the names of environment
  113.           variables may contain only letters, numbers, and the
  114.           underscore character. In addition, the first character may
  115.           not be a number. Characters which do not match this
  116.           restriction will be replaced by an underscore when passed to
  117.           CGI scripts and SSI pages.</li>
  118.         </ul>
  119.     
  120.   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  121. <div class="section">
  122. <h2><a name="using" id="using">Using Environment Variables</a></h2>
  123.     
  124.  
  125.     <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_access.html">mod_access</a></code></li><li><code class="module"><a href="./mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code></li><li><code class="module"><a href="./mod/mod_headers.html">mod_headers</a></code></li><li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code></li><li><code class="module"><a href="./mod/mod_log_config.html">mod_log_config</a></code></li><li><code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_access.html#allow">Allow</a></code></li><li><code class="directive"><a href="./mod/mod_log_config.html#customlog">CustomLog</a></code></li><li><code class="directive"><a href="./mod/mod_access.html#deny">Deny</a></code></li><li><code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code></li><li><code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code></li><li><code class="directive"><a href="./mod/mod_log_config.html#logformat">LogFormat</a></code></li><li><code class="directive"><a href="./mod/mod_rewrite.html#rewritecond">RewriteCond</a></code></li><li><code class="directive"><a href="./mod/mod_rewrite.html#rewriterule">RewriteRule</a></code></li></ul></td></tr></table>
  126.  
  127.     <h3><a name="cgi-scripts" id="cgi-scripts">CGI Scripts</a></h3>
  128.         
  129.  
  130.         <p>One of the primary uses of environment variables is to
  131.         communicate information to CGI scripts. As discussed above, the
  132.         environment passed to CGI scripts includes standard
  133.         meta-information about the request in addition to any variables
  134.         set within the Apache configuration. For more details, see the
  135.         <a href="howto/cgi.html">CGI tutorial</a>.</p>
  136.  
  137.     
  138.     <h3><a name="ssi-pages" id="ssi-pages">SSI Pages</a></h3>
  139.         
  140.  
  141.         <p>Server-parsed (SSI) documents processed by mod_include's
  142.         <code>INCLUDES</code> filter can print environment variables
  143.         using the <code>echo</code> element, and can use environment
  144.         variables in flow control elements to makes parts of a page
  145.         conditional on characteristics of a request. Apache also
  146.         provides SSI pages with the standard CGI environment variables
  147.         as discussed above. For more details, see the <a href="howto/ssi.html">SSI tutorial</a>.</p>
  148.  
  149.     
  150.     <h3><a name="access-control" id="access-control">Access Control</a></h3>
  151.         
  152.  
  153.         <p>Access to the server can be controlled based on the value of
  154.         environment variables using the <code>allow from env=</code>
  155.         and <code>deny from env=</code> directives. In combination with
  156.         <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>, this 
  157.         allows for flexible control of access to the server based on 
  158.         characteristics of the client. For example, you can use these 
  159.         directives to deny access to a particular browser (User-Agent).
  160.         </p>
  161.  
  162.     
  163.     <h3><a name="logging" id="logging">Conditional Logging</a></h3>
  164.         
  165.  
  166.         <p>Environment variables can be logged in the access log using
  167.         the <code class="directive"><a href="./mod/mod_log_config.html#logformat">LogFormat</a></code>
  168.         option <code>%e</code>. In addition, the decision on whether
  169.         or not to log requests can be made based on the status of 
  170.         environment variables using the conditional form of the 
  171.         <code class="directive"><a href="./mod/mod_log_config.html#customlog">CustomLog</a></code>
  172.         directive. In combination with <code class="directive"><a href="./mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> this allows for flexible control of which 
  173.         requests are logged. For example, you can choose not to log 
  174.         requests for filenames ending in <code>gif</code>, or you can
  175.         choose to only log requests from clients which are outside your
  176.         subnet.</p>
  177.  
  178.     
  179.     <h3><a name="response-headers" id="response-headers">Conditional Response Headers</a></h3>
  180.         
  181.  
  182.         <p>The <code class="directive"><a href="./mod/mod_headers.html#header">Header</a></code>
  183.         directive can use the presence or
  184.         absence of an environment variable to determine whether or not
  185.         a certain HTTP header will be placed in the response to the
  186.         client. This allows, for example, a certain response header to
  187.         be sent only if a corresponding header is received in the
  188.         request from the client.</p>
  189.  
  190.     
  191.  
  192.     <h3><a name="external-filter" id="external-filter">External Filter Activation</a></h3>
  193.         
  194.  
  195.         <p>External filters configured by <code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code>
  196.         using the <code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code> directive can
  197.         by activated conditional on an environment variable using the
  198.         <code>disableenv=</code> and <code>enableenv=</code> options.</p>
  199.     
  200.  
  201.     <h3><a name="url-rewriting" id="url-rewriting">URL Rewriting</a></h3>
  202.         
  203.  
  204.         <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in
  205.         the <code class="directive"><a href="./mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
  206.         allows mod_rewrite's rewrite
  207.         engine to make decisions conditional on environment variables.
  208.         Note that the variables accessible in mod_rewrite without the
  209.         <code>ENV:</code> prefix are not actually environment
  210.         variables. Rather, they are variables special to mod_rewrite
  211.         which cannot be accessed from other modules.</p>
  212.     
  213.   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  214. <div class="section">
  215. <h2><a name="special" id="special">Special Purpose Environment Variables</a></h2>
  216.     
  217.  
  218.         <p>Interoperability problems have led to the introduction of
  219.         mechanisms to modify the way Apache behaves when talking to
  220.         particular clients. To make these mechanisms as flexible as
  221.         possible, they are invoked by defining environment variables,
  222.         typically with <code class="directive"><a href="./mod/mod_setenvif.html#browsermatch">BrowserMatch</a></code>,
  223.         though <code class="directive"><a href="./mod/mod_env.html#setenv">SetEnv</a></code> and 
  224.         <code class="directive"><a href="./mod/mod_env.html#passenv">PassEnv</a></code> could also be used,
  225.         for example.</p>
  226.  
  227.     <h3><a name="downgrade" id="downgrade">downgrade-1.0</a></h3>
  228.         
  229.  
  230.         <p>This forces the request to be treated as a HTTP/1.0 request
  231.         even if it was in a later dialect.</p>
  232.  
  233.     
  234.     <h3><a name="force-no-vary" id="force-no-vary">force-no-vary</a></h3>
  235.         
  236.  
  237.         <p>This causes any <code>Vary</code> fields to be removed from
  238.         the response header before it is sent back to the client. Some
  239.         clients don't interpret this field correctly (see the <a href="misc/known_client_problems.html">known client
  240.         problems</a> page); setting this variable can work around this
  241.         problem. Setting this variable also implies
  242.         <strong>force-response-1.0</strong>.</p>
  243.  
  244.     
  245.     <h3><a name="force-response" id="force-response">force-response-1.0</a></h3>
  246.         
  247.  
  248.       <p>This forces an HTTP/1.0 response to clients making an HTTP/1.0
  249.       request. It was originally
  250.       implemented as a result of a problem with AOL's proxies. Some
  251.       HTTP/1.0 clients may not behave correctly when given an HTTP/1.1
  252.       response, and this can be used to interoperate with them.</p>
  253.  
  254.     
  255.  
  256.     <h3><a name="gzip-only-text-html" id="gzip-only-text-html">gzip-only-text/html</a></h3>
  257.         
  258.  
  259.         <p>When set to a value of "1", this variable disables the DEFLATE
  260.         output filter provided by <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> for
  261.         content-types other than <code>text/html</code>.</p>
  262.     
  263.  
  264.     <h3><a name="no-gzip" id="no-gzip">no-gzip</a></h3>
  265.  
  266.         <p>When set, the <code>DEFLATE</code> filter of
  267.         <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> will be turned off.</p>
  268.  
  269.     
  270.  
  271.     <h3><a name="nokeepalive" id="nokeepalive">nokeepalive</a></h3>
  272.         
  273.  
  274.         <p>This disables <code class="directive"><a href="./mod/core.html#keepalive">KeepAlive</a></code> when set.</p>
  275.  
  276.     
  277.  
  278.     <h3><a name="prefer-language" id="prefer-language">prefer-language</a></h3>
  279.  
  280.         <p>This influences <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code>'s behaviour. If
  281.         it contains a language tag (such as <code>en</code>, <code>ja</code>
  282.         or <code>x-klingon</code>), <code class="module"><a href="./mod/mod_negotiation.html">mod_negotiation</a></code> tries
  283.         to deliver a variant with that language. If there's no such variant,
  284.         the normal <a href="content-negotiation.html">negotiation</a> process
  285.         applies.</p>
  286.  
  287.     
  288.  
  289.     <h3><a name="redirect-carefully" id="redirect-carefully">redirect-carefully</a></h3>
  290.         
  291.  
  292.         <p>This forces the server to be more careful when sending a redirect
  293.         to the client.  This is typically used when a client has a known
  294.         problem handling redirects.  This was originally implemented as a
  295.         result of a problem with Microsoft's WebFolders software which has
  296.         a problem handling redirects on directory resources via DAV 
  297.         methods.</p>
  298.  
  299.     
  300.  
  301.    <h3><a name="suppress-error-charset" id="suppress-error-charset">suppress-error-charset</a></h3>
  302.        
  303.  
  304.     <p><em>Available in versions after 2.0.40</em></p>
  305.  
  306.     <p>When Apache issues a redirect in response to a client request,
  307.     the response includes some actual text to be displayed in case
  308.     the client can't (or doesn't) automatically follow the redirection.
  309.     Apache ordinarily labels this text according to the character set
  310.     which it uses, which is ISO-8859-1.</p>
  311.     <p> However, if the redirection is to a page that uses a different
  312.     character set, some broken browser versions will try to use the
  313.     character set from the redirection text rather than the actual page.
  314.     This can result in Greek, for instance, being incorrectly rendered.</p>
  315.     <p>Setting this environment variable causes Apache to omit the character
  316.     set for the redirection text, and these broken browsers will then correctly
  317.     use that of the destination page.</p>
  318.  
  319.    
  320.  
  321.   </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  322. <div class="section">
  323. <h2><a name="examples" id="examples">Examples</a></h2>
  324.     
  325.  
  326.     <h3><a name="misbehaving" id="misbehaving">Changing protocol behavior with misbehaving clients</a></h3>
  327.         
  328.  
  329.         <p>We recommend that the following lines be included in
  330.         httpd.conf to deal with known client problems.</p>
  331. <div class="example"><pre>
  332. #
  333. # The following directives modify normal HTTP response behavior.
  334. # The first directive disables keepalive for Netscape 2.x and browsers that
  335. # spoof it. There are known problems with these browser implementations.
  336. # The second directive is for Microsoft Internet Explorer 4.0b2
  337. # which has a broken HTTP/1.1 implementation and does not properly
  338. # support keepalive when it is used on 301 or 302 (redirect) responses.
  339. #
  340. BrowserMatch "Mozilla/2" nokeepalive
  341. BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
  342.  
  343. #
  344. # The following directive disables HTTP/1.1 responses to browsers which
  345. # are in violation of the HTTP/1.0 spec by not being able to grok a
  346. # basic 1.1 response.
  347. #
  348. BrowserMatch "RealPlayer 4\.0" force-response-1.0
  349. BrowserMatch "Java/1\.0" force-response-1.0
  350. BrowserMatch "JDK/1\.0" force-response-1.0</pre></div>
  351.  
  352.     
  353.     <h3><a name="no-img-log" id="no-img-log">Do not log requests for images in the access log</a></h3>
  354.         
  355.  
  356.         <p>This example keeps requests for images from appearing in the
  357.         access log. It can be easily modified to prevent logging of
  358.         particular directories, or to prevent logging of requests
  359.         coming from particular hosts.</p>
  360.     <div class="example"><pre>
  361. SetEnvIf Request_URI \.gif image-request
  362. SetEnvIf Request_URI \.jpg image-request
  363. SetEnvIf Request_URI \.png image-request
  364. CustomLog logs/access_log common env=!image-request</pre></div>
  365.  
  366.     
  367.     <h3><a name="image-theft" id="image-theft">Prevent "Image Theft"</a></h3>
  368.         
  369.  
  370.         <p>This example shows how to keep people not on your server
  371.         from using images on your server as inline-images on their
  372.         pages. This is not a recommended configuration, but it can work
  373.         in limited circumstances. We assume that all your images are in
  374.         a directory called /web/images.</p>
  375.     <div class="example"><pre>
  376. SetEnvIf Referer "^http://www.example.com/" local_referal
  377. # Allow browsers that do not send Referer info
  378. SetEnvIf Referer "^$" local_referal
  379. <Directory /web/images>
  380.    Order Deny,Allow
  381.    Deny from all
  382.    Allow from env=local_referal
  383. </Directory></pre></div>
  384.  
  385.         <p>For more information about this technique, see the
  386.         ApacheToday tutorial " <a href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS">
  387.     Keeping Your Images from Adorning Other Sites</a>".</p>
  388.     
  389.   </div></div>
  390. <div class="bottomlang">
  391. <p><span>Available Languages: </span><a href="./en/env.html" title="English"> en </a> |
  392. <a href="./ja/env.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
  393. <a href="./ko/env.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
  394. </div><div id="footer">
  395. <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
  396. <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
  397. </body></html>