Commit 1337dafe authored by Joshua Slive's avatar Joshua Slive
Browse files

This is the second in a series of clean-ups of the 

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
parent fc139b17

docs/manual/env.html

+67 −23
Original line number Original line Diff line number Diff line
@@ -54,23 +54,60 @@ explains some of the ways to use environment variables in Apache.</p> 
<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>

<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>

</td></tr></table>

</td></tr></table>





<h3>Basic Environment Manipulation</h3>



<p>The most basic way to set an environment variable in Apache is

<p>The most basic way to set an environment variable in Apache is

using the unconditional <code>SetEnv</code> directive.  Variables

using the unconditional <code>SetEnv</code> directive.  Variables

may also be passed from the environment when Apache is started

may also be passed from the environment of the shell which started

using the <code>PassEnv</code> directive.</p>

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

<h3>Unique Identifiers</h3>

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>





<p>Finally, mod_unique_id sets the environment variable

<p>Finally, mod_unique_id sets the environment variable

<code>UNIQUE_ID</code> for each request to a value which is guaranteed

<code>UNIQUE_ID</code> for each request to a value which is guaranteed

to be unique across "all" requests under very specific conditions.</p>

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>

<hr>





<h2><a name="using">Using Environment Variables</a></h2>

<h2><a name="using">Using Environment Variables</a></h2>
@@ -87,34 +124,37 @@ to be unique across "all" requests under very specific conditions.</p> 
</td><td valign="top">

</td><td valign="top">

<strong>Related Directives</strong><br><br>

<strong>Related Directives</strong><br><br>





<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>

<A HREF="mod/mod_access.html#allow">Allow</A><br>

<a href="mod/mod_log_config.html#customlog-conditional">CustomLog

<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>

(conditional)</a><br>

<A HREF="mod/mod_access.html#deny">Deny</A><br>

<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>

<a href="mod/mod_log_config.html#logformat">LogFormat</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#RewriteCond">RewriteCond</A><br>

<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>

<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>





</td></tr></table>

</td></tr></table>





<h3>CGI Scripts</h3>



<p>One of the primary uses of environment variables is to communicate

<p>One of the primary uses of environment variables is to communicate

information to CGI scripts.  In addition to all environment variables

information to CGI scripts.  As discussed above, the environment

set within Apache, CGI scripts are provided with a set of

passed to CGI scripts includes standard meta-information about the request

meta-information about the request as provided for in the <a

in addition to any variables set within the Apache configuration.

href="misc/FAQ.html#cgi-spec">CGI specification</a>.  If you are using

For more details, see the <a href="howto/cgi.html">CGI tutorial</a>.

<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>.

</p>

</p>





<h3>SSI Pages</h3>



<p>Server-parsed (SSI) documents processed by mod_include's

<p>Server-parsed (SSI) documents processed by mod_include's

<code>server-parsed</code> handler can print environment variables

<code>server-parsed</code> handler can print environment variables

using the <code>echo</code> element, and can use 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>

</p>





<h3>Access Control</h3>



<p>Access to the server can be controlled based on the value of

<p>Access to the server can be controlled based on the value of

environment variables using the <code>allow from env=</code> and

environment variables using the <code>allow from env=</code> and

<code>deny from env=</code></a> directives.  In combination with

<code>deny from env=</code></a> directives.  In combination with
@@ -124,6 +164,8 @@ can use these directives to deny access to a particular browser 
(User-Agent).

(User-Agent).

</p>

</p>





<h3>Conditional Logging</h3>



<p>Environment variables can be logged in the access log using the

<p>Environment variables can be logged in the access log using the

<code>LogFormat</code> option <code>%e</code>.  In addition, 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

decision on whether or not to log requests can be made based on the
@@ -135,6 +177,8 @@ for filenames ending in <code>gif</code>, or you can choose to only 
log requests from clients which are outside your subnet.

log requests from clients which are outside your subnet.

</p>

</p>





<h3>URL Rewriting</h3>



<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the

<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the

<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make

<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make

decisions conditional on environment variables.  Note that the

decisions conditional on environment variables.  Note that the

docs/manual/env.html.en

+67 −23
Original line number Original line Diff line number Diff line
@@ -54,23 +54,60 @@ explains some of the ways to use environment variables in Apache.</p> 
<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>

<A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>

</td></tr></table>

</td></tr></table>





<h3>Basic Environment Manipulation</h3>



