homelab/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Use the same case everywhere

Browse source
This commit is contained in:
Ludovic Fernandez 2019-07-01 11:30:05 +02:00 • committed by Traefiker Bot
parent f6436663eb
commit c7d336f958
179 changed files with 5118 additions and 4436 deletions
Download patch file Download diff file Expand all files Collapse all files

276
docs/content/https/acme.md
View file

@ -12,56 +12,103 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
??? example "Enabling ACME"
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
[acme] # every router with TLS enabled will now be able to use ACME for its certificates
email = "your-email@your-domain.org"
storage = "acme.json"
onHostRule = true # dynamic generation based on the Host() & HostSNI() matchers
[acme.httpChallenge]
entryPoint = "web" # used during the challenge
```
??? example "Configuring Wildcard Certificates"
```toml
```toml tab="TOML"
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
# every router with TLS enabled will now be able to use ACME for its certificates
[acme]
email = "your-email@your-domain.org"
storage = "acme.json"
# dynamic generation based on the Host() & HostSNI() matchers
onHostRule = true
[acme.httpChallenge]
# used during the challenge
entryPoint = "web"
```
```yaml tab="YAML"
entryPoints:
web:
address: ":80"
http-tls:
address: ":443"
# every router with TLS enabled will now be able to use ACME for its certificates
acme:
email: your-email@your-domain.org
storage: acme.json
# dynamic generation based on the Host() & HostSNI() matchers
onHostRule: true
httpChallenge:
# used during the challenge
entryPoint: web
```
??? example "Configuring Wildcard Certificates"
```toml tab="TOML"
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
[acme]
email = "your-email@your-domain.org"
storage = "acme.json"
[acme.dnsChallenge]
provider = "xxx"
[[acme.domains]]
main = "*.mydomain.com"
sans = ["mydomain.com"]
```
```yaml tab="YAML"
entryPoints:
web:
address: ":80"
http-tls:
address: ":443"
acme:
email: your-email@your-domain.org
storage: acme.json
dnsChallenge:
provide: xxx
domains:
- main: "*.mydomain.com"
sans:
- mydomain.com
```
??? note "Configuration Reference"
There are many available options for ACME. For a quick glance at what's possible, browse the configuration reference:
There are many available options for ACME.
For a quick glance at what's possible, browse the configuration reference:
```toml
```toml tab="TOML"
--8<-- "content/https/ref-acme.toml"
```
```yaml tab="YAML"
--8<-- "content/https/ref-acme.yaml"
```
## Automatic Renewals
Traefik automatically tracks the expiry date of ACME certificates it generates.
If there are less than 30 days remaining before the certificate expires, Traefik will attempt to rewnew it automatically.
If there are less than 30 days remaining before the certificate expires, Traefik will attempt to renew it automatically.
!!! note
Certificates that are no longer used may still be renewed, as Traefik does not currently check if the certificate is being used before renewing.
@ -77,9 +124,14 @@ when using the `TLS-ALPN-01` challenge, Traefik must be reachable by Let's Encry
??? example "Configuring the `tlsChallenge`"
```toml
```toml tab="TOML"
[acme]
[acme.tlsChallenge]
[acme.tlsChallenge]
```
```yaml tab="YAML"
acme:
tlsChallenge: {}
```
### `httpChallenge`
@ -91,11 +143,18 @@ when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reac
??? example "Using an EntryPoint Called http for the `httpChallenge`"
```toml
```toml tab="TOML"
[acme]
# ...
[acme.httpChallenge]
entryPoint = "http"
# ...
[acme.httpChallenge]
entryPoint = "http"
```
```yaml tab="YAML"
acme:
# ...
httpChallenge:
entryPoint: http
```
!!! note
@ -107,12 +166,21 @@ Use the `DNS-01` challenge to generate and renew ACME certificates by provisioni
??? example "Configuring a `dnsChallenge` with the DigitalOcean Provider"
```toml
```toml tab="TOML"
[acme]
# ...
[acme.dnsChallenge]
provider = "digitalocean"
delayBeforeCheck = 0
# ...
[acme.dnsChallenge]
provider = "digitalocean"
delayBeforeCheck = 0
# ...
```
```yaml tab="YAML"
acme:
# ...
dnsChallenge:
provider: digitalocean
delayBeforeCheck: 0
# ...
```
@ -200,12 +268,22 @@ For example, `CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email` could be used
Use custom DNS servers to resolve the FQDN authority.
```toml
```toml tab="TOML"
[acme]
# ...
[acme.dnsChallenge]
# ...
resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
# ...
[acme.dnsChallenge]
# ...
resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
```
```yaml tab="YAML"
acme:
# ...
dnsChallenge:
# ...
resolvers:
- "1.1.1.1:53"
- "8.8.8.8:53"
```
#### Wildcard Domains
@ -213,12 +291,23 @@ Use custom DNS servers to resolve the FQDN authority.
[ACME V2](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579) supports wildcard certificates.
As described in [Let's Encrypt's post](https://community.letsencrypt.org/t/staging-endpoint-for-acme-v2/49605) wildcard certificates can only be generated through a [`DNS-01` challenge](#dnschallenge).
```toml
```toml tab="TOML"
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
```
```yaml tab="YAML"
acme:
# ...
domains:
- main: "*.local1.com"
sans:
- local1.com
# ...
```
@ -240,17 +329,33 @@ 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.
```toml
```toml tab="TOML"
[acme]
# ...
[[acme.domains]]
main = "local1.com"
sans = ["test1.local1.com", "test2.local1.com"]
[[acme.domains]]
main = "local2.com"
[[acme.domains]]
main = "*.local3.com"
sans = ["local3.com", "test1.test1.local3.com"]
# ...
[[acme.domains]]
main = "local1.com"
sans = ["test1.local1.com", "test2.local1.com"]
[[acme.domains]]
main = "local2.com"
[[acme.domains]]
main = "*.local3.com"
sans = ["local3.com", "test1.test1.local3.com"]
# ...
```
```yaml tab="YAML"
acme:
# ...
domains:
- main: "local1.com"
sans:
- "test1.local1.com"
- "test2.local1.com"
- main: "local2.com"
- main: "*.local3.com"
sans:
- "local3.com"
- "test1.test1.local3.com"
# ...
```
@ -264,11 +369,18 @@ Each domain & SAN will lead to a certificate request.
??? example "Using the Let's Encrypt staging server"
```toml
```toml tab="TOML"
[acme]
# ...
caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
# ...
caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
```
```yaml tab="YAML"
acme:
# ...
caServer: https://acme-staging-v02.api.letsencrypt.org/directory
# ...
```
## `onHostRule`
@ -277,11 +389,18 @@ Enable certificate generation on [routers](../routing/routers/index.md) `Host` &
This will request a certificate from Let's Encrypt for each router with a Host rule.
```toml
```toml tab="TOML"
[acme]
# ...
onHostRule = true
# ...
# ...
onHostRule = true
# ...
```
```yaml tab="YAML"
acme:
# ...
onHostRule: true
# ...
```
!!! note "Multiple Hosts in a Rule"
@ -294,17 +413,23 @@ This will request a certificate from Let's Encrypt for each router with a Host r
The `storage` option sets the location where your ACME certificates are saved to.
```toml
```toml tab="TOML"
[acme]
# ...
storage = "acme.json"
# ...
# ...
storage = "acme.json"
# ...
```
The value can refer to two kinds of storage:
```yaml tab="YAML"
acme
# ...
storage: acme.json
# ...
```
The value can refer to some kinds of storage:
- a JSON file
- a KV store entry
### In a File
@ -323,19 +448,6 @@ docker run -v "/my/host/acme:/etc/traefik/acme" traefik
!!! warning
For concurrency reason, this file cannot be shared across multiple instances of Traefik. Use a key value store entry instead.
### In a a Key Value Store Entry
ACME certificates can be stored in a key-value store entry.
```toml
storage = "traefik/acme/account"
```
!!! note "Storage Size"
Because key-value stores have limited entry size, the certificates list is compressed _before_ it is saved.
For example, it is possible to store up to _approximately_ 100 ACME certificates in Consul.
## Fallback
If Let's Encrypt is not reachable, the following certificates will apply:

