mod_setenvifplus

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 application via HTTP header data. mod_setenvifplus is derived from the standard Apache modules mod_setenvif and mod_headers .

 


mod_setenvifplus is an open source software licensed under the Apache License. You can download the latest release at SourceForge.net.

 

Configuration

mod_setenvifplus directives are configured on a per server or location basis. Multiple directive settings of the same type are processed in the order they appear in the configuration file.

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.
      Remote_Net - the network (mask /24 for IPv4 and /64 for IPv6) of the client making the request.
      Server_Addr - the IP address of the server on which the request was received.
      Server_Port - the port of the server on which the request was received.
      Request_Method - the name of the method being used (GET, POST, etc.).
      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 portion 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 remaining arguments are evaluated.
    The third argument (env-variable) gives the name of a variable to set and an optional value to which it should be set. This takes one of the following forms:
    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 (except the name of the variable is the same as the target variable to set).
    Functions can be used to manipulate the parts of the value. Each function has a name 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.
    $enc(<string>) - implements encryption.
    $dec(<string>) - implements decryption ($end() and $dec() use the key defined by the SP_KEY environment variable).
    $RND(<num>) - creates the specified number (num) of random data (chars).

    These directives are considered in the following order:
    1. Directives within the server configuration (outside Location or Directory) are processed very early (in the very first request processing phase called post read request).
    2. Directives within a Location or Directory directive are either processed early at the header parser or "late" at the fixup hook, depending on their optional fourth argument.
    3. Directives are processed in the order they appear in the configuration files.
  • 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. ResponseSetEnvIfPlus[NoCase] allows also to match against the server's HTTP response status code using the Response_Status attribute string. Available at Location / Directory level only.
  • 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 level and is executed after the SetEnvIfPlus directive.
    The first argument specifies the action to take:
    set - is used to set (add or replace) an HTTP request header.
    unset - is used to unset (delete) an HTTP request header.
    add - is used to add an HTTP request header.
    The second argument (header) specifies the HTTP header name.
    The "value" argument defines the value of the header. This argument 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 insensitive) 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.
  • ChangeResponseHeaderPlus <header> <regex> <value>
    Same as ChangeRequestHeaderPlus but processing the HTTP response header.
  • ChangeQueryIfPlus <env-variable>
    Replaces the request query by the value of the specifed environment variable.
  • SetQueryIfPlus <attribute> <regex> <paramater name>[=<value>]
    Works similar to SetEnvIfPlus but adds the defined query paramater to the request instead of adding an environment variable.
    Note: If you like to log the modifed request line within Apache's access log, you should use the argument %m %U%q %H instead of %r within your log format directive settings.
  • SetEnvIfCmpPlus <env-variable1> eq|ne|gt|lt <env-variable2> [!]<env-variable>[=<value>] [late]
    Sets the defined environment variable if the specifed env-variables[1|2] are numerical or alphabetically (case insensitive) equal (eq), not equal (ne) greater (gt), or less (lt). The value string may also contain other environment variable names surrounded by "${" and "}" which are resolved by the values of those variables.
    The fifth attribute "late" applies the directive late in the request processing at the fixup hook.
  • SetHashHeaderPlus <header name> <env-variable>
    Creates a hash of the value stored in the defined variable and stores it within the defined requst header.
    Available at server level only (outside location).
  • RequestHeaderRemovePattern <header> <pattern>
    Removes the specified pattern from the HTTP request header.
    Available at Location level only.
  • 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.
    Available at Location level only.
  • SetStatusPlus <code> <env-variable>
    Changes the status code of the HTTP response if the specified environment variable is set.
  • CookieEncPlus <name>
    Encrypts a cookie with the defined name using the key set within the SP_COOKIE_KEY environment variable.
    You may use several request attributes to build the SP_COOKIE_KEY string, e.g. the user id Request_User and a session secret using mod_clientid .
    Available at server level only (outside location).
  • AddOutputFilterPlus <filter name> [!]<env-variable>
    Activates a particular output filter for a request if the specified environment variable is set (or not set if the name of the variable is prefixed by '!').
  • SetVarPrefixPlus '$'|'%'
    Defines the prefix of the variable place holder which is either ${...} or %{...} for compatibilty with Apache 2.4 (avoids AH00111 warning messages). Default is '$' as described in the directive usage above.

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 an HTTP request header
RequestHeaderPlus set x-item ${VAR_ITEM}

Build

mod_setenvifplus is an Apache module. You can build the shared library using apxs .
Example:
cd apache2
apxs -i -c mod_setenvifplus.c -lcrypto


© 2010-2020, Pascal Buchbinder