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 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
@@ -89,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 ")"
+
+listfunc ::= listfuncname "(" words ")"
+
+words ::= word
+ | word "," list
+
+regex ::= "/" regpattern "/" [regflags]
+ | "m" regsep regpattern regsep [regflags]
+
+regsub ::= "s" regsep regpattern regsep string regsep [regflags]
-rebackref ::= "$" [0-9]
+regany ::= regex | regsub
-function ::= funcname "(" word ")"
+regsep ::= "/" | "#" | "$" | "%" | "^" | "|" | "?" | "!" | "'" | '"' | "," | ";" | ":" | "." | "_" | "-"
-listfunction ::= listfuncname "(" word ")"
+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">
@@ -134,14 +204,20 @@ listfunction ::= listfuncname "(" word ")"
%{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 witht the
- req function.
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.
| Name | |
|---|---|
HTTP_ACCEPT | |
HTTP_COOKIE | |
HTTP_FORWARDED | |
HTTP_HOST | |
HTTP_PROXY_CONNECTION | |
REQUEST_URI |
The path part of the request's URI |
DOCUMENT_URI |
- Same as REQUEST_URI | Same as REQUEST_URI |
REQUEST_FILENAME |
The full local filesystem path to the file or script matching the
request, if this has already been determined by the server at the
@@ -195,10 +271,12 @@ listfunction ::= listfuncname "(" word ")"
"GET /index.html HTTP/1.1") |
REMOTE_ADDR |
The IP address of the remote host |
REMOTE_PORT |
+ The port of the remote host (2.4.26 and later) |
REMOTE_HOST |
The host name of the remote host |
REMOTE_USER |
- The name of the authenticated user (if any) | The name of the authenticated user, if any (not available during |
REMOTE_IDENT |
The user name set by |
SERVER_NAME |
@@ -211,18 +289,35 @@ listfunction ::= listfuncname "(" word ")"
The |
SERVER_PROTOCOL |
- The protocol used by the request | The protocol used by the request (e.g. HTTP/1.1). In some types of
+ internal subrequests, this variable has the value
+ INCLUDED. |
+
SERVER_PROTOCOL_VERSION |
+ A number that encodes the HTTP version of the request:
+ 1000 * major + minor. For example, 1001
+ corresponds to HTTP/1.1 and 9 corresponds
+ to HTTP/0.9 |
SERVER_PROTOCOL_VERSION_MAJOR |
+ The major version part of the HTTP version of the request,
+ e.g. 1 for HTTP/1.0 |
SERVER_PROTOCOL_VERSION_MINOR |
+ The minor version part of the HTTP version of the request,
+ e.g. 0 for HTTP/1.0 |
DOCUMENT_ROOT |
The |
AUTH_TYPE |
- The configured basic") | The configured basic") |
CONTENT_TYPE |
- The content type of the response | The content type of the response (not available during |
HANDLER |
The name of the handler creating the response |
HTTP2 |
+ "on" if the request uses http/2,
+ "off" otherwise |
HTTPS |
"on" if the request uses https,
"off" otherwise | "on" if the connection uses IPv6,
"off" otherwise |
REQUEST_STATUS |
- The HTTP error status of the request | The HTTP error status of the request (not available during |
REQUEST_LOG_ID |
The error log id of the request (see
|
CONN_REMOTE_ADDR |
The peer IP address of the connection (see the
|
CONTEXT_PREFIX |
+ |
CONTEXT_DOCUMENT_ROOT |
+
TIME_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 | Get HTTP request header; header names may be added to the Vary + header, see below | + |
req_novary |
+ 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 | 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 |
- Convert string to uppser case | Convert string to upper case |
escape |
Escape special characters in %hex encoding | |
unescape |
Unescape %hex encoded string, leaving encoded slashes alone; return empty string if %00 is found | |
base64 |
+ Encode the string using base64 encoding | |
unbase64 |
+ Decode base64 encoded string, return truncated string if 0x00 is + found | |
md5 |
+ Hash the string using MD5, then encode the hash with hexadecimal + encoding | |
sha1 |
+ 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
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.
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
+ 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. 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
@@ -472,30 +651,78 @@ listfunction ::= listfuncname "(" word ")"
- <If "%{HTTP_HOST} == 'example.com'">
-
-
- # Force text/plain if requesting a file with the query string contains 'forcetext'
- <If "%{QUERY_STRING} =~ /forcetext/">
-
-
- # Only allow access to this content during business hours
- <Directory "/foo/bar/business">
-
- 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
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.