mod_setenvif.xml revision cea021a7fc2657b091df4d3b031c4254ec371dd7
d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<description>Allows the setting of environment variables based
d24d4c5159bcb11c25bb294926cfe7105c789ea9sliveon characteristics of the request</description>
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>The <module>mod_setenvif</module> module allows you to set
d6736da1df3ed890b1e24c604503dce770e1346cslive environment variables according to whether different aspects of
d6736da1df3ed890b1e24c604503dce770e1346cslive the request match regular expressions you specify. These
d6736da1df3ed890b1e24c604503dce770e1346cslive environment variables can be used by other parts of the server
d6736da1df3ed890b1e24c604503dce770e1346cslive to make decisions about actions to be taken.</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>The directives are considered in the order they appear in
d6736da1df3ed890b1e24c604503dce770e1346cslive the configuration files. So more complex sequences can be used,
d6736da1df3ed890b1e24c604503dce770e1346cslive such as this example, which sets <code>netscape</code> if the
d6736da1df3ed890b1e24c604503dce770e1346cslive browser is mozilla but not MSIE.</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatch ^Mozilla netscape<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatch MSIE !netscape<br />
cea021a7fc2657b091df4d3b031c4254ec371dd7rbowen<seealso><a href="/env.html">Environment Variables in Apache HTTP Server</a></seealso>
d6736da1df3ed890b1e24c604503dce770e1346cslive<directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<description>Sets environment variables conditional on HTTP User-Agent
d6736da1df3ed890b1e24c604503dce770e1346cslive</description>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<syntax>BrowserMatch <em>regex [!]env-variable</em>[=<em>value</em>]
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
832292cf428167a83e71c7f17493fc0ab6cb7a7eslive<context>virtual host</context><context>directory</context>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <p>The <directive>BrowserMatch</directive> is a special cases of the
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <directive module="mod_setenvif">SetEnvIf</directive> directive that
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive sets environment variables conditional on the
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <code>User-Agent</code> HTTP request header. The following two
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive lines have the same effect:</p>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive BrowserMatchNoCase Robot is_a_robot<br />
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive SetEnvIfNoCase User-Agent Robot is_a_robot<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatch ^Mozilla forms jpeg=yes browser=netscape<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatch MSIE !javascript<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive</directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<description>Sets environment variables conditional on User-Agent without
d6736da1df3ed890b1e24c604503dce770e1346csliverespect to case</description>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<syntax>BrowserMatchNoCase <em>regex [!]env-variable</em>[=<em>value</em>]
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
832292cf428167a83e71c7f17493fc0ab6cb7a7eslive<context>virtual host</context><context>directory</context>
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>The <directive>BrowserMatchNoCase</directive> directive is
d6736da1df3ed890b1e24c604503dce770e1346cslive semantically identical to the <directive
d6736da1df3ed890b1e24c604503dce770e1346cslive module="mod_setenvif">BrowserMatch</directive> directive.
d6736da1df3ed890b1e24c604503dce770e1346cslive However, it provides for case-insensitive matching. For
d6736da1df3ed890b1e24c604503dce770e1346cslive example:</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatchNoCase mac platform=macintosh<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatchNoCase win platform=windows<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive <directive>BrowserMatchNoCase</directive> directives are special cases of
d6736da1df3ed890b1e24c604503dce770e1346cslive the <directive module="mod_setenvif">SetEnvIf</directive> and <directive
d6736da1df3ed890b1e24c604503dce770e1346cslive directives. The following two lines have the same effect:</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive BrowserMatchNoCase Robot is_a_robot<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIfNoCase User-Agent Robot is_a_robot<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive</directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<description>Sets environment variables based on attributes of the request
d6736da1df3ed890b1e24c604503dce770e1346cslive</description>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
832292cf428167a83e71c7f17493fc0ab6cb7a7eslive<context>virtual host</context><context>directory</context>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <p>The <directive>SetEnvIf</directive> directive defines
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive environment variables based on attributes of the request. The
353b33c8469f4e66be201a7f1a111dddcec8482bmartin <em>attribute</em> specified in the first argument can be one of four
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive things:</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive for more information about these); for example: <code>Host</code>,
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <code>Accept-Language</code>. A regular expression may be
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive used to specify a set of request headers.</li>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<li>One of the following aspects of the request:
d6736da1df3ed890b1e24c604503dce770e1346cslive <li><code>Remote_Host</code> - the hostname (if available) of
d6736da1df3ed890b1e24c604503dce770e1346cslive the client making the request</li>
d6736da1df3ed890b1e24c604503dce770e1346cslive <li><code>Remote_Addr</code> - the IP address of the client
d6736da1df3ed890b1e24c604503dce770e1346cslive making the request</li>
dbfb93984828591bba354a753b6bfb10ccdf9ccccoar <li><code>Server_Addr</code> - the IP address of the server
dbfb93984828591bba354a753b6bfb10ccdf9ccccoar on which the request was received (only with versions later
dbfb93984828591bba354a753b6bfb10ccdf9ccccoar than 2.0.43)</li>
d6736da1df3ed890b1e24c604503dce770e1346cslive <li><code>Request_Method</code> - the name of the method
d6736da1df3ed890b1e24c604503dce770e1346cslive being used (<code>GET</code>, <code>POST</code>, <em>et
d6736da1df3ed890b1e24c604503dce770e1346cslive <li><code>Request_Protocol</code> - the name and version of
d6736da1df3ed890b1e24c604503dce770e1346cslive the protocol with which the request was made (<em>e.g.</em>,
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <li><code>Request_URI</code> - the resource requested on the HTTP
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive request line -- generally the portion of the URL
ff21ab9f1cc3037fe58a2029432834581594b6c4pctony following the scheme and host portion without the query string. See
34b11cd9ddef75bc1e0df83f3d83dab1072a953ferikabele the <directive module="mod_rewrite">RewriteCond</directive>
34b11cd9ddef75bc1e0df83f3d83dab1072a953ferikabele directive of <module>mod_rewrite</module> for extra information on
34b11cd9ddef75bc1e0df83f3d83dab1072a953ferikabele how to match your query string.</li>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<li>The name of an environment variable in the list of those
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveassociated with the request. This allows
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<directive>SetEnvIf</directive> directives to test against the result
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveof prior matches. Only those environment variables defined by earlier
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<code>SetEnvIf[NoCase]</code> directives are available for testing in
2dd9f0336a1f802c9cac866cfecee63d03b177b8slivethis manner. 'Earlier' means that they were defined at a broader scope
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive(such as server-wide) or previously in the current directive's scope.
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveEnvironment variables will be considered only if there was no match
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveamong request characteristics and a regular expression was not
353b33c8469f4e66be201a7f1a111dddcec8482bmartin A reference to an extension of an SSL client certificate, located by
353b33c8469f4e66be201a7f1a111dddcec8482bmartin If a non-SSL request, or in absense of the configured <em>oid</em>,
353b33c8469f4e66be201a7f1a111dddcec8482bmartin no variable will be set. If the <em>oid</em> is found multiple times,
353b33c8469f4e66be201a7f1a111dddcec8482bmartin the individual strings will be concatenated, separated by a comma <code>','</code>.
353b33c8469f4e66be201a7f1a111dddcec8482bmartin The <em>oid</em> should reference a string-valued extension.
030108b1816bcda3d925df65357feabdce83bc94sliveref="regex">regular expression</glossary>. If the <em>regex</em>
030108b1816bcda3d925df65357feabdce83bc94slivematches against the <em>attribute</em>, then the remainder of the
030108b1816bcda3d925df65357feabdce83bc94slivearguments are evaluated.</p>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive<p>The rest of the arguments give the names of variables to set, and
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveoptionally values to which they should be set. These take the form
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <p>In the first form, the value will be set to "1". The second
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive will remove the given variable if already defined, and the
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive third will set the variable to the literal value given by
cea021a7fc2657b091df4d3b031c4254ec371dd7rbowen <code><em>value</em></code>. Since version 2.0.51, Apache httpd will
5d81a8bafa2703e966db5bfd5abb33b176d47589nd recognize occurrences of <code>$1</code>..<code>$9</code> within
5d81a8bafa2703e966db5bfd5abb33b176d47589nd <var>value</var> and replace them by parenthesized subexpressions
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf Request_URI "\.gif$" object_is_image=gif<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf Request_URI "\.jpg$" object_is_image=jpg<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf Request_URI "\.xbm$" object_is_image=xbm<br />
a1ac1a5495b92d11422abe39a70f58fc7f4e2904takashi SetEnvIf Referer www\.mydomain\.example\.com intra_site_referral<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf object_is_image xbm XBIT_PROCESSING=1<br />
353b33c8469f4e66be201a7f1a111dddcec8482bmartin SetEnvIf OID("2.16.840.1.113730.1.13") "(.*)" NetscapeComment=$1<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf ^TS* ^[a-z].* HAVE_TS<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>The first three will set the environment variable
d6736da1df3ed890b1e24c604503dce770e1346cslive <code>object_is_image</code> if the request was for an image
d6736da1df3ed890b1e24c604503dce770e1346cslive file, and the fourth sets <code>intra_site_referral</code> if
d6736da1df3ed890b1e24c604503dce770e1346cslive the referring page was somewhere on the
353b33c8469f4e66be201a7f1a111dddcec8482bmartin <p>The sixth example will set the <code>NetscapeComment</code>
353b33c8469f4e66be201a7f1a111dddcec8482bmartin environment variable to the string found in the corresponding
353b33c8469f4e66be201a7f1a111dddcec8482bmartin SSL client certificate field (if found).</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>The last example will set environment variable
d6736da1df3ed890b1e24c604503dce770e1346cslive <code>HAVE_TS</code> if the request contains any headers that
d6736da1df3ed890b1e24c604503dce770e1346cslive begin with "TS" whose values begins with any character in the
d6736da1df3ed890b1e24c604503dce770e1346cslive set [a-z].</p>
cea021a7fc2657b091df4d3b031c4254ec371dd7rbowen<seealso><a href="/env.html">Environment Variables in Apache HTTP Server</a>,
c22a6dc8ecfb9540649e9d371d0c28676ec6a57drbowenfor additional examples.
d6736da1df3ed890b1e24c604503dce770e1346cslive</directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<directivesynopsis>
d6736da1df3ed890b1e24c604503dce770e1346cslive<description>Sets environment variables based on attributes of the request
d6736da1df3ed890b1e24c604503dce770e1346cslivewithout respect to case</description>
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
832292cf428167a83e71c7f17493fc0ab6cb7a7eslive<context>virtual host</context><context>directory</context>
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>The <directive>SetEnvIfNoCase</directive> is semantically identical to
d6736da1df3ed890b1e24c604503dce770e1346cslive the <directive module="mod_setenvif">SetEnvIf</directive> directive,
d6736da1df3ed890b1e24c604503dce770e1346cslive and differs only in that the regular expression matching is
d6736da1df3ed890b1e24c604503dce770e1346cslive performed in a case-insensitive manner. For example:</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIfNoCase Host Apache\.Org site=apache
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>This will cause the <code>site</code> environment variable
d6736da1df3ed890b1e24c604503dce770e1346cslive to be set to "<code>apache</code>" if the HTTP request header
d6736da1df3ed890b1e24c604503dce770e1346cslive <code>Apache.Org</code>, <code>apache.org</code>, or any other
d6736da1df3ed890b1e24c604503dce770e1346cslive combination.</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive</directivesynopsis>
c22a6dc8ecfb9540649e9d371d0c28676ec6a57drbowen</modulesynopsis>