This documentation website doesn’t support Internet Explorer. Please visit our old documentation to find what you’re looking for.
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.
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
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
Eflag (provided by
- Values set by the SSLOptions StdEnvVars configuration option (provided by
- 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
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:
ENVshould 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.
ENVis for accessing OS-level environment variables.
ENVdoes 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
SSL_SESSION_IDchanges on a per-client basis.
- 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.