From: Joshua Slive Date: Thu, 14 Feb 2002 00:48:39 +0000 (+0000) Subject: Add the first xml doc. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9199635e8e5e2a6d7d10538d68e72340cd0d2f92;p=apache Add the first xml doc. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93399 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_setenvif.xml b/docs/manual/mod/mod_setenvif.xml new file mode 100644 index 0000000000..41bc4ddb04 --- /dev/null +++ b/docs/manual/mod/mod_setenvif.xml @@ -0,0 +1,258 @@ + + + + +mod_setenvif +Base +setenvif_module +mod_setenvif.c +Available in Apache 1.3 and later + +Allows the setting of environment variables based +on characteristics of the request + + + +

The mod_setenvif module allows you to set + 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.

+ +

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

+ + + BrowserMatch ^Mozilla netscape
+ BrowserMatch MSIE !netscape
+ + + +Environment Variables in Apache + + +BrowserMatch +Sets environment variables conditional on HTTP User-Agent + +BrowserMatch regex env-variable[=value] +[env-variable[=value]] ... +none +server config, virtual host, directory, .htaccess +FileInfo +Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module) + + +

The BrowserMatch directive defines + environment variables based on the User-Agent HTTP + request header field. The first argument should be a POSIX.2 + extended regular expression (similar to an + egrep-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

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

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 + value. If a User-Agent + 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.

+ +

For example:

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

Note that the regular expression string is + case-sensitive. For case-INsensitive matching, + see the BrowserMatchNoCase + directive.

+ +

The BrowserMatch and + BrowserMatchNoCase directives are special cases of + the SetEnvIf and SetEnvIfNoCase + directives. The following two lines have the same effect:

+ + BrowserMatchNoCase Robot is_a_robot
+ SetEnvIfNoCase User-Agent Robot is_a_robot
+ + + + + +BrowserMatchNoCase +Sets environment variables conditional on User-Agent without +respect to case +BrowserMatchNoCase regex env-variable[=value] + [env-variable[=value]] ... +none +server config, virtual host, directory, .htaccess +FileInfo +Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module) + + + +

The BrowserMatchNoCase directive is + semantically identical to the BrowserMatch directive. + However, it provides for case-insensitive matching. For + example:

+ + BrowserMatchNoCase mac platform=macintosh
+ BrowserMatchNoCase win platform=windows
+ + +

The BrowserMatch and + BrowserMatchNoCase directives are special cases of + the SetEnvIf and SetEnvIfNoCase + directives. The following two lines have the same effect:

+ + BrowserMatchNoCase Robot is_a_robot
+ SetEnvIfNoCase User-Agent Robot is_a_robot
+ + + + + +SetEnvIf +Sets environment variables based on attributes of the request + +SetEnvIf attribute + regex env-variable[=value] + [env-variable[=value]] ... +none + server config, virtual host, directory, .htaccess +FileInfo +Apache 1.3 and + above; the Request_Protocol keyword and environment-variable + matching are only available with 1.3.7 and later + + +

The SetEnvIf directive defines environment + variables based on attributes of the request. These attributes + can be the values of various HTTP request header fields (see RFC2616 + for more information about these), or of other aspects of the + request, including the following:

+ +
    +
  • Remote_Host - the hostname (if available) of + the client making the request
    • + +
  • Remote_Addr - the IP address of the client + making the request
    • + +
  • Remote_User - the authenticated username (if + available)
    • + +
  • 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 portion of the URL + following the scheme and host portion
    • +
+ +

Some of the more commonly used request header field names + include Host, User-Agent, and + Referer.

+ +

If the attribute 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 + SetEnvIf directives to test against the result of + prior matches.

+ + + Only those environment variables defined by earlier + SetEnvIf[NoCase] 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. + + +

attribute may be a regular expression when used to + match a request header. If attribute is a regular + expression and it doesn't match any of the request's header + names, then attribute is not tested against the + request's environment variable list.

+ + +Example: + 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
+ :
+ SetEnvIf ^TS* ^[a-z].* HAVE_TS
+ + +

The first three will set the environment variable + object_is_image if the request was for an image + file, and the fourth sets intra_site_referral if + the referring page was somewhere on the + www.mydomain.com Web site.

+ +

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

+ + + + +SetEnvIfNoCase +Sets environment variables based on attributes of the request +without respect to case +SetEnvIfNoCase attribute regex env-variable[=value] + [env-variable[=value]] ... +none +server config, virtual host, directory, .htaccess +FileInfo +Apache 1.3 and above + + + +

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

+ + SetEnvIfNoCase Host Apache\.Org site=apache + + +

This will cause the site environment variable + to be set to "apache" if the HTTP request header + field Host: was included and contained + Apache.Org, apache.org, or any other + combination.

+ + + \ No newline at end of file