Multiple services can be defined in order to route requests to different servers, depending on the request content. In this case, each service has one or more conditional statements (conditionals, for short), that define conditions which a request must match in order to be routed to backends within that particular service. Syntactically, such conditionals have the form:
kw [options] "pattern"
where kw is a keyword specifying what part of the request is used in comparison, pattern is a textual pattern which that part is matched against, and options are zero or more flags starting with a dash sign, which define matching algorithm.
Perhaps the most often used condition is Host, which compares
the value of the HTTP ‘Host’ header with the given pattern. By
default it uses exact case-insensitive match:
Host "example.com"
To treat the pattern as a regular expression, use the -re option, as in:
Host -re ".*\\.example\\.com"
Whenever we speak about regular expression we usually mean POSIX extended regular expressions (see POSIX extended regular expressions in GNU sed). However, other regex types can also be used. This is covered in Regular Expressions.
Notice the use of double backslashes in the above example. The backslash before each dot is needed to match it literally, while another one protects the first one from being interpreted as an escape character in string (see Strings).
Other useful options are -beg and -end, which
enable exact matching at the beginning and end of the value,
correspondingly. Thus, the Host statement above can be rewritten
as:
Host -end ".example.com"
The set of options available for use in conditions is uniform. See conditional-option, for a detailed discussion of available options.
The following configuration snippet illustrates the use of conditions to select appropriate service (and, correspondingly, backend). It will route all requests for ‘www.example.com’ to backend ‘192.0.2.1:8080’, and requests for ‘admin.example.com’ to ‘192.0.2.4:8080’:
ListenHTTP
Address 0.0.0.0
Port 80
Service
Host "www.example.com"
Backend
Address 192.0.2.1
Port 8080
End
End
Service
Host "admin.example.com"
Backend
Address 192.0.2.4
Port 8080
End
End
End
Other conditions use POSIX regexp matching by default. These are:
HeaderCompare HTTP header against a pattern. E.g.
Header "Content-Type:[[:space:]]*text/.*"
URLMatch URL:
URL "/login/.*&name=.*"
PathMatch the path part of the URL:
Path -beg "/login"
QueryMatch the query part of the URL.
QueryParamMatch the value of a query parameter. This statement takes two arguments: parameter name and pattern, e.g.:
QueryParam "type" "(int)|(bool)"
See Service Selection Statements, for a detailed description of these and other conditions.
Multiple conditions can be used together. Unless expressly specified otherwise, they are joined by logical ‘and’ operation. For example:
Service
Host "www.example.com"
URL "^/admin(/.*)?"
Backend
Address 192.0.2.4
Port 8080
End
End
This service will be used for requests directed to host name ‘www.example.com’ whose URL begins with ‘/admin’, optionally followed by more path components (such as, e.g. ‘http://www.example.com/admin/login’).
To select a service that matches one of defined rules (i.e. combine the
rules using logical ‘or’), enclose them in Match OR block,
as in:
Match OR
Host "example.com"
Host "www.example.com"
End
The argument to Match can be ‘OR’ or ‘AND’,
specifying logical operation to be used to join the enclosed
statements. The argument can be omitted, in which case ‘AND’ is
implied. Match statements can be nested to arbitrary depth,
which allows for defining criteria of arbitrary complexity. For
example:
Service
Match OR
Host "admin.example.com"
Match AND
Host "www.example.com"
URL "^/admin(/.*)?"
End
End
Backend
Address 192.0.2.4
Port 8080
End
End