httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <jos...@slive.ca>
Subject update of env variable docs
Date Sun, 07 Jan 2001 21:02:03 GMT
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
   &quot;<SAMP>apache</SAMP>&quot; 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.


Mime
View raw message