Rules and Priorities

A router is in charge of connecting incoming requests to the services that can handle them. In the process, routers may use pieces of middleware to update the request, or act before forwarding the request to the service.

Configuration Example

Check the HostSNI, match all connections

apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: HostSNI(`*`)
    kind: Rule
    services:
    - name: whoami
      port: 80

Check on the HostSNI, match example.com subdomains

apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: HostSNIRegexp(`^.+\.example\.com$`)
    kind: Rule
    # The bigger the number, the higher the priority
    priority: 10000
    services:
    - name: whoami
      port: 80

Rules

Rules are a set of matchers configured with values, that determine if a particular connection matches specific criteria. If the rule is verified, the router becomes active, calls middlewares, and then forwards the request to the service.

The table below lists all the available matchers:

Rule	Description
HostSNI(`domain`)	Checks if the connection's Server Name Indication is equal to domain. More information here.
HostSNIRegexp(`regexp`)	Checks if the connection's Server Name Indication matches regexp. Use a Go flavored syntax. More information here.
ClientIP(`ip`)	Checks if the connection's client IP correspond to ip. It accepts IPv4, IPv6 and CIDR formats. More information here.
ALPN(`protocol`)	Checks if the connection's ALPN protocol equals protocol. More information here.

Backticks or Quotes?

To set the value of a rule, use backticks ` or escaped double-quotes \".

Single quotes ' are not accepted since the values are Go's String Literals.

Expressing Complex Rules Using Operators and Parenthesis

The usual AND (&&) and OR (||) logical operators can be used, with the expected precedence rules, as well as parentheses.

One can invert a matcher by using the NOT (!) operator.

The following rule matches connections where:

• Either Server Name Indication is example.com OR,
• Server Name Indication is example.org AND ALPN protocol is NOT h2

HostSNI(`example.com`) || (HostSNI(`example.org`) && !ALPN(`h2`))

HostSNI and HostSNIRegexp

HostSNI and HostSNIRegexp matchers allow to match connections targeted to a given domain.

These matchers do not support non-ASCII characters, use punycode encoded values (rfc 3492) to match such domains.

HostSNI & TLS

It is important to note that the Server Name Indication is an extension of the TLS protocol. Hence, only TLS routers will be able to specify a domain name with that rule. However, there is one special use case for HostSNI with non-TLS routers: when one wants a non-TLS router that matches all (non-TLS) requests, one should use the specific HostSNI(`*`) syntax.

Examples

Match all connections:

HostSNI

HostSNI(`*`)

HostSNIRegexp

HostSNIRegexp(`^.*$`)

Match TCP connections sent to example.com:

HostSNI(`example.com`)

Match TCP connections opened on any subdomain of example.com:

HostSNIRegexp(`^.+\.example\.com$`)

ClientIP

The ClientIP matcher allows matching connections opened by a client with the given IP.

Examples

Match connections opened by a given IP:

IPv4

IPv4

ClientIP(`10.76.105.11`)

IPv6

IPv6

ClientIP(`::1`)

Match connections coming from a given subnet:

IPv4

IPv4

ClientIP(`192.168.1.0/24`)

IPv6

IPv6

ClientIP(`fe80::/10`)

ALPN

The ALPN matcher allows matching connections the given protocol.

It would be a security issue to let a user-defined router catch the response to an ACME TLS challenge previously initiated by Traefik. For this reason, the ALPN matcher is not allowed to match the ACME-TLS/1 protocol, and Traefik returns an error if this is attempted.

Example

Match connections using the ALPN protocol h2:

ALPN(`h2`)

Priority

To avoid path overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority.

A value of 0 for the priority is ignored: priority = 0 means that the default rules length sorting is used.

Example

The table below shows that Router-2 has a higher computed priority than Router-1.

Name	Rule	Priority
Router-1	ClientIP(`192.168.0.12`)	24
Router-2	ClientIP(`192.168.0.0/24`)	26

Which means that requests from 192.168.0.12 would go to Router-2 even though Router-1 is intended to specifically handle them. To achieve this intention, a priority (higher than 26) should be set on Router-1.