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