mirror of
https://github.com/apache/httpd.git
synced 2025-05-17 15:21:13 +03:00
a235af4c8f
environment variable docs. Here is what I have done: 1. Removed some obsolete CERN references and done a tiny bit of cleanup of mod_env.html. 2. Included references from mod_env.html and mod_setenvif.html to env.html. 3. Prettied-up env.html a little bit by including sub-headings. 4. Added some "caveats" to env.html: - No overriding basic CGI variables - suexec restrictions - no non-alphanumeric characters in env variable names git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87621 13f79535-47bb-0310-9956-ffa450edef68
423 lines
12 KiB
HTML
423 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_setenvif</TITLE>
|
|
</HEAD>
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
<H1 ALIGN="CENTER">Module mod_setenvif</H1>
|
|
<P>
|
|
This module provides the ability to set environment variables based
|
|
upon attributes of the request.
|
|
</P>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_setenvif.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> setenvif_module
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
|
|
</P>
|
|
|
|
<H2>Summary</H2>
|
|
<P>
|
|
The <SAMP>mod_setenvif</SAMP> module allows you to set environment
|
|
variables according to whether different aspects of the request match
|
|
<a href="../misc/FAQ.html#regex">regular expressions</a>
|
|
you specify. These environment variables can be used by
|
|
other parts of the server to make decisions about actions to be taken.
|
|
</P>
|
|
<P>The directives are considered in the order they appear in the
|
|
configuration files. So more complex sequences can be used, such
|
|
as this example, which sets <CODE>netscape</CODE> if the browser
|
|
is mozilla but not MSIE.
|
|
<BLOCKQUOTE><PRE>
|
|
BrowserMatch ^Mozilla netscape
|
|
BrowserMatch MSIE !netscape
|
|
</PRE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<p>For additional information, we proved a document on
|
|
<a href="../env.html">Environment Variables in Apache</a>.</p>
|
|
|
|
<H2>Directives</H2>
|
|
<UL>
|
|
<LI><A HREF="#BrowserMatch">BrowserMatch</A>
|
|
</LI>
|
|
<LI><A HREF="#BrowserMatchNoCase">BrowserMatchNoCase</A>
|
|
</LI>
|
|
<LI><A HREF="#SetEnvIf">SetEnvIf</A>
|
|
</LI>
|
|
<LI><A HREF="#SetEnvIfNoCase">SetEnvIfNoCase</A>
|
|
</LI>
|
|
</UL>
|
|
|
|
<HR> <!-- the HR is part of the directive description -->
|
|
<H2><A NAME="BrowserMatch">BrowserMatch directive</A></H2>
|
|
<P>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> BrowserMatch <EM>regex
|
|
envar</em>[=<em>value</em>] [<em>envar</em>[=<em>value</em>]] ...
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <i>none</i>
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
|
|
.htaccess
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> FileInfo
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_setenvif
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2
|
|
this directive was found in the now-obsolete mod_browser module)
|
|
</P>
|
|
<P>
|
|
The BrowserMatch directive defines environment variables based on the
|
|
<SAMP>User-Agent</SAMP> HTTP request header field. The first argument
|
|
should be a POSIX.2 extended regular expression (similar to an
|
|
<SAMP>egrep</SAMP>-style regex). The rest of the arguments give the
|
|
names of variables to set, and optionally values to which they should
|
|
be set. These take the form of
|
|
</P>
|
|
<OL>
|
|
<LI><SAMP><EM>varname</EM></SAMP>, or
|
|
</LI>
|
|
<LI><SAMP>!<EM>varname</EM></SAMP>, or
|
|
</LI>
|
|
<LI><SAMP><EM>varname</EM>=<EM>value</EM></SAMP>
|
|
</LI>
|
|
</OL>
|
|
<P>
|
|
In the first form, the value will be set to "1". The second
|
|
will remove the given variable if already defined, and the third will
|
|
set the variable to the value given by <SAMP><EM>value</EM></SAMP>. If a
|
|
<SAMP>User-Agent</SAMP> string matches more than one entry, they will
|
|
be merged. Entries are processed in the order in which they appear,
|
|
and later entries can override earlier ones.
|
|
</P>
|
|
<P>
|
|
For example:
|
|
</P>
|
|
<PRE>
|
|
BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
|
|
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
|
|
BrowserMatch MSIE !javascript
|
|
</PRE>
|
|
<P>
|
|
Note that the regular expression string is
|
|
<STRONG>case-sensitive</STRONG>. For cane-INsensitive matching, see
|
|
the
|
|
<A
|
|
HREF="#BrowserMatchNoCase"
|
|
><SAMP>BrowserMatchNoCase</SAMP></A>
|
|
directive.
|
|
</P>
|
|
<P>
|
|
The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP>
|
|
directives are special cases of the
|
|
<A
|
|
HREF="#SetEnvIf"
|
|
><SAMP>SetEnvIf</SAMP></A>
|
|
and
|
|
<A
|
|
HREF="#SetEnvIfNoCase"
|
|
><SAMP>SetEnvIfNoCase</SAMP></A>
|
|
directives. The following two lines have the same effect:
|
|
</P>
|
|
<PRE>
|
|
BrowserMatchNoCase Robot is_a_robot
|
|
SetEnvIfNoCase User-Agent Robot is_a_robot
|
|
</PRE>
|
|
|
|
<HR> <!-- the HR is part of the directive description -->
|
|
<H2>
|
|
<A NAME="BrowserMatchNoCase">BrowserMatchNoCase directive
|
|
</A>
|
|
</H2>
|
|
<P>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> BrowserMatchNoCase <EM>regex
|
|
envar</em>[=<em>value</em>] [<em>envar</em>[=<em>value</em>]] ...
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <EM>none</EM>
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
|
|
.htaccess
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> FileInfo
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_setenvif
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.2 and above (in Apache 1.2
|
|
this directive was found in the now-obsolete mod_browser module)
|
|
</P>
|
|
<P>
|
|
The <SAMP>BrowserMatchNoCase</SAMP> directive is semantically identical to
|
|
the
|
|
<A
|
|
HREF="#BrowserMatch"
|
|
><SAMP>BrowserMatch</SAMP></A>
|
|
directive. However, it provides for case-insensitive matching. For
|
|
example:
|
|
</P>
|
|
<PRE>
|
|
BrowserMatchNoCase mac platform=macintosh
|
|
BrowserMatchNoCase win platform=windows
|
|
</PRE>
|
|
<P>
|
|
The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP>
|
|
directives are special cases of the
|
|
<A
|
|
HREF="#SetEnvIf"
|
|
><SAMP>SetEnvIf</SAMP></A>
|
|
and
|
|
<A
|
|
HREF="#SetEnvIfNoCase"
|
|
><SAMP>SetEnvIfNoCase</SAMP></A>
|
|
directives. The following two lines have the same effect:
|
|
</P>
|
|
<PRE>
|
|
BrowserMatchNoCase Robot is_a_robot
|
|
SetEnvIfNoCase User-Agent Robot is_a_robot
|
|
</PRE>
|
|
|
|
<HR> <!-- the HR is part of the directive description -->
|
|
<H2>
|
|
<A NAME="SetEnvIf">SetEnvIf directive
|
|
</A>
|
|
</H2>
|
|
<P>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> SetEnvIf <EM> attribute regex
|
|
envar</em>[=<em>value</em>] [<em>envar</em>[=<em>value</em>]] ...
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <EM>none</EM>
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
|
|
.htaccess
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> FileInfo
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_setenvif
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above; the
|
|
Request_Protocol keyword and environment-variable matching are only
|
|
available with 1.3.7 and later
|
|
</P>
|
|
<P>
|
|
The <SAMP>SetEnvIf</SAMP> directive defines environment variables
|
|
based on attributes of the request. These attributes can be the
|
|
values of various HTTP request header fields (see
|
|
<a href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
|
|
for more information about these), or of other aspects of the request,
|
|
including the following:
|
|
</P>
|
|
<UL>
|
|
<LI><SAMP>Remote_Host</SAMP> - the hostname (if available) of the
|
|
client making the request
|
|
</LI>
|
|
<LI><SAMP>Remote_Addr</SAMP> - the IP address of the client making
|
|
the request
|
|
</LI>
|
|
<LI><SAMP>Remote_User</SAMP> - the authenticated username (if
|
|
available)
|
|
</LI>
|
|
<LI><SAMP>Request_Method</SAMP> - the name of the method being used
|
|
(<SAMP>GET</SAMP>, <SAMP>POST</SAMP>, <EM>et cetera</EM>)
|
|
</LI>
|
|
<LI><SAMP>Request_Protocol</SAMP> - the name and version of the protocol
|
|
with which the request was made (<EM>e.g.</EM>, "HTTP/0.9", "HTTP/1.1",
|
|
<EM>etc.</EM>)
|
|
</LI>
|
|
<LI><SAMP>Request_URI</SAMP> - the portion of the URL following the
|
|
scheme and host portion
|
|
</LI>
|
|
</UL>
|
|
<P>
|
|
Some of the more commonly used request header field names include
|
|
<SAMP>Host</SAMP>, <SAMP>User-Agent</SAMP>, and <SAMP>Referer</SAMP>.
|
|
</P>
|
|
<P>
|
|
If the <EM>attribute</EM> name doesn't match any of the special keywords,
|
|
nor any of the request's header field names, it is tested as the name
|
|
of an environment variable in the list of those associated with the request.
|
|
This allows <CODE>SetEnvIf</CODE> directives to test against the result
|
|
of prior matches.
|
|
</P>
|
|
<BLOCKQUOTE>
|
|
<STRONG>Only those environment variables defined by earlier
|
|
<CODE>SetEnvIf[NoCase]</CODE> directives are available for testing in
|
|
this manner. 'Earlier' means that they were defined at a broader scope
|
|
(such as server-wide) or previously in the current directive's
|
|
scope.</STRONG>
|
|
</BLOCKQUOTE>
|
|
<P>
|
|
Example:
|
|
</P>
|
|
<PRE>
|
|
SetEnvIf Request_URI "\.gif$" object_is_image=gif
|
|
SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
|
|
SetEnvIf Request_URI "\.xbm$" object_is_image=xbm
|
|
:
|
|
SetEnvIf Referer www\.mydomain\.com intra_site_referral
|
|
:
|
|
SetEnvIf object_is_image xbm XBIT_PROCESSING=1
|
|
</PRE>
|
|
<P>
|
|
The first three will set the environment variable <SAMP>object_is_image</SAMP> if the
|
|
request was for an image file, and the fourth sets
|
|
<SAMP>intra_site_referral</SAMP> if the referring page was somewhere
|
|
on the <SAMP>www.mydomain.com</SAMP> Web site.
|
|
</P>
|
|
|
|
<HR> <!-- the HR is part of the directive description -->
|
|
<H2>
|
|
<A NAME="SetEnvIfNoCase">SetEnvIfNoCase directive
|
|
</A>
|
|
</H2>
|
|
<P>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> SetEnvIfNoCase <EM> attribute regex
|
|
envar</em>[=<em>value</em>] [<em>envar</em>[=<em>value</em>]] ...
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <EM>none</EM>
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
|
|
.htaccess
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> FileInfo
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_setenvif
|
|
<BR>
|
|
<A
|
|
HREF="directive-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Apache 1.3 and above
|
|
</P>
|
|
<P>
|
|
The <SAMP>SetEnvIfNoCase</SAMP> is semantically identical to the
|
|
<A
|
|
HREF="#SetEnvIf"
|
|
><SAMP>SetEnvIf</SAMP></A>
|
|
directive, and differs only in that the regular expression matching is
|
|
performed in a case-insensitive manner. For example:
|
|
</P>
|
|
<PRE>
|
|
SetEnvIfNoCase Host Apache\.Org site=apache
|
|
</PRE>
|
|
<P>
|
|
This will cause the <SAMP>site</SAMP> environment variable to be set to
|
|
"<SAMP>apache</SAMP>" if the HTTP request header field
|
|
<SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>,
|
|
<SAMP>apache.org</SAMP>, or any other combination.
|
|
</P>
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|