mirror of
https://github.com/apache/httpd.git
synced 2025-07-10 08:01:00 +03:00
fda8a5e6f9
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1727647 13f79535-47bb-0310-9956-ffa450edef68
329 lines
13 KiB
XML
329 lines
13 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_setenvif.xml.meta">
|
|
|
|
<name>mod_setenvif</name>
|
|
<description>Allows the setting of environment variables based
|
|
on characteristics of the request</description>
|
|
<status>Base</status>
|
|
<sourcefile>mod_setenvif.c</sourcefile>
|
|
<identifier>setenvif_module</identifier>
|
|
|
|
|
|
<summary>
|
|
|
|
<p>The <module>mod_setenvif</module> 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.</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.</p>
|
|
|
|
<highlight language="config">
|
|
BrowserMatch ^Mozilla netscape
|
|
BrowserMatch MSIE !netscape
|
|
</highlight>
|
|
|
|
<p>When the server looks up a path via an internal
|
|
<glossary ref="subrequest">subrequest</glossary> such as looking
|
|
for a <directive module="mod_dir" >DirectoryIndex</directive>
|
|
or generating a directory listing with <module>mod_autoindex</module>,
|
|
per-request environment variables are <em>not</em> inherited in the
|
|
subrequest. Additionally,
|
|
<directive module="mod_setenvif">SetEnvIf</directive> directives
|
|
are not separately evaluated in the subrequest due to the API phases
|
|
<module>mod_setenvif</module> takes action in.</p>
|
|
|
|
</summary>
|
|
|
|
<seealso><a href="../env.html">Environment Variables in Apache HTTP Server</a></seealso>
|
|
|
|
<directivesynopsis>
|
|
<name>BrowserMatch</name>
|
|
<description>Sets environment variables conditional on HTTP User-Agent
|
|
</description>
|
|
<syntax>BrowserMatch <em>regex [!]env-variable</em>[=<em>value</em>]
|
|
[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
<p>The <directive>BrowserMatch</directive> is a special cases of the
|
|
<directive module="mod_setenvif">SetEnvIf</directive> directive that
|
|
sets environment variables conditional on the
|
|
<code>User-Agent</code> HTTP request header. The following two
|
|
lines have the same effect:</p>
|
|
<highlight language="config">
|
|
BrowserMatch Robot is_a_robot
|
|
SetEnvIf User-Agent Robot is_a_robot
|
|
</highlight>
|
|
|
|
<p>Some additional examples:</p>
|
|
<highlight language="config">
|
|
BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
|
|
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
|
|
BrowserMatch MSIE !javascript
|
|
</highlight>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>BrowserMatchNoCase</name>
|
|
<description>Sets environment variables conditional on User-Agent without
|
|
respect to case</description>
|
|
<syntax>BrowserMatchNoCase <em>regex [!]env-variable</em>[=<em>value</em>]
|
|
[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
|
|
<p>The <directive>BrowserMatchNoCase</directive> directive is
|
|
semantically identical to the <directive
|
|
module="mod_setenvif">BrowserMatch</directive> directive.
|
|
However, it provides for case-insensitive matching. For
|
|
example:</p>
|
|
<highlight language="config">
|
|
BrowserMatchNoCase mac platform=macintosh
|
|
BrowserMatchNoCase win platform=windows
|
|
</highlight>
|
|
|
|
<p>The <directive>BrowserMatch</directive> and
|
|
<directive>BrowserMatchNoCase</directive> directives are special cases of
|
|
the <directive module="mod_setenvif">SetEnvIf</directive> and <directive
|
|
module="mod_setenvif">SetEnvIfNoCase</directive>
|
|
directives. The following two lines have the same effect:</p>
|
|
<highlight language="config">
|
|
BrowserMatchNoCase Robot is_a_robot
|
|
SetEnvIfNoCase User-Agent Robot is_a_robot
|
|
</highlight>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SetEnvIf</name>
|
|
<description>Sets environment variables based on attributes of the request
|
|
</description>
|
|
<syntax>SetEnvIf <em>attribute
|
|
regex [!]env-variable</em>[=<em>value</em>]
|
|
[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
<p>The <directive>SetEnvIf</directive> directive defines
|
|
environment variables based on attributes of the request. The
|
|
<em>attribute</em> specified in the first argument can be one of four
|
|
things:</p>
|
|
|
|
<ol>
|
|
<li>An HTTP request header field (see <a
|
|
href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
|
|
for more information about these); for example: <code>Host</code>,
|
|
<code>User-Agent</code>, <code>Referer</code>, and
|
|
<code>Accept-Language</code>. A regular expression may be
|
|
used to specify a set of request headers.</li>
|
|
|
|
<li>One of the following aspects of the request:
|
|
<ul>
|
|
<li><code>Remote_Host</code> - the hostname (if available) of
|
|
the client making the request</li>
|
|
|
|
<li><code>Remote_Addr</code> - the IP address of the client
|
|
making the request</li>
|
|
|
|
<li><code>Server_Addr</code> - the IP address of the server
|
|
on which the request was received (only with versions later
|
|
than 2.0.43)</li>
|
|
|
|
<li><code>Request_Method</code> - the name of the method
|
|
being used (<code>GET</code>, <code>POST</code>, <em>et
|
|
cetera</em>)</li>
|
|
|
|
<li><code>Request_Protocol</code> - 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><code>Request_URI</code> - 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
|
|
the <directive module="mod_rewrite">RewriteCond</directive>
|
|
directive of <module>mod_rewrite</module> for extra information on
|
|
how to match your query string.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>The name of an environment variable in the list of those
|
|
associated with the request. This allows
|
|
<directive>SetEnvIf</directive> directives to test against the result
|
|
of prior matches. 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.
|
|
Environment variables will be considered only if there was no match
|
|
among request characteristics and a regular expression was not
|
|
used for the <em>attribute</em>.</li>
|
|
|
|
</ol>
|
|
|
|
<p>The second argument (<em>regex</em>) is a <glossary
|
|
ref="regex">regular expression</glossary>. If the <em>regex</em>
|
|
matches against the <em>attribute</em>, then the remainder of the
|
|
arguments are evaluated.</p>
|
|
|
|
<p>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><code><em>varname</em></code>, or</li>
|
|
|
|
<li><code>!<em>varname</em></code>, or</li>
|
|
|
|
<li><code><em>varname</em>=<em>value</em></code></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 literal value given by
|
|
<code><em>value</em></code>. Since version 2.0.51, Apache httpd will
|
|
recognize occurrences of <code>$1</code>..<code>$9</code> within
|
|
<var>value</var> and replace them by parenthesized subexpressions
|
|
of <var>regex</var>. <code>$0</code> provides access to the whole
|
|
string matched by that pattern.</p>
|
|
|
|
<highlight language="config">
|
|
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\.example\.com intra_site_referral
|
|
|
|
SetEnvIf object_is_image xbm XBIT_PROCESSING=1
|
|
|
|
SetEnvIf Request_URI "\.(.*)$" EXTENSION=$1
|
|
|
|
SetEnvIf ^TS ^[a-z] HAVE_TS
|
|
</highlight>
|
|
|
|
<p>The first three will set the environment variable
|
|
<code>object_is_image</code> if the request was for an image
|
|
file, and the fourth sets <code>intra_site_referral</code> if
|
|
the referring page was somewhere on the
|
|
<code>www.mydomain.example.com</code> Web site.</p>
|
|
|
|
<p>The last example will set environment variable
|
|
<code>HAVE_TS</code> if the request contains any headers that
|
|
begin with "TS" whose values begins with any character in the
|
|
set [a-z].</p>
|
|
</usage>
|
|
|
|
<seealso><a href="../env.html">Environment Variables in Apache HTTP Server</a>,
|
|
for additional examples.
|
|
</seealso>
|
|
</directivesynopsis>
|
|
|
|
|
|
<directivesynopsis>
|
|
|
|
<name>SetEnvIfExpr</name>
|
|
<description>Sets environment variables based on an ap_expr expression</description>
|
|
<syntax>SetEnvIfExpr <em>expr
|
|
[!]env-variable</em>[=<em>value</em>]
|
|
[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
<p>The <directive>SetEnvIfExpr</directive> directive defines
|
|
environment variables based on an <directive module="core" type="section">If</directive>
|
|
<code>ap_expr</code>. These expressions will be evaluated at runtime,
|
|
and applied <em>env-variable</em> in the same fashion as <directive
|
|
>SetEnvIf</directive>.</p>
|
|
|
|
<highlight language="config">
|
|
SetEnvIfExpr "tolower(req('X-Sendfile')) == 'd:\images\very_big.iso')" iso_delivered
|
|
</highlight>
|
|
|
|
<p>This would set the environment variable <code>iso_delivered</code>
|
|
every time our application attempts to send it via <code>X-Sendfile</code></p>
|
|
|
|
<p>A more useful example would be to set the variable rfc1918 if the
|
|
remote IP address is a private address according to RFC 1918:</p>
|
|
|
|
<highlight language="config">
|
|
SetEnvIfExpr "-R '10.0.0.0/8' || -R '172.16.0.0/12' || -R '192.168.0.0/16'" rfc1918
|
|
</highlight>
|
|
</usage>
|
|
|
|
<seealso><a href="../expr.html">Expressions in Apache HTTP Server</a>,
|
|
for a complete reference and more examples.</seealso>
|
|
<seealso><directive module="core" type="section">If</directive> can be used to achieve similar
|
|
results.</seealso>
|
|
<seealso><module>mod_filter</module></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SetEnvIfNoCase</name>
|
|
<description>Sets environment variables based on attributes of the request
|
|
without respect to case</description>
|
|
<syntax>SetEnvIfNoCase <em>attribute regex
|
|
[!]env-variable</em>[=<em>value</em>]
|
|
[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
|
|
<usage>
|
|
|
|
<p>The <directive>SetEnvIfNoCase</directive> is semantically identical to
|
|
the <directive module="mod_setenvif">SetEnvIf</directive> directive,
|
|
and differs only in that the regular expression matching is
|
|
performed in a case-insensitive manner. For example:</p>
|
|
<highlight language="config">
|
|
SetEnvIfNoCase Host Example\.Org site=example
|
|
</highlight>
|
|
|
|
<p>This will cause the <code>site</code> environment variable
|
|
to be set to "<code>example</code>" if the HTTP request header
|
|
field <code>Host:</code> was included and contained
|
|
<code>Example.Org</code>, <code>example.org</code>, or any other
|
|
combination.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
</modulesynopsis>
|