mod_setenvifplus

The mod_setenvifplus module allows you to set environment variables according to whether different aspects of the request match regular expressions you specify. These environment variables can be used by other parts of the server to make decisions about actions to be taken, e.g. by using mod_qos or to propagate supplemental information to the appliaction via HTTP header data. mod_setenvifplus is derived from the standard Apache modules mod_setenvif and mod_headers.

mod_setenviflus is available at SourceForge.net under the Apache License Version 2.0.

Configuration

SetEnvIfPlus[NoCase]
ResponseSetEnvIfPlus[NoCase]
RequestHeaderPlus
ResponseHeaderPlus
ChangeRequestHeaderPlus
ChangeResponseHeaderPlus
SetUserPlus

Configuration

Directives

SetEnvIfPlus[NoCase] <attribute> <regex> [!]<env-variable>[=<value>] [late]
The SetEnvIfPlus[NoCase] directive defines Apache environment variables based on attributes of the request (the SetEnvIfPlusNoCase differs from the SetEnvIfPlus only in that the regular expression matching is performed in a case-insensitive manner).
The first argument (attribute) can be one of three things:
- An HTTP request header field for example: Host or User-Agent. A regular expression may be used to specify a set of request headers.
- One of the following aspects of the request:
  Remote_Host - the hostname (if available) of the client making the request.
  Remote_Addr - the IP address of the client making the request.
  Server_Addr - the IP address of the server on which the request was received.
  Request_Method - the name of the method being used (GET, POST, et cetera).
  Request_Protocol - the name and version of the protocol with which the request was made (e.g., "HTTP/0.9", "HTTP/1.1", etc.).
  Request_URI - the resource requested on the HTTP request line -- generally the path portion of the URL without the query string.
  Request_Query - the query protion of the request URL.
  Request_User - name of the user authenticated by the Apache server. Available in "late" request processing only.
- The name of an environment variable in the list of those associated with the request. This allows SetEnvIfPlus* directives to test against the result of prior matches. Only those environment variables defined by earlier SetEnvIfPlus* directives are available for testing in this manner. 'Earlier' means that they were defined at a broader scope (such as server-wide) or previously in the current directive's scope. Environment variables will be considered only if there was no match among request characteristics and a regular expression was not used for the attribute.
The second argument (regex) is a regular expression. If this expression matches against the attribute, then the remainder of the arguments are evaluated.
The third argument (env-variable) gives the name of a variable to set and an opional value to which it should be set. This takes one of the following form:
1. env-variable
2. !env-variable
3. env-variable=value
In the first form, the value of the env-variable will be set to "1". The second will remove the given env-variable if already defined, and the third will set the env-variable to the literal value given by value. mod_setenvifplus will recognize occurrences of $1..$9 within the value and replace them by parenthesized subexpressions of the regular expression.
The value string may also contain other environment variable names surrounded by "${" and "}" which are resolved by the values of those variables. The env-variable will NOT be set if any of those variable names within the value string can't be resolved because the variable is not available.
Functions can be used to manipulate the parts of the value. Each function has a nane and surrounds the string to process by brackes (nested functions are not allowed within a single attribute). Functions are processed after resolving sub-expressions ($1..$9) and variables (${name}). The following functions are available:
$e64(<string>) - implements base64 encoding.
$d64(<string>) - implements base64 decoding.
$eURL(<string>) - implements URL encoding.
$dURL(<string>) - implements URL decoding.
$RND(<num>) - creates the specified number (num) of random data (chars).
These directives are considered in the following order:
1. Directives are processed in the order they appear in the configuration files.
2. Directives within the server configuration (outside Location or Directory) are processed very early (in the very first request processing phase called post read request).
3. Directives within a Location or Directory directive are either processed early at the header parser or "late" at the fixup hook, depending of the their optionnal fourth argument.

ResponseSetEnvIfPlus[NoCase] <attribute> <regex> [!]<env-variable>[=<value>]
Same as the SetEnvIfPlus[NoCase] directive but applied at HTTP response processing and against the HTTP response header. Available at Location/Directory level only. ResponseSetEnvIfPlus[NoCase] allows also to match against the servers HTTP response status code using the Response_Status attribute string.

RequestHeaderPlus set|unset|add <header> [<value>] [env=[!]<env-variable>] [late]
This directive is used to manipulate HTTP request headers. This directive may be used at server or at Location/Directory level and is executed after the SetEnvIfPlus directive.
The first argment specifies the action to take:
set - is used to set (add or replace) a HTTP request header.
unset - is used to unset (delete) a HTTP request header.
add - is used to add a HTTP request header.
The second argument (header) specifies the HTTP header name.
The "value" argument defines the value of the header. This argment may only be used in conjunction with a "set" or "add" action. The value string may also contain other environment variable names surrounded by "${" and "}" which are resolved by the values of those variables. The header will NOT be set if any of those variable names within the value string can't be resolved because the variable is not available.
The env=... option is used to specify a condition to determine if the action should be performed. The action will only take effect if the specified env-variable exists (or if the environment variable does not exist and env=!... is specified).
The fifth attribute "late" applies the directive late in the request processing at the fixup hook.

ResponseHeaderPlus set|unset|add <header> [<value>] [env=[!]<env-variable>]
Same as the RequestHeaderPlus directive but applied to HTTP response header.

ChangeRequestHeaderPlus <header> <regex> <value>
Changes the value of the specified request header if the regular expression (case insensitiv) matches its value. Occurrences of $1..$9 within the value are replaced by parenthesized subexpressions of the regular expression. The value string may also contain other environment variable names surrounded by "${" and "}" which are resolved by the values of those variables.

ChangeResponeHeaderPlus <header> <regex> <value>
Same as ChangeRequestHeaderPlus but processing the HTTP response header.

SetUserPlus <header> <regex> <value>
Used to set the an authenticated user name using the 'value' if the specified expression matches the header. Occurrences of $1..$9 within the value are replaced by parenthesized subexpressions of the regular expression.

Sample configuration:

# stores the numeric value of the query with the name "item" in the variable VAR_ITEM
SetEnvIfPlus Request_Query item=([0-9]+) VAR_ITEM=$1

# implement base64 encoding to the value of the variable VAR_ITEM
SetEnvIfPlus VAR_ITEM (.*) VAR_ITEM=$e64(${VAR_ITEM})

# set the encoded variable as a HTTP request header
RequestHeaderPlus set x-item ${VAR_ITEM}