Expressions in Apache HTTP Server

Grammar in Backus-Naur Form notation ¶

Backus-Naur Form (BNF) is a notation technique for context-free grammars, often used to describe the syntax of languages used in computing. In most cases, expressions are used to express boolean values. For these, the starting point in the BNF is cond. Directives like ErrorDocument, Require, AuthName, Redirect, Header, CryptoKey or LogMessage accept expressions that evaluate to a string value. For those, the starting point in the BNF is string.

expr        ::= cond
              | string

string      ::= substring
              | string substring

cond        ::= "true" 
              | "false"
              | "!" cond
              | cond "&&" cond
              | cond "||" cond
              | comp
              | "(" cond ")"

comp        ::= stringcomp
              | integercomp
              | unaryop word
              | word binaryop word
              | word "in" listfunc
              | word "=~" regex
              | word "!~" regex
              | word "in" "{" list "}"


stringcomp  ::= word "==" word
              | word "!=" word
              | word "<"  word
              | word "<=" word
              | word ">"  word
              | word ">=" word

integercomp ::= word "-eq" word | word "eq" word
              | word "-ne" word | word "ne" word
              | word "-lt" word | word "lt" word
              | word "-le" word | word "le" word
              | word "-gt" word | word "gt" word
              | word "-ge" word | word "ge" word

word        ::= digits
              | "'" string "'"
              | '"' string '"'
              | word "." word
              | variable
              | sub
              | join
              | function
              | "(" word ")"

list        ::= split
              | listfunc
              | "{" words "}"
              | "(" list ")"

substring   ::= cstring
              | variable

variable    ::= "%{" varname "}"
              | "%{" funcname ":" funcargs "}"
              | "%{:" word ":}"
              | "%{:" cond ":}"
              | rebackref

sub         ::= "sub" ["("] regsub "," word [")"]

join        ::= "join" ["("] list [")"]
              | "join" ["("] list "," word [")"]

split       ::= "split" ["("] regany "," list [")"]
              | "split" ["("] regany "," word [")"]

function    ::= funcname "(" words ")"

listfunc    ::= listfuncname "(" words ")"

words       ::= word
              | word "," list

regex       ::= "/" regpattern "/" [regflags]
              | "m" regsep regpattern regsep [regflags]

regsub      ::= "s" regsep regpattern regsep string regsep [regflags]

regany      ::= regex | regsub

regsep      ::= "/" | "#" | "$" | "%" | "^" | "|" | "?" | "!" | "'" | '"' | "," | ";" | ":" | "." | "_" | "-"

regflags    ::= 1*("i" | "s" | "m" | "g")
regpattern  ::= cstring ; except enclosing regsep

rebackref   ::= "$" DIGIT

digits      ::= 1*(DIGIT)
cstring     ::= 0*(TEXT)

TEXT        ::= <any OCTET except CTLs>
DIGIT       ::= <any US-ASCII digit "0".."9">

Variables ¶

The expression parser provides a number of variables of the form %{HTTP_HOST}. Note that the value of a variable may depend on the phase of the request processing in which it is evaluated. For example, an expression used in an <If > directive is evaluated before authentication is done. Therefore, %{REMOTE_USER} will not be set in this case.

The following variables provide the values of the named HTTP request headers. The values of other headers can be obtained with the req function. Using these variables may cause the header name to be added to the Vary header of the HTTP response, except where otherwise noted for the directive accepting the expression. The req_novary function may be used to circumvent this behavior.

Other request related variables

Misc variables

Some modules register additional variables, see e.g. mod_ssl.

Any variable can be embedded in a string, both in quoted strings from boolean expressions but also in string expressions, resulting in the concatenation of the constant and dynamic parts as expected.

There exists another form of variables (temporaries) expressed like %{:word:} and which allow embedding of the more powerful word syntax (and constructs) in both type of expressions, without colliding with the constant part of such strings. They are mainly useful in string expressions though, since the word is directly available in boolean expressions already. By using this form of variables, one can evaluate regexes, substitutions, join and/or split strings and lists in the scope of string expressions, hence construct complex strings dynamically.

Binary operators ¶

With the exception of some built-in comparison operators, binary operators have the form "-[a-zA-Z][a-zA-Z0-9_]+", i.e. a minus and at least two characters. The name is not case sensitive. Modules may register additional binary operators.

