2017-08-26 10:12:44 +00:00
# Global Configuration
2017-08-25 19:32:33 +00:00
2017-08-26 10:12:44 +00:00
## Main Section
2017-08-25 19:32:33 +00:00
```toml
2017-09-26 08:22:03 +00:00
# DEPRECATED - for general usage instruction see [lifeCycle.graceTimeOut].
#
# If both the deprecated option and the new one are given, the deprecated one
# takes precedence.
# A value of zero is equivalent to omitting the parameter, causing
# [lifeCycle.graceTimeOut] to be effective. Pass zero to the new option in
# order to disable the grace period.
2017-08-25 19:32:33 +00:00
#
# Optional
2017-09-26 08:22:03 +00:00
# Default: "0s"
2017-08-25 19:32:33 +00:00
#
# graceTimeOut = "10s"
2017-09-11 17:10:04 +00:00
# Enable debug mode.
2017-11-20 10:04:03 +00:00
# This will install HTTP handlers to expose Go expvars under /debug/vars and
# pprof profiling data under /debug/pprof.
# Additionally, the log level will be set to DEBUG.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: false
#
# debug = true
2017-09-11 17:10:04 +00:00
# Periodically check if a new version has been released.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: true
#
# checkNewVersion = false
2017-09-11 17:10:04 +00:00
# Backends throttle duration.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: "2s"
#
# ProvidersThrottleDuration = "2s"
2017-09-11 17:10:04 +00:00
# Controls the maximum idle (keep-alive) connections to keep per-host.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: 200
#
# MaxIdleConnsPerHost = 200
# If set to true invalid SSL certificates are accepted for backends.
2017-09-11 17:10:04 +00:00
# This disables detection of man-in-the-middle attacks so should only be used on secure backend networks.
2017-09-05 13:58:03 +00:00
#
2017-08-25 19:32:33 +00:00
# Optional
# Default: false
#
# InsecureSkipVerify = true
2017-09-11 17:10:04 +00:00
# Register Certificates in the RootCA.
#
2017-08-25 19:32:33 +00:00
# Optional
# Default: []
#
# RootCAs = [ "/mycert.cert" ]
# Entrypoints to be used by frontends that do not specify any entrypoint.
# Each frontend can specify its own entrypoints.
#
# Optional
# Default: ["http"]
#
# defaultEntryPoints = ["http", "https"]
```
2017-09-11 17:10:04 +00:00
- `graceTimeOut` : Duration to give active requests a chance to finish before Traefik stops.
Can be provided in a format supported by [time.ParseDuration ](https://golang.org/pkg/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` : Backends 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 ](https://golang.org/pkg/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.
2017-09-05 13:58:03 +00:00
## Constraints
2017-08-25 19:32:33 +00:00
In a micro-service architecture, with a central service discovery, setting constraints limits Træfik scope to a smaller number of routes.
Træfik filters services according to service attributes/tags set in your configuration backends.
Supported filters:
- `tag`
2017-09-05 13:58:03 +00:00
### Simple
2017-08-25 19:32:33 +00:00
```toml
# Simple matching constraint
2017-09-05 13:58:03 +00:00
constraints = ["tag==api"]
2017-08-26 10:12:44 +00:00
2017-08-25 19:32:33 +00:00
# Simple mismatching constraint
2017-09-05 13:58:03 +00:00
constraints = ["tag!=api"]
2017-08-26 10:12:44 +00:00
2017-08-25 19:32:33 +00:00
# Globbing
2017-09-05 13:58:03 +00:00
constraints = ["tag==us-*"]
```
### Multiple
2017-08-26 10:12:44 +00:00
2017-09-05 13:58:03 +00:00
```toml
2017-08-25 19:32:33 +00:00
# Multiple constraints
# - "tag==" must match with at least one tag
# - "tag!=" must match with none of tags
2017-09-05 13:58:03 +00:00
constraints = ["tag!=us-*", "tag!=asia-*"]
```
2017-08-26 10:12:44 +00:00
2017-09-05 13:58:03 +00:00
### Backend-specific
2017-09-11 17:10:04 +00:00
Supported backends:
- Docker
- Consul K/V
- BoltDB
- Zookeeper
- Etcd
- Consul Catalog
- Rancher
- Marathon
- Kubernetes (using a provider-specific mechanism based on label selectors)
2017-09-05 13:58:03 +00:00
```toml
2017-08-26 10:12:44 +00:00
# Backend-specific constraint
2017-09-05 13:58:03 +00:00
[consulCatalog]
2017-09-11 17:10:04 +00:00
# ...
2017-09-05 13:58:03 +00:00
constraints = ["tag==api"]
2017-08-26 10:12:44 +00:00
2017-09-11 17:10:04 +00:00
# Backend-specific constraint
2017-09-05 13:58:03 +00:00
[marathon]
2017-09-11 17:10:04 +00:00
# ...
2017-09-05 13:58:03 +00:00
constraints = ["tag==api", "tag!=v*-beta"]
2017-08-25 19:32:33 +00:00
```
2017-09-05 13:58:03 +00:00
## Logs Definition
### Traefik logs
2017-09-01 18:04:41 +00:00
```toml
# Traefik logs file
# If not defined, logs to stdout
2017-09-21 08:42:02 +00:00
#
# DEPRECATED - see [traefikLog] lower down
# In case both traefikLogsFile and traefikLog.filePath are specified, the latter will take precedence.
# Optional
#
2017-09-05 13:58:03 +00:00
traefikLogsFile = "log/traefik.log"
2017-09-01 18:04:41 +00:00
# Log level
#
# Optional
# Default: "ERROR"
2017-09-05 13:58:03 +00:00
#
2017-09-01 18:04:41 +00:00
# Accepted values, in order of severity: "DEBUG", "INFO", "WARN", "ERROR", "FATAL", "PANIC"
# Messages at and above the selected level will be logged.
#
2017-09-05 13:58:03 +00:00
logLevel = "ERROR"
2017-09-01 18:04:41 +00:00
```
2017-09-21 08:42:02 +00:00
## Traefik Logs
By default the Traefik log is written to stdout in text format.
To write the logs into a logfile specify the `filePath` .
```toml
[traefikLog]
filePath = "/path/to/traefik.log"
```
To write JSON format logs, specify `json` as the format:
```toml
[traefikLog]
filePath = "/path/to/traefik.log"
format = "json"
```
2017-09-05 13:58:03 +00:00
### Access Logs
2017-08-25 19:32:33 +00:00
2017-09-07 10:02:03 +00:00
Access logs are written when `[accessLog]` is defined.
2017-08-25 19:32:33 +00:00
By default it will write to stdout and produce logs in the textual Common Log Format (CLF), extended with additional fields.
To enable access logs using the default settings just add the `[accessLog]` entry.
```toml
[accessLog]
```
To write the logs into a logfile specify the `filePath` .
```toml
[accessLog]
2017-09-05 13:58:03 +00:00
filePath = "/path/to/access.log"
2017-08-25 19:32:33 +00:00
```
To write JSON format logs, specify `json` as the format:
```toml
[accessLog]
2017-09-05 13:58:03 +00:00
filePath = "/path/to/access.log"
format = "json"
2017-08-25 19:32:33 +00:00
```
2017-09-01 18:04:41 +00:00
Deprecated way (before 1.4):
```toml
# Access logs file
#
# DEPRECATED - see [accessLog] lower down
#
accessLogsFile = "log/access.log"
```
2017-09-05 13:58:03 +00:00
### Log Rotation
2017-09-01 18:04:41 +00:00
Traefik will close and reopen its log files, assuming they're configured, on receipt of a USR1 signal.
This allows the logs to be rotated and processed by an external program, such as `logrotate` .
!!! note
2017-09-11 17:10:04 +00:00
This does not work on Windows due to the lack of USR signals.
2017-09-01 18:04:41 +00:00
## Custom Error pages
Custom error pages can be returned, in lieu of the default, according to frontend-configured ranges of HTTP Status codes.
2017-09-11 17:10:04 +00:00
2017-09-01 18:04:41 +00:00
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.
2017-09-11 17:10:04 +00:00
!!! note
The `503.html` page itself is not hosted on Traefik, but some other infrastructure.
2017-09-01 18:04:41 +00:00
```toml
[frontends]
[frontends.website]
backend = "website"
[frontends.website.errors]
[frontends.website.errors.network]
status = ["500-599"]
backend = "error"
query = "/{status}.html"
[frontends.website.routes.website]
rule = "Host: website.mydomain.com"
[backends]
[backends.website]
[backends.website.servers.website]
url = "https://1.2.3.4"
[backends.error]
[backends.error.servers.error]
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` .
2017-12-19 08:48:03 +00:00
## 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.
```toml
[frontends]
[frontends.frontend1]
2018-01-29 13:36:03 +00:00
# ...
[frontends.frontend1.ratelimit]
extractorfunc = "client.ip"
[frontends.frontend1.ratelimit.rateset.rateset1]
period = "10s"
average = 100
burst = 200
[frontends.frontend1.ratelimit.rateset.rateset2]
period = "3s"
average = 5
burst = 10
2017-12-19 08:48:03 +00:00
```
In the above example, frontend1 is configured to limit requests by the client's ip address.
An average of 5 requests every 3 seconds is allowed and an average of 100 requests every 10 seconds.
These can "burst" up to 10 and 200 in each period respectively.
2017-08-26 10:12:44 +00:00
## Retry Configuration
2017-08-25 19:32:33 +00:00
```toml
# Enable retry sending request if network error
[retry]
# Number of attempts
#
# Optional
# Default: (number servers in backend) -1
#
# attempts = 3
```
2017-09-05 13:58:03 +00:00
2017-08-26 10:12:44 +00:00
## Health Check Configuration
2017-08-25 19:32:33 +00:00
```toml
# Enable custom health check options.
[healthcheck]
2017-09-11 17:10:04 +00:00
# Set the default health check interval.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: "30s"
#
# interval = "30s"
```
2017-09-11 17:10:04 +00:00
- `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 ](https://golang.org/pkg/time/#ParseDuration ) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
2017-09-05 13:58:03 +00:00
2017-09-26 08:22:03 +00:00
## Life Cycle
Controls the behavior of Traefik during the shutdown phase.
```toml
[lifeCycle]
# Duration to keep accepting requests prior to initiating the graceful
# termination period (as defined by the `graceTimeOut` option). This
# option is meant to give downstream load-balancers sufficient time to
# take Traefik out of rotation.
# Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
# If no units are provided, the value is parsed assuming seconds.
# The zero duration disables the request accepting grace period, i.e.,
# Traefik will immediately proceed to the grace period.
#
# Optional
# Default: 0
#
# requestAcceptGraceTimeout = "10s"
# Duration to give active requests a chance to finish before Traefik stops.
# Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/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.
#
# Optional
# Default: "10s"
#
# graceTimeOut = "10s"
```
2017-09-05 13:58:03 +00:00
## Timeouts
### Responding Timeouts
`respondingTimeouts` are timeouts for incoming requests to the Traefik instance.
2017-08-26 10:12:44 +00:00
```toml
2017-08-25 19:32:33 +00:00
[respondingTimeouts]
# readTimeout is the maximum duration for reading the entire request, including the body.
2017-09-07 10:02:03 +00:00
#
2017-08-25 19:32:33 +00:00
# Optional
# Default: "0s"
2017-09-07 10:02:03 +00:00
#
2017-08-25 19:32:33 +00:00
# readTimeout = "5s"
2017-09-11 17:10:04 +00:00
# writeTimeout is the maximum duration before timing out writes of the response.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: "0s"
2017-09-07 10:02:03 +00:00
#
2017-08-25 19:32:33 +00:00
# writeTimeout = "5s"
# idleTimeout is the maximum duration an idle (keep-alive) connection will remain idle before closing itself.
#
# Optional
# Default: "180s"
#
# idleTimeout = "360s"
```
2017-09-11 17:10:04 +00:00
- `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 ](https://golang.org/pkg/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 ](https://golang.org/pkg/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 ](https://golang.org/pkg/time/#ParseDuration ) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
2017-09-05 13:58:03 +00:00
### Forwarding Timeouts
`forwardingTimeouts` are timeouts for requests forwarded to the backend servers.
2017-08-26 10:12:44 +00:00
```toml
2017-08-25 19:32:33 +00:00
[forwardingTimeouts]
2017-09-07 10:02:03 +00:00
# dialTimeout is the amount of time to wait until a connection to a backend server can be established.
#
2017-08-25 19:32:33 +00:00
# Optional
# Default: "30s"
2017-09-07 10:02:03 +00:00
#
2017-08-25 19:32:33 +00:00
# dialTimeout = "30s"
2017-09-07 10:02:03 +00:00
# responseHeaderTimeout is the amount of time to wait for a server's response headers after fully writing the request (including its body, if any).
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: "0s"
2017-09-07 10:02:03 +00:00
#
2017-08-25 19:32:33 +00:00
# responseHeaderTimeout = "0s"
2017-09-01 18:04:41 +00:00
```
2017-09-11 17:10:04 +00:00
- `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 ](https://golang.org/pkg/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 ](https://golang.org/pkg/time/#ParseDuration ) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
2017-09-05 13:58:03 +00:00
### Idle Timeout (deprecated)
2017-09-07 10:02:03 +00:00
Use [respondingTimeouts ](/configuration/commons/#responding-timeouts ) instead of `IdleTimeout` .
2017-09-05 13:58:03 +00:00
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 ](https://golang.org/pkg/time/#ParseDuration ) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
```toml
# IdleTimeout
2017-09-07 10:02:03 +00:00
#
2017-09-05 13:58:03 +00:00
# DEPRECATED - see [respondingTimeouts] section.
#
# Optional
# Default: "180s"
#
IdleTimeout = "360s"
```
## Override Default Configuration Template
!!! warning
For advanced users only.
Supported by all backends except: File backend, Web backend and DynamoDB backend.
```toml
[backend_name]
# Override default configuration template. For advanced users :)
#
# Optional
# Default: ""
#
filename = "custom_config_template.tpml"
# Enable debug logging of generated configuration template.
#
# Optional
# Default: false
#
debugLogGeneratedTemplate = true
```
Example:
```toml
[marathon]
filename = "my_custom_config_template.tpml"
```
The template files can be written using functions provided by:
2017-09-07 10:02:03 +00:00
- [go template ](https://golang.org/pkg/text/template/ )
2017-09-05 13:58:03 +00:00
- [sprig library ](https://masterminds.github.io/sprig/ )
Example:
```tmpl
[backends]
[backends.backend1]
url = "http://firstserver"
[backends.backend2]
url = "http://secondserver"
{{$frontends := dict "frontend1" "backend1" "frontend2" "backend2"}}
[frontends]
{{range $frontend, $backend := $frontends}}
[frontends.{{$frontend}}]
backend = "{{$backend}}"
{{end}}
```