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.
All directive described below can read a list of conditions from a disk file and reload that list upon any changes. See File-based Conditions, for a detailed discussion of this feature.
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.
Defines an unnamed ACL to match the source IP against. The ACL definition
is read from the file filename, one CIDR per line. Empty lines
and comments are allowed. If filename is relative, it is looked
up in the include directory. The form with -file reads
the file contents once, at the program startup. The one with
-filewatch reads it and then monitors that file for changes.
See File-based Conditions, 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 at startup, so that further
authorizations do not result in disk operations. The file will be
reloaded if changed (see File-based Conditions).
See Authentication, for a detailed description.
For consistency with other conditions, BasicAuth accepts the
following options: -file and -filewatch. The
latter enables the default behavior and so need not be specified
explicitly. The former disables file change monitoring.
Evaluates to ‘true’, if the request contains at least one header
matching the given pattern. The directive has two forms.
In first form, the pattern is compared against entire header line.
In second form, the field argument supplies the header name, and
pattern the pattern to match against its value (or the name of
the file to read patterns from, if options is -file or
-filewatch).
An example of Header statement in first form:
Header "^Content-Type:[[:space:]]*text/.+"
Here’s the corresponding statement in second form:
Header "Content-Type" "text/.+"
In both forms, pattern is treated as case-insensitive POSIX extended regular expression. This can be changed by options, described below.
In first form, pattern modification options, such as -beg or
-contain apply to entire header line. In second form, they
apply to header value only. For example, you can write:
Header "Content-Type" -beg "text/"
to match a request whose ‘Content-Type’ header value begins with ‘text/’, or
Header -contain "forwarded"
to match requests that contain any header with the word ‘forwarded’ anywhere, be it header field name or its value.
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 conditional-option, 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 conditional-option, 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 options discussed below:
Exact match at the beginning of string (prefix match).
Case-sensitive comparison.
Match if pattern is a substring of the original value.
Exact match at the end of string (suffix match).
Exact string match.
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.
Same as -file, but the file will be monitored for changes and
reloaded as soon as such are detected. See File-based Conditions, for a detailed description.
Case-insensitive comparison.
Use Perl-compatible regular expression. See Regular Expressions.
Use POSIX extended regular expression. See Regular Expressions.
Use regular expression match. This assumes the default regular
expression type, as set by the RegexType directive
(see Regular Expressions).
Tag this conditional with string t. The tag can be used by another statements to refer to substrings obtained when matching this pattern.
For example:
Host -tag host -re "(www\\.)?(example.(org|com))" Header "Content-Type" -tag "type" -re -icase "^application/(.+)" Path -tag "path" -re "/public/(.+)" SetPath "$3(host)/$1(type)$1(path)"
See Backreference expansion, for a detailed discussion of how backreferences are expanded in strings.
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.