From: Joshua Slive Date: Wed, 11 Oct 2000 21:56:54 +0000 (+0000) Subject: Change env.html from a specific discussion of special-purpose environment X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=047125326ef6d2bb1d043914319613a1282a96fb;p=apache Change env.html from a specific discussion of special-purpose environment variables to a general discussion of environment variables in Apache. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@86548 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/env.html b/docs/manual/env.html index 962dbe90ae..ca380f44b4 100644 --- a/docs/manual/env.html +++ b/docs/manual/env.html @@ -13,7 +13,136 @@ ALINK="#FF0000" > -

Special Purpose Environment Variables

+

Environment Variables in Apache

+ +

Many operating systems provide a facility for storage and +transmission of information called environment variables. Apache uses +environment variables in many ways to control operations and to +communicate with other programs like CGI scripts. This document +explains some of the ways to use environment variables in Apache.

+ + + +
+ +

Setting Environment Variables

+ +

Related Modules

+ + + +

Related Directives

+ + + +

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.

+ +

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.

+ +

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.

+ +
+ +

Using Environment Variables

+ +

Related Modules

+ + + +

Related Directives

+ + + + +

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

+ +

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

+ +

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 +SetEnvIf, this allows for flexible control of access to +the server based on characteristics of the client. For example, you +can use these directives to deny access to a particular browser +(User-Agent). +

+ +

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 +status of environment variables using the conditional form of the +CustomLog directive. In combination with +SetEnvIf this allows for flexible control of which +requests are logged. For example, you can choose not to log requests +for filenames ending in gif, or you can choose to only +log requests from clients which are outside your subnet. +

+ +

The %{ENV:...} form of TestString in the +RewriteCond allows mod_rewrite's rewrite engine to make +decisions conditional on environment variables. + +

+ +

Special Purpose Environment Variables

Interoperability problems have led to the introduction of mechanisms to modify the way Apache behaves when talking to particular @@ -51,13 +180,78 @@ them.

nokeepalive

-This disables KeepAlive when set. Because -of problems with Netscape 2.x and KeepAlive, we recommend the following -directive be used: +This disables KeepAlive when set.

-
-    BrowserMatch Mozilla/2 nokeepalive
-
+ + +
+ +

Examples

+ +

Changing protocol behavior with misbehaving clients

+ +

We recommend that the following lines be included in httpd.conf +to deal with known client problems.

+ +
+#
+# The following directives modify normal HTTP response behavior.
+# The first directive disables keepalive for Netscape 2.x and browsers that
+# spoof it. There are known problems with these browser implementations.
+# The second directive is for Microsoft Internet Explorer 4.0b2
+# which has a broken HTTP/1.1 implementation and does not properly
+# support keepalive when it is used on 301 or 302 (redirect) responses.
+#
+BrowserMatch "Mozilla/2" nokeepalive
+BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
+
+#
+# The following directive disables HTTP/1.1 responses to browsers which
+# are in violation of the HTTP/1.0 spec by not being able to grok a
+# basic 1.1 response.
+#
+BrowserMatch "RealPlayer 4\.0" force-response-1.0
+BrowserMatch "Java/1\.0" force-response-1.0
+BrowserMatch "JDK/1\.0" force-response-1.0
+
+ +

Do not log requests for images in the access log

+ +

This example keeps requests for images from appearing +in the access log. It can be easily modified to prevent logging +of particular directories, or to prevent logging of requests +coming from particular hosts.

+ +
+    SetEnvIf Request_URI \.gif image-request
+    SetEnvIf Request_URI \.jpg image-request
+    SetEnvIf Request_URI \.png image-request
+    CustomLog logs/access_log env=!image-request
+
+ +

Prevent "Image Theft"

+ +

This example shows how to keep people not on your server from using +images on your server as inline-images on their pages. This is not +a recommended configuration, but it can work in limited +circumstances. We assume that all your images are in a directory +called /web/images.

+ +
+    SetEnvIf Referer "^http://www.example.com/" local_referal
+    # Allow browsers that do not send Referer info
+    SetEnvIf Referer "^$" local_referal
+    <Directory /web/images>
+       Order Deny,Allow
+       Deny from all
+       Allow from env=local_referal
+    </Directory>
+
+ +

For more information about this technique, see the ApacheToday +tutorial "Keeping +Your Images from Adorning Other Sites".

diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en index 962dbe90ae..ca380f44b4 100644 --- a/docs/manual/env.html.en +++ b/docs/manual/env.html.en @@ -13,7 +13,136 @@ ALINK="#FF0000" > -

Special Purpose Environment Variables

+

