Edit page

Python and Apache per-request environment variables

If you are using Passenger in its Apache integration mode, then you may be aware of the fact that Apache supports per-request environment variables. This page explains how Passenger passes per-request environment variables to the application.

This page is not talking about system environment variables!

There is a difference between operating system-level environment variables (which are controlled by the OS) and per-request environment variables (which are controlled by Apache). This page is only talking about the latter. If you are looking for information about OS-level environment variables, please refer to About environment variables. Refer to the Apache documentation to understand the differences.

Table of contents

  1. Loading...

Examples of per-request environment variables

Per-request environment variables are set by various Apache features and Apache modules. Here are some examples:

  • Values set by Shibboleth, the identity federation Apache module.
  • Values set by the RewriteRule E flag (provided by mod_rewrite).
  • Values set by the SSLOptions StdEnvVars configuration option (provided by mod_ssl).
  • Values set by the Apache SetEnv directive (provided by mod_env). These values are static (hardcoded into the configuration file) and do not change on a per-request basis.

Please refer to Apache's documentation to learn more.

How Python apps can access per-request environment variables

The WSGI environment dict

Per-request environment variables can be accessed through the WSGI environment dict. This dict contains all information about the request, including per-request environment variables.

Pretty much all Python web frameworks are built in top of WSGI. If you are using a web framework, then please refer to your framework's documentation to find out how to access the WSGI environment dict.

Suppose that your site is using SSL, and that you that SSLOptions StdEnvVars enabled. You can access the SSL_SESSION_ID environment variable as follows:

env = framework_specific_code_to_obtain_the_wsgi_dict()
env['SSL_SESSION_ID']   # => ...session ID value...

The os.environ object

When Passenger handles a request and decides to spawn a new application process, Passenger will store the values of any per-request environment variables into OS-level environment variables. This is only done once per application process, and only when the application process is spawned.

This is primarily useful for ensuring that the SetEnv directive works as expected. For example, suppose that you have this in your Apache configuration file:

SetEnv APP_NAME mydemoapp

You can then access APP_NAME using os.environ, which is a mechanism in Python for accessing OS-level environment variables:

os.environ['APP_NAME']   # => "mydemoapp"

There are three important caveats to be aware of:

  1. os.environ should not be confused with the WSGI environment object, which is often called env. The WSGI environment object is something totally different, and is for accessing per-request information. os.environ is for accessing OS-level environment variables.
  2. os.environ does not change, so it must not be used for accessing per-request environment variables whose values may change on a per-request basis. For example, do not call os.environ['SSL_SESSION_ID'] because SSL_SESSION_ID changes on a per-client basis.
  3. If Passenger spawns an application process, but not as part of handling a request, then that application process will not have per-request environment variables stored inside OS-level environment variables.