31
docs/content/https/ref-acme.toml
View file

@ -7,31 +7,11 @@
#
email = "test@traefik.io"
# File used for certificates storage.
#
# Optional (Deprecated)
#
#storageFile = "acme.json"
# File or key used for certificates storage.
#
# Required
#
storage = "acme.json"
# or `storage = "traefik/acme/account"` if using KV store.
# Deprecated, replaced by [acme.dnsChallenge].
#
# Optional.
#
# dnsProvider = "digitalocean"
# Deprecated, replaced by [acme.dnsChallenge.delayBeforeCheck].
#
# Optional
# Default: 0
#
# delayDontCheckDNS = 0
# If true, display debug log messages from the acme client library.
#
@ -47,14 +27,7 @@ storage = "acme.json"
#
# overrideCertificates = true
# Deprecated. Enable on demand certificate generation.
#
# Optional
# Default: false
#
# onDemand = true
# Enable certificate generation on frontends host rules.
# Enable certificate generation on routers host rules.
#
# Optional
# Default: false
@ -95,7 +68,7 @@ storage = "acme.json"
#
# Required
#
# entryPoint = "http"
# entryPoint = "web"
# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.

127
docs/content/https/ref-acme.yaml Normal file
View file

@ -0,0 +1,127 @@
# Enable ACME (Let's Encrypt): automatic SSL.
acme:
# Email address used for registration.
#
# Required
#
email: "test@traefik.io"
# File or key used for certificates storage.
#
# Required
#
storage: "acme.json"
# If true, display debug log messages from the acme client library.
#
# Optional
# Default: false
#
# acmeLogging: true
# If true, override certificates in key-value store when using storeconfig.
#
# Optional
# Default: false
#
# overrideCertificates: true
# Enable certificate generation on routers host rules.
#
# Optional
# Default: false
#
# onHostRule: true
# CA server to use.
# Uncomment the line to use Let's Encrypt's staging server,
# leave commented to go to prod.
#
# Optional
# Default: "https://acme-v02.api.letsencrypt.org/directory"
#
# caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
# KeyType: RSA4096
# Use a TLS-ALPN-01 ACME challenge.
#
# Optional (but recommended)
#
tlsChallenge:
# Use a HTTP-01 ACME challenge.
#
# Optional
#
# httpChallenge:
# EntryPoint to use for the HTTP-01 challenges.
#
# Required
#
# entryPoint: web
# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
# dnsChallenge:
# DNS provider used.
#
# Required
#
# provider: digitalocean
# By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
# If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
# Useful if internal networks block external DNS queries.
#
# Optional
# Default: 0
#
# delayBeforeCheck: 0
# Use following DNS servers to resolve the FQDN authority.
#
# Optional
# Default: empty
#
# resolvers
# - "1.1.1.1:53"
# - "8.8.8.8:53"
# Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
#
# NOT RECOMMENDED:
# Increase the risk of reaching Let's Encrypt's rate limits.
#
# Optional
# Default: false
#
# disablePropagationCheck: true
# Domains list.
# Only domains defined here can generate wildcard certificates.
# The certificates for these domains are negotiated at traefik startup only.
#
# domains:
# - main: "local1.com"
# sans:
# - "test1.local1.com"
# - "test2.local1.com"
# - main: "local2.com"
# - main: "*.local3.com"
# sans:
# - "local3.com"
# - "test1.test1.local3.com"

