mod_setenvif.xml revision 5d81a8bafa2703e966db5bfd5abb33b176d47589
78cd48acd325773619d78ac0d7263a99a8922faend<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
ab2c1c1c83ec91415565da5a71fbc15d9685caa6fielding<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd<modulesynopsis>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<description>Allows the setting of environment variables based
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcndon characteristics of the request</description>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>The <module>mod_setenvif</module> module allows you to set
7708bd70088b64148d7d78fd84ede43ced63c713minfrin environment variables according to whether different aspects of
7708bd70088b64148d7d78fd84ede43ced63c713minfrin the request match regular expressions you specify. These
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding environment variables can be used by other parts of the server
36a72c96fc2dda27eadbae8a108fa428cc1419c1wrowe to make decisions about actions to be taken.</p>
59b96ad34c087942eea06884c97d12c2796a977amturk <p>The directives are considered in the order they appear in
c0a549c3f6e8edc87e921cf76fac95d04feba72bwrowe the configuration files. So more complex sequences can be used,
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe such as this example, which sets <code>netscape</code> if the
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe browser is mozilla but not MSIE.</p>
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe BrowserMatch ^Mozilla netscape<br />
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe BrowserMatch MSIE !netscape<br />
e9501b71b8a1e76384cb010b1e41e76a1e47aacctrawick<seealso><a href="/env.html">Environment Variables in Apache</a></seealso>
6335eb31f0f0ed54628a04ed32946360b8b77684minfrin<directivesynopsis>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<description>Sets environment variables conditional on HTTP User-Agent
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding</description>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<syntax>BrowserMatch <em>regex [!]env-variable</em>[=<em>value</em>]
2ceedfca3a2fdfdb5ff60ca17f030ce91f6331cbwrowe[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
2ceedfca3a2fdfdb5ff60ca17f030ce91f6331cbwrowe<context>virtual host</context><context>directory</context>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>The <directive>BrowserMatch</directive> is a special cases of the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <directive module="mod_setenvif">SetEnvIf</directive> directive that
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding sets environment variables conditional on the
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <code>User-Agent</code> HTTP request header. The following two
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding lines have the same effect:</p>
33cb45dc8c5106018b7c2f6ae42478b109423e0eniq BrowserMatchNoCase Robot is_a_robot<br />
a812b025d139f465a31c76fc02ed162ed5271b03nd SetEnvIfNoCase User-Agent Robot is_a_robot<br />
a812b025d139f465a31c76fc02ed162ed5271b03nd BrowserMatch ^Mozilla forms jpeg=yes browser=netscape<br />
a812b025d139f465a31c76fc02ed162ed5271b03nd BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript<br />
a812b025d139f465a31c76fc02ed162ed5271b03nd BrowserMatch MSIE !javascript<br />
a812b025d139f465a31c76fc02ed162ed5271b03nd</directivesynopsis>
a812b025d139f465a31c76fc02ed162ed5271b03nd<directivesynopsis>
00211b036b78699ace57a6d800a52e6c2d57652fnd<description>Sets environment variables conditional on User-Agent without
00211b036b78699ace57a6d800a52e6c2d57652fndrespect to case</description>
a812b025d139f465a31c76fc02ed162ed5271b03nd<syntax>BrowserMatchNoCase <em>regex [!]env-variable</em>[=<em>value</em>]
33cb45dc8c5106018b7c2f6ae42478b109423e0eniq<context>virtual host</context><context>directory</context>
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe<compatibility>Apache 1.2 and
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe above (in Apache 1.2 this directive was found in the
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe now-obsolete mod_browser module)</compatibility>
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe <p>The <directive>BrowserMatchNoCase</directive> directive is
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe semantically identical to the <directive
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe module="mod_setenvif">BrowserMatch</directive> directive.
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe However, it provides for case-insensitive matching. For
eee895b02dd7867622afd0a8a94f2efc7de9c618wrowe example:</p>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe BrowserMatchNoCase mac platform=macintosh<br />
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe BrowserMatchNoCase win platform=windows<br />
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <directive>BrowserMatchNoCase</directive> directives are special cases of
9f1a88897168c3f1e5009acb585daf01e38a0299jim the <directive module="mod_setenvif">SetEnvIf</directive> and <directive
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk directives. The following two lines have the same effect:</p>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe BrowserMatchNoCase Robot is_a_robot<br />
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe SetEnvIfNoCase User-Agent Robot is_a_robot<br />
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk</directivesynopsis>
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk<directivesynopsis>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe<description>Sets environment variables based on attributes of the request
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe</description>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk<context>virtual host</context><context>directory</context>
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe <p>The <directive>SetEnvIf</directive> directive defines
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe environment variables based on attributes of the request. The
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <em>attribute</em> specified in the first argument can be one of three
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe things:</p>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe for more information about these); for example: <code>Host</code>,
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <code>Accept-Language</code>. A regular expression may be
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe used to specify a set of request headers.</li>
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk<li>One of the following aspects of the request:
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <li><code>Remote_Host</code> - the hostname (if available) of
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe the client making the request</li>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <li><code>Remote_Addr</code> - the IP address of the client
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe making the request</li>
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk <li><code>Server_Addr</code> - the IP address of the server
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk on which the request was received (only with versions later
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk than 2.0.43)</li>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <li><code>Remote_User</code> - the authenticated username (if
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe available)</li>
38fd849bd99e2765ee633b6dc576b5f17acdc455wrowe <li><code>Request_Method</code> - the name of the method
9621e4c4056383e4a2b844b14687bae500b33a82wrowe being used (<code>GET</code>, <code>POST</code>, <em>et
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk <li><code>Request_Protocol</code> - the name and version of
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk the protocol with which the request was made (<em>e.g.</em>,
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe <li><code>Request_URI</code> - the resource requested on the HTTP
9621e4c4056383e4a2b844b14687bae500b33a82wrowe request line -- generally the portion of the URL
9621e4c4056383e4a2b844b14687bae500b33a82wrowe following the scheme and host portion without the query string</li>
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk<li>The name of an environment variable in the list of those
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturkassociated with the request. This allows
4c67ef499845a08771e81254ce6eb2324a160bc7wrowe<directive>SetEnvIf</directive> directives to test against the result
4c67ef499845a08771e81254ce6eb2324a160bc7wroweof prior matches. Only those environment variables defined by earlier
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe<code>SetEnvIf[NoCase]</code> directives are available for testing in
4c67ef499845a08771e81254ce6eb2324a160bc7wrowethis manner. 'Earlier' means that they were defined at a broader scope
4c67ef499845a08771e81254ce6eb2324a160bc7wrowe(such as server-wide) or previously in the current directive's scope.
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wroweEnvironment variables will be considered only if there was no match
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wroweamong request characteristics and a regular expression was not
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowehref="http://www.pcre.org/">Perl compatible regular expression</a>.
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wroweThis is similar to a POSIX.2 egrep-style regular expression.
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wroweIf the <em>regex</em> matches against the <em>attribute</em>,
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowethen the remainder of the arguments are evaluated.</p>
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wrowe<p>The rest of the arguments give the names of variables to set, and
1dac466bcc84f8ebf410016dcf2a4cd4312e8611wroweoptionally values to which they should be set. These take the form
eee895b02dd7867622afd0a8a94f2efc7de9c618wrowe <p>In the first form, the value will be set to "1". The second
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk will remove the given variable if already defined, and the
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk third will set the variable to the literal value given by
1d2ff7570139286b0f0d16f92187a16ed5932291mturk <code><em>value</em></code>. Since version 2.1 Apache will
1d2ff7570139286b0f0d16f92187a16ed5932291mturk recognize occurrences of <code>$1</code>..<code>$9</code> within
eee895b02dd7867622afd0a8a94f2efc7de9c618wrowe <var>value</var> and replace them by parenthesized subexpressions
1d2ff7570139286b0f0d16f92187a16ed5932291mturk SetEnvIf Request_URI "\.gif$" object_is_image=gif<br />
1d2ff7570139286b0f0d16f92187a16ed5932291mturk SetEnvIf Request_URI "\.jpg$" object_is_image=jpg<br />
eee895b02dd7867622afd0a8a94f2efc7de9c618wrowe SetEnvIf Request_URI "\.xbm$" object_is_image=xbm<br />
4415d997ac73262e513c0a571bd5be4f609040bawrowe SetEnvIf Referer www\.mydomain\.com intra_site_referral<br />
4415d997ac73262e513c0a571bd5be4f609040bawrowe SetEnvIf object_is_image xbm XBIT_PROCESSING=1<br />
4415d997ac73262e513c0a571bd5be4f609040bawrowe SetEnvIf ^TS* ^[a-z].* HAVE_TS<br />
eee895b02dd7867622afd0a8a94f2efc7de9c618wrowe <p>The first three will set the environment variable
4415d997ac73262e513c0a571bd5be4f609040bawrowe <code>object_is_image</code> if the request was for an image
4415d997ac73262e513c0a571bd5be4f609040bawrowe file, and the fourth sets <code>intra_site_referral</code> if
4415d997ac73262e513c0a571bd5be4f609040bawrowe the referring page was somewhere on the
4415d997ac73262e513c0a571bd5be4f609040bawrowe <p>The last example will set environment variable
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk <code>HAVE_TS</code> if the request contains any headers that
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk begin with "TS" whose values begins with any character in the
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk set [a-z].</p>
4415d997ac73262e513c0a571bd5be4f609040bawrowe<seealso><a href="/env.html">Environment Variables in Apache</a>,
4415d997ac73262e513c0a571bd5be4f609040bawrowefor additional examples.
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk</directivesynopsis>
01261c7d9578aadd1891f94c8ee03f32ba51db3dmturk<directivesynopsis>
4415d997ac73262e513c0a571bd5be4f609040bawrowe<description>Sets environment variables based on attributes of the request
4415d997ac73262e513c0a571bd5be4f609040bawrowewithout respect to case</description>
4415d997ac73262e513c0a571bd5be4f609040bawrowe [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
4415d997ac73262e513c0a571bd5be4f609040bawrowe<context>virtual host</context><context>directory</context>
4415d997ac73262e513c0a571bd5be4f609040bawrowe <p>The <directive>SetEnvIfNoCase</directive> is semantically identical to
eee895b02dd7867622afd0a8a94f2efc7de9c618wrowe the <directive module="mod_setenvif">SetEnvIf</directive> directive,
4415d997ac73262e513c0a571bd5be4f609040bawrowe and differs only in that the regular expression matching is
4415d997ac73262e513c0a571bd5be4f609040bawrowe performed in a case-insensitive manner. For example:</p>
00b70ae978854b5eb51722cbeda99c9067b5faf2mturk SetEnvIfNoCase Host Apache\.Org site=apache
00b70ae978854b5eb51722cbeda99c9067b5faf2mturk <p>This will cause the <code>site</code> environment variable
00b70ae978854b5eb51722cbeda99c9067b5faf2mturk to be set to "<code>apache</code>" if the HTTP request header
00b70ae978854b5eb51722cbeda99c9067b5faf2mturk <code>Apache.Org</code>, <code>apache.org</code>, or any other
00b70ae978854b5eb51722cbeda99c9067b5faf2mturk combination.</p>
4415d997ac73262e513c0a571bd5be4f609040bawrowe</directivesynopsis>
65efbf0826de766a90d745cc44427bfa4e2447b6mturk</modulesynopsis>