granicus.if.org Git - apache/blob - docs/manual/mod/mod_setenvif.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $Revision: 1.14 $ -->
   5
   6 <!--
   7  Copyright 2002-2004 The Apache Software Foundation
   8
   9  Licensed under the Apache License, Version 2.0 (the "License");
  10  you may not use this file except in compliance with the License.
  11  You may obtain a copy of the License at
  12
  13      http://www.apache.org/licenses/LICENSE-2.0
  14
  15  Unless required by applicable law or agreed to in writing, software
  16  distributed under the License is distributed on an "AS IS" BASIS,
  17  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  See the License for the specific language governing permissions and
  19  limitations under the License.
  20 -->
  21
  22 <modulesynopsis metafile="mod_setenvif.xml.meta">
  23
  24 <name>mod_setenvif</name>
  25 <description>Allows the setting of environment variables based
  26 on characteristics of the request</description>
  27 <status>Base</status>
  28 <sourcefile>mod_setenvif.c</sourcefile>
  29 <identifier>setenvif_module</identifier>
  30
  31
  32 <summary>
  33
  34     <p>The <module>mod_setenvif</module> module allows you to set
  35     environment variables according to whether different aspects of
  36     the request match regular expressions you specify. These
  37     environment variables can be used by other parts of the server
  38     to make decisions about actions to be taken.</p>
  39
  40     <p>The directives are considered in the order they appear in
  41     the configuration files. So more complex sequences can be used,
  42     such as this example, which sets <code>netscape</code> if the
  43     browser is mozilla but not MSIE.</p>
  44
  45 <example>
  46   BrowserMatch ^Mozilla netscape<br />
  47   BrowserMatch MSIE !netscape<br />
  48 </example>
  49 </summary>
  50
  51 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
  52
  53 <directivesynopsis>
  54 <name>BrowserMatch</name>
  55 <description>Sets environment variables conditional on HTTP User-Agent
  56 </description>
  57 <syntax>BrowserMatch <em>regex [!]env-variable</em>[=<em>value</em>]
  58 [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
  59 <contextlist><context>server config</context>
  60 <context>virtual host</context><context>directory</context>
  61 <context>.htaccess</context></contextlist>
  62 <override>FileInfo</override>
  63
  64 <usage>
  65   <p>The <directive>BrowserMatch</directive> is a special cases of the
  66   <directive module="mod_setenvif">SetEnvIf</directive> directive that
  67   sets environment variables conditional on the
  68   <code>User-Agent</code> HTTP request header.  The following two
  69   lines have the same effect:</p>
  70 <example>
  71    BrowserMatchNoCase Robot is_a_robot<br />
  72    SetEnvIfNoCase User-Agent Robot is_a_robot<br />
  73 </example>
  74
  75     <p>Some additional examples:</p>
  76 <example>
  77     BrowserMatch ^Mozilla forms jpeg=yes browser=netscape<br />
  78     BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript<br />
  79     BrowserMatch MSIE !javascript<br />
  80 </example>
  81 </usage>
  82 </directivesynopsis>
  83
  84 <directivesynopsis>
  85 <name>BrowserMatchNoCase</name>
  86 <description>Sets environment variables conditional on User-Agent without
  87 respect to case</description>
  88 <syntax>BrowserMatchNoCase  <em>regex [!]env-variable</em>[=<em>value</em>]
  89     [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
  90 <contextlist><context>server config</context>
  91 <context>virtual host</context><context>directory</context>
  92 <context>.htaccess</context></contextlist>
  93 <override>FileInfo</override>
  94 <compatibility>Apache 1.2 and
  95     above (in Apache 1.2 this directive was found in the
  96     now-obsolete mod_browser module)</compatibility>
  97
  98 <usage>
  99
 100     <p>The <directive>BrowserMatchNoCase</directive> directive is
 101     semantically identical to the <directive
 102     module="mod_setenvif">BrowserMatch</directive> directive.
 103     However, it provides for case-insensitive matching. For
 104     example:</p>
 105 <example>
 106     BrowserMatchNoCase mac platform=macintosh<br />
 107     BrowserMatchNoCase win platform=windows<br />
 108 </example>
 109
 110     <p>The <directive>BrowserMatch</directive> and
 111     <directive>BrowserMatchNoCase</directive> directives are special cases of
 112     the <directive module="mod_setenvif">SetEnvIf</directive> and <directive
 113     module="mod_setenvif">SetEnvIfNoCase</directive>
 114     directives. The following two lines have the same effect:</p>
 115 <example>
 116    BrowserMatchNoCase Robot is_a_robot<br />
 117    SetEnvIfNoCase User-Agent Robot is_a_robot<br />
 118 </example>
 119 </usage>
 120 </directivesynopsis>
 121
 122 <directivesynopsis>
 123 <name>SetEnvIf</name>
 124 <description>Sets environment variables based on attributes of the request
 125 </description>
 126 <syntax>SetEnvIf <em>attribute
 127     regex [!]env-variable</em>[=<em>value</em>]
 128     [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
 129 <contextlist><context>server config</context>
 130 <context>virtual host</context><context>directory</context>
 131 <context>.htaccess</context></contextlist>
 132 <override>FileInfo</override>
 133
 134 <usage>
 135     <p>The <directive>SetEnvIf</directive> directive defines
 136     environment variables based on attributes of the request. The
 137     <em>attribute</em> specified in the first argument can be one of three
 138     things:</p>
 139
 140 <ol>
 141 <li>An HTTP request header field (see <a
 142     href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
 143     for more information about these); for example: <code>Host</code>,
 144     <code>User-Agent</code>, <code>Referer</code>, and
 145     <code>Accept-Language</code>.  A regular expression may be
 146     used to specify a set of request headers.</li>
 147
 148 <li>One of the following aspects of the request:
 149     <ul>
 150       <li><code>Remote_Host</code> - the hostname (if available) of
 151       the client making the request</li>
 152
 153       <li><code>Remote_Addr</code> - the IP address of the client
 154       making the request</li>
 155
 156       <li><code>Server_Addr</code> - the IP address of the server
 157       on which the request was received (only with versions later
 158       than 2.0.43)</li>
 159
 160       <li><code>Request_Method</code> - the name of the method
 161       being used (<code>GET</code>, <code>POST</code>, <em>et
 162       cetera</em>)</li>
 163
 164       <li><code>Request_Protocol</code> - the name and version of
 165       the protocol with which the request was made (<em>e.g.</em>,
 166       "HTTP/0.9", "HTTP/1.1", <em>etc.</em>)</li>
 167
 168       <li><code>Request_URI</code> - the resource requested on the HTTP
 169        request line -- generally the portion of the URL
 170       following the scheme and host portion without the query string</li>
 171     </ul>
 172 </li>
 173
 174 <li>The name of an environment variable in the list of those
 175 associated with the request. This allows
 176 <directive>SetEnvIf</directive> directives to test against the result
 177 of prior matches. Only those environment variables defined by earlier
 178 <code>SetEnvIf[NoCase]</code> directives are available for testing in
 179 this manner. 'Earlier' means that they were defined at a broader scope
 180 (such as server-wide) or previously in the current directive's scope.
 181 Environment variables will be considered only if there was no match
 182 among request characteristics and a regular expression was not
 183 used for the <em>attribute</em>.</li>
 184 </ol>
 185
 186 <p>The second argument (<em>regex</em>) is a <a
 187 href="http://www.pcre.org/">Perl compatible regular expression</a>.
 188 This is similar to a POSIX.2 egrep-style regular expression.
 189 If the <em>regex</em> matches against the <em>attribute</em>,
 190 then the remainder of the arguments are evaluated.</p>
 191
 192 <p>The rest of the arguments give the names of variables to set, and
 193 optionally values to which they should be set. These take the form
 194 of</p>
 195
 196     <ol>
 197       <li><code><em>varname</em></code>, or</li>
 198
 199       <li><code>!<em>varname</em></code>, or</li>
 200
 201       <li><code><em>varname</em>=<em>value</em></code></li>
 202     </ol>
 203
 204     <p>In the first form, the value will be set to "1". The second
 205     will remove the given variable if already defined, and the
 206     third will set the variable to the literal value given by
 207     <code><em>value</em></code>. Since version 2.0.51 Apache will
 208     recognize occurrences of <code>$1</code>..<code>$9</code> within
 209     <var>value</var> and replace them by parenthesized subexpressions
 210     of <var>regex</var>.</p>
 211
 212 <example>
 213 <title>Example:</title>
 214    SetEnvIf Request_URI "\.gif$" object_is_image=gif<br />
 215    SetEnvIf Request_URI "\.jpg$" object_is_image=jpg<br />
 216    SetEnvIf Request_URI "\.xbm$" object_is_image=xbm<br />
 217         :<br />
 218    SetEnvIf Referer www\.mydomain\.com intra_site_referral<br />
 219         :<br />
 220    SetEnvIf object_is_image xbm XBIT_PROCESSING=1<br />
 221         :<br />
 222    SetEnvIf ^TS*  ^[a-z].*  HAVE_TS<br />
 223 </example>
 224
 225     <p>The first three will set the environment variable
 226     <code>object_is_image</code> if the request was for an image
 227     file, and the fourth sets <code>intra_site_referral</code> if
 228     the referring page was somewhere on the
 229     <code>www.mydomain.com</code> Web site.</p>
 230
 231     <p>The last example will set environment variable
 232     <code>HAVE_TS</code> if the request contains any headers that
 233     begin with "TS" whose values begins with any character in the
 234     set [a-z].</p>
 235 </usage>
 236
 237 <seealso><a href="../env.html">Environment Variables in Apache</a>,
 238 for additional examples.
 239 </seealso>
 240 </directivesynopsis>
 241
 242 <directivesynopsis>
 243 <name>SetEnvIfNoCase</name>
 244 <description>Sets environment variables based on attributes of the request
 245 without respect to case</description>
 246 <syntax>SetEnvIfNoCase <em>attribute regex
 247         [!]env-variable</em>[=<em>value</em>]
 248     [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
 249 <contextlist><context>server config</context>
 250 <context>virtual host</context><context>directory</context>
 251 <context>.htaccess</context></contextlist>
 252 <override>FileInfo</override>
 253 <compatibility>Apache 1.3 and above</compatibility>
 254
 255 <usage>
 256
 257     <p>The <directive>SetEnvIfNoCase</directive> is semantically identical to
 258     the <directive module="mod_setenvif">SetEnvIf</directive> directive,
 259     and differs only in that the regular expression matching is
 260     performed in a case-insensitive manner. For example:</p>
 261 <example>
 262    SetEnvIfNoCase Host Apache\.Org site=apache
 263 </example>
 264
 265     <p>This will cause the <code>site</code> environment variable
 266     to be set to "<code>apache</code>" if the HTTP request header
 267     field <code>Host:</code> was included and contained
 268     <code>Apache.Org</code>, <code>apache.org</code>, or any other
 269     combination.</p>
 270 </usage>
 271 </directivesynopsis>
 272 </modulesynopsis>