<p>The most basic way to set an environment variable in Apache is

<p>The most basic way to set an environment variable in Apache is

using the unconditional <code>SetEnv</code> directive.  Variables

using the unconditional <code>SetEnv</code> directive.  Variables

may also be passed from the environment when Apache is started

may also be passed from the environment of the shell which started

using the <code>PassEnv</code> directive.</p>

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

<h3>Unique Identifiers</h3>

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>





<p>Finally, mod_unique_id sets the environment variable

<p>Finally, mod_unique_id sets the environment variable

<code>UNIQUE_ID</code> for each request to a value which is guaranteed

<code>UNIQUE_ID</code> for each request to a value which is guaranteed

to be unique across "all" requests under very specific conditions.</p>

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>

<hr>





<h2><a name="using">Using Environment Variables</a></h2>

<h2><a name="using">Using Environment Variables</a></h2>
@@ -87,34 +124,37 @@ to be unique across "all" requests under very specific conditions.</p> 
</td><td valign="top">

</td><td valign="top">

<strong>Related Directives</strong><br><br>

<strong>Related Directives</strong><br><br>





<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>

<A HREF="mod/mod_access.html#allow">Allow</A><br>

<a href="mod/mod_log_config.html#customlog-conditional">CustomLog

<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>

(conditional)</a><br>

<A HREF="mod/mod_access.html#deny">Deny</A><br>

<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>

<a href="mod/mod_log_config.html#logformat">LogFormat</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#RewriteCond">RewriteCond</A><br>

<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>

<A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>





</td></tr></table>

</td></tr></table>





<h3>CGI Scripts</h3>



<p>One of the primary uses of environment variables is to communicate

<p>One of the primary uses of environment variables is to communicate

information to CGI scripts.  In addition to all environment variables

information to CGI scripts.  As discussed above, the environment

set within Apache, CGI scripts are provided with a set of

passed to CGI scripts includes standard meta-information about the request

meta-information about the request as provided for in the <a

in addition to any variables set within the Apache configuration.

href="misc/FAQ.html#cgi-spec">CGI specification</a>.  If you are using

For more details, see the <a href="howto/cgi.html">CGI tutorial</a>.

<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>.

</p>

</p>





<h3>SSI Pages</h3>



<p>Server-parsed (SSI) documents processed by mod_include's

<p>Server-parsed (SSI) documents processed by mod_include's

<code>server-parsed</code> handler can print environment variables

<code>server-parsed</code> handler can print environment variables

using the <code>echo</code> element, and can use 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>

</p>





<h3>Access Control</h3>



<p>Access to the server can be controlled based on the value of

<p>Access to the server can be controlled based on the value of

environment variables using the <code>allow from env=</code> and

environment variables using the <code>allow from env=</code> and

<code>deny from env=</code></a> directives.  In combination with

<code>deny from env=</code></a> directives.  In combination with
@@ -124,6 +164,8 @@ can use these directives to deny access to a particular browser 
(User-Agent).

(User-Agent).

</p>

</p>





<h3>Conditional Logging</h3>



<p>Environment variables can be logged in the access log using the

<p>Environment variables can be logged in the access log using the

<code>LogFormat</code> option <code>%e</code>.  In addition, 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

decision on whether or not to log requests can be made based on the
@@ -135,6 +177,8 @@ for filenames ending in <code>gif</code>, or you can choose to only 
log requests from clients which are outside your subnet.

log requests from clients which are outside your subnet.

</p>

</p>





<h3>URL Rewriting</h3>



<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the

<p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the

<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make

<code>RewriteCond</code> allows mod_rewrite's rewrite engine to make

decisions conditional on environment variables.  Note that the

decisions conditional on environment variables.  Note that the

docs/manual/mod/mod_env.html

+15 −14
Original line number Original line Diff line number Diff line
@@ -15,8 +15,8 @@ 
<!--#include virtual="header.html" -->

<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER">Apache module mod_env</H1>

<H1 ALIGN="CENTER">Apache module mod_env</H1>





<p>This module provides for

<p>This module provides for modifying the environment which

passing environment variables to CGI/SSI scripts.</p>

is passed to CGI scripts and SSI pages.</p>





<P><A

<P><A

HREF="module-dict.html#Status"

HREF="module-dict.html#Status"
@@ -40,12 +40,15 @@ REL="Help" 
</P>

</P>





<H2>Summary</H2>

<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

<p>This module allows for control of the environment that will be

environment variables from the shell which invoked the httpd process.

provided to CGI scripts and SSI pages.  Environment variables may be

CERN web-servers are able to do this, so this module is especially

passed from the shell which invoked the httpd process.  Alternatively,

useful to web-admins who wish to migrate from CERN to Apache without

environment variables may be set or unset within the configuration

rewriting all their scripts</p>

process.</p>



<p>For additional information, we provide a document on

<a href="../env.html">Environment Variables in Apache</a>.</p>





<H2>Directives</H2>

<H2>Directives</H2>

<UL>

<UL>
@@ -81,7 +84,8 @@ rewriting all their scripts</p> 
Apache 1.1 and later.<P>

Apache 1.1 and later.<P>





Specifies one or more environment variables to pass to CGI scripts

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>

<PRE>

    PassEnv LD_LIBRARY_PATH

    PassEnv LD_LIBRARY_PATH

</PRE>

</PRE>
@@ -112,7 +116,7 @@ from the server's own environment. Example: 
Apache 1.1 and later.<P>

Apache 1.1 and later.<P>





Sets an environment variable, which is then passed on to CGI

Sets an environment variable, which is then passed on to CGI

scripts. Example:

scripts and SSI pages. Example:

<PRE>

<PRE>

    SetEnv SPECIAL_PATH /foo/bin

    SetEnv SPECIAL_PATH /foo/bin

</PRE>

</PRE>
@@ -144,14 +148,11 @@ scripts. Example: 
Apache 1.1 and later.<P>

Apache 1.1 and later.<P>





Removes one or more environment variables from those passed on to

Removes one or more environment variables from those passed on to

CGI scripts. Example:

CGI scripts and SSI pages. Example:

<PRE>

<PRE>

    UnsetEnv LD_LIBRARY_PATH

    UnsetEnv LD_LIBRARY_PATH

</PRE>

</PRE>









<P>

<!--#include virtual="footer.html" -->

<!--#include virtual="footer.html" -->

</BODY>

</BODY>

</HTML>

</HTML>

docs/manual/mod/mod_setenvif.html

+7 −3
Original line number Original line Diff line number Diff line
@@ -43,7 +43,8 @@ REL="Help" 
  <P>

  <P>

  The <SAMP>mod_setenvif</SAMP> module allows you to set environment

  The <SAMP>mod_setenvif</SAMP> module allows you to set environment

  variables according to whether different aspects of the request match

  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.

  other parts of the server to make decisions about actions to be taken.

  </P>

  </P>

  <P>The directives are considered in the order they appear in the

  <P>The directives are considered in the order they appear in the
@@ -56,6 +57,9 @@ REL="Help" 
  </PRE></BLOCKQUOTE>

  </PRE></BLOCKQUOTE>

  </P>

  </P>





  <p>For additional information, we proved a document on

  <a href="../env.html">Environment Variables in Apache</a>.</p>



  <H2>Directives</H2>

  <H2>Directives</H2>

  <UL>

  <UL>

   <LI><A HREF="#BrowserMatch">BrowserMatch</A>

   <LI><A HREF="#BrowserMatch">BrowserMatch</A>
@@ -346,7 +350,7 @@ REL="Help" 
   SetEnvIf object_is_image xbm XBIT_PROCESSING=1

   SetEnvIf object_is_image xbm XBIT_PROCESSING=1

  </PRE>

  </PRE>

  <P>

  <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

  request was for an image file, and the fourth sets

  <SAMP>intra_site_referral</SAMP> if the referring page was somewhere

  <SAMP>intra_site_referral</SAMP> if the referring page was somewhere

  on the <SAMP>www.mydomain.com</SAMP> Web site.

  on the <SAMP>www.mydomain.com</SAMP> Web site.
@@ -407,7 +411,7 @@ REL="Help" 
   SetEnvIfNoCase Host Apache\.Org site=apache

   SetEnvIfNoCase Host Apache\.Org site=apache

  </PRE>

  </PRE>

  <P>

  <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

  &quot;<SAMP>apache</SAMP>&quot; if the HTTP request header field

  &quot;<SAMP>apache</SAMP>&quot; if the HTTP request header field

  <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>,

  <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>,

  <SAMP>apache.org</SAMP>, or any other combination.

  <SAMP>apache.org</SAMP>, or any other combination.