• Routers
    • Configuration Example
    • Configuring HTTP Routers
      • EntryPoints
      • Rule
      • Middlewares
      • Service
      • TLS
        • General
        • options
        • certResolver
        • domains
    • Configuring TCP Routers
      • General
      • EntryPoints
      • Rule
      • Services
      • TLS
        • General
        • options
        • certResolver
        • domains

    Routers

    Connecting Requests to Services

    routers

    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

    Requests /foo are Handled by service-foo — Using the File Provider

    1.   [http.routers]
    2.     [http.routers.my-router]
    3.       rule = "Path(`/foo`)"
    4.       service = "service-foo"
    1.   http:
    2.     routers:
    3.       my-router:
    4.         rule: "Path(`/foo`)"
    5.         service: service-foo

    With a middleware — using the File Provider

    1.   [http.routers]
    2.     [http.routers.my-router]
    3.       rule = "Path(`/foo`)"
    4.       # declared elsewhere
    5.       middlewares = ["authentication"]
    6.       service = "service-foo"
    1.   http:
    2.     routers:
    3.       my-router:
    4.         rule: "Path(`/foo`)"
    5.         # declared elsewhere
    6.         middlewares:
    7.         - authentication
    8.         service: service-foo

    Forwarding all (non-tls) requests on port 3306 to a database service

    1. ## Static configuration ##
    3. [entryPoints]
    4.   [entryPoints.web]
    5.     address = ":80"
    6.   [entryPoints.mysql-default]
    7.     address = ":3306"   
    9. ## Dynamic configuration ##
    11. [tcp]
    12.   [tcp.routers]
    13.     [tcp.routers.to-database]
    14.       entryPoints = ["mysql-default"]
    15.       # Catch every request (only available rule for non-tls routers. See below.)
    16.       rule = "HostSNI(`*`)"
    17.       service = "database"
    1. ## Static configuration ##
    3. entryPoints:
    4.   web:
    5.     address: ":80"
    6.   mysql-default:
    7.     address: ":3306"   
    9. ## Dynamic configuration ##
    11. tcp:
    12.   routers:
    13.     to-database:
    14.       entryPoints:
    15.       - "mysql-default"
    16.       # Catch every request (only available rule for non-tls routers. See below.)
    17.       rule: "HostSNI(`*`)"
    18.       service: database

    Configuring HTTP Routers

    EntryPoints

    If not specified, HTTP routers will accept requests from all defined entry points.If you want to limit the router scope to a set of entry points, set the entryPoints option.Listens to Every EntryPoint

    1. ## Static configuration ##
    3. [entryPoints]
    4.   [entryPoints.web]
    5.     # ...
    6.   [entryPoints.web-secure]
    7.     # ...
    8.   [entryPoints.other]
    9.     # ...
    12. ## Dynamic configuration ##
    14. [http.routers]
    15.   [http.routers.Router-1]
    16.     # By default, routers listen to every entry points
    17.     rule = "Host(`traefik.io`)"
    18.     service = "service-1"
    1. ## Static configuration ##
    3. entryPoints:
    4.   web:
    5.     # ...
    6.   web-secure:
    7.     # ...
    8.   other:
    9.     # ...
    11. ## Dynamic configuration ##
    13. http:
    14.   routers:
    15.     Router-1:
    16.       # By default, routers listen to every entry points
    17.       rule: "Host(`traefik.io`)"
    18.       service: "service-1"

    Listens to Specific EntryPoints

    1. ## Static configuration ##
    3. [entryPoints]
    4.   [entryPoints.web]
    5.     # ...
    6.   [entryPoints.web-secure]
    7.     # ...
    8.   [entryPoints.other]
    9.     # ...
    11. ## Dynamic configuration ##
    13. [http.routers]
    14.   [http.routers.Router-1]
    15.     # won't listen to entry point web
    16.     entryPoints = ["web-secure", "other"]
    17.     rule = "Host(`traefik.io`)"
    18.     service = "service-1"
    1. ## Static configuration ##
    3. entryPoints:
    4.   web:
    5.     # ...
    6.   web-secure:
    7.     # ...
    8.   other:
    9.     # ...
    11. ## Dynamic configuration ##
    13. http:
    14.   routers:
    15.     Router-1:
    16.       # won't listen to entry point web
    17.       entryPoints:
    18.       - "web-secure"
    19.       - "other"
    20.       rule: "Host(`traefik.io`)"
    21.       service: "service-1"

    Rule

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

    1. rule = "Host(`traefik.io`)"

    Host is traefik.io OR Host is containo.us AND path is /traefik

    1. rule = "Host(`traefik.io`) || (Host(`containo.us`) && Path(`/traefik`))"

    The table below lists all the available matchers:

    RuleDescription
    Headers(key, value)Check if there is a key keydefined in the headers, with the value value
    HeadersRegexp(key, regexp)Check if there is a key keydefined in the headers, with a value that matches the regular expression regexp
    Host(domain-1, …)Check if the request domain targets one of the given domains.
    HostRegexp(traefik.io, {subdomain:[a-z]+}.traefik.io, …)Check if the request domain matches the given regexp.
    Method(GET, …)Check if the request method is one of the given methods (GET, POST, PUT, DELETE, PATCH)
    Path(/path, /articles/{category}/{id:[0-9]+}, …)Match exact request path. It accepts a sequence of literal and regular expression paths.
    PathPrefix(/products/, /articles/{category}/{id:[0-9]+})Match request prefix path. It accepts a sequence of literal and regular expression prefix paths.
    Query(foo=bar, bar=baz)Match` Query String parameters. It accepts a sequence of key=value pairs.

    Regexp Syntax

    In order to use regular expressions with Host and Path expressions,you must declare an arbitrarily named variable followed by the colon-separated regular expression, all enclosed in curly braces.Any pattern supported by Go's regexp package may be used (example: /posts/{id:[0-9]+}).

    Combining Matchers Using Operators and Parenthesis

    You can combine multiple matchers using the AND (&&) and OR (||) operators. You can also use parenthesis.

    Rule, Middleware, and Services

    The rule is evaluated "before" any middleware has the opportunity to work, and "before" the request is forwarded to the service.

    Path Vs PathPrefix

    Use Path if your service listens on the exact path only. For instance, Path: /products would match /products but not /products/shoes.

    Use a Prefix matcher if your service listens on a particular base path but also serves requests on sub-paths.For instance, PathPrefix: /products would match /products but also /products/shoes and /products/shirts.Since the path is forwarded as-is, your service is expected to listen on /products.

    Middlewares

    You can attach a list of middlewares to each HTTP router.The middlewares will take effect only if the rule matches, and before forwarding the request to the service.

    Service

    You must attach a service per router.Services are the target for the router.

    HTTP Only

    HTTP routers can only target HTTP services (not TCP services).

    TLS

    General

    When a TLS section is specified, it instructs Traefik that the current router is dedicated to HTTPS requests only (and that the router should ignore HTTP (non TLS) requests).Traefik will terminate the SSL connections (meaning that it will send decrypted data to the services).Configuring the router to accept HTTPS requests only

    1. [http.routers]
    2.   [http.routers.Router-1]
    3.     rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
    4.     service = "service-id"
    5.     # will terminate the TLS request
    6.     [http.routers.Router-1.tls]
    1. http:
    2.   routers:
    3.     Router-1:
    4.       rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
    5.       service: service-id
    6.       # will terminate the TLS request
    7.       tls: {}

    HTTPS & ACME

    In the current version, with ACME enabled, automatic certificate generation will apply to every router declaring a TLS section.

    Routers for HTTP & HTTPS

    If you need to define the same route for both HTTP and HTTPS requests, you will need to define two different routers: one with the tls section, one without.HTTP & HTTPS routes

    1. [http.routers]
    2.   [http.routers.my-https-router]
    3.     rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
    4.     service = "service-id"
    5.     # will terminate the TLS request
    6.     [http.routers.my-https-router.tls]
    8.   [http.routers.my-http-router]
    9.     rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
    10.     service = "service-id"
    1. http:
    2.   routers:
    3.     my-https-router:
    4.       rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
    5.       service: service-id
    6.       # will terminate the TLS request
    7.       tls: {}
    9.     my-http-router:
    10.       rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
    11.       service: service-id

    options

    The options field enables fine-grained control of the TLS parameters.It refers to a TLS Options and will be applied only if a Host rule is defined.

    Server Name Association

    Even though one might get the impression that a TLS options reference is mapped to a router, or a router rule, one should realize that it is actually mapped only to the host name found in the Host part of the rule. Of course, there could also be several Host parts in a rule, in which case the TLS options reference would be mapped to as many host names.

    Another thing to keep in mind is: the TLS option is picked from the mapping mentioned above and based on the server name provided during the TLS handshake, and it all happens before routing actually occurs.

    Configuring the TLS options

    1. [http.routers]
    2.   [http.routers.Router-1]
    3.     rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
    4.     service = "service-id"
    5.     # will terminate the TLS request
    6.     [http.routers.Router-1.tls]
    7.       options = "foo"
    9. [tls.options]
    10.   [tls.options.foo]
    11.     minVersion = "VersionTLS12"
    12.     cipherSuites = [
    13.       "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    14.       "TLS_RSA_WITH_AES_256_GCM_SHA384"
    15.     ]
    1. http:
    2.   routers:
    3.     Router-1:
    4.       rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
    5.       service: service-id
    6.       # will terminate the TLS request
    7.       tls:
    8.         options: foo
    10. tls:
    11.   options:
    12.     foo:
    13.       minVersion: VersionTLS12
    14.       cipherSuites:
    15.       - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    16.       - TLS_RSA_WITH_AES_256_GCM_SHA384

    Conflicting TLS Options

    Since a TLS options reference is mapped to a host name, if a configuration introduces a situation where the same host name (from a Host rule) gets matched with two TLS options references, a conflict occurs, such as in the example below:

    1. [http.routers]
    2.   [http.routers.routerfoo]
    3.     rule = "Host(`snitest.com`) && Path(`/foo`)"
    4.     [http.routers.routerfoo.tls]
    5.       options = "foo"
    7. [http.routers]
    8.   [http.routers.routerbar]
    9.     rule = "Host(`snitest.com`) && Path(`/bar`)"
    10.     [http.routers.routerbar.tls]
    11.       options = "bar"
    1. http:
    2.   routers:
    3.     routerfoo:
    4.       rule: "Host(`snitest.com`) && Path(`/foo`)"
    5.       tls:
    6.         options: foo
    8.     routerbar:
    9.       rule: "Host(`snitest.com`) && Path(`/bar`)"
    10.       tls:
    11.         options: bar

    If that happens, both mappings are discarded, and the host name (snitest.com in this case) for these routers gets associated with the default TLS options instead.

    certResolver

    If certResolver is defined, Traefik will try to generate certificates based on routers Host & HostSNI rules.

    1. [http.routers]
    2.   [http.routers.routerfoo]
    3.     rule = "Host(`snitest.com`) && Path(`/foo`)"
    4.     [http.routers.routerfoo.tls]
    5.       certResolver = "foo"
    1. http:
    2.   routers:
    3.     routerfoo:
    4.       rule: "Host(`snitest.com`) && Path(`/foo`)"
    5.       tls:
    6.         certResolver: foo

    Multiple Hosts in a Rule

    The rule Host(test1.traefik.io,test2.traefik.io) will request a certificate with the main domain test1.traefik.io and SAN test2.traefik.io.

    domains

    You can set SANs (alternative domains) for each main domain.Every domain must have A/AAAA records pointing to Traefik.Each domain & SAN will lead to a certificate request.

    1. [http.routers]
    2.   [http.routers.routerbar]
    3.     rule = "Host(`snitest.com`) && Path(`/bar`)"
    4.     [http.routers.routerbar.tls]
    5.       certResolver = "bar"
    6.       [[http.routers.routerbar.tls.domains]]
    7.         main = "snitest.com"
    8.         sans = "*.snitest.com"
    1. http:
    2.   routers:
    3.     routerbar:
    4.       rule: "Host(`snitest.com`) && Path(`/bar`)"
    5.       tls:
    6.         certResolver: "bar"
    7.         domains:
    8.         - main: "snitest.com"
    9.           sans: "*.snitest.com"

    ACME v2 supports wildcard certificates.As described in Let's Encrypt's post wildcard certificates can only be generated through a DNS-01 challenge.

    Most likely the root domain should receive a certificate too, so it needs to be specified as SAN and 2 DNS-01 challenges are executed.In this case the generated DNS TXT record for both domains is the same.Even though this behavior is DNS RFC compliant,it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the DNS-01 challenge fail.

    The Traefik ACME client library LEGO supports some but not all DNS providers to work around this issue.The Supported provider table indicates if they allow generating certificates for a wildcard domain and its root domain.

    Note

    Wildcard certificates can only be verified through a DNS-01 challenge.

    Double Wildcard Certificates

    It is not possible to request a double wildcard certificate for a domain (for example ..local.com).

    Configuring TCP Routers

    General

    If both HTTP routers and TCP routers listen to the same entry points, the TCP routers will apply before the HTTP routers.If no matching route is found for the TCP routers, then the HTTP routers will take over.

    EntryPoints

    If not specified, TCP routers will accept requests from all defined entry points.If you want to limit the router scope to a set of entry points, set the entry points option.Listens to Every Entry Point

    1. ## Static configuration ##
    3. [entryPoints]
    4.   [entryPoints.web]
    5.     # ...
    6.   [entryPoints.web-secure]
    7.     # ...
    8.   [entryPoints.other]
    9.     # ...
    11. ## Dynamic configuration ##
    13. [tcp.routers]
    14.   [tcp.routers.Router-1]
    15.     # By default, routers listen to every entrypoints
    16.     rule = "HostSNI(`traefik.io`)"
    17.     service = "service-1"
    18.     # will route TLS requests (and ignore non tls requests)
    19.     [tcp.routers.Router-1.tls]
    1. ## Static configuration ##
    3. entryPoints:
    4.   web:
    5.     # ...
    6.   web-secure:
    7.     # ...
    8.   other:
    9.     # ...
    11. ## Dynamic configuration ##
    13. tcp:
    14.   routers:
    15.     Router-1:
    16.       # By default, routers listen to every entrypoints
    17.       rule: "HostSNI(`traefik.io`)"
    18.       service: "service-1"
    19.       # will route TLS requests (and ignore non tls requests)
    20.       tls: {}

    Listens to Specific Entry Points

    1. ## Static configuration ##
    3. [entryPoints]
    4.   [entryPoints.web]
    5.     # ...
    6.   [entryPoints.web-secure]
    7.     # ...
    8.   [entryPoints.other]
    9.     # ...
    11. ## Dynamic configuration ##
    13. [tcp.routers]
    14.   [tcp.routers.Router-1]
    15.     # won't listen to entry point web
    16.     entryPoints = ["web-secure", "other"]
    17.     rule = "HostSNI(`traefik.io`)"
    18.     service = "service-1"
    19.     # will route TLS requests (and ignore non tls requests)
    20.     [tcp.routers.Router-1.tls]
    1. ## Static configuration ##
    3. entryPoints:
    4.   web:
    5.     # ...
    6.   web-secure:
    7.     # ...
    8.   other:
    9.     # ...
    11. ## Dynamic configuration ##
    13. tcp:
    14.   routers:
    15.     Router-1:
    16.       # won't listen to entry point web
    17.       entryPoints:
    18.       - "web-secure"
    19.       - "other"
    20.       rule: "HostSNI(`traefik.io`)"
    21.       service: "service-1"
    22.       # will route TLS requests (and ignore non tls requests)
    23.       tls: {}

    Rule

    RuleDescription
    HostSNI(domain-1, …)Check if the Server Name Indication corresponds to the given 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, non-TLS routers will have to explicitly use that rule with * (every domain) to state that every non-TLS request will be handled by the router.

    Services

    You must attach a TCP service per TCP router.Services are the target for the router.

    TCP Only

    TCP routers can only target TCP services (not HTTP services).

    TLS

    General

    When a TLS section is specified, it instructs Traefik that the current router is dedicated to TLS requests only (and that the router should ignore non-TLS requests).By default, Traefik will terminate the SSL connections (meaning that it will send decrypted data to the services), but Traefik can be configured in order to let the requests pass through (keeping the data encrypted), and be forwarded to the service "as is".Configuring TLS Termination

    1. [tcp.routers]
    2.   [tcp.routers.Router-1]
    3.     rule = "HostSNI(`foo-domain`)"
    4.     service = "service-id"
    5.     # will terminate the TLS request by default
    6.     [tcp.routers.Router-1.tls]
    1. tcp:
    2.   routers:
    3.     Router-1:
    4.       rule: "HostSNI(`foo-domain`)"
    5.       service: service-id
    6.       # will terminate the TLS request by default
    7.       tls: {}

    Configuring passthrough

    1. [tcp.routers]
    2.   [tcp.routers.Router-1]
    3.     rule = "HostSNI(`foo-domain`)"
    4.     service = "service-id"
    5.     [tcp.routers.Router-1.tls]
    6.       passthrough = true
    1. tcp:
    2.   routers:
    3.     Router-1:
    4.       rule: "HostSNI(`foo-domain`)"
    5.       service: service-id
    6.       tls:
    7.         passthrough: true

    TLS & ACME

    In the current version, with ACME enabled, automatic certificate generation will apply to every router declaring a TLS section.

    options

    The options field enables fine-grained control of the TLS parameters.It refers to a TLS Options and will be applied only if a HostSNI rule is defined.Configuring the tls options

    1. [tcp.routers]
    2.   [tcp.routers.Router-1]
    3.     rule = "HostSNI(`foo-domain`)"
    4.     service = "service-id"
    5.     # will terminate the TLS request
    6.     [tcp.routers.Router-1.tls]
    7.       options = "foo"
    9. [tls.options]
    10.   [tls.options.foo]
    11.     minVersion = "VersionTLS12"
    12.     cipherSuites = [
    13.       "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    14.       "TLS_RSA_WITH_AES_256_GCM_SHA384"
    15.     ]
    1. tcp:
    2.   routers:
    3.     Router-1:
    4.       rule: "HostSNI(`foo-domain`)"
    5.       service: service-id
    6.       # will terminate the TLS request
    7.       tls:
    8.         options: foo
    10. tls:
    11.   options:
    12.     foo:
    13.       minVersion: VersionTLS12
    14.       cipherSuites:
    15.       - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
    16.       - "TLS_RSA_WITH_AES_256_GCM_SHA384"

    certResolver

    See certResolver for HTTP router for more information.

    1. [tcp.routers]
    2.   [tcp.routers.routerfoo]
    3.     rule = "HostSNI(`snitest.com`)"
    4.     [tcp.routers.routerfoo.tls]
    5.       certResolver = "foo"
    1. tcp:
    2.   routers:
    3.     routerfoo:
    4.       rule: "HostSNI(`snitest.com`)"
    5.       tls:
    6.         certResolver: foo

    domains

    See domains for HTTP router for more information.

    1. [tcp.routers]
    2.   [tcp.routers.routerbar]
    3.     rule = "HostSNI(`snitest.com`)"
    4.     [tcp.routers.routerbar.tls]
    5.       certResolver = "bar"
    6.       [[tcp.routers.routerbar.tls.domains]]
    7.         main = "snitest.com"
    8.         sans = "*.snitest.com"
    1. tcp:
    2.   routers:
    3.     routerbar:
    4.       rule: "HostSNI(`snitest.com`)"
    5.       tls:
    6.         certResolver: "bar"
    7.         domains:
    8.         - main: "snitest.com"
    9.           sans: "*.snitest.com"