env.xml revision b597281295360dba8ac57b7606c5f5c1ef2b69b0
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek<!-- $LastChangedRevision$ -->
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek Copyright 2002-2005 The Apache Software Foundation or its licensors, as
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek Licensed under the Apache License, Version 2.0 (the "License");
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek you may not use this file except in compliance with the License.
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek You may obtain a copy of the License at
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek http://www.apache.org/licenses/LICENSE-2.0
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek Unless required by applicable law or agreed to in writing, software
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek distributed under the License is distributed on an "AS IS" BASIS,
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek See the License for the specific language governing permissions and
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek limitations under the License.
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek<manualpage metafile="env.xml.meta">
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Environment Variables in Apache</title>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <p>The Apache HTTP Server provides a mechanism for storing
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek information in named variables that are called <em>environment
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek variables</em>. This information can be used to control various
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek operations such as logging or access control. The variables are
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek also used as a mechanism to communicate with external programs
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek such as CGI scripts. This document discusses different ways to
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek manipulate and use these variables.</p>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <p>Although these variables are referred to as <em>environment
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek variables</em>, they are not the same as the environment
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek variables controlled by the underlying operating system.
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek Instead, these variables are stored and manipulated in an
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek internal Apache structure. They only become actual operating
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek system environment variables when they are provided to CGI
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek scripts and Server Side Include scripts. If you wish to
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek manipulate the operating system environment under which the
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek server itself runs, you must use the standard environment
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek manipulation mechanisms provided by your operating system
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Setting Environment Variables</title>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_setenvif">BrowserMatch</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_setenvif">BrowserMatchNoCase</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_rewrite">RewriteRule</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_env">SetEnv</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_setenvif">SetEnvIf</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_setenvif">SetEnvIfNoCase</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_env">UnsetEnv</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek </directivelist>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <section id="basic-manipulation">
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Basic Environment Manipulation</title>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <p>The most basic way to set an environment variable in Apache
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek is using the unconditional <directive module="mod_env"
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek >SetEnv</directive> directive. Variables may also be passed from
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek the environment of the shell which started the server using the
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_env">PassEnv</directive> directive.</p>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Conditional Per-Request Settings</title>
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <p>For additional flexibility, the directives provided by
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek mod_setenvif allow environment variables to be set on a
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek per-request basis, conditional on characteristics of particular
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek requests. For example, a variable could be set only when a
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek specific browser (User-Agent) is making a request, or only when
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek a specific Referer [sic] header is found. Even more flexibility
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek is available through the mod_rewrite's <directive
b8bde11658366290521e3d03316378b482600323Jan Engelhardt module="mod_rewrite">RewriteRule</directive> which uses the
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <code>[E=...]</code> option to set environment variables.</p>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <section id="unique-identifiers">
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Unique Identifiers</title>
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <p>Finally, mod_unique_id sets the environment variable
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <code>UNIQUE_ID</code> for each request to a value which is
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek guaranteed to be unique across "all" requests under very
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek specific conditions.</p>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Standard CGI Variables</title>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <p>In addition to all environment variables set within the
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek Apache configuration and passed from the shell, CGI scripts and
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek SSI pages are provided with a set of environment variables
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek containing meta-information about the request as required by
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek the <a href="http://cgi-spec.golux.com/">CGI
dca348bcbb462305864526c587495a14a76bfcdeJan Engelhardt <li>It is not possible to override or change the standard CGI
dca348bcbb462305864526c587495a14a76bfcdeJan Engelhardt variables using the environment manipulation directives.</li>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <li>When <program>suexec</program> is used to launch
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek CGI scripts, the environment will be cleaned down to a set of
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <em>safe</em> variables before CGI scripts are launched. The
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek list of <em>safe</em> variables is defined at compile-time in
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <li>For portability reasons, the names of environment
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek variables may contain only letters, numbers, and the
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek underscore character. In addition, the first character may
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek not be a number. Characters which do not match this
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek restriction will be replaced by an underscore when passed to
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek CGI scripts and SSI pages.</li>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>Using Environment Variables</title>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_authz_host">Allow</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_log_config">CustomLog</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_authz_host">Deny</directive>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <directive module="mod_ext_filter">ExtFilterDefine</directive>
# The first directive disables keepalive for Netscape 2.x and browsers that
SetEnvIf Referer "^http://www.example.com/" local_referal