<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
</td></tr></table>
+<h3>Basic Environment Manipulation</h3>
+
<p>The most basic way to set an environment variable in Apache is
using the unconditional <code>SetEnv</code> directive. Variables
-may also be passed from the environment when Apache is started
-using the <code>PassEnv</code> directive.</p>
+may also be passed from the environment of the shell which started
+the server using the <code>PassEnv</code> directive.</p>
+
+<h3>Conditional Per-Request Settings</h3>
+
+<p>For additional flexibility, the directives provided by mod_setenvif
+allow environment variables to be set on a per-request basis,
+conditional on characteristics of particular requests. For example, a
+variable could be set only when a specific browser (User-Agent) is
+making a request, or only when a specific Referer [sic] header is
+found. Even more flexibility is available through the mod_rewrite's
+<code>RewriteRule</code> which uses the <code>[E=...]</code> option to
+set environment variables.</p>
-<p>The directives provided by mod_setenvif allow environment variables
-to be set on a per-request basis based on characteristics of particular
-requests. For example, a variable could be set only when a specific
-browser (User-Agent) is making a request, or only when a specific
-Referer header is found. Even more flexibility is available through the
-mod_rewrite's <code>RewriteRule</code> which uses the
-<code>[E=...]</code> option to set environment variables.</p>
+<h3>Unique Identifiers</h3>
<p>Finally, mod_unique_id sets the environment variable
<code>UNIQUE_ID</code> for each request to a value which is guaranteed
to be unique across "all" requests under very specific conditions.</p>
+<h3>Standard CGI Variables</h3>
+
+<p>In addition to all environment variables set within the Apache
+configuration and passed from the shell, CGI scripts and SSI pages are
+provided with a set of environment variables containing
+meta-information about the request as required by the <a
+href="misc/FAQ.html#cgi-spec">CGI specification</a>.</p>
+
+<h3>Some Caveats</h3>
+
+<ul>
+
+<li>It is not possible to override or change the standard CGI
+variables using the environment manipulation directives.</li>
+
+<li>When <a href="suexec.html">suexec</a> is used to launch CGI
+scripts, the environment will be cleaned down to a set of
+<em>safe</em> variables before CGI scripts are launched. The list of
+<em>safe</em> variables is defined at compile-time in
+<code>suexec.c</code>.</li>
+
+<li>For portability reasons, the names of environment variables
+may contain only letters, numbers, and the underscore character.
+In addition, the first character may not be a number. Characters
+which do not match this restriction will be replaced by an
+underscore when passed to CGI scripts and SSI pages.</li>
+
+</ul>
+
+
<hr>
<h2><a name="using">Using Environment Variables</a></h2>
</td><td valign="top">
<strong>Related Directives</strong><br><br>
-<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>
-<a href="mod/mod_log_config.html#customlog-conditional">CustomLog
-(conditional)</a><br>
-<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>
+<A HREF="mod/mod_access.html#allow">Allow</A><br>
+<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>
+<A HREF="mod/mod_access.html#deny">Deny</A><br>
<a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
<A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
</td></tr></table>
+<h3>CGI Scripts</h3>
+
<p>One of the primary uses of environment variables is to communicate
-information to CGI scripts. In addition to all environment variables
-set within Apache, CGI scripts are provided with a set of
-meta-information about the request as provided for in the <a
-href="misc/FAQ.html#cgi-spec">CGI specification</a>. If you are using
-<a href="suexec.html">Suexec</a> to execute CGI scripts under
-different userids, note that the environment will be cleaned down to a
-set of <em>safe</em> environment variables before the CGI script is
-executed. The set of safe environment variables is defined at
-compile time in <code>suexec.c</code>.
+information to CGI scripts. As discussed above, the environment
+passed to CGI scripts includes standard meta-information about the request
+in addition to any variables set within the Apache configuration.
+For more details, see the <a href="howto/cgi.html">CGI tutorial</a>.
</p>
+<h3>SSI Pages</h3>
+
<p>Server-parsed (SSI) documents processed by mod_include's
<code>server-parsed</code> handler can print environment variables
using the <code>echo</code> element, and can use environment variables
-in flow control elements.
+in flow control elements to makes parts of a page conditional on
+characteristics of a request. Apache also provides SSI pages with the
+standard CGI environment variables as discussed above. For more
+details, see the <a href="howto/ssi.html">SSI tutorial</a>.
</p>
+<h3>Access Control</h3>
+
<p>Access to the server can be controlled based on the value of
environment variables using the <code>allow from env=</code> and
<code>deny from env=</code></a> directives. In combination with
(User-Agent).
</p>
+<h3>Conditional Logging</h3>
+
<p>Environment variables can be logged in the access log using the
<code>LogFormat</code> option <code>%e</code>. In addition, the
decision on whether or not to log requests can be made based on the
log requests from clients which are outside your subnet.
</p>
+<h3>URL Rewriting</h3>
+
<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
decisions conditional on environment variables. Note that the
<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
</td></tr></table>
+<h3>Basic Environment Manipulation</h3>
+
<p>The most basic way to set an environment variable in Apache is
using the unconditional <code>SetEnv</code> directive. Variables
-may also be passed from the environment when Apache is started
-using the <code>PassEnv</code> directive.</p>
+may also be passed from the environment of the shell which started
+the server using the <code>PassEnv</code> directive.</p>
+
+<h3>Conditional Per-Request Settings</h3>
+
+<p>For additional flexibility, the directives provided by mod_setenvif
+allow environment variables to be set on a per-request basis,
+conditional on characteristics of particular requests. For example, a
+variable could be set only when a specific browser (User-Agent) is
+making a request, or only when a specific Referer [sic] header is
+found. Even more flexibility is available through the mod_rewrite's
+<code>RewriteRule</code> which uses the <code>[E=...]</code> option to
+set environment variables.</p>
-<p>The directives provided by mod_setenvif allow environment variables
-to be set on a per-request basis based on characteristics of particular
-requests. For example, a variable could be set only when a specific
-browser (User-Agent) is making a request, or only when a specific
-Referer header is found. Even more flexibility is available through the
-mod_rewrite's <code>RewriteRule</code> which uses the
-<code>[E=...]</code> option to set environment variables.</p>
+<h3>Unique Identifiers</h3>
<p>Finally, mod_unique_id sets the environment variable
<code>UNIQUE_ID</code> for each request to a value which is guaranteed
to be unique across "all" requests under very specific conditions.</p>
+<h3>Standard CGI Variables</h3>
+
+<p>In addition to all environment variables set within the Apache
+configuration and passed from the shell, CGI scripts and SSI pages are
+provided with a set of environment variables containing
+meta-information about the request as required by the <a
+href="misc/FAQ.html#cgi-spec">CGI specification</a>.</p>
+
+<h3>Some Caveats</h3>
+
+<ul>
+
+<li>It is not possible to override or change the standard CGI
+variables using the environment manipulation directives.</li>
+
+<li>When <a href="suexec.html">suexec</a> is used to launch CGI
+scripts, the environment will be cleaned down to a set of
+<em>safe</em> variables before CGI scripts are launched. The list of
+<em>safe</em> variables is defined at compile-time in
+<code>suexec.c</code>.</li>
+
+<li>For portability reasons, the names of environment variables
+may contain only letters, numbers, and the underscore character.
+In addition, the first character may not be a number. Characters
+which do not match this restriction will be replaced by an
+underscore when passed to CGI scripts and SSI pages.</li>
+
+</ul>
+
+
<hr>
<h2><a name="using">Using Environment Variables</a></h2>
</td><td valign="top">
<strong>Related Directives</strong><br><br>
-<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>
-<a href="mod/mod_log_config.html#customlog-conditional">CustomLog
-(conditional)</a><br>
-<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>
+<A HREF="mod/mod_access.html#allow">Allow</A><br>
+<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>
+<A HREF="mod/mod_access.html#deny">Deny</A><br>
<a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
<A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
</td></tr></table>
+<h3>CGI Scripts</h3>
+
<p>One of the primary uses of environment variables is to communicate
-information to CGI scripts. In addition to all environment variables
-set within Apache, CGI scripts are provided with a set of
-meta-information about the request as provided for in the <a
-href="misc/FAQ.html#cgi-spec">CGI specification</a>. If you are using
-<a href="suexec.html">Suexec</a> to execute CGI scripts under
-different userids, note that the environment will be cleaned down to a
-set of <em>safe</em> environment variables before the CGI script is
-executed. The set of safe environment variables is defined at
-compile time in <code>suexec.c</code>.
+information to CGI scripts. As discussed above, the environment
+passed to CGI scripts includes standard meta-information about the request
+in addition to any variables set within the Apache configuration.
+For more details, see the <a href="howto/cgi.html">CGI tutorial</a>.
</p>
+<h3>SSI Pages</h3>
+
<p>Server-parsed (SSI) documents processed by mod_include's
<code>server-parsed</code> handler can print environment variables
using the <code>echo</code> element, and can use environment variables
-in flow control elements.
+in flow control elements to makes parts of a page conditional on
+characteristics of a request. Apache also provides SSI pages with the
+standard CGI environment variables as discussed above. For more
+details, see the <a href="howto/ssi.html">SSI tutorial</a>.
</p>
+<h3>Access Control</h3>
+
<p>Access to the server can be controlled based on the value of
environment variables using the <code>allow from env=</code> and
<code>deny from env=</code></a> directives. In combination with
(User-Agent).
</p>
+<h3>Conditional Logging</h3>
+
<p>Environment variables can be logged in the access log using the
<code>LogFormat</code> option <code>%e</code>. In addition, the
decision on whether or not to log requests can be made based on the
log requests from clients which are outside your subnet.
</p>
+<h3>URL Rewriting</h3>
+
<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
decisions conditional on environment variables. Note that the
<!--#include virtual="header.html" -->
<H1 ALIGN="CENTER">Apache module mod_env</H1>
-<p>This module provides for
-passing environment variables to CGI/SSI scripts.</p>
+<p>This module provides for modifying the environment which
+is passed to CGI scripts and SSI pages.</p>
<P><A
HREF="module-dict.html#Status"
</P>
<H2>Summary</H2>
-<!-- XXX: Should mention mod_setenvif and the effect of suexec -->
-<p>This module allows Apache's CGI and SSI environment to inherit
-environment variables from the shell which invoked the httpd process.
-CERN web-servers are able to do this, so this module is especially
-useful to web-admins who wish to migrate from CERN to Apache without
-rewriting all their scripts</p>
+
+<p>This module allows for control of the environment that will be
+provided to CGI scripts and SSI pages. Environment variables may be
+passed from the shell which invoked the httpd process. Alternatively,
+environment variables may be set or unset within the configuration
+process.</p>
+
+<p>For additional information, we provide a document on
+<a href="../env.html">Environment Variables in Apache</a>.</p>
<H2>Directives</H2>
<UL>
Apache 1.1 and later.<P>
Specifies one or more environment variables to pass to CGI scripts
-from the server's own environment. Example:
+and SSI pages from the environment of the shell which invoked
+the httpd process. Example:
<PRE>
PassEnv LD_LIBRARY_PATH
</PRE>
Apache 1.1 and later.<P>
Sets an environment variable, which is then passed on to CGI
-scripts. Example:
+scripts and SSI pages. Example:
<PRE>
SetEnv SPECIAL_PATH /foo/bin
</PRE>
Apache 1.1 and later.<P>
Removes one or more environment variables from those passed on to
-CGI scripts. Example:
+CGI scripts and SSI pages. Example:
<PRE>
UnsetEnv LD_LIBRARY_PATH
</PRE>
-
-
-<P>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
<P>
The <SAMP>mod_setenvif</SAMP> module allows you to set environment
variables according to whether different aspects of the request match
- regular expressions you specify. These envariables can be used by
+ <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
</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>
SetEnvIf object_is_image xbm XBIT_PROCESSING=1
</PRE>
<P>
- The first three will set the envariable <SAMP>object_is_image</SAMP> if the
+ 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.
SetEnvIfNoCase Host Apache\.Org site=apache
</PRE>
<P>
- This will cause the <SAMP>site</SAMP> envariable to be set to
+ 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.
projects / apache / commitdiff