mod_setenvif.html revision 37d54185c36fc14ea39d21c0fcd1ea19b35e9c93
e59faf65ce864fe95dc00f5d52b8323cdbd0608aTimo Sirainen<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
02a54da28f376dd66d7939d8546a196a0045b486Timo Sirainen<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
be1ce4990d3e5eda1e80a032e355e41aabc29d6fTimo Sirainen BGCOLOR="#FFFFFF"
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen TEXT="#000000"
02a54da28f376dd66d7939d8546a196a0045b486Timo Sirainen LINK="#0000FF"
02a54da28f376dd66d7939d8546a196a0045b486Timo Sirainen VLINK="#000080"
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen ALINK="#FF0000"
02a54da28f376dd66d7939d8546a196a0045b486Timo Sirainen<!--#include virtual="header.html" -->
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen This module is contained in the <SAMP>mod_setenvif.c</SAMP> file, and
9e808b253bf5c20878fedfb44e4f2273db31da7cTimo Sirainen <STRONG>is</STRONG> compiled in by default. It provides for
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen the ability to set environment variables based upon attributes of the
ccd4a548556a72a74a8183fa46cdd616dceae456Timo Sirainen The <SAMP>mod_setenvif</SAMP> module allows you to set environment
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen variables according to whether different aspects of the request match
8c0e314c57b91253c8b2c3491e162967bd3a2cd3Timo Sirainen regular expressions you specify. These envariables can be used by
8c0e314c57b91253c8b2c3491e162967bd3a2cd3Timo Sirainen other parts of the server to make decisions about actions to be taken.
08a0b7b0d0444875001847ef2b1b7b76122620abTimo Sirainen <p>The directives are considered in the order they appear in the
e50c1eb31159d8ccc116d8fb487a5e231d2033a1Timo Sirainen configuration files. So more complex sequences can be used, such
e50c1eb31159d8ccc116d8fb487a5e231d2033a1Timo Sirainen as this example, which sets <code>netscape</code> if the browser
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen is mozilla but not MSIE.
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen BrowserMatch ^Mozilla netscape
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen BrowserMatch MSIE !netscape
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen <LI><A HREF="#BrowserMatchNoCase">BrowserMatchNoCase</A>
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen <LI><A HREF="#SetEnvIfNoCase">SetEnvIfNoCase</A>
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen <HR> <!-- the HR is part of the directive description -->
14f172fb8fc5585ec450ae3c233c676a033e5324Timo Sirainen <H2><A NAME="BrowserMatch">The <SAMP>BrowserMatch</SAMP> Directive</A></H2>
14f172fb8fc5585ec450ae3c233c676a033e5324Timo Sirainen ><STRONG>Syntax:</STRONG></A> BrowserMatch <EM>regex envar[=value] [...]</EM>
9e808b253bf5c20878fedfb44e4f2273db31da7cTimo Sirainen HREF="directive-dict.html#Compatibility"
7dc2c953377fdf3f98e392c2eb7c9caa3dfc5d4fTimo Sirainen ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above
9fa54323c1382c969190ec46eb1c7ca783aec9b9Timo Sirainen The BrowserMatch directive defines environment variables based on the
9fa54323c1382c969190ec46eb1c7ca783aec9b9Timo Sirainen <SAMP>User-Agent</SAMP> HTTP request header field. The first argument
9261dbf0675204898c6557591c7aa376e23a52b2Timo Sirainen should be a POSIX.2 extended regular expression (similar to an
9261dbf0675204898c6557591c7aa376e23a52b2Timo Sirainen <SAMP>egrep</SAMP>-style regex). The rest of the arguments give the
9261dbf0675204898c6557591c7aa376e23a52b2Timo Sirainen names of variables to set, and optionally values to which they should
9261dbf0675204898c6557591c7aa376e23a52b2Timo Sirainen be set. These take the form of
9e808b253bf5c20878fedfb44e4f2273db31da7cTimo Sirainen <LI><SAMP><EM>varname</EM>=<EM>value</EM></SAMP>
9e808b253bf5c20878fedfb44e4f2273db31da7cTimo Sirainen In the first form, the value will be set to "1". The second
3809b9691c46926aa54968ac8e418d04361e1efaTimo Sirainen will remove the given variable if already defined, and the third will
3809b9691c46926aa54968ac8e418d04361e1efaTimo Sirainen set the variable to the value given by <SAMP><EM>value</EM></SAMP>. If a
3809b9691c46926aa54968ac8e418d04361e1efaTimo Sirainen <SAMP>User-Agent</SAMP> string matches more than one entry, they will
3809b9691c46926aa54968ac8e418d04361e1efaTimo Sirainen be merged. Entries are processed in the order in which they appear,
3809b9691c46926aa54968ac8e418d04361e1efaTimo Sirainen and later entries can override earlier ones.
395ad9a760c494a2106fada1392c5432a1629de6Timo Sirainen BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
395ad9a760c494a2106fada1392c5432a1629de6Timo Sirainen BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
395ad9a760c494a2106fada1392c5432a1629de6Timo Sirainen BrowserMatch MSIE !javascript
395ad9a760c494a2106fada1392c5432a1629de6Timo Sirainen Note that the regular expression string is
395ad9a760c494a2106fada1392c5432a1629de6Timo Sirainen <STRONG>case-sensitive</STRONG>. For cane-INsensitive matching, see
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="#BrowserMatchNoCase"
375848bde4272b83b43865698f88c1b75f39162dTimo Sirainen The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP>
375848bde4272b83b43865698f88c1b75f39162dTimo Sirainen directives are special cases of the
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="#SetEnvIf"
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="#SetEnvIfNoCase"
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainen directives. The following two lines have the same effect:
188fe6051d70c861236e41ffc14f949a9994c324Timo Sirainen BrowserMatchNoCase Robot is_a_robot
375848bde4272b83b43865698f88c1b75f39162dTimo Sirainen SetEnvIfNoCase User-Agent Robot is_a_robot
375848bde4272b83b43865698f88c1b75f39162dTimo Sirainen <HR> <!-- the HR is part of the directive description -->
e7ca5f820d6a1a8fe549a2966ac707a60e055ef4Timo Sirainen ><STRONG>Syntax:</STRONG></A> BrowserMatchNoCase <EM>regex envar[=value] [...]</EM>
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen HREF="directive-dict.html#Compatibility"
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainen ><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen The <SAMP>BrowserMatchNoCase</SAMP> directive is semantically identical to
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="#BrowserMatch"
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen directive. However, it provides for case-insensitive matching. For
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen BrowserMatchNoCase mac platform=macintosh
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen BrowserMatchNoCase win platform=windows
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP>
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen directives are special cases of the
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="#SetEnvIf"
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="#SetEnvIfNoCase"
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen directives. The following two lines have the same effect:
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen BrowserMatchNoCase Robot is_a_robot
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen SetEnvIfNoCase User-Agent Robot is_a_robot
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen <HR> <!-- the HR is part of the directive description -->
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen ><STRONG>Syntax:</STRONG></A> SetEnvIf <EM> attribute regex envar[=value] [...]</EM>
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen HREF="directive-dict.html#Compatibility"
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen The <SAMP>SetEnvIf</SAMP> directive defines environment variables
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen based on attributes of the request. These attributes can be the
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen values of various HTTP request header fields (see
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen for more information about these), or of other aspects of the request,
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen including the following:
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen <LI><SAMP>Remote_Host</SAMP> - the hostname (if available) of the
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainen client making the request
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen <LI><SAMP>Remote_Addr</SAMP> - the IP address of the client making
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen <LI><SAMP>Remote_User</SAMP> - the authenticated username (if
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen <LI><SAMP>Request_Method</SAMP> - the name of the method being used
2615df45a8027948a474abe5e817b34b0499c171Timo Sirainen (<SAMP>GET</SAMP>, <SAMP>POST</SAMP>, <EM>et cetera</EM>)
da9f6acdcb303d0fe5160b669668aedf39c8f45aTimo Sirainen <LI><SAMP>Request_URI</SAMP> - the portion of the URL following the
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen scheme and host portion
2f122b4db3f0d4eeb59ff9d306e54b2009d72cf9Timo Sirainen Some of the more commonly used request header field names include
2f122b4db3f0d4eeb59ff9d306e54b2009d72cf9Timo Sirainen <SAMP>Host</SAMP>, <SAMP>User-Agent</SAMP>, and <SAMP>Referer</SAMP>.
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen SetEnvIf Request_URI "\.(gif)|(jpg)|(xbm)$" object_is_image
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen SetEnvIf Referer www\.mydomain\.com intra_site_referral
0d7b2e0750386fe1646a17d83a803d1d5eb3d3a0Timo Sirainen The first will set the envariable <SAMP>object_is_image</SAMP> if the
02a54da28f376dd66d7939d8546a196a0045b486Timo Sirainen request was for an image file, and the second sets
02a54da28f376dd66d7939d8546a196a0045b486Timo Sirainen <SAMP>intra_site_referral</SAMP> if the referring page was somewhere
0d7b2e0750386fe1646a17d83a803d1d5eb3d3a0Timo Sirainen on the <SAMP>www.mydomain.com</SAMP> Web site.
0d7b2e0750386fe1646a17d83a803d1d5eb3d3a0Timo Sirainen <HR> <!-- the HR is part of the directive description -->
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen HREF="directive-dict.html#Compatibility"
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen ><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen The <SAMP>SetEnvIfNoCase</SAMP> is semantically identical to the
3d817546d5a111cd235d04e7de137cfa8a2415b7Timo Sirainen HREF="#SetEnvIf"
3d817546d5a111cd235d04e7de137cfa8a2415b7Timo Sirainen directive, and differs only in that the regular expression matching is
7fb70daba4e571eab5b64f496d20b9e37e31141bTimo Sirainen performed in a case-insensitive manner. For example:
4213f20d2086ad5d3d1d82b5476fa1e9efdbb394Timo Sirainen SetEnvIfNoCase Host Apache\.Org site=apache
4213f20d2086ad5d3d1d82b5476fa1e9efdbb394Timo Sirainen This will cause the <SAMP>site</SAMP> envariable to be set to
2f122b4db3f0d4eeb59ff9d306e54b2009d72cf9Timo Sirainen "<SAMP>apache</SAMP>" if the HTTP request header field
5d202199f527590be29784e736600ddde4e4812bTimo Sirainen <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>,
2f122b4db3f0d4eeb59ff9d306e54b2009d72cf9Timo Sirainen <SAMP>apache.org</SAMP>, or any other combination.
2f122b4db3f0d4eeb59ff9d306e54b2009d72cf9Timo Sirainen<!--#include virtual="footer.html" -->