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
d1c7ce2d430a6c91c2eddd709396da020e5d4412covener internal 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
d1c7ce2d430a6c91c2eddd709396da020e5d4412covener to make decisions about actions to be taken, as well as becoming
d1c7ce2d430a6c91c2eddd709396da020e5d4412covener available to CGI scripts and SSI pages.</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>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatch ^Mozilla netscape
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatch MSIE !netscape
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <p>When the server looks up a path via an internal
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <glossary ref="subrequest">subrequest</glossary> such as looking
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar for a <directive module="mod_dir" >DirectoryIndex</directive>
d144b9b28896eb3edcd845f3e077c170d563031dcovener or generating a directory listing with <module>mod_autoindex</module>,
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar per-request environment variables are <em>not</em> inherited in the
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar subrequest. Additionally,
d144b9b28896eb3edcd845f3e077c170d563031dcovener <directive module="mod_setenvif">SetEnvIf</directive> directives
d144b9b28896eb3edcd845f3e077c170d563031dcovener are not separately evaluated in the subrequest due to the API phases
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>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatchNoCase Robot is_a_robot
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIfNoCase User-Agent Robot is_a_robot
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatch ^Mozilla forms jpeg=yes browser=netscape
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatch MSIE !javascript
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>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatchNoCase mac platform=macintosh
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatchNoCase win platform=windows
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>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohBrowserMatchNoCase Robot is_a_robot
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIfNoCase User-Agent Robot is_a_robot
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
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
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIf Request_URI "\.gif$" object_is_image=gif
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIf Request_URI "\.jpg$" object_is_image=jpg
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIf Request_URI "\.xbm$" object_is_image=xbm
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIf Referer www\.mydomain\.example\.com intra_site_referral
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIf object_is_image xbm XBIT_PROCESSING=1
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSetEnvIf ^TS ^[a-z] HAVE_TS
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>
cea021a7fc2657b091df4d3b031c4254ec371dd7rbowen<seealso><a href="/env.html">Environment Variables in Apache HTTP Server</a>,
c22a6dc8ecfb9540649e9d371d0c28676ec6a57drbowenfor additional examples.
d6736da1df3ed890b1e24c604503dce770e1346cslive</directivesynopsis>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic<directivesynopsis>
6b3904b27e9d68c753cdd1fbab9b375eec50fb88sf<description>Sets environment variables based on an ap_expr expression</description>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic [[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic<context>virtual host</context><context>directory</context>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic <p>The <directive>SetEnvIfExpr</directive> directive defines
7d7dbae8644ed3d98ffd0a56aa5191f48787fff6sf environment variables based on an <directive module="core" type="section">If</directive>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic <code>ap_expr</code>. These expressions will be evaluated at runtime,
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic and applied <em>env-variable</em> in the same fashion as <directive
02c4e4fe19f1120c6bdf561950ab60077c61cc5fsf SetEnvIfExpr "tolower(req('X-Sendfile')) == 'd:\images\very_big.iso')" iso_delivered
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic <p>This would set the environment variable <code>iso_delivered</code>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic every time our application attempts to send it via <code>X-Sendfile</code></p>
6b3904b27e9d68c753cdd1fbab9b375eec50fb88sf <p>A more useful example would be to set the variable rfc1918 if the
6b3904b27e9d68c753cdd1fbab9b375eec50fb88sf remote IP address is a private address according to RFC 1918:</p>
6b3904b27e9d68c753cdd1fbab9b375eec50fb88sf SetEnvIfExpr "-R '10.0.0.0/8' || -R '172.16.0.0/12' || -R '192.168.0.0/16'" rfc1918
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic<seealso><a href="/expr.html">Expressions in Apache HTTP Server</a>,
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalicfor a complete reference and more examples.</seealso>
7d7dbae8644ed3d98ffd0a56aa5191f48787fff6sf<seealso><directive module="core" type="section">If</directive> can be used to achieve similar
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalicresults.</seealso>
94aba9caa9b2f7a0e95a55f51264c908b69470e2igalic</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>
a330659fa32865eb8521adaccf5d9b75687b9aebtrawick SetEnvIfNoCase Host Example\.Org site=example
d6736da1df3ed890b1e24c604503dce770e1346cslive <p>This will cause the <code>site</code> environment variable
a330659fa32865eb8521adaccf5d9b75687b9aebtrawick to be set to "<code>example</code>" if the HTTP request header
a330659fa32865eb8521adaccf5d9b75687b9aebtrawick <code>Example.Org</code>, <code>example.org</code>, or any other
d6736da1df3ed890b1e24c604503dce770e1346cslive combination.</p>
d6736da1df3ed890b1e24c604503dce770e1346cslive</directivesynopsis>
c22a6dc8ecfb9540649e9d371d0c28676ec6a57drbowen</modulesynopsis>