rewrite statementThe Rewrite block statement associates one or more header
modification directives discussed above with request matching
directives, so that request modification takes place only
when the request matches certain conditions.
Syntactically, a Rewrite section is:
Rewrite [ request ]
conditional_directives…
modification_directives…
[ Else
conditional_directives…
modification_directives… ]
End
where conditional_directives represents one or more request
conditionals described below and modification_directives stands
for one or more header modification directives. The Else part
is optional; any number of Else blocks can be supplied, thus
providing for conditional branching.
The Rewrite statement is processed sequentially until a branch
is found whose conditional_directives yield ‘true’, or
End is encountered. If a matching branch is found, its
modification_directives are applied to the request.
Request matching directives or request conditionals are special statements that, being applied to a HTTP request, yield ‘true’ or ‘false’ depending on whether the request satisfies the condition described in the directive. The following conditionals are available:
Returns ‘true’ if the source IP matches one of the CIDRs from the named access control list name. The ACL itself must have been defined earlier (see ACL Definition).
See ACL, for a detailed discussion.
This statement defines an unnamed ACL to match the source IP against.
This line must be followed by one or more lines defining CIDRs, as
described in ACL Definition. The ACL definition is finished with an
End keyword on a line by itself.
Semantically, this statement is equivalent to the named ACL reference described above.
See ACL, for a detailed discussion.
Evaluates to ‘true’, if the incoming request passes basic authorization
as described in RFC 7617. Filename is the name of a plain text
file containing usernames and passwords, created with htpasswd
or similar utility. Unless the name starts with a slash, it is taken
relative to the IncludeDir directory (see include directory).
The file is cached in the memory on the first authorization attempt,
so that further authorizations do not result in disk operations. The
file will be re-scanned if pound notices that its
modification time has changed.
See Authentication.
Yields ‘true’, if the request contains at least one header matching the given pattern. By default, pattern is treated as case-insensitive POSIX extended regular expression. This can be changed by options, described below.
Evaluates to ‘true’, if the Host header matches
hostname. In the absence of options, case-insensitive
exact match is assumed, i.e. this construct is equivalent to
Header "Host:[[:space:]]*qhost"
where qhost is the hostname argument in quoted form, i.e. with all characters that have special meaning in regular expressions escaped.
See Table 9.2, for a detailed discussion of options and their effect on matching.
This statement is provided to facilitate handling of virtual hosts. See Service Selection, for details.
Returns ‘true’, if the path part of the incoming request matches pattern.
Returns ‘true’, if the query part of the incoming request matches pattern. The argument must be properly percent-encoded, if it contains whitespace or other non-printable characters.
Returns ‘true’, if the value of the query parameter name matches pattern.
See Table 9.2, for a detailed discussion of options and their effect on matching.
Expands string as described in String Expansions and matches the resulting value against pattern.
Matches URL of the request. Pattern is treated as case-sensitive extended regular expression, unless instructed otherwise by options (see below).
In these directives, options is a whitespace-delimited list of zero or more flags from the following table:
| Flag | Meaning |
|---|---|
-beg | Exact match at the beginning of string (prefix match). |
-case | Case-sensitive comparison. |
-contain | Match if pattern is a substring of the original value. |
-end | Exact match at the end of string (suffix match). |
-exact | Use exact string match. |
-file | Treat pattern as
the name of a file to read patterns from. If the name is relative, it
will be looked up in the include directory. Patterns are read
from the file line by line. Leading and trailing whitespace is
removed. Empty lines and comments (lines starting with #) are
ignored.
|
-icase | Case-insensitive comparison. |
-pcre | Use Perl-compatible regular expression. see Regular Expressions. |
-perl | Same as -pcre.
|
-posix | Use POSIX extended regular expression. see Regular Expressions. |
-re | Use regular expression match. This assumes the
default regular expression type, as set by the RegexType
directive (see Regular Expressions). |
Table 9.2: Conditional directive flags
The following options are mutually exclusive: -beg, -contain,
-end, -exact, -pcre (-perl),
-posix, -re. If more than one of these are used, the
last one takes effect.
Placing the keyword Not before a header matching directive reverts its
meaning. For example, the following will match any request whose URL
does not begin with /static/:
Not URL -beg "/static/"
The Match block statement can be used to join multiple header
matching directives. Its syntax is:
Match op … End
where … stands for any number of matching directives, and
op is a boolean operation: AND or OR
(case-insensitive). For example, the statement
Match OR Host "www.example.net" Path -beg "/ssl" End
will match if the request Host header has the value
‘www.example.net’, or the path part of its URL starts with
‘/ssl’. In contrast, the statement below:
Match AND Host "www.example.net" Path -beg "/ssl" End
will match only if both these conditions are met. As a syntactical
short-cut, two or more matching statements appearing outside of
Match are joined by an implicit logical AND, so that the
latter example is equivalent to:
Host "www.example.net" Path -beg "/ssl"
The Match statement, like any other matching directive, can be
prefixed with Not, which reverts its meaning.