97
docs/content/https/tls.md
View file

@ -13,7 +13,7 @@ See the [Let's Encrypt](./acme.md) page.
To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the [dynamic configuration](../getting-started/configuration-overview.md), in the `[[tls.certificates]]` section:
```toml
```toml tab="TOML"
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
@ -23,6 +23,15 @@ To add / remove TLS certificates, even when Traefik is already running, their de
keyFile = "/path/to/other-domain.key"
```
```yaml tab="YAML"
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
```
!!! important "File Provider Only"
In the above example, we've used the [file provider](../providers/file.md) to handle these definitions.
@ -32,23 +41,29 @@ To add / remove TLS certificates, even when Traefik is already running, their de
In Traefik, certificates are grouped together in certificates stores, which are defined as such:
```toml
```toml tab="TOML"
[tls.stores]
[tls.stores.default]
```
```yaml tab="YAML"
tls:
stores:
default: {}
```
!!! important "Alpha restriction"
During the alpha version, any store definition other than the default one (named `default`) will be ignored,
and there is thefore only one globally available TLS store.
In the `[[tls.certificates]]` section, a list of stores can then be specified to indicate where the certificates should be stored:
In the `tls.certificates` section, a list of stores can then be specified to indicate where the certificates should be stored:
```toml
```toml tab="TOML"
[[tls.certificates]]
stores = ["default"]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
stores = ["default"]
[[tls.certificates]]
# Note that since no store is defined,
@ -57,6 +72,19 @@ In the `[[tls.certificates]]` section, a list of stores can then be specified to
keyFile = "/path/to/other-domain.key"
```
```yaml tab="YAML"
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
stores:
- default
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
```
!!! important "Alpha restriction"
During the alpha version, the `stores` list will actually be ignored and automatically set to `["default"]`.
@ -66,7 +94,7 @@ In the `[[tls.certificates]]` section, a list of stores can then be specified to
Traefik can use a default certificate for connections without a SNI, or without a matching domain.
This default certificate should be defined in a TLS store:
```toml
```toml tab="TOML"
[tls.stores]
[tls.stores.default]
[tls.stores.default.defaultCertificate]
@ -74,6 +102,15 @@ This default certificate should be defined in a TLS store:
keyFile = "path/to/cert.key"
```
```yaml tab="YAML"
tls:
stores:
default:
defaultCertificate:
certFile: path/to/cert.crt
keyFile: path/to/cert.key
```
If no default certificate is provided, Traefik generates and uses a self-signed certificate.
## TLS Options
@ -82,7 +119,7 @@ The TLS options allow one to configure some parameters of the TLS connection.
### Minimum TLS Version
```toml
```toml tab="TOML"
[tls.options]
[tls.options.default]
@ -92,6 +129,16 @@ The TLS options allow one to configure some parameters of the TLS connection.
minVersion = "VersionTLS13"
```
```yaml tab="YAML"
tls:
options:
default:
minVersion: VersionTLS12
mintls13:
minVersion: VersionTLS13
```
### Mutual Authentication
Traefik supports both optional and strict (which is the default) mutual authentication, though the `ClientCA.files` section.
@ -102,20 +149,32 @@ For clients with a certificate, the `optional` option governs the behaviour as f
- When `optional = false`, Traefik accepts connections only from clients presenting a certificate signed by a CA listed in `ClientCA.files`.
- When `optional = true`, Traefik authorizes connections from clients presenting a certificate signed by an unknown CA.
```toml
```toml tab="TOML"
[tls.options]
[tls.options.default]
[tls.options.default.ClientCA]
[tls.options.default.clientCA]
# in PEM format. each file can contain multiple CAs.
files = ["tests/clientca1.crt", "tests/clientca2.crt"]
optional = false
```
```yaml tab="YAML"
tls:
options:
default:
clientCA:
# in PEM format. each file can contain multiple CAs.
files:
- tests/clientca1.crt
- tests/clientca2.crt
optional: false
```
### Cipher Suites
See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information.
```toml
```toml tab="TOML"
[tls.options]
[tls.options.default]
cipherSuites = [
@ -124,13 +183,29 @@ See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more informat
]
```
```yaml tab="YAML"
tls:
options:
default:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
### Strict SNI Checking
With strict SNI checking, Traefik won't allow connections from clients connections
that do not specify a server_name extension.
```toml
```toml tab="TOML"
[tls.options]
[tls.options.default]
sniStrict = true
```
```yaml tab="YAML"
tls:
options:
default:
sniStrict: true
```