Draft of "Environment Variables in Apache"

3 Oct 2000 17:30:32 -0000 

This is a draft of a propsed new doc file.  Actually, it would be a
replacement for the existing "Special Purpose Environment
Variables" document.

The purpose is to provide a unifying document, along the same lines as
"Apache's Handler Use" to show how environment variables are set and used
in Apache.  I think this is useful because environment variables have
grown to be very powerful in Apache, and they touch on so many modules
that it is hard to figure out how they work from the module docs.

I don't think I really like the current format of what I have written.  I
would be interested in feedback on the overall idea, as well as specifics
of how it should be presented.

Thanks.

-- 
Joshua Slive
[EMAIL PROTECTED]
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871
Title: 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

Apache provides four modules which can be used to modify the environment:

  • mod_env - Provides directives to unconditionally set and unset environment variables: SetEnv and UnSetEnv, and a directive to pass environment variables from the shell when starting Apache: PassEnv.
  • mod_setenvif - Provides directives to set environment variables conditional on other environment variables, or on characteristics of a particular client request: SetEnvIf and SetEnvIfNoCase. The BrowserMatch directive is a special case of the SetEnvIf directive used to set environment variables conditional on the client User-Agent.
  • mod_unique_id - When active, this module sets an environment variable UNIQUE_ID for each request to a value which is guaranteed to be unique across "all" requests under very specific conditions.
  • mod_rewrite - The env flag of the RewriteRule directive can be used to set environment variables. This allows all the power and flexibility of mod_rewrite's rewrite engine to be applied to setting environment variables.

Using Environment Variables

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. However, if you are using Suexec to execute CGI scripts under different userids, then the environment will be cleaned down to a set of safe environment variables before the CGI script is executed.

Server-parsed (SSI) documents processed by mod_include 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 %e LogFormat option of mod_log_config. 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.

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 clients. To make these mechanisms as flexible as possible, they are invoked by defining environment variables, typically with BrowserMatch, though SetEnv and PassEnv could also be used, for example.

downgrade-1.0

This forces the request to be treated as a HTTP/1.0 request even if it was in a later dialect.

force-no-vary

This causes any Vary fields to be removed from the response header before it is sent back to the client. Some clients don't interpret this field correctly (see the known client problems page); setting this variable can work around this problem. Setting this variable also implies force-response-1.0.

force-response-1.0

This forces an HTTP/1.0 response when set. It was originally implemented as a result of a problem with AOL's proxies. Some clients may not behave correctly when given an HTTP/1.1 response, and this can be used to interoperate with them.

nokeepalive

This disables KeepAlive when set.

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
    </Directory>

Reply via email to