Conditional parameters and pragmas

There are filters/servlets which support conditional parameters and pragmas. While conditions allow dynamic configurations based on different sources, pragmas can modify the behavior of the conditions. The exact result of a condition depends on the implementation of the corresponding filter/servlet. This means that a filter can have multiple conditions, and most often the conditional parameter is returned on the first matching condition, but it is also possible that multiple conditions form the parameter value list.

Conditions

You can use conditions to enable dynamic configuration attributes, depending on various input sources like request headers, environment variables, query parameters and more. The following rules apply:

1. If no condition is defined, the parameter value is enabled automatically.
2. As soon as a conditions matches, the following conditions are no longer considered.
3. If a condition does not match, the subsequent parameter value is ignored.
4. A preceding "!" negates the condition.
5. Only one condition per line is accepted, but multiple condition lines can be added (linked by logical AND) before a parameter value.

The syntax of conditions are:

[!]Condition:<SOURCE>:<VARIABLE>:<EXPRESSION>

Where <SOURCE> can be one of the following:

• HEADER: source of request header
• PARAM: source of parameters in query or POST body
• AUTH: source of nevisAuth and session attributes
• ENV: source of Apache environment variables
• SESSION: source of session attribute
• CONST: constant values

The <VARIABLE> is the name of the given variable in the source context, and <EXPRESSION> is a regular expression for the value of the variable.

The ENV source also contains variables that are generated internally by nevisProxy itself, e.g. the variables generated by the connector servlet processing a request. For example, use ENV:bcx.servlet.response.<header_name> to access HTTP response headers.

The result of a condition can be negated by adding the "!" character in front of the condition:

  !Condition:REQUEST_METHOD:^POST$

In the following example, if the remote client address is in the specified address range, the IPisMatchingParameter parameter is taken. If the remote client address is not in the specified range, the system proceeds with the next condition block. The last parameter, the DefaultParameter is taken if no condition matches.

Condition:REMOTE_ADDR:CIDR/10.4.12.0/24/
IPisMatchingParameter
!Condition:HEADER:User-Agent:mozilla.*
Condition:AUTH:isiwebuser:.*
DoubleConditionParameter
DefaultParameter

Pragmas

Optional command pragmas can modify the behavior of conditions, for example determine whether conditions break on the first match or proceed. If the condition of a filter supports pragma, it also has a default, usually it is break. All filters which support conditional and/or pragmas contains a remark in the description.

• Pragma:break: If a condition matches, the first parameter value after the condition is taken.
• Pragma:continue: Modifies the second rule of the conditions. If a condition matches, all following parameter values are taken, and subsequent conditions are no longer ignored. Only specific parameters support it.
• Pragma: block-begin/Pragma: block-end: Attributes in the block are handled as one. This pragma is only supported by parameters that allow continue.

Example for break pragma:

Pragma:break
Condition:HEADER:User-Agent:mozilla.*
MozillaParameter
DefaultParameter

If the user agent contains mozilla in its name, the MozillaParameteris taken, and the DefaultParameter is skipped. If it does not match, the DefaultParameter is taken.

Example for continue pragma:

Pragma:continue
Condition:HEADER:User-Agent:mozilla.*
MozillaParameter
DefaultParameter

If the user agent contains mozilla in its name, both the MozillaParameterand the DefaultParameter are taken.

Example for block begin and end pragma with default break pragma:

Condition:HEADER:User-Agent:mozilla.*
Pragma: block-begin
MozillaParameter1
MozillaParameter2
Pragma: block-end
DefaultParameter

In this case, the block pragmas wraps the two mozilla parameter into one block, so if the condition matches, the parameter MozillaParameter1 and MozillaParameter2 are taken. If it does not match, the DefaultParameter is taken.

Example

For a more complex example, assume we have the following request headers:

Content-Type: text/plain
User-Agent: firefox

And the following configuration with pragma break:

Pragma:break
Condition:HEADER:User-Agent:firefox
Condition:Header:Content-Type:application/.*
value1
Condition:HEADER:User-Agent:firefox
Condition:Header:Content-Type:text/.*
value2
!Condition:Header:Content-Type:text/html
value3

Result is value2.

A similar configuration with the same headers but with pragma continue:

Pragma:continue
Condition:HEADER:User-Agent:firefox
Condition:Header:Content-Type:application/.*
value1
value2
Condition:HEADER:User-Agent:firefox
Condition:Header:Content-Type:text/.*
value3
value4
!Condition:Header:Content-Type:text/html
value5

Result:

value2
value3
value4
value5

The same configuration by wrapping the values with pragma block begin and end:

Pragma:continue
Condition:HEADER:Uesr-Agent:firefox
Condition:Header:Content-Type:application/.*
Pragma: block-begin
value1
value2
Pragma: block-end
Condition:HEADER:Uesr-Agent:firefox
Condition:Header:Content-Type:text/.*
value3
value4
!Condition:Header:Content-Type:text/html
value5

Result:

value3
value4
value5