env.html and a template for future docs

[Joshua Slive]

So, here is a second draft of my "Apache Environment Variables"
doc.  It is also an example of the format I would image future
task-specific docs could take.  The idea is quite simple:

1. Take a task/topic.

2. List all related modules.

3. List all related directives.

4. Provide a brief discussion of how the directives work,
and how they are related to each other.  Extensive detail is not
necessary, because it should be covered in the directive definitions.

5. Provide a few examples.

I imagine the same general format could work for a whole new set
of documentation addressing things like authentication, 
logging, process creation, etc.  This is not meant to replace the
tutorials and books that are being written about Apache.  Rather,
it is just a way to give people a fighting chance to understand the server
as a whole from the docs.

As always, comments and suggestions are welcome.

-- 
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 Using Environment Variables Special Purpose Environment Variables Examples Setting Environment Variables Related Modules mod_env mod_rewrite mod_setenvif mod_unique_id Related Directives BrowserMatch BrowserMatchNoCase PassEnv RewriteRule SetEnv SetEnvIf SetEnvIfNoCase UnsetEnv 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, the handler provided by 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 mod_access mod_cgi mod_include mod_log_config mod_rewrite Related Directives Allow from env= CustomLog (conditional) Deny from env= LogFormat RewriteCond RewriteRule 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'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 %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>