rewrite statementThe Rewrite block statement associates one or more header
modification directives discussed above with conditionals, 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).
By default, ACL operates on the actual originator IP address.
This is changed if -forwarded is specified, in which case it
uses an IP determined from the X-Forwarded-For (or similar)
header (see %a).
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.
The -forwarded option instructs pound to use source
IP address determined from the X-Forwarded-For header
(see %a), instead of the actual originator IP.
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.
The meaning of -forwarded is as described above.
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 the detached condition name. The result is
cached, so that each detached condition is evaluated at most once.
All Eval directives referring to its name will reuse the cached
value. See Detached Conditions, for a detailed discussion.
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.
Run Lua function func with the supplied arguments. Use its return value (which must be boolean) as the result of the test.
The func can be either an unqualified function name, or function
name with module qualifier (module.func).
Each arg is subject to to backreference expansion and request accessor interpretation, as discussed in Request modifications.
This statement is available only if pound was built with Lua
support. See Lua conditionals, for a detailed discussion.
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.
options is zero or more conditional options, as discussed in conditional-option.
Returns ‘true’, if query parameter name is defined and its value matches pattern.
options is zero or more conditional options (see conditional-option), or -decode, which instructs the program to percent-decode the value prior to comparison.
Expands string as described in String Expansions and matches the resulting value against pattern.
See conditional-option, for a detailed discussion of options and their effect on matching.
Defines a token bucket filter condition. See Rate-limiting, for a detailed discussion. Arguments are:
A string identifying the bucket. It is subject to backreference expansion and request accessor interpretation, as described in String Expansions.
Rate limit. A single decimal number means requests per second. To specify another time unit, follow the number with a slash, another number and optional unit specifier (‘s’ for seconds, ‘ms’ for milliseconds, and ‘us’ for microseconds). Examples:
1/2s ⇒ "one request per two seconds" 200/500ms ⇒ "200 requests per 500 milliseconds"
Burst value, i.e. maximum number of tokens the bucket can contain.
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
conditional statements. Its syntax is:
Match op … End
where … stands for any number of conditionals, 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 conditionals 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 conditional, can be
prefixed with Not, which reverts its meaning.