From 5dff2d61cc1c27747ee398e04d8e02843aabb1f8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Tue, 7 May 2024 04:04:06 +0200 Subject: Adding upstream version 2.4.38. Signed-off-by: Daniel Baumann --- docs/manual/expr.html.en | 656 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 656 insertions(+) create mode 100644 docs/manual/expr.html.en (limited to 'docs/manual/expr.html.en') diff --git a/docs/manual/expr.html.en b/docs/manual/expr.html.en new file mode 100644 index 0000000..ee03528 --- /dev/null +++ b/docs/manual/expr.html.en @@ -0,0 +1,656 @@ + + + + + +Expressions in Apache HTTP Server - Apache HTTP Server Version 2.4 + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+

Expressions in Apache HTTP Server

+
+

Available Languages:  en  | + fr 

+
+ +

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 SSLRequire expressions can be replaced + by Require expr.

+
+ +
top
+
+

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 expr. + However, a few directives like LogMessage accept expressions + that evaluate to a string value. For those, the starting point in + the BNF is string. +

+
+
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 ")"
+
+ +
top
+
+

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.

+ + + + + + + + + +
Name
HTTP_ACCEPT
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_PROXY_CONNECTION
HTTP_REFERER
HTTP_USER_AGENT
+ +

Other request related variables

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
REQUEST_METHODThe HTTP method of the incoming request (e.g. + GET)
REQUEST_SCHEMEThe scheme part of the request's URI
REQUEST_URIThe path part of the request's URI
DOCUMENT_URISame as REQUEST_URI
REQUEST_FILENAMEThe full local filesystem path to the file or script matching the + request, if this has already been determined by the server at the + time REQUEST_FILENAME is referenced. Otherwise, such + as when used in virtual host context, the same value as + REQUEST_URI
SCRIPT_FILENAMESame as REQUEST_FILENAME
LAST_MODIFIEDThe date and time of last modification of the file in the format + 20101231235959, if this has already been determined by + the server at the time LAST_MODIFIED is referenced. +
SCRIPT_USERThe user name of the owner of the script.
SCRIPT_GROUPThe group name of the group of the script.
PATH_INFOThe trailing path name information, see + AcceptPathInfo
QUERY_STRINGThe query string of the current request
IS_SUBREQ"true" if the current request is a subrequest, + "false" otherwise
THE_REQUESTThe complete request line (e.g., + "GET /index.html HTTP/1.1")
REMOTE_ADDRThe IP address of the remote host
REMOTE_PORTThe port of the remote host (2.4.26 and later)
REMOTE_HOSTThe host name of the remote host
REMOTE_USERThe name of the authenticated user, if any (not available during <If>)
REMOTE_IDENTThe user name set by mod_ident
SERVER_NAMEThe ServerName of + the current vhost
SERVER_PORTThe server port of the current vhost, see + ServerName
SERVER_ADMINThe ServerAdmin of + the current vhost
SERVER_PROTOCOLThe protocol used by the request
DOCUMENT_ROOTThe DocumentRoot of + the current vhost
AUTH_TYPEThe configured AuthType (e.g. + "basic")
CONTENT_TYPEThe content type of the response (not available during <If>)
HANDLERThe 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
IPV6"on" if the connection uses IPv6, + "off" otherwise
REQUEST_STATUSThe HTTP error status of the request (not available during <If>)
REQUEST_LOG_IDThe error log id of the request (see + ErrorLogFormat)
CONN_LOG_IDThe error log id of the connection (see + ErrorLogFormat)
CONN_REMOTE_ADDRThe peer IP address of the connection (see the + mod_remoteip module)
CONTEXT_PREFIX
CONTEXT_DOCUMENT_ROOT
+ +

Misc variables

+ + + + + + + + + + + + + + + + + + + + + + +
NameDescription
TIME_YEARThe current year (e.g. 2010)
TIME_MONThe current month (01, ..., 12)
TIME_DAYThe current day of the month (01, ...)
TIME_HOURThe hour part of the current time + (00, ..., 23)
TIME_MINThe minute part of the current time
TIME_SECThe second part of the current time
TIME_WDAYThe day of the week (starting with 0 + for Sunday)
TIMEThe date and time in the format + 20101231235959
SERVER_SOFTWAREThe server version string
API_VERSIONThe date of the API version (module magic number)
+ +

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

