From: Joshua Slive Date: Tue, 9 Jan 2001 03:24:50 +0000 (+0000) Subject: This is the second in a series of clean-ups of the X-Git-Tag: APACHE_2_0_BETA_CANDIDATE_1~251 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a235af4c8fb42627d07996105981f4f345bb1956;p=apache 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 --- diff --git a/docs/manual/env.html b/docs/manual/env.html index b32847fbbf..f436e32819 100644 --- a/docs/manual/env.html +++ b/docs/manual/env.html @@ -54,23 +54,60 @@ explains some of the ways to use environment variables in Apache.

UnsetEnv
+

Basic Environment Manipulation

+

The most basic way to set an environment variable in Apache is using the unconditional SetEnv directive. Variables -may also be passed from the environment when Apache is started -using the PassEnv directive.

+may also be passed from the environment of the shell which started +the server using the PassEnv directive.

+ +

Conditional Per-Request Settings

+ +

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 +RewriteRule which uses the [E=...] option to +set environment variables.

-

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 RewriteRule which uses the -[E=...] option to set environment variables.

+

Unique Identifiers

Finally, mod_unique_id sets the environment variable UNIQUE_ID for each request to a value which is guaranteed to be unique across "all" requests under very specific conditions.

+

Standard CGI Variables

+ +

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

+ +

Some Caveats

+ + + +

Using Environment Variables

@@ -87,34 +124,37 @@ to be unique across "all" requests under very specific conditions.

Related Directives

-Allow from env=
-CustomLog -(conditional)
-Deny from env=
+Allow
+CustomLog
+Deny
LogFormat
RewriteCond
RewriteRule
+

CGI Scripts

+

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 CGI specification. If you are using -Suexec to execute CGI scripts under -different userids, note that the environment will be cleaned down to a -set of safe environment variables before the CGI script is -executed. The set of safe environment variables is defined at -compile time in suexec.c. +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 CGI tutorial.

+

SSI Pages

+

Server-parsed (SSI) documents processed by mod_include's server-parsed handler can print environment variables using the echo 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 SSI tutorial.

+

Access Control

+

Access to the server can be controlled based on the value of environment variables using the allow from env= and deny from env= directives. In combination with @@ -124,6 +164,8 @@ can use these directives to deny access to a particular browser (User-Agent).

+

Conditional Logging

+

Environment variables can be logged in the access log using the LogFormat option %e. In addition, the decision on whether or not to log requests can be made based on the @@ -135,6 +177,8 @@ for filenames ending in gif, or you can choose to only log requests from clients which are outside your subnet.

+

URL Rewriting

+

The %{ENV:...} form of TestString in the RewriteCond allows mod_rewrite's rewrite engine to make decisions conditional on environment variables. Note that the diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en index b32847fbbf..f436e32819 100644 --- a/docs/manual/env.html.en +++ b/docs/manual/env.html.en @@ -54,23 +54,60 @@ explains some of the ways to use environment variables in Apache.

UnsetEnv
+

Basic Environment Manipulation

+

The most basic way to set an environment variable in Apache is using the unconditional SetEnv directive. Variables -may also be passed from the environment when Apache is started -using the PassEnv directive.

+may also be passed from the environment of the shell which started +the server using the PassEnv directive.

+ +

Conditional Per-Request Settings

+ +

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 +RewriteRule which uses the [E=...] option to +set environment variables.

-

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 RewriteRule which uses the -[E=...] option to set environment variables.

+

Unique Identifiers

Finally, mod_unique_id sets the environment variable UNIQUE_ID for each request to a value which is guaranteed to be unique across "all" requests under very specific conditions.

+

Standard CGI Variables

+ +

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

+ +

Some Caveats

+ + + +

Using Environment Variables

@@ -87,34 +124,37 @@ to be unique across "all" requests under very specific conditions.

Related Directives

-Allow from env=
-CustomLog -(conditional)
-Deny from env=
+Allow
+CustomLog
+Deny
LogFormat
RewriteCond
RewriteRule
+

CGI Scripts

+

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 CGI specification. If you are using -Suexec to execute CGI scripts under -different userids, note that the environment will be cleaned down to a -set of safe environment variables before the CGI script is -executed. The set of safe environment variables is defined at -compile time in suexec.c. +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 CGI tutorial.

+

SSI Pages

+

Server-parsed (SSI) documents processed by mod_include's server-parsed handler can print environment variables using the echo 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 SSI tutorial.

+

Access Control

+

Access to the server can be controlled based on the value of environment variables using the allow from env= and deny from env= directives. In combination with @@ -124,6 +164,8 @@ can use these directives to deny access to a particular browser (User-Agent).

+

Conditional Logging

+

Environment variables can be logged in the access log using the LogFormat option %e. In addition, the decision on whether or not to log requests can be made based on the @@ -135,6 +177,8 @@ for filenames ending in gif, or you can choose to only log requests from clients which are outside your subnet.

+

URL Rewriting

+

The %{ENV:...} form of TestString in the RewriteCond allows mod_rewrite's rewrite engine to make decisions conditional on environment variables. Note that the diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html index bda93ec2db..3d6d610fe9 100644 --- a/docs/manual/mod/mod_env.html +++ b/docs/manual/mod/mod_env.html @@ -15,8 +15,8 @@

Apache module mod_env

-

This module provides for -passing environment variables to CGI/SSI scripts.

+

This module provides for modifying the environment which +is passed to CGI scripts and SSI pages.

Summary

- -

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

+ +

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.

+ +

For additional information, we provide a document on +Environment Variables in Apache.

Directives