Ruby and Apache per-request environment variables

Relevant selection for this article:

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.

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 Ruby apps can access per-request environment variables

The Rack environment object

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

Pretty much all Ruby web frameworks are built in top of Rack. If you are using a web framework, then please refer to your framework's documentation to find out how to access the Rack environment object. Rails applications can access the Rack environment object from a controller through request.env.

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:

# From a Rails controller:
request.env['SSL_SESSION_ID']   # => ...session ID value...

# From a non-Rails app:
env = framework_specific_code_to_obtain_the_rack_object
env['SSL_SESSION_ID']   # => ...session ID value...

The ENV 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 the ENV top-level constant, which is a mechanism in Ruby for accessing OS-level environment variables:

ENV['APP_NAME']   # => "mydemoapp"

There are three important caveats to be aware of:

1. ENV should not be confused with the Rack environment object, which is often called env. The Rack environment object is something totally different, and is for accessing per-request information. ENV is for accessing OS-level environment variables.
2. ENV 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 ENV['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.