Apache Module mod_setenvif

Summary

Themod_setenvif module allows you to set internal environment variables according to whether different aspects of the request match regular expressions you specify. These environment variables can be used by other parts of the server to make decisions about actions to be taken, as well as becoming available to CGI scripts and SSI pages.

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 setsnetscape if the browser is mozilla but not MSIE.

BrowserMatch ^Mozilla netscapeBrowserMatch MSIE !netscape

When the server looks up a path via an internalsubrequest such as looking for aDirectoryIndex or generating a directory listing withmod_autoindex, per-request environment variables arenot inherited in the subrequest. Additionally,SetEnvIf directives are not separately evaluated in the subrequest due to the API phasesmod_setenvif takes action in.

Directives

• BrowserMatch
• BrowserMatchNoCase
• SetEnvIf
• SetEnvIfExpr
• SetEnvIfNoCase

Bugfix checklist

• httpd changelog
• Known issues
• Report a bug

See also

• Environment Variables in Apache HTTP Server
• Comments

BrowserMatchDirective

TheBrowserMatch is a special cases of theSetEnvIf directive that sets environment variables conditional on theUser-Agent HTTP request header. The following two lines have the same effect:

BrowserMatch Robot is_a_robotSetEnvIf User-Agent Robot is_a_robot

Some additional examples:

BrowserMatch ^Mozilla forms jpeg=yes browser=netscapeBrowserMatch "^Mozilla/[2-3]" tables agif frames javascriptBrowserMatch MSIE !javascript

BrowserMatchNoCaseDirective

TheBrowserMatchNoCase directive is semantically identical to theBrowserMatch directive. However, it provides for case-insensitive matching. For example:

BrowserMatchNoCase mac platform=macintoshBrowserMatchNoCase win platform=windows

TheBrowserMatch andBrowserMatchNoCase directives are special cases of theSetEnvIf andSetEnvIfNoCase directives. The following two lines have the same effect:

BrowserMatchNoCase Robot is_a_robotSetEnvIfNoCase User-Agent Robot is_a_robot

SetEnvIfDirective

TheSetEnvIf directive defines environment variables based on attributes of the request. Theattribute specified in the first argument can be one of four things:

1. An HTTP request header field (seeRFC2616 for more information about these); for example:Host,User-Agent,Referer, andAccept-Language. A regular expression may be used to specify a set of request headers.
2. One of the following aspects of the request:
   • Remote_Host - the hostname (if available) of the client making the request
   • Remote_Addr - the IP address of the client making the request
   • Server_Addr - the IP address of the server on which the request was received (only with versions later than 2.0.43)
   • Request_Method - the name of the method being used (GET,POST,et cetera)
   • Request_Protocol - the name and version of the protocol with which the request was made (e.g., "HTTP/0.9", "HTTP/1.1",etc.)
   • Request_URI - the resource requested on the HTTP request line -- generally the portion of the URL following the scheme and host portion without the query string. See theRewriteCond directive ofmod_rewrite for extra information on how to match your query string.
3. The name of an environment variable in the list of thoseassociated with the request. This allowsSetEnvIf directives to test against the resultof prior matches. Only those environment variables defined by earlierSetEnvIf[NoCase] directives are available for testing inthis manner. 'Earlier' means that they were defined at a broader scope(such as server-wide) or previously in the current directive's scope.Environment variables will be considered only if there was no matchamong request characteristics and a regular expression was notused for theattribute.

The second argument (regex) is aregular expression. If theregexmatches against theattribute, then the remainder of thearguments are evaluated.

The rest of the arguments give the names of variables to set, andoptionally values to which they should be set. These take the formof

1. varname, or
2. !varname, or
3. varname=value

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 literal value given byvalue. Since version 2.0.51, Apache httpd will recognize occurrences of$1..$9 withinvalue and replace them by parenthesized subexpressions ofregex.$0 provides access to the whole string matched by that pattern.

SetEnvIf Request_URI "\.gif$" object_is_image=gifSetEnvIf Request_URI "\.jpg$" object_is_image=jpgSetEnvIf Request_URI "\.xbm$" object_is_image=xbm    SetEnvIf Referer www\.mydomain\.example\.com intra_site_referral    SetEnvIf object_is_image xbm XBIT_PROCESSING=1    SetEnvIf Request_URI "\.(.*)$" EXTENSION=$1SetEnvIf ^TS  ^[a-z]  HAVE_TS

The first three will set the environment variableobject_is_image if the request was for an image file, and the fourth setsintra_site_referral if the referring page was somewhere on thewww.mydomain.example.com Web site.

The last example will set environment variableHAVE_TS if the request contains any headers that begin with "TS" whose values begins with any character in the set [a-z].

See also

• Environment Variables in Apache HTTP Server,for additional examples.

SetEnvIfExprDirective

TheSetEnvIfExpr directive defines environment variables based on anexpression. These expressions will be evaluated at runtime, and appliedenv-variable in the same fashion asSetEnvIf, including backreferences.

    SetEnvIfExpr "tolower(req('X-Sendfile')) == 'd:\images\very_big.iso')" iso_delivered    SetEnvIfExpr "tolower(req('X-Sendfile')) =~ /(.*\.iso$)/" iso-path=$1

This would set the environment variableiso_delivered every time our application attempts to send it viaX-Sendfile

A more useful example would be to set the variable rfc1918 if the remote IP address is a private address according to RFC 1918:

SetEnvIfExpr "-R '10.0.0.0/8' || -R '172.16.0.0/12' || -R '192.168.0.0/16'" rfc1918

See also

• Expressions in Apache HTTP Server,for a complete reference and more examples.
• <If> can be used to achieve similarresults.
• mod_filter

SetEnvIfNoCaseDirective

TheSetEnvIfNoCase is semantically identical to theSetEnvIf directive, and differs only in that the regular expression matching is performed in a case-insensitive manner. For example:

SetEnvIfNoCase Host Example\.Org site=example

This will cause thesite environment variable to be set to "example" if the HTTP request header fieldHost: was included and containedExample.Org,example.org, or any other combination.