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. +
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.
The ap_expr expression is intended to replace most other
- expression variants in HTTPD. For example, the deprecated
-
Backus-Naur Form (BNF) is a notation - technique for context-free grammars, often used to describe the syntax of languages used in computing. +
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 expr. However, a few directives
- like string.
+ For these, the starting point in the BNF is cond.
+ Directives like string.
-expr ::= "true" | "false"
- | "!" expr
- | expr "&&" expr
- | expr "||" expr
- | "(" expr ")"
+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" "{" wordlist "}"
- | word "in" listfunction
+ | word "in" listfunc
| word "=~" regex
| word "!~" regex
+ | word "in" "{" list "}"
stringcomp ::= word "==" word
@@ -97,35 +130,64 @@ integercomp ::= word "-eq" word | word "eq" wo
| word "-gt" word | word "gt" word
| word "-ge" word | word "ge" word
-wordlist ::= word
- | wordlist "," word
-
-word ::= word "." word
- | digit
+word ::= digits
| "'" string "'"
- | """ string """
+ | '"' string '"'
+ | word "." word
| variable
- | rebackref
+ | sub
+ | join
| function
+ | "(" word ")"
-string ::= stringpart
- | string stringpart
+list ::= split
+ | listfunc
+ | "{" words "}"
+ | "(" list ")"
-stringpart ::= cstring
+substring ::= cstring
| variable
- | rebackref
-
-cstring ::= ...
-digit ::= [0-9]+
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 ")"
-rebackref ::= "$" [0-9]
+listfunc ::= listfuncname "(" words ")"
-function ::= funcname "(" word ")"
+words ::= word
+ | word "," list
-listfunction ::= listfuncname "(" word ")"
+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">
@@ -155,6 +217,7 @@ listfunction ::= listfuncname "(" word ")"
HTTP_ACCEPTHTTP_COOKIEHTTP_FORWARDEDHTTP_HOSTHTTP_PROXY_CONNECTIONREQUEST_URIDOCUMENT_URIREQUEST_URIREQUEST_FILENAMEGET /index.html HTTP/1.1")REMOTE_ADDRREMOTE_PORTREMOTE_HOSTREMOTE_USERREMOTE_IDENTSERVER_NAMEAUTH_TYPEbasic")basic")CONTENT_TYPEHANDLERHTTP2on" if the request uses http/2,
+ "off" otherwiseHTTPSon" if the request uses https,
"off" otherwiseon" if the connection uses IPv6,
"off" otherwiseREQUEST_STATUSREQUEST_LOG_IDCONN_REMOTE_ADDRCONTEXT_PREFIXCONTEXT_DOCUMENT_ROOTTIME_YEAR2010)TIME_MON1, ..., 12)01, ..., 12)TIME_DAY01, ...)TIME_HOUR0, ..., 23)00, ..., 23)
TIME_MINTIME_SEC0
for Sunday)TIME2010123123595920101231235959SERVER_SOFTWAREAPI_VERSIONSome modules register additional variables, see e.g.
Some modules register additional variables, see e.g.
+
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.
>==~!~-eqeqfalse", or "no" (case insensitive).
True otherwise.-R%{REMOTE_ADDR} -ipmatch ...", but more efficient
+ %{REMOTE_ADDR} -ipmatch ...", but more
+ efficient
| Name | Description | Restricted |
|---|---|---|
| Name | Description | Special notes |
req, http |
Get HTTP request header; header names may be added to the Vary header, see below | Same as req, but header names will not be added to the
Vary header |
resp |
- Get HTTP response header | Get HTTP response header (most response headers will not yet be set
+ during |
reqenv |
- Lookup request environment variable (as a shortcut, v can be used too to access variables). | Lookup request environment variable (as a shortcut,
+ v can also be used to access variables).
+ |
+ ordering |
osenv |
Lookup operating system environment variable | |
note |
- Lookup request note | Lookup request note | ordering |
env |
Return first match of note, reqenv,
- osenv | ordering |
tolower |
Convert string to lower case | |
toupper |
@@ -488,15 +589,46 @@ listfunction ::= listfuncname "(" word ")"
Hash the string using SHA1, then encode the hash with hexadecimal encoding | |
file |
- Read contents from a file | yes | Read contents from a file (including line endings, when present) + | restricted | +
filemod |
+ Return last modification time of a file (or 0 if file does not exist + or is not regular file) | restricted |
filesize |
Return size of a file (or 0 if file does not exist or is not - regular file) | yes | restricted | +
ldap |
+ Escape characters as required by LDAP distinguished name escaping + (RFC4514) and LDAP filter escaping (RFC4515). | |
replace |
+ replace(string, "from", "to") replaces all occurrences of "from" + in the string with "to". |
The functions marked as "restricted" are not available in some modules
- like
The functions marked as "restricted" in the final column are not
+ available in some modules like
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
+ <
reqenv is used outside of <When the functions req or http are used,
the header name will automatically be added to the Vary header of the
@@ -504,11 +636,11 @@ listfunction ::= listfuncname "(" word ")"
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 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.
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. The following examples show how expressions might be used to evaluate requests: The following examples show how expressions might be used to
+ evaluate requests:PeerExtList. See the description of
@@ -519,14 +651,16 @@ listfunction ::= listfuncname "(" word ")"
Name Alternative Description -ininstring contained in string list string contained in list
/regexp/m#regexp#Regular expression (the second form allows different delimiters than /) Regular expression (the second form allows different
+ delimiters than /)
/regexp/im#regexp#iCase insensitive regular expression