+ +
top
+
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameAlternative Description
===String equality
!= + String inequality
< + String less than
<= + String less than or equal
> + String greater than
>= + String greater than or equal
=~ + String matches the regular expression
!~ + String does not match the regular expression
-eqeqInteger equality
-neneInteger inequality
-ltltInteger less than
-leleInteger less than or equal
-gtgtInteger greater than
-gegeInteger greater than or equal
+ + +

Other binary operators

+ + + + + + + + + + + +
NameDescription
-ipmatchIP address matches address/netmask
-strmatchleft string matches pattern given by right string (containing + wildcards *, ?, [])
-strcmatchsame as -strmatch, but case insensitive
-fnmatchsame as -strmatch, but slashes are not matched by + wildcards
+ + +
top
+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionRestricted
-dThe argument is treated as a filename. + True if the file exists and is a directoryyes
-eThe argument is treated as a filename. + True if the file (or dir or special) existsyes
-fThe argument is treated as a filename. + True if the file exists and is regular fileyes
-sThe argument is treated as a filename. + True if the file exists and is not emptyyes
-LThe argument is treated as a filename. + True if the file exists and is symlinkyes
-hThe argument is treated as a filename. + True if the file exists and is symlink + (same as -L)yes
-FTrue if string is a valid file, accessible via all the server's + currently-configured access controls for that path. This uses an + internal subrequest to do the check, so use it with care - it can + impact your server's performance!
-UTrue if string is a valid URL, accessible via all the server's + currently-configured access controls for that path. This uses an + internal subrequest to do the check, so use it with care - it can + impact your server's performance!
-AAlias for -U
-nTrue if string is not empty
-zTrue if string is empty
-TFalse if string is empty, "0", "off", + "false", or "no" (case insensitive). + True otherwise.
-RSame as "%{REMOTE_ADDR} -ipmatch ...", but more + efficient +
+ +

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

+
top
+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionSpecial notes
req, httpGet HTTP request header; header names may be added to the Vary + header, see below
req_novarySame as req, but header names will not be added to the + Vary header
respGet HTTP response header (most response headers will not yet be set + during <If>)
reqenvLookup request environment variable (as a shortcut, + v can also be used to access variables). + ordering
osenvLookup operating system environment variable
noteLookup request noteordering
envReturn first match of note, reqenv, + osenvordering
tolowerConvert string to lower case
toupperConvert string to upper case
escapeEscape special characters in %hex encoding
unescapeUnescape %hex encoded string, leaving encoded slashes alone; + return empty string if %00 is found
base64Encode the string using base64 encoding
unbase64Decode base64 encoded string, return truncated string if 0x00 is + found
md5Hash the string using MD5, then encode the hash with hexadecimal + encoding
sha1Hash the string using SHA1, then encode the hash with hexadecimal + encoding
fileRead contents from a file (including line endings, when present) + restricted
filemodReturn last modification time of a file (or 0 if file does not exist + or is not regular file)restricted
filesizeReturn size of a file (or 0 if file does not exist or is not + regular file)restricted
+ +

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.

+
+

Environment variable ordering

+ When environment variables are looked up within an + <If> condition, it's important + to consider how extremely early in request processing that this + resolution occurs. As a guideline, any directive defined outside of virtual host + context (directory, location, htaccess) is not likely to have yet had a + chance to execute. SetEnvIf + in virtual host scope is one directive that runs prior to this resolution +
+
+ When reqenv is used outside of <If>, the resolution will generally occur later, but the + exact timing depends on the directive the expression has been used within. +
+ +

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 + 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).

+ +
top
+
+

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 example in boolean context
+<If "md5('foo') == 'acbd18db4cc2f85cedef654fccc4a4d8'">
+  Header set checksum-matched true
+</If>
+
+# 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$#"
+
+# 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'}"
+ +
top
+
+

Other

+ + + + + + + + + + + + + + +
NameAlternative Description
-ininstring contained in wordlist
/regexp/m#regexp#Regular expression (the second form allows different + delimiters than /)
/regexp/im#regexp#iCase insensitive regular expression
$0 ... $9 + Regular expression backreferences
+ +

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.

+ + +
top
+
+

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.

+
top
+
+

Version History

+ +

The req_novary function + is available for versions 2.4.4 and later.

+
+
+

Available Languages:  en  | + fr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3