1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5 6<html xmlns="http://www.w3.org/1999/xhtml"> 7 <head> 8 <meta name="generator" content="HTML Tidy, see www.w3.org" /> 9 10 <title>Environment Variables in Apache</title> 11 </head> 12 <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 13 14 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 15 vlink="#000080" alink="#FF0000"> 16 <div align="CENTER"> 17 <img src="images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 18 19 <h3>Apache HTTP Server</h3> 20 </div> 21 22 23 24 <h1 align="center">Environment Variables in Apache</h1> 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 46 <ul> 47 <li><a href="#setting">Setting Environment Variables</a></li> 48 49 <li><a href="#using">Using Environment Variables</a></li> 50 51 <li><a href="#special">Special Purpose Environment 52 Variables</a></li> 53 54 <li><a href="#examples">Examples</a></li> 55 </ul> 56 <hr /> 57 58 <h2><a id="setting" name="setting">Setting Environment 59 Variables</a></h2> 60 61 <table border="1"> 62 <tr> 63 <td valign="top"><strong>Related Modules</strong><br /> 64 <br /> 65 <a href="mod/mod_env.html">mod_env</a><br /> 66 <a href="mod/mod_rewrite.html">mod_rewrite</a><br /> 67 <a href="mod/mod_setenvif.html">mod_setenvif</a><br /> 68 <a href="mod/mod_unique_id.html">mod_unique_id</a><br /> 69 </td> 70 71 <td valign="top"><strong>Related Directives</strong><br /> 72 <br /> 73 <a 74 href="mod/mod_setenvif.html#browsermatch">BrowserMatch</a><br /> 75 <a 76 href="mod/mod_setenvif.html#browsermatchnocase">BrowserMatchNoCase</a><br /> 77 <a href="mod/mod_env.html#passenv">PassEnv</a><br /> 78 <a 79 href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br /> 80 <a href="mod/mod_env.html#setenv">SetEnv</a><br /> 81 <a 82 href="mod/mod_setenvif.html#setenvif">SetEnvIf</a><br /> 83 <a 84 href="mod/mod_setenvif.html#setenvifnocase">SetEnvIfNoCase</a><br /> 85 <a href="mod/mod_env.html#unsetenv">UnsetEnv</a><br /> 86 </td> 87 </tr> 88 </table> 89 90 <h3>Basic Environment Manipulation</h3> 91 92 <p>The most basic way to set an environment variable in Apache 93 is using the unconditional <code>SetEnv</code> directive. 94 Variables may also be passed from the environment of the shell 95 which started the server using the <code>PassEnv</code> 96 directive.</p> 97 98 <h3>Conditional Per-Request Settings</h3> 99 100 <p>For additional flexibility, the directives provided by 101 mod_setenvif allow environment variables to be set on a 102 per-request basis, conditional on characteristics of particular 103 requests. For example, a variable could be set only when a 104 specific browser (User-Agent) is making a request, or only when 105 a specific Referer [sic] header is found. Even more flexibility 106 is available through the mod_rewrite's <code>RewriteRule</code> 107 which uses the <code>[E=...]</code> option to set environment 108 variables.</p> 109 110 <h3>Unique Identifiers</h3> 111 112 <p>Finally, mod_unique_id sets the environment variable 113 <code>UNIQUE_ID</code> for each request to a value which is 114 guaranteed to be unique across "all" requests under very 115 specific conditions.</p> 116 117 <h3>Standard CGI Variables</h3> 118 119 <p>In addition to all environment variables set within the 120 Apache configuration and passed from the shell, CGI scripts and 121 SSI pages are provided with a set of environment variables 122 containing meta-information about the request as required by 123 the <a href="FAQ.html#cgi-spec">CGI specification</a>.</p> 124 125 <h3>Some Caveats</h3> 126 127 <ul> 128 <li>It is not possible to override or change the standard CGI 129 variables using the environment manipulation directives.</li> 130 131 <li>When <a href="suexec.html">suexec</a> is used to launch 132 CGI scripts, the environment will be cleaned down to a set of 133 <em>safe</em> variables before CGI scripts are launched. The 134 list of <em>safe</em> variables is defined at compile-time in 135 <code>suexec.c</code>.</li> 136 137 <li>For portability reasons, the names of environment 138 variables may contain only letters, numbers, and the 139 underscore character. In addition, the first character may 140 not be a number. Characters which do not match this 141 restriction will be replaced by an underscore when passed to 142 CGI scripts and SSI pages.</li> 143 </ul> 144 <hr /> 145 146 <h2><a id="using" name="using">Using Environment 147 Variables</a></h2> 148 149 <table border="1"> 150 <tr> 151 <td valign="top"><strong>Related Modules</strong><br /> 152 <br /> 153 <a href="mod/mod_access.html">mod_access</a><br /> 154 <a href="mod/mod_cgi.html">mod_cgi</a><br /> 155 <a href="mod/mod_include.html">mod_include</a><br /> 156 <a href="mod/mod_log_config.html">mod_log_config</a><br /> 157 <a href="mod/mod_rewrite.html">mod_rewrite</a><br /> 158 </td> 159 160 <td valign="top"><strong>Related Directives</strong><br /> 161 <br /> 162 <a href="mod/mod_access.html#allow">Allow</a><br /> 163 <a 164 href="mod/mod_log_config.html#customlog">CustomLog</a><br /> 165 <a href="mod/mod_access.html#deny">Deny</a><br /> 166 <a 167 href="mod/mod_log_config.html#logformat">LogFormat</a><br /> 168 <a 169 href="mod/mod_rewrite.html#RewriteCond">RewriteCond</a><br /> 170 <a 171 href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br /> 172 </td> 173 </tr> 174 </table> 175 176 <h3>CGI Scripts</h3> 177 178 <p>One of the primary uses of environment variables is to 179 communicate information to CGI scripts. As discussed above, the 180 environment passed to CGI scripts includes standard 181 meta-information about the request in addition to any variables 182 set within the Apache configuration. For more details, see the 183 <a href="howto/cgi.html">CGI tutorial</a>.</p> 184 185 <h3>SSI Pages</h3> 186 187 <p>Server-parsed (SSI) documents processed by mod_include's 188 <code>server-parsed</code> handler can print environment 189 variables using the <code>echo</code> element, and can use 190 environment variables in flow control elements to makes parts 191 of a page conditional on characteristics of a request. Apache 192 also provides SSI pages with the standard CGI environment 193 variables as discussed above. For more details, see the <a 194 href="howto/ssi.html">SSI tutorial</a>.</p> 195 196 <h3>Access Control</h3> 197 198 <p>Access to the server can be controlled based on the value of 199 environment variables using the <code>allow from env=</code> 200 and <code>deny from env=</code> directives. In combination with 201 <code>SetEnvIf</code>, this allows for flexible control of 202 access to the server based on characteristics of the client. 203 For example, you can use these directives to deny access to a 204 particular browser (User-Agent).</p> 205 206 <h3>Conditional Logging</h3> 207 208 <p>Environment variables can be logged in the access log using 209 the <code>LogFormat</code> option <code>%e</code>. In addition, 210 the decision on whether or not to log requests can be made 211 based on the status of environment variables using the 212 conditional form of the <code>CustomLog</code> directive. In 213 combination with <code>SetEnvIf</code> this allows for flexible 214 control of which requests are logged. For example, you can 215 choose not to log requests for filenames ending in 216 <code>gif</code>, or you can choose to only log requests from 217 clients which are outside your subnet.</p> 218 219 <h3>URL Rewriting</h3> 220 221 <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in 222 the <code>RewriteCond</code> allows mod_rewrite's rewrite 223 engine to make decisions conditional on environment variables. 224 Note that the variables accessible in mod_rewrite without the 225 <code>ENV:</code> prefix are not actually environment 226 variables. Rather, they are variables special to mod_rewrite 227 which cannot be accessed from other modules.</p> 228 <hr /> 229 230 <h2><a id="special" name="special">Special Purpose Environment 231 Variables</a></h2> 232 233 <p>Interoperability problems have led to the introduction of 234 mechanisms to modify the way Apache behaves when talking to 235 particular clients. To make these mechanisms as flexible as 236 possible, they are invoked by defining environment variables, 237 typically with <a 238 href="mod/mod_setenvif.html#browsermatch">BrowserMatch</a>, 239 though <a href="mod/mod_env.html#setenv">SetEnv</a> and <a 240 href="mod/mod_env.html#passenv">PassEnv</a> could also be used, 241 for example.</p> 242 243 <h2>downgrade-1.0</h2> 244 245 <p>This forces the request to be treated as a HTTP/1.0 request 246 even if it was in a later dialect.</p> 247 248 <h2>force-no-vary</h2> 249 250 <p>This causes any <code>Vary</code> fields to be removed from 251 the response header before it is sent back to the client. Some 252 clients don't interpret this field correctly (see the <a 253 href="misc/known_client_problems.html">known client 254 problems</a> page); setting this variable can work around this 255 problem. Setting this variable also implies 256 <strong>force-response-1.0</strong>.</p> 257 258 <h2>force-response-1.0</h2> 259 260 <p>This forces an HTTP/1.0 response when set. It was originally 261 implemented as a result of a problem with AOL's proxies. Some 262 clients may not behave correctly when given an HTTP/1.1 263 response, and this can be used to interoperate with them.</p> 264 265 <h2>nokeepalive</h2> 266 267 <p>This disables <a 268 href="mod/core.html#keepalive">KeepAlive</a> when set.</p> 269 270 <h2>suppress-error-charset</h2> 271 <p><i>Available in versions after 1.3.26 and 2.0.40</i></p> 272 <p>When Apache issues a redirect in response to a client request, 273 the response includes some actual text to be displayed in case 274 the client can't (or doesn't) automatically follow the redirection. 275 Apache ordinarily labels this text according to the character set 276 which it uses, which is ISO-8859-1.</p> 277 <p> However, if the redirection is to a page that uses a different 278 character set, some broken browser versions will try to use the 279 character set from the redirection text rather than the actual page. 280 This can result in Greek, for instance, being incorrectly rendered.</p> 281 <p>Setting this environment variable causes Apache to omit the character 282 set for the redirection text, and these broken browsers will then correctly 283 use that of the destination page.</p> 284 <hr /> 285 286 <h2><a id="examples" name="examples">Examples</a></h2> 287 288 <h3>Changing protocol behavior with misbehaving clients</h3> 289 290 <p>We recommend that the following lines be included in 291 httpd.conf to deal with known client problems.</p> 292<pre> 293# 294# The following directives modify normal HTTP response behavior. 295# The first directive disables keepalive for Netscape 2.x and browsers that 296# spoof it. There are known problems with these browser implementations. 297# The second directive is for Microsoft Internet Explorer 4.0b2 298# which has a broken HTTP/1.1 implementation and does not properly 299# support keepalive when it is used on 301 or 302 (redirect) responses. 300# 301BrowserMatch "Mozilla/2" nokeepalive 302BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 303 304# 305# The following directive disables HTTP/1.1 responses to browsers which 306# are in violation of the HTTP/1.0 spec by not being able to grok a 307# basic 1.1 response. 308# 309BrowserMatch "RealPlayer 4\.0" force-response-1.0 310BrowserMatch "Java/1\.0" force-response-1.0 311BrowserMatch "JDK/1\.0" force-response-1.0 312</pre> 313 314 <h3>Do not log requests for images in the access log</h3> 315 316 <p>This example keeps requests for images from appearing in the 317 access log. It can be easily modified to prevent logging of 318 particular directories, or to prevent logging of requests 319 coming from particular hosts.</p> 320<pre> 321 SetEnvIf Request_URI \.gif image-request 322 SetEnvIf Request_URI \.jpg image-request 323 SetEnvIf Request_URI \.png image-request 324 CustomLog logs/access_log env=!image-request 325</pre> 326 327 <h3>Prevent "Image Theft"</h3> 328 329 <p>This example shows how to keep people not on your server 330 from using images on your server as inline-images on their 331 pages. This is not a recommended configuration, but it can work 332 in limited circumstances. We assume that all your images are in 333 a directory called /web/images.</p> 334<pre> 335 SetEnvIf Referer "^http://www.example.com/" local_referal 336 # Allow browsers that do not send Referer info 337 SetEnvIf Referer "^$" local_referal 338 <Directory /web/images> 339 Order Deny,Allow 340 Deny from all 341 Allow from env=local_referal 342 </Directory> 343</pre> 344 345 <p><em>Note:</em> spelling of 'referer' and 'referal' is 346 intentional.</p> 347 348 <p>For more information about this technique, see the 349 ApacheToday tutorial " <a 350 href="http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-PS"> 351 Keeping Your Images from Adorning Other Sites</a>".</p> 352 <hr /> 353 354 <h3 align="CENTER">Apache HTTP Server</h3> 355 <a href="./"><img src="images/index.gif" alt="Index" /></a> 356 357 </body> 358</html> 359 360 361 362