Environment Variables in Apache

+ +

Many operating systems provide a facility for storage and +transmission of information called environment variables. Apache uses +environment variables in many ways to control operations and to +communicate with other programs like CGI scripts. This document +explains some of the ways to use environment variables in Apache.

+ + + +
+ +

Setting Environment Variables

+ +

Related Modules

+ + + +

Related Directives

+ + + +

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.

+ +

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.

+ +

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.

+ +
+ +

Using Environment Variables

+ +

Related Modules

+ + + +

Related Directives

+ + + + +

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

+ +

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

+ +

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 +SetEnvIf, this allows for flexible control of access to +the server based on characteristics of the client. For example, you +can use these directives to deny access to a particular browser +(User-Agent). +

+ +

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 +status of environment variables using the conditional form of the +CustomLog directive. In combination with +SetEnvIf this allows for flexible control of which +requests are logged. For example, you can choose not to log requests +for filenames ending in gif, or you can choose to only +log requests from clients which are outside your subnet. +

+ +

The %{ENV:...} form of TestString in the +RewriteCond allows mod_rewrite's rewrite engine to make +decisions conditional on environment variables. + +

+ +

Special Purpose Environment Variables

Interoperability problems have led to the introduction of mechanisms to modify the way Apache behaves when talking to particular @@ -51,13 +180,78 @@ them.

nokeepalive

-This disables KeepAlive when set. Because -of problems with Netscape 2.x and KeepAlive, we recommend the following -directive be used: +This disables KeepAlive when set.

-
-    BrowserMatch Mozilla/2 nokeepalive
-
+ + +
+ +

Examples

+ +

Changing protocol behavior with misbehaving clients

+ +

We recommend that the following lines be included in httpd.conf +to deal with known client problems.

+ +
+#
+# The following directives modify normal HTTP response behavior.
+# The first directive disables keepalive for Netscape 2.x and browsers that
+# spoof it. There are known problems with these browser implementations.
+# The second directive is for Microsoft Internet Explorer 4.0b2
+# which has a broken HTTP/1.1 implementation and does not properly
+# support keepalive when it is used on 301 or 302 (redirect) responses.
+#
+BrowserMatch "Mozilla/2" nokeepalive
+BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0
+
+#
+# The following directive disables HTTP/1.1 responses to browsers which
+# are in violation of the HTTP/1.0 spec by not being able to grok a
+# basic 1.1 response.
+#
+BrowserMatch "RealPlayer 4\.0" force-response-1.0
+BrowserMatch "Java/1\.0" force-response-1.0
+BrowserMatch "JDK/1\.0" force-response-1.0
+
+ +

Do not log requests for images in the access log

+ +

This example keeps requests for images from appearing +in the access log. It can be easily modified to prevent logging +of particular directories, or to prevent logging of requests +coming from particular hosts.

+ +
+    SetEnvIf Request_URI \.gif image-request
+    SetEnvIf Request_URI \.jpg image-request
+    SetEnvIf Request_URI \.png image-request
+    CustomLog logs/access_log env=!image-request
+
+ +

Prevent "Image Theft"

+ +

This example shows how to keep people not on your server from using +images on your server as inline-images on their pages. This is not +a recommended configuration, but it can work in limited +circumstances. We assume that all your images are in a directory +called /web/images.

+ +
+    SetEnvIf Referer "^http://www.example.com/" local_referal
+    # Allow browsers that do not send Referer info
+    SetEnvIf Referer "^$" local_referal
+    <Directory /web/images>
+       Order Deny,Allow
+       Deny from all
+       Allow from env=local_referal
+    </Directory>
+
+ +

For more information about this technique, see the ApacheToday +tutorial "Keeping +Your Images from Adorning Other Sites".

diff --git a/docs/manual/index.html b/docs/manual/index.html index 3c209ede45..1be6b2074c 100644 --- a/docs/manual/index.html +++ b/docs/manual/index.html @@ -39,7 +39,7 @@
  • Dynamic Shared Object (DSO) support
  • Handlers
  • Content negotiation -
  • Special purpose environment variables +
  • Environment Variables
  • The Apache API
  • Using SetUserID Execution for CGI diff --git a/docs/manual/index.html.en b/docs/manual/index.html.en index 3c209ede45..1be6b2074c 100644 --- a/docs/manual/index.html.en +++ b/docs/manual/index.html.en @@ -39,7 +39,7 @@
  • Dynamic Shared Object (DSO) support
  • Handlers
  • Content negotiation -
  • Special purpose environment variables +
  • Environment Variables
  • The Apache API
  • Using SetUserID Execution for CGI