Expressions in Apache HTTP Server

Available Languages: en

Historically, there are several syntax variants for expressions used to express a condition in the different modules of the Apache HTTP Server. There is some ongoing effort to only use a single variant, called ap_expr, for all configuration directives. This document describes the ap_expr expression parser.

Grammar in BNF notation
Variables
Binary operators
Unary operators
Functions
Other

Grammar in BNF notation

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

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


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

wordlist    ::= word
              | wordlist "," word

word        ::= word "." word
              | digit
              | "'" string "'"
              | """ string """
              | variable
              | rebackref
              | function

string      ::= stringpart
              | string stringpart

stringpart  ::= cstring
              | variable
              | rebackref

cstring     ::= ...
digit       ::= [0-9]+

variable    ::= "%{" varname "}"
              | "%{" funcname ":" funcargs "}"

rebackref   ::= "$" [0-9]

function     ::= funcname "(" word ")"

listfunction ::= listfuncname "(" word ")"

Variables

XXX: not all vars are available in all request phases

Request headers (XXX:see req function)

Name
`HTTP_ACCEPT`
`HTTP_FORWARDED`
`HTTP_HOST`
`HTTP_PROXY_CONNECTION`
`HTTP_REFERER`
`HTTP_USER_AGENT`

Other request related variables

Name	Description
`REQUEST_METHOD`
`REQUEST_SCHEME`
`REQUEST_URI`
`REQUEST_FILENAME`
`REMOTE_HOST`
`REMOTE_IDENT`
`REMOTE_USER`
`SERVER_ADMIN`
`SERVER_NAME`
`SERVER_PORT`
`SERVER_PROTOCOL`
`SCRIPT_FILENAME`
`PATH_INFO`
`QUERY_STRING`
`IS_SUBREQ`
`DOCUMENT_ROOT`
`AUTH_TYPE`
`THE_REQUEST`
`CONTENT_TYPE`
`HANDLER`
`REMOTE_ADDR`
`HTTPS`
`IPV6`
`REQUEST_LOG_ID`
`CONN_LOG_ID`

Misc variables

Name	Description
`TIME_YEAR`
`TIME_MON`
`TIME_DAY`
`TIME_HOUR`
`TIME_MIN`
`TIME_SEC`
`TIME_WDAY`
`TIME`
`SERVER_SOFTWARE`
`API_VERSION`

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

Name	Alternative	Description
`==`	`=`	String equality
`!=`		String inequality
`<`		String less than
`<=`		String less than or equal
`>`		String greater than
`>=`		String greater than or equal
`-eq`	`eq`	Integer equality
`-ne`	`ne`	Integer inequality
`-lt`	`lt`	Integer less than
`-le`	`le`	Integer less than or equal
`-gt`	`gt`	Integer greater than
`-ge`	`ge`	Integer greater than or equal

Other binary operators

Name	Description
`-ipmatch`	IP address matches address/netmask
`-strmatch`	left string matches pattern given by right string (containing wildcards *, ?, [])
`-strcmatch`	same as `-strmatch`, but case insensitive
`-fnmatch`	same as `-strmatch`, but slashes are not matched by wildcards

Unary operators

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

Name	Description
`-n`	String is not empty
`-z`	String is empty
`-R`	Same as "`%{REMOTE_ADDR} -ipmatch ...`", but more efficient

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.

Name	Description
`req`, `http`	Get HTTP request header
`resp`	Get HTTP response header
`reqenv`	Lookup request environment variable
`osenv`	Lookup operating system environment variable
`note`	Lookup request note
`env`	Return first match of `note`, `reqenv`, `osenv`
`tolower`	Convert string to lower case
`toupper`	Convert string to uppser case
`escape`	Escape special characters in %hex encoding
`unescape`	Unescape %hex encoded string, leaving URL-special characters encoded (XXX: describe better)
`file`	Read contents from a file

In addition to string-valued functions, there are also list-valued functions which take one string as argument and return a wordlist, i.e. a list of strings. The wordlist 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

Name	Alternative	Description
`-in`	`in`	string contained in string list
`/regexp/`	`m#regexp#`	Regular expression (the second form allows different delimiters than /)
`/regexp/i`	`m#regexp#i`	Case insensitive regular expression
`$0 ... $9`		Regular expression backreferences

Regular expression backreferences

The strings $0 ... $9 allow to reference the capture groups form 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.