Global Configuration

Main Section

  1. # DEPRECATED - for general usage instruction see [lifeCycle.graceTimeOut].
  2. #
  3. # If both the deprecated option and the new one are given, the deprecated one
  4. # takes precedence.
  5. # A value of zero is equivalent to omitting the parameter, causing
  6. # [lifeCycle.graceTimeOut] to be effective. Pass zero to the new option in
  7. # order to disable the grace period.
  8. #
  9. # Optional
  10. # Default: "0s"
  11. #
  12. # graceTimeOut = "10s"
  13. # Enable debug mode.
  14. # This will install HTTP handlers to expose Go expvars under /debug/vars and
  15. # pprof profiling data under /debug/pprof/.
  16. # The log level will be set to DEBUG unless `logLevel` is specified.
  17. #
  18. # Optional
  19. # Default: false
  20. #
  21. # debug = true
  22. # Periodically check if a new version has been released.
  23. #
  24. # Optional
  25. # Default: true
  26. #
  27. # checkNewVersion = false
  28. # Tells traefik whether it should keep the trailing slashes in the paths (e.g. /paths/) or redirect to the no trailing slash paths instead (/paths).
  29. #
  30. # Optional
  31. # Default: false
  32. #
  33. # keepTrailingSlash = false
  34. # Providers throttle duration.
  35. #
  36. # Optional
  37. # Default: "2s"
  38. #
  39. # providersThrottleDuration = "2s"
  40. # Controls the maximum idle (keep-alive) connections to keep per-host.
  41. #
  42. # Optional
  43. # Default: 200
  44. #
  45. # maxIdleConnsPerHost = 200
  46. # If set to true invalid SSL certificates are accepted for backends.
  47. # This disables detection of man-in-the-middle attacks so should only be used on secure backend networks.
  48. #
  49. # Optional
  50. # Default: false
  51. #
  52. # insecureSkipVerify = true
  53. # Register Certificates in the rootCA.
  54. #
  55. # Optional
  56. # Default: []
  57. #
  58. # rootCAs = [ "/mycert.cert" ]
  59. # Entrypoints to be used by frontends that do not specify any entrypoint.
  60. # Each frontend can specify its own entrypoints.
  61. #
  62. # Optional
  63. # Default: ["http"]
  64. #
  65. # defaultEntryPoints = ["http", "https"]
  66. # Allow the use of 0 as server weight.
  67. # - false: a weight 0 means internally a weight of 1.
  68. # - true: a weight 0 means internally a weight of 0 (a server with a weight of 0 is removed from the available servers).
  69. #
  70. # Optional
  71. # Default: false
  72. #
  73. # AllowMinWeightZero = true
  • graceTimeOut: Duration to give active requests a chance to finish before Traefik stops.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

    Note: in this time frame no new requests are accepted.

  • providersThrottleDuration: Providers throttle duration: minimum duration in seconds between 2 events from providers before applying a new configuration. It avoids unnecessary reloads if multiples events are sent in a short amount of time.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

  • maxIdleConnsPerHost: Controls the maximum idle (keep-alive) connections to keep per-host.

    If zero, DefaultMaxIdleConnsPerHost from the Go standard library net/http module is used. If you encounter 'too many open files' errors, you can either increase this value or change the ulimit.

  • insecureSkipVerify : If set to true invalid SSL certificates are accepted for backends.

    Note: This disables detection of man-in-the-middle attacks so should only be used on secure backend networks.

  • rootCAs: Register Certificates in the RootCA. This certificates will be use for backends calls.

    Note You can use file path or cert content directly

  • defaultEntryPoints: Entrypoints to be used by frontends that do not specify any entrypoint.

    Each frontend can specify its own entrypoints.

  • keepTrailingSlash: Tells Træfik whether it should keep the trailing slashes that might be present in the paths of incoming requests (true), or if it should redirect to the slashless version of the URL (default behavior: false)

Note

Beware that the value of keepTrailingSlash can have a significant impact on the way your frontend rules are interpreted. The table below tries to sum up several behaviors depending on requests/configurations. The current default behavior is deprecated and kept for compatibility reasons. As a consequence, we encourage you to set keepTrailingSlash to true.

Incoming request keepTrailingSlash Path:{value} Behavior
http://foo.com/path/ false Path:/path/ Proceeds with the request
http://foo.com/path/ false Path:/path 301 to http://foo.com/path
http://foo.com/path false Path:/path/ Proceeds with the request
http://foo.com/path false Path:/path Proceeds with the request
http://foo.com/path/ true Path:/path/ Proceeds with the request
http://foo.com/path/ true Path:/path 404
http://foo.com/path true Path:/path/ 404
http://foo.com/path true Path:/path Proceeds with the request

Constraints

In a micro-service architecture, with a central service discovery, setting constraints limits Traefik scope to a smaller number of routes.

Traefik filters services according to service attributes/tags set in your providers.

Supported filters:

  • tag

Simple

  1. # Simple matching constraint
  2. constraints = ["tag==api"]
  3. # Simple mismatching constraint
  4. constraints = ["tag!=api"]
  5. # Globbing
  6. constraints = ["tag==us-*"]

Multiple

  1. # Multiple constraints
  2. # - "tag==" must match with at least one tag
  3. # - "tag!=" must match with none of tags
  4. constraints = ["tag!=us-*", "tag!=asia-*"]

provider-specific

Supported Providers:

  • Docker
  • Consul K/V
  • BoltDB
  • Zookeeper
  • ECS
  • Etcd
  • Consul Catalog
  • Rancher
  • Marathon
  • Kubernetes (using a provider-specific mechanism based on label selectors)
  1. # Provider-specific constraint
  2. [consulCatalog]
  3. # ...
  4. constraints = ["tag==api"]
  5. # Provider-specific constraint
  6. [marathon]
  7. # ...
  8. constraints = ["tag==api", "tag!=v*-beta"]

Custom Error pages

Custom error pages can be returned, in lieu of the default, according to frontend-configured ranges of HTTP Status codes.

In the example below, if a 503 status is returned from the frontend "website", the custom error page at http://2.3.4.5/503.html is returned with the actual status code set in the HTTP header.

Note

The 503.html page itself is not hosted on Traefik, but some other infrastructure.

  1. [frontends]
  2. [frontends.website]
  3. backend = "website"
  4. [frontends.website.errors]
  5. [frontends.website.errors.network]
  6. status = ["500-599"]
  7. backend = "error"
  8. query = "/{status}.html"
  9. [frontends.website.routes.website]
  10. rule = "Host: website.mydomain.com"
  11. [backends]
  12. [backends.website]
  13. [backends.website.servers.website]
  14. url = "https://1.2.3.4"
  15. [backends.error]
  16. [backends.error.servers.error]
  17. url = "http://2.3.4.5"

In the above example, the error page rendered was based on the status code. Instead, the query parameter can also be set to some generic error page like so: query = "/500s.html"

Now the 500s.html error page is returned for the configured code range. The configured status code ranges are inclusive; that is, in the above example, the 500s.html page will be returned for status codes 500 through, and including, 599.

Rate limiting

Rate limiting can be configured per frontend.

Multiple sets of rates can be added to each frontend, but the time periods must be unique.

  1. [frontends]
  2. [frontends.frontend1]
  3. # ...
  4. [frontends.frontend1.ratelimit]
  5. extractorfunc = "client.ip"
  6. [frontends.frontend1.ratelimit.rateset.rateset1]
  7. period = "10s"
  8. average = 100
  9. burst = 200
  10. [frontends.frontend1.ratelimit.rateset.rateset2]
  11. period = "3s"
  12. average = 5
  13. burst = 10

In the above example, frontend1 is configured to limit requests by the client's ip address.

A sustained rate of 100 requests every 10 seconds (10 req/s) is allowed for rateset1, and 5 requests every 3 seconds (~1.67 req/s) for rateset2.

In addition, these can "burst" up to 200 and 10 in each period respectively.

Another way to describe the above parameters, is to use the leaky bucket analogy: for rateset1, the size of the bucket is 200 drops, and it is leaking at a rate of 10 drop/s. If the incoming rate of drops falling into the bucket gets high enough that the bucket gets filled, any subsequent drop overflows out of the bucket (i.e. the request is discarded). This situation holds until the incoming rate gets low enough again, and remains that way, for the water level in the bucket to go down.

Valid values for extractorfunc are: client.ip request.host * request.header.

Buffering

In some cases request/buffering can be enabled for a specific backend. By enabling this, Traefik will read the entire request into memory (possibly buffering large requests into disk) and will reject requests that are over a specified limit. This may help services deal with large data (multipart/form-data for example) more efficiently and should minimise time spent when sending data to a backend server.

For more information please check oxy/buffer documentation.

Example configuration:

  1. [backends]
  2. [backends.backend1]
  3. [backends.backend1.buffering]
  4. maxRequestBodyBytes = 10485760
  5. memRequestBodyBytes = 2097152
  6. maxResponseBodyBytes = 10485760
  7. memResponseBodyBytes = 2097152
  8. retryExpression = "IsNetworkError() && Attempts() <= 2"

Retry Configuration

  1. # Enable retry sending request if network error
  2. [retry]
  3. # Number of attempts
  4. #
  5. # Optional
  6. # Default: (number servers in backend) -1
  7. #
  8. # attempts = 3

Health Check Configuration

  1. # Enable custom health check options.
  2. [healthcheck]
  3. # Set the default health check interval.
  4. #
  5. # Optional
  6. # Default: "30s"
  7. #
  8. # interval = "30s"
  • interval set the default health check interval.

    Will only be effective if health check paths are defined.

    Given provider-specific support, the value may be overridden on a per-backend basis.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits).

    If no units are provided, the value is parsed assuming seconds.

Life Cycle

Controls the behavior of Traefik during the shutdown phase.

  1. [lifeCycle]
  2. # Duration to keep accepting requests prior to initiating the graceful
  3. # termination period (as defined by the `graceTimeOut` option). This
  4. # option is meant to give downstream load-balancers sufficient time to
  5. # take Traefik out of rotation.
  6. # Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
  7. # If no units are provided, the value is parsed assuming seconds.
  8. # The zero duration disables the request accepting grace period, i.e.,
  9. # Traefik will immediately proceed to the grace period.
  10. #
  11. # Optional
  12. # Default: 0
  13. #
  14. # requestAcceptGraceTimeout = "10s"
  15. # Duration to give active requests a chance to finish before Traefik stops.
  16. # Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
  17. # If no units are provided, the value is parsed assuming seconds.
  18. # Note: in this time frame no new requests are accepted.
  19. #
  20. # Optional
  21. # Default: "10s"
  22. #
  23. # graceTimeOut = "10s"

Timeouts

Responding Timeouts

respondingTimeouts are timeouts for incoming requests to the Traefik instance.

  1. [respondingTimeouts]
  2. # readTimeout is the maximum duration for reading the entire request, including the body.
  3. #
  4. # Optional
  5. # Default: "0s"
  6. #
  7. # readTimeout = "5s"
  8. # writeTimeout is the maximum duration before timing out writes of the response.
  9. #
  10. # Optional
  11. # Default: "0s"
  12. #
  13. # writeTimeout = "5s"
  14. # idleTimeout is the maximum duration an idle (keep-alive) connection will remain idle before closing itself.
  15. #
  16. # Optional
  17. # Default: "180s"
  18. #
  19. # idleTimeout = "360s"
  • readTimeout is the maximum duration for reading the entire request, including the body.

    If zero, no timeout exists.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

  • writeTimeout is the maximum duration before timing out writes of the response.

    It covers the time from the end of the request header read to the end of the response write. If zero, no timeout exists.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

  • idleTimeout is the maximum duration an idle (keep-alive) connection will remain idle before closing itself.

    If zero, no timeout exists.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

Forwarding Timeouts

forwardingTimeouts are timeouts for requests forwarded to the backend servers.

  1. [forwardingTimeouts]
  2. # dialTimeout is the amount of time to wait until a connection to a backend server can be established.
  3. #
  4. # Optional
  5. # Default: "30s"
  6. #
  7. # dialTimeout = "30s"
  8. # responseHeaderTimeout is the amount of time to wait for a server's response headers after fully writing the request (including its body, if any).
  9. #
  10. # Optional
  11. # Default: "0s"
  12. #
  13. # responseHeaderTimeout = "0s"
  • dialTimeout is the amount of time to wait until a connection to a backend server can be established.

    If zero, no timeout exists.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

  • responseHeaderTimeout is the amount of time to wait for a server's response headers after fully writing the request (including its body, if any).

    If zero, no timeout exists.

    Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

Idle Timeout (deprecated)

Use respondingTimeouts instead of idleTimeout. In the case both settings are configured, the deprecated option will be overwritten.

idleTimeout is the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. This is set to enforce closing of stale client connections.

Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.

  1. # idleTimeout
  2. #
  3. # DEPRECATED - see [respondingTimeouts] section.
  4. #
  5. # Optional
  6. # Default: "180s"
  7. #
  8. idleTimeout = "360s"

Host Resolver

hostResolver are used for request host matching process.

  1. [hostResolver]
  2. # cnameFlattening is a trigger to flatten request host, assuming it is a CNAME record
  3. #
  4. # Optional
  5. # Default : false
  6. #
  7. cnameFlattening = true
  8. # resolvConf is dns resolving configuration file, the default is /etc/resolv.conf
  9. #
  10. # Optional
  11. # Default : "/etc/resolv.conf"
  12. #
  13. # resolvConf = "/etc/resolv.conf"
  14. # resolvDepth is the maximum CNAME recursive lookup
  15. #
  16. # Optional
  17. # Default : 5
  18. #
  19. # resolvDepth = 5
  • To allow serving secure https request and generate the SSL using ACME while cnameFlattening is active. The acme configuration for HTTP-01 challenge and onDemand is mandatory. Refer to ACME configuration for more information.

Override Default Configuration Template

Warning

For advanced users only.

Supported by all providers except: File Provider, Web Provider and DynamoDB Provider.

  1. [provider_name]
  2. # Override default provider configuration template. For advanced users :)
  3. #
  4. # Optional
  5. # Default: ""
  6. #
  7. filename = "custom_config_template.tpml"
  8. # Enable debug logging of generated configuration template.
  9. #
  10. # Optional
  11. # Default: false
  12. #
  13. debugLogGeneratedTemplate = true

Example:

  1. [marathon]
  2. filename = "my_custom_config_template.tpml"

The template files can be written using functions provided by:

Example:

  1. [backends]
  2. [backends.backend1]
  3. url = "http://firstserver"
  4. [backends.backend2]
  5. url = "http://secondserver"
  6. {{$frontends := dict "frontend1" "backend1" "frontend2" "backend2"}}
  7. [frontends]
  8. {{range $frontend, $backend := $frontends}}
  9. [frontends.{{$frontend}}]
  10. backend = "{{$backend}}"
  11. {{end}}

Pass TLS Client Cert

  1. # Pass the escaped client cert infos selected below in a `X-Forwarded-Ssl-Client-Cert-Infos` header.
  2. [frontends.frontend1.passTLSClientCert]
  3. pem = true
  4. [frontends.frontend1.passTLSClientCert.infos]
  5. notBefore = true
  6. notAfter = true
  7. [frontends.frontend1.passTLSClientCert.infos.subject]
  8. country = true
  9. domainComponent = true
  10. province = true
  11. locality = true
  12. organization = true
  13. commonName = true
  14. serialNumber = true
  15. [frontends.frontend1.passTLSClientCert.infos.issuer]
  16. country = true
  17. domainComponent = true
  18. province = true
  19. locality = true
  20. organization = true
  21. commonName = true
  22. serialNumber = true

Pass TLS Client Cert pem defines if the escaped pem is added to a X-Forwarded-Ssl-Client-Cert header.

Pass TLS Client Cert infos defines how the certificate data are added to a X-Forwarded-Ssl-Client-Cert-Infos header.

The following example shows an unescaped result that uses all the available fields: If there are more than one certificate, they are separated by a ;

  1. Subject="DC=org,DC=cheese,C=FR,C=US,ST=Cheese org state,ST=Cheese com state,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=*.cheese.com",Issuer="DC=org,DC=cheese,C=FR,C=US,ST=Signing State,ST=Signing State 2,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=Simple Signing CA 2",NB=1544094616,NA=1607166616,SAN=*.cheese.org,*.cheese.net,*.cheese.com,[email protected],[email protected],10.0.1.0,10.0.1.2