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 The patch is included below, or the whole files are available at http://garibaldi.commerce.ubc.ca:8080/ap13/htdocs/manual/env.html and similarly for mod_env and mod_setenvif. Feedback welcome! Index: env.html =================================================================== RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/env.html,v retrieving revision 1.15 diff -u -d -b -r1.15 env.html --- env.html 2000/12/03 03:37:43 1.15 +++ env.html 2001/01/07 20:55:35 @@ -54,23 +54,62 @@ <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> -<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 [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> +<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> + +<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> + +<p> + <hr> <h2><a name="using">Using Environment Variables</a></h2> @@ -97,24 +136,28 @@ </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> directives. In combination with @@ -124,6 +167,8 @@ (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 @@ -134,6 +179,8 @@ for filenames ending in <code>gif</code>, or you can choose to only 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 Index: mod/mod_env.html =================================================================== RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_env.html,v retrieving revision 1.16 diff -u -d -b -r1.16 mod_env.html --- mod/mod_env.html 2000/12/08 20:53:26 1.16 +++ mod/mod_env.html 2001/01/07 20:55:35 @@ -15,8 +15,8 @@ <!--#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" @@ -40,13 +40,16 @@ </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> <LI><A HREF="#passenv">PassEnv</A> @@ -81,7 +84,8 @@ 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> @@ -149,9 +153,6 @@ UnsetEnv LD_LIBRARY_PATH </PRE> - - -<P> <!--#include virtual="footer.html" --> </BODY> </HTML> Index: mod/mod_setenvif.html =================================================================== RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/mod/mod_setenvif.html,v retrieving revision 1.13 diff -u -d -b -r1.13 mod_setenvif.html --- mod/mod_setenvif.html 2000/12/08 20:53:35 1.13 +++ mod/mod_setenvif.html 2001/01/07 20:55:35 @@ -43,7 +43,8 @@ <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 @@ -57,6 +58,9 @@ BrowserMatch MSIE !netscape </PRE></BLOCKQUOTE> + <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> @@ -349,7 +353,7 @@ 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. @@ -413,7 +417,7 @@ 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.
