mod_setenvif.xml revision d24d4c5159bcb11c25bb294926cfe7105c789ea9
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<?xml-stylesheet type="text/xsl" href="/style/manual.xsl"?>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<modulesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<description>Allows the setting of environment variables based
a78048ccbdb6256da15e6b0e7e95355e480c2301ndon characteristics of the request</description>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<compatibility>Available in Apache 1.3 and later</compatibility>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The <module>mod_setenvif</module> module allows you to set
d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen environment variables according to whether different aspects of
3f08db06526d6901aa08c110b5bc7dde6bc39905nd the request match regular expressions you specify. These
a78048ccbdb6256da15e6b0e7e95355e480c2301nd environment variables can be used by other parts of the server
a78048ccbdb6256da15e6b0e7e95355e480c2301nd to make decisions about actions to be taken.</p>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd <p>The directives are considered in the order they appear in
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the configuration files. So more complex sequences can be used,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd such as this example, which sets <code>netscape</code> if the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd browser is mozilla but not MSIE.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatch ^Mozilla netscape<br />
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung BrowserMatch MSIE !netscape<br />
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak<seealso><a href="/env.html">Environment Variables in Apache</a></seealso>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<directivesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<description>Sets environment variables conditional on HTTP User-Agent
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</description>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<syntax>BrowserMatch <em>regex env-variable</em>[=<em>value</em>]
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak[<em>env-variable</em>[=<em>value</em>]] ...</syntax>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak<context>virtual host</context><context>directory</context>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak<compatibility>Apache 1.2 and
a78048ccbdb6256da15e6b0e7e95355e480c2301nd above (in Apache 1.2 this directive was found in the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd now-obsolete mod_browser module)</compatibility>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak <p>The <directive>BrowserMatch</directive> directive defines
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak environment variables based on the <code>User-Agent</code> HTTP
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak request header field. The first argument should be a POSIX.2
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak extended regular expression (similar to an
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak <code>egrep</code>-style regex). The rest of the arguments give
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak the names of variables to set, and optionally values to which they
a78048ccbdb6256da15e6b0e7e95355e480c2301nd should be set. These take the form of</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>In the first form, the value will be set to "1". The second
a78048ccbdb6256da15e6b0e7e95355e480c2301nd will remove the given variable if already defined, and the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd third will set the variable to the value given by
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <code><em>value</em></code>. If a <code>User-Agent</code>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd string matches more than one entry, they will be merged.
a78048ccbdb6256da15e6b0e7e95355e480c2301nd Entries are processed in the order in which they appear, and
a78048ccbdb6256da15e6b0e7e95355e480c2301nd later entries can override earlier ones.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatch ^Mozilla forms jpeg=yes browser=netscape<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatch MSIE !javascript<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>Note that the regular expression string is
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <strong>case-sensitive</strong>. For case-INsensitive matching,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd see the <directive
a78048ccbdb6256da15e6b0e7e95355e480c2301nd directive.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <directive>BrowserMatchNoCase</directive> directives are special cases of
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the <directive module="mod_setenvif">SetEnvIf</directive> and <directive
a78048ccbdb6256da15e6b0e7e95355e480c2301nd directives. The following two lines have the same effect:</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatchNoCase Robot is_a_robot<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIfNoCase User-Agent Robot is_a_robot<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</directivesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<directivesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<description>Sets environment variables conditional on User-Agent without
a78048ccbdb6256da15e6b0e7e95355e480c2301ndrespect to case</description>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<syntax>BrowserMatchNoCase <em>regex env-variable</em>[=<em>value</em>]
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<context>virtual host</context><context>directory</context>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<compatibility>Apache 1.2 and
a78048ccbdb6256da15e6b0e7e95355e480c2301nd above (in Apache 1.2 this directive was found in the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd now-obsolete mod_browser module)</compatibility>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The <directive>BrowserMatchNoCase</directive> directive is
a78048ccbdb6256da15e6b0e7e95355e480c2301nd semantically identical to the <directive
a78048ccbdb6256da15e6b0e7e95355e480c2301nd module="mod_setenvif">BrowserMatch</directive> directive.
a78048ccbdb6256da15e6b0e7e95355e480c2301nd However, it provides for case-insensitive matching. For
a78048ccbdb6256da15e6b0e7e95355e480c2301nd example:</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatchNoCase mac platform=macintosh<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatchNoCase win platform=windows<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <directive>BrowserMatchNoCase</directive> directives are special cases of
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the <directive module="mod_setenvif">SetEnvIf</directive> and <directive
a78048ccbdb6256da15e6b0e7e95355e480c2301nd directives. The following two lines have the same effect:</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd BrowserMatchNoCase Robot is_a_robot<br />
627c978514c54179736d152923478be7c8707f9bnd SetEnvIfNoCase User-Agent Robot is_a_robot<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</directivesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<directivesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<description>Sets environment variables based on attributes of the request
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</description>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak [<em>env-variable</em>[=<em>value</em>]] ...</syntax>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak<context>virtual host</context><context>directory</context>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<compatibility>Apache 1.3 and
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak above; the Request_Protocol keyword and environment-variable
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak matching are only available with 1.3.7 and later</compatibility>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The <directive>SetEnvIf</directive> directive defines environment
a78048ccbdb6256da15e6b0e7e95355e480c2301nd variables based on attributes of the request. These attributes
a78048ccbdb6256da15e6b0e7e95355e480c2301nd can be the values of various HTTP request header fields (see <a
a78048ccbdb6256da15e6b0e7e95355e480c2301nd href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
627c978514c54179736d152923478be7c8707f9bnd for more information about these), or of other aspects of the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd request, including the following:</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <li><code>Remote_Host</code> - the hostname (if available) of
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the client making the request</li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <li><code>Remote_Addr</code> - the IP address of the client
a78048ccbdb6256da15e6b0e7e95355e480c2301nd making the request</li>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak <li><code>Remote_User</code> - the authenticated username (if
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak available)</li>
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak <li><code>Request_Method</code> - the name of the method
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak being used (<code>GET</code>, <code>POST</code>, <em>et
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <li><code>Request_Protocol</code> - the name and version of
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the protocol with which the request was made (<em>e.g.</em>,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd following the scheme and host portion</li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>Some of the more commonly used request header field names
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>If the <em>attribute</em> name doesn't match any of the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd special keywords, nor any of the request's header field names,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd it is tested as the name of an environment variable in the list
a78048ccbdb6256da15e6b0e7e95355e480c2301nd of those associated with the request. This allows
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <directive>SetEnvIf</directive> directives to test against the result of
a78048ccbdb6256da15e6b0e7e95355e480c2301nd prior matches.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <strong>Only those environment variables defined by earlier
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <code>SetEnvIf[NoCase]</code> directives are available for
a78048ccbdb6256da15e6b0e7e95355e480c2301nd testing in this manner. 'Earlier' means that they were
a78048ccbdb6256da15e6b0e7e95355e480c2301nd defined at a broader scope (such as server-wide) or
a78048ccbdb6256da15e6b0e7e95355e480c2301nd previously in the current directive's scope.</strong>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p><em>attribute</em> may be a regular expression when used to
a78048ccbdb6256da15e6b0e7e95355e480c2301nd match a request header. If <em>attribute</em> is a regular
a78048ccbdb6256da15e6b0e7e95355e480c2301nd expression and it doesn't match any of the request's header
a78048ccbdb6256da15e6b0e7e95355e480c2301nd request's environment variable list.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIf Request_URI "\.gif$" object_is_image=gif<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIf Request_URI "\.jpg$" object_is_image=jpg<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIf Request_URI "\.xbm$" object_is_image=xbm<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIf Referer www\.mydomain\.com intra_site_referral<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIf object_is_image xbm XBIT_PROCESSING=1<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd SetEnvIf ^TS* ^[a-z].* HAVE_TS<br />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The first three will set the environment variable
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <code>object_is_image</code> if the request was for an image
a78048ccbdb6256da15e6b0e7e95355e480c2301nd file, and the fourth sets <code>intra_site_referral</code> if
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the referring page was somewhere on the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The last example will set environment variable
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <code>HAVE_TS</code> if the request contains any headers that
a78048ccbdb6256da15e6b0e7e95355e480c2301nd begin with "TS" whose values begins with any character in the
5effc8b39fae5cd169d17f342bfc265705840014rbowen set [a-z].</p>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd</directivesynopsis>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd<directivesynopsis>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<description>Sets environment variables based on attributes of the request