mod_setenvif.xml revision dbfb93984828591bba354a753b6bfb10ccdf9ccc
d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
d6736da1df3ed890b1e24c604503dce770e1346cslive<modulesynopsis>
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 />
d6736da1df3ed890b1e24c604503dce770e1346cslive<seealso><a href="/env.html">Environment Variables in Apache</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<compatibility>Apache 1.2 and
d6736da1df3ed890b1e24c604503dce770e1346cslive above (in Apache 1.2 this directive was found in the
d6736da1df3ed890b1e24c604503dce770e1346cslive now-obsolete mod_browser module)</compatibility>
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
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive <em>attribute</em> specified in the first argument can be one of three
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>Remote_User</code> - the authenticated username (if
d6736da1df3ed890b1e24c604503dce770e1346cslive available)</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
2dd9f0336a1f802c9cac866cfecee63d03b177b8slive following the scheme and host portion without the 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
2dd9f0336a1f802c9cac866cfecee63d03b177b8slivehref="http://www.pcre.org/">Perl compatible regular expression</a>.
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveThis is similar to a POSIX.2 egrep-style regular expression.
2dd9f0336a1f802c9cac866cfecee63d03b177b8sliveIf the <em>regex</em> matches against the <em>attribute</em>,
2dd9f0336a1f802c9cac866cfecee63d03b177b8slivethen the remainder of the arguments 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
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 />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf Referer www\.mydomain\.com intra_site_referral<br />
d6736da1df3ed890b1e24c604503dce770e1346cslive SetEnvIf object_is_image xbm XBIT_PROCESSING=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
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>
c22a6dc8ecfb9540649e9d371d0c28676ec6a57drbowen<seealso><a href="/env.html">Environment Variables in Apache</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>