4.1 Service Selection

To route requests to different servers, multiple services are used. In this case, each service has one or more matching rules, i.e. statements that define conditions that a request must match in order to be routed to that particular service. Syntactically, such rules 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 matching statements is uniform. See Table 9.2, for a detailed discussion of available options.

The following configuration snippet illustrates the use of matching rules 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 matching statements use POSIX regexp matching by default. These are:

Header

Compare HTTP header against a pattern. E.g.

Header "Content-Type:[[:space:]]*text/.*"

URL

Match URL:

URL "/login/.*&name=.*"

Path

Match the path part of the URL:

Path -beg "/login"

Query

Match the query part of the URL.

QueryParam

Match 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 matching statements.

Multiple matching rules can be used. 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