Comparison operators

Other binary operators

Unary operators ¶

Unary operators take one argument and have the form "-[a-zA-Z]", i.e. a minus and one character. The name is case sensitive. Modules may register additional unary operators.

The operators marked as "restricted" are not available in some modules like mod_include.

Functions ¶

Normal string-valued functions take one string as argument and return a string. Functions names are not case sensitive. Modules may register additional functions.

The functions marked as "restricted" in the final column are not available in some modules like mod_include.

The functions marked as "ordering" in the final column require some consideration for the ordering of different components of the server, especially when the function is used within the <If> directive which is evaluated relatively early.

When the functions req or http are used, the header name will automatically be added to the Vary header of the HTTP response, except where otherwise noted for the directive accepting the expression. The req_novary function can be used to prevent names from being added to the Vary header.

In addition to string-valued functions, there are also list-valued functions which take one string as argument and return a list, i.e. a list of strings. The list can be used with the special -in operator. Functions names are not case sensitive. Modules may register additional functions.

There are no built-in list-valued functions. mod_ssl provides PeerExtList. See the description of SSLRequire for details (but PeerExtList is also usable outside of SSLRequire).

Other ¶

Regular expression backreferences

The strings $0 ... $9 allow to reference the capture groups from a previously executed, successfully matching regular expressions. They can normally only be used in the same expression as the matching regex, but some modules allow special uses.

Comparison with SSLRequire ¶

The ap_expr syntax is mostly a superset of the syntax of the deprecated SSLRequire directive. The differences are described in SSLRequire's documentation.

Version History ¶

The req_novary function is available for versions 2.4.4 and later.

The SERVER_PROTOCOL_VERSION, SERVER_PROTOCOL_VERSION_MAJOR and SERVER_PROTOCOL_VERSION_MINOR variables are available for versions 2.5.0 and later.

Example expressions ¶

The following examples show how expressions might be used to evaluate requests:

# Compare the host name to example.com and redirect to www.example.com if it matches
<If "%{HTTP_HOST} == 'example.com'">
    Redirect permanent "/" "http://www.example.com/"
</If>

# Force text/plain if requesting a file with the query string contains 'forcetext'
<If "%{QUERY_STRING} =~ /forcetext/">
    ForceType text/plain
</If>

# Only allow access to this content during business hours
<Directory "/foo/bar/business">
    Require expr %{TIME_HOUR} -gt 9 && %{TIME_HOUR} -lt 17
</Directory>

# Check a HTTP header for a list of values
<If "%{HTTP:X-example-header} in { 'foo', 'bar', 'baz' }">
    Header set matched true
</If>

# Check an environment variable for a regular expression, negated.
<If "! reqenv('REDIRECT_FOO') =~ /bar/">
    Header set matched true
</If>

# Check result of URI mapping by running in Directory context with -f
<Directory "/var/www">
    AddEncoding x-gzip gz
<If "-f '%{REQUEST_FILENAME}.unzipme' && ! %{HTTP:Accept-Encoding} =~ /gzip/">
      SetOutputFilter INFLATE
</If>
</Directory>

# Check against the client IP
<If "-R '192.168.1.0/24'">
    Header set matched true
</If>

# Function examples in boolean context
<If "md5('foo') == 'acbd18db4cc2f85cedef654fccc4a4d8'">
  Header set checksum-matched true
</If>

Require expr replace(%{REQUEST_METHOD},  'E', 'O') == 'GET'"

# Function example in string context
Header set foo-checksum "expr=%{md5:foo}"

# This delays the evaluation of the condition clause compared to <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path\.php$#"

# Add a header to forward client's certificate SAN to some backend
RequestHeader set X-Client-SAN "expr=%{:join PeerExtList('subjectAltName'):}"

# Require that the remote IP be in the client's certificate SAN
Require expr %{REMOTE_ADDR} -in split s/.*?IP Address:([^,]+)/$1/, PeerExtList('subjectAltName')
# or alternatively:
Require expr "IP Address:%{REMOTE_ADDR}" -in split/, /, join PeerExtList('subjectAltName')

# Conditional logging
CustomLog logs/access-errors.log common "expr=%{REQUEST_STATUS} >= 400"
CustomLog logs/access-errors-specific.log common "expr=%{REQUEST_STATUS} -in {'405','410'}"