homelab/traefik
1
0
Fork 0
Code Activity

Enhance documentation.

Browse source
This commit is contained in:
Ludovic Fernandez 2017-09-05 15:58:03 +02:00 • committed by Traefiker
parent 732d73dd43
commit b0a0e16136
21 changed files with 676 additions and 434 deletions
Download patch file Download diff file Expand all files Collapse all files

344
docs/configuration/commons.md
View file

@ -3,10 +3,6 @@
## Main Section
```toml
################################################################
# Global configuration
################################################################
# 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.
@ -43,21 +39,6 @@
#
# ProvidersThrottleDuration = "2s"
# IdleTimeout
#
# DEPRECATED - see [respondingTimeouts] section. 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.
#
# Optional
# Default: "180s"
#
# IdleTimeout = "360s"
# 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
@ -70,6 +51,7 @@
# 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.
#
# Optional
# Default: false
#
@ -91,7 +73,8 @@
# defaultEntryPoints = ["http", "https"]
```
### Constraints
## Constraints
In a micro-service architecture, with a central service discovery, setting constraints limits Træfik scope to a smaller number of routes.
@ -113,57 +96,63 @@ Supported filters:
- `tag`
### Simple
```toml
# Constraints definition
#
# Optional
#
# Simple matching constraint
# constraints = ["tag==api"]
constraints = ["tag==api"]
# Simple mismatching constraint
# constraints = ["tag!=api"]
constraints = ["tag!=api"]
# Globbing
# constraints = ["tag==us-*"]
constraints = ["tag==us-*"]
```
### Multiple
```toml
# Multiple constraints
# - "tag==" must match with at least one tag
# - "tag!=" must match with none of tags
# constraints = ["tag!=us-*", "tag!=asia-*"]
# Backend-specific constraint
# [consulCatalog]
# endpoint = 127.0.0.1:8500
# constraints = ["tag==api"]
# [consulCatalog]
# endpoint = 127.0.0.1:8500
# constraints = ["tag==api", "tag!=v*-beta"]
constraints = ["tag!=us-*", "tag!=asia-*"]
```
## Traefik Logs
### Backend-specific
```toml
# Backend-specific constraint
[consulCatalog]
endpoint = "127.0.0.1:8500"
constraints = ["tag==api"]
[marathon]
endpoint = "127.0.0.1:8800"
constraints = ["tag==api", "tag!=v*-beta"]
```
## Logs Definition
### Traefik logs
```toml
# Traefik logs file
# If not defined, logs to stdout
#
# Optional
#
# traefikLogsFile = "log/traefik.log"
traefikLogsFile = "log/traefik.log"
# Log level
#
# Optional
# Default: "ERROR"
#
# Accepted values, in order of severity: "DEBUG", "INFO", "WARN", "ERROR", "FATAL", "PANIC"
# Messages at and above the selected level will be logged.
#
# logLevel = "ERROR"
logLevel = "ERROR"
```
## Access Log Definition
### Access Logs
Access logs are written when `[accessLog]` is defined.
By default it will write to stdout and produce logs in the textual Common Log Format (CLF), extended with additional fields.
@ -176,14 +165,14 @@ To enable access logs using the default settings just add the `[accessLog]` entr
To write the logs into a logfile specify the `filePath`.
```toml
[accessLog]
filePath = "/path/to/access.log"
filePath = "/path/to/access.log"
```
To write JSON format logs, specify `json` as the format:
```toml
[accessLog]
filePath = "/path/to/access.log"
format = "json"
filePath = "/path/to/access.log"
format = "json"
```
Deprecated way (before 1.4):
@ -191,12 +180,11 @@ Deprecated way (before 1.4):
# Access logs file
#
# DEPRECATED - see [accessLog] lower down
# Optional
#
accessLogsFile = "log/access.log"
```
## Log Rotation
### Log Rotation
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`.
@ -239,166 +227,10 @@ 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`.
## Entry Points Definition
```toml
# Entrypoints definition
#
# Default:
# [entryPoints]
# [entryPoints.http]
# address = ":80"
#
[entryPoints]
[entryPoints.http]
address = ":80"
```
### Redirect HTTP to HTTPS
```toml
# To redirect an http entrypoint to an https entrypoint (with SNI support):
#
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.redirect]
entryPoint = "https"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[[entryPoints.https.tls.certificates]]
CertFile = "integration/fixtures/https/snitest.com.cert"
KeyFile = "integration/fixtures/https/snitest.com.key"
[[entryPoints.https.tls.certificates]]
CertFile = "integration/fixtures/https/snitest.org.cert"
KeyFile = "integration/fixtures/https/snitest.org.key"
```
### Rewriting URL
```toml
# To redirect an entrypoint rewriting the URL:
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.redirect]
regex = "^http://localhost/(.*)"
replacement = "http://mydomain/$1"
```
### TLS Mutual Authentication
```toml
# Only accept clients that present a certificate signed by a specified
# Certificate Authority (CA)
# ClientCAFiles can be configured with multiple CA:s in the same file or
# use multiple files containing one or several CA:s. The CA:s has to be in PEM format.
# All clients will be required to present a valid cert.
# The requirement will apply to all server certs in the entrypoint
# In the example below both snitest.com and snitest.org will require client certs
#
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
ClientCAFiles = ["tests/clientca1.crt", "tests/clientca2.crt"]
[[entryPoints.https.tls.certificates]]
CertFile = "integration/fixtures/https/snitest.com.cert"
KeyFile = "integration/fixtures/https/snitest.com.key"
[[entryPoints.https.tls.certificates]]
CertFile = "integration/fixtures/https/snitest.org.cert"
KeyFile = "integration/fixtures/https/snitest.org.key"
```
### Basic & Digest Authentication
```toml
# To enable basic auth on an entrypoint
#
# with 2 user/pass: test:test and test2:test2
# Passwords can be encoded in MD5, SHA1 and BCrypt: you can use htpasswd to generate those ones.
# Users can be specified directly in the toml file, or indirectly by referencing an external file;
# if both are provided, the two are merged, with external file contents having precedence.
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.auth.basic]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
usersFile = "/path/to/.htpasswd"
```
```toml
# To enable digest auth on an entrypoint
#
# with 2 user/realm/pass: test:traefik:test and test2:traefik:test2
# You can use htdigest to generate those ones
# Users can be specified directly in the toml file, or indirectly by referencing an external file;
# if both are provided, the two are merged, with external file contents having precedence
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.auth.basic]
users = ["test:traefik:a2688e031edb4be6a3797f3882655c05 ", "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"]
usersFile = "/path/to/.htdigest"
```
### Specify Minimum TLS Version
```toml
# To specify an https entrypoint with a minimum TLS version,
# and specifying an array of cipher suites (from crypto/tls):
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
MinVersion = "VersionTLS12"
CipherSuites = ["TLS_RSA_WITH_AES_256_GCM_SHA384"]
[[entryPoints.https.tls.certificates]]
CertFile = "integration/fixtures/https/snitest.com.cert"
KeyFile = "integration/fixtures/https/snitest.com.key"
[[entryPoints.https.tls.certificates]]
CertFile = "integration/fixtures/https/snitest.org.cert"
KeyFile = "integration/fixtures/https/snitest.org.key"
```
### Compression
```toml
# To enable compression support using gzip format:
[entryPoints]
[entryPoints.http]
address = ":80"
compress = true
```
### Whitelisting
```toml
# To enable IP whitelisting at the entrypoint level:
[entryPoints]
[entryPoints.http]
address = ":80"
whiteListSourceRange = ["127.0.0.1/32"]
```
### ProxyProtocol Support
```toml
# To enable ProxyProtocol support (https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt):
[entryPoints]
[entryPoints.http]
address = ":80"
proxyprotocol = true
```
## Retry Configuration
```toml
# Enable retry sending request if network error
#
# Optional
#
[retry]
# Number of attempts
@ -409,13 +241,11 @@ The configured status code ranges are inclusive; that is, in the above example,
# attempts = 3
```
## Health Check Configuration
```toml
# Enable custom health check options.
#
# Optional
#
[healthcheck]
# Set the default health check interval. Will only be effective if health check
@ -431,13 +261,14 @@ The configured status code ranges are inclusive; that is, in the above example,
# interval = "30s"
```
## Responding Timeouts
## Timeouts
### Responding Timeouts
`respondingTimeouts` are timeouts for incoming requests to the Traefik instance.
```toml
# respondingTimeouts are timeouts for incoming requests to the Traefik instance.
#
# Optional
#
[respondingTimeouts]
# readTimeout is the maximum duration for reading the entire request, including the body.
@ -470,16 +301,13 @@ The configured status code ranges are inclusive; that is, in the above example,
# Default: "180s"
#
# idleTimeout = "360s"
```
## Forwarding Timeouts
### Forwarding Timeouts
`forwardingTimeouts` are timeouts for requests forwarded to the backend servers.
```toml
# forwardingTimeouts are timeouts for requests forwarded to the backend servers.
#
# Optional
#
[forwardingTimeouts]
# dialTimeout is the amount of time to wait until a connection to a backend server can be established.
@ -503,3 +331,79 @@ The configured status code ranges are inclusive; that is, in the above example,
# responseHeaderTimeout = "0s"
```
### Idle Timeout (deprecated)
Use [respondingTimeouts](/configuration/commons/#responding-timeouts) 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](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
```toml
# IdleTimeout
#
# 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:
- [go template](https://golang.org/pkg/text/template/)
- [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}}
```