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

Certificate resolvers.

Browse source 
Co-authored-by: Julien Salleyron <julien.salleyron@gmail.com>
Co-authored-by: Jean-Baptiste Doumenjou <jb.doumenjou@gmail.com>
This commit is contained in:
Ludovic Fernandez 2019-07-19 11:52:04 +02:00 • committed by Traefiker Bot
parent e3627e9cba
commit f75f73f3d2
47 changed files with 1573 additions and 1249 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -11,8 +11,8 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
## Configuration Examples
??? example "Enabling ACME"
```toml tab="TOML"
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
@ -20,18 +20,15 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
[entryPoints.web-secure]
address = ":443"
# every router with TLS enabled will now be able to use ACME for its certificates
[acme]
[certificatesResolvers.sample.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"
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
@ -39,50 +36,24 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
web-secure:
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-secure]
address = ":443"
[acme]
email = "your-email@your-domain.org"
storage = "acme.json"
[acme.dnsChallenge]
provider = "xxx"
[[acme.domains]]
main = "*.mydomain.com"
sans = ["mydomain.com"]
certificatesResolvers:
sample:
acme:
email: your-email@your-domain.org
storage: acme.json
httpChallenge:
# used during the challenge
entryPoint: web
```
```yaml tab="YAML"
entryPoints:
web-secure:
address: ":443"
acme:
email: your-email@your-domain.org
storage: acme.json
dnsChallenge:
provide: xxx
domains:
- main: "*.mydomain.com"
sans:
- mydomain.com
```bash tab="CLI"
--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.email: your-email@your-domain.org
--certificatesResolvers.sample.acme.storage: acme.json
# used during the challenge
--certificatesResolvers.sample.acme.httpChallenge.entryPoint: web
```
??? note "Configuration Reference"
@ -90,13 +61,17 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
There are many available options for ACME.
For a quick glance at what's possible, browse the configuration reference:
```toml tab="TOML"
```toml tab="File (TOML)"
--8<-- "content/https/ref-acme.toml"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
--8<-- "content/https/ref-acme.yaml"
```
```bash tab="CLI"
--8<-- "content/https/ref-acme.txt"
```
## Automatic Renewals
@ -118,16 +93,25 @@ when using the `TLS-ALPN-01` challenge, Traefik must be reachable by Let's Encry
??? example "Configuring the `tlsChallenge`"
```toml tab="TOML"
[acme]
[acme.tlsChallenge]
```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
# ...
[certificatesResolvers.sample.acme.tlsChallenge]
```
```yaml tab="YAML"
acme:
tlsChallenge: {}
```yaml tab="File (YAML)"
certificatesResolvers:
sample:
acme:
# ...
tlsChallenge: {}
```
```bash tab="CLI"
# ...
--certificatesResolvers.sample.acme.tlsChallenge
```
### `httpChallenge`
Use the `HTTP-01` challenge to generate and renew ACME certificates by provisioning an HTTP resource under a well-known URI.
@ -137,7 +121,7 @@ when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reac
??? example "Using an EntryPoint Called http for the `httpChallenge`"
```toml tab="TOML"
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
@ -145,13 +129,13 @@ when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reac
[entryPoints.web-secure]
address = ":443"
[acme]
[certificatesResolvers.sample.acme]
# ...
[acme.httpChallenge]
[certificatesResolvers.sample.acme.httpChallenge]
entryPoint = "web"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
@ -159,10 +143,19 @@ when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reac
web-secure:
address: ":443"
acme:
# ...
httpChallenge:
entryPoint: web
certificatesResolvers:
sample:
acme:
# ...
httpChallenge:
entryPoint: web
```
```bash tab="CLI"
--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web
```
!!! note
@ -174,21 +167,30 @@ Use the `DNS-01` challenge to generate and renew ACME certificates by provisioni
??? example "Configuring a `dnsChallenge` with the DigitalOcean Provider"
```toml tab="TOML"
[acme]
```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
# ...
[acme.dnsChallenge]
[certificatesResolvers.sample.acme.dnsChallenge]
provider = "digitalocean"
delayBeforeCheck = 0
# ...
```
```yaml tab="YAML"
acme:
# ...
dnsChallenge:
provider: digitalocean
delayBeforeCheck: 0
```yaml tab="File (YAML)"
certificatesResolvers:
sample:
acme:
# ...
dnsChallenge:
provider: digitalocean
delayBeforeCheck: 0
# ...
```
```bash tab="CLI"
# ...
--certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean
--certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0
# ...
```
@ -238,7 +240,7 @@ For example, `CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email` could be used
| [Lightsail](https://aws.amazon.com/lightsail/) | `lightsail` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `DNS_ZONE` | [Additional configuration](https://go-acme.github.io/lego/dns/lightsail) |
| [Linode](https://www.linode.com) | `linode` | `LINODE_API_KEY` | [Additional configuration](https://go-acme.github.io/lego/dns/linode) |
| [Linode v4](https://www.linode.com) | `linodev4` | `LINODE_TOKEN` | [Additional configuration](https://go-acme.github.io/lego/dns/linodev4) |
| manual | - | none, but you need to run Traefik interactively [^4], turn on `acmeLogging` to see instructions and press <kbd>Enter</kbd>. | |
| manual | - | none, but you need to run Traefik interactively [^4], turn on debug log to see instructions and press <kbd>Enter</kbd>. | |
| [MyDNS.jp](https://www.mydns.jp/) | `mydnsjp` | `MYDNSJP_MASTER_ID`, `MYDNSJP_PASSWORD` | [Additional configuration](https://go-acme.github.io/lego/dns/mydnsjp) |
| [Namecheap](https://www.namecheap.com) | `namecheap` | `NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY` | [Additional configuration](https://go-acme.github.io/lego/dns/namecheap) |
| [name.com](https://www.name.com/) | `namedotcom` | `NAMECOM_USERNAME`, `NAMECOM_API_TOKEN`, `NAMECOM_SERVER` | [Additional configuration](https://go-acme.github.io/lego/dns/namedotcom) |
@ -276,22 +278,29 @@ 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 tab="TOML"
[acme]
```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
# ...
[acme.dnsChallenge]
[certificatesResolvers.sample.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"
```yaml tab="File (YAML)"
certificatesResolvers:
sample:
acme:
# ...
dnsChallenge:
# ...
resolvers:
- "1.1.1.1:53"
- "8.8.8.8:53"
```
```bash tab="CLI"
# ...
--certificatesResolvers.sample.acme.dnsChallenge.resolvers:="1.1.1.1:53,8.8.8.8:53"
```
#### Wildcard Domains
@ -299,140 +308,56 @@ acme:
[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 tab="TOML"
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
```
```yaml tab="YAML"
acme:
# ...
domains:
- main: "*.local1.com"
sans:
- local1.com
# ...
```
!!! note "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com`).
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](https://community.letsencrypt.org/t/wildcard-issuance-two-txt-records-for-the-same-name/54528/2) 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](https://github.com/go-acme/lego) supports some but not all DNS providers to work around this issue.
The [Supported `provider` table](#providers) indicates if they allow generating certificates for a wildcard domain and its root domain.
## Known Domains, SANs
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 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"]
# ...
```
```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"
# ...
```
!!! important
The certificates for the domains listed in `acme.domains` are negotiated at Traefik startup only.
!!! note
Wildcard certificates can only be verified through a `DNS-01` challenge.
## `caServer`
??? example "Using the Let's Encrypt staging server"
```toml tab="TOML"
[acme]
```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
# ...
caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
```
```yaml tab="YAML"
acme:
# ...
caServer: https://acme-staging-v02.api.letsencrypt.org/directory
# ...
```yaml tab="File (YAML)"
certificatesResolvers:
sample:
acme:
# ...
caServer: https://acme-staging-v02.api.letsencrypt.org/directory
# ...
```
## `onHostRule`
Enable certificate generation on [routers](../routing/routers/index.md) `Host` & `HostSNI` rules.
This will request a certificate from Let's Encrypt for each router with a Host rule.
```toml tab="TOML"
[acme]
# ...
onHostRule = true
# ...
```
```yaml tab="YAML"
acme:
# ...
onHostRule: true
# ...
```
!!! note "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`.
!!! warning
`onHostRule` option can not be used to generate wildcard certificates. Refer to [wildcard generation](#wildcard-domains) for further information.
```bash tab="CLI"
# ...
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
```
## `storage`
The `storage` option sets the location where your ACME certificates are saved to.
```toml tab="TOML"
[acme]
```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
# ...
storage = "acme.json"
# ...
```
```yaml tab="YAML"
acme
# ...
storage: acme.json
# ...
```toml tab="File (TOML)"
certificatesResolvers:
sample:
acme:
# ...
storage: acme.json
# ...
```
```bash tab="CLI"
# ...
--certificatesResolvers.sample.acme.storage=acme.json
# ...
```
The value can refer to some kinds of storage:

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

@ -1,123 +1,89 @@
# Enable ACME (Let's Encrypt): automatic SSL.
[acme]
[certificatesResolvers.sample.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)
#
[acme.tlsChallenge]
# Use a HTTP-01 ACME challenge.
#
# Optional
#
# [acme.httpChallenge]
# EntryPoint to use for the HTTP-01 challenges.
# Email address used for registration.
#
# Required
#
# entryPoint = "web"
email = "test@traefik.io"
# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
# [acme.dnsChallenge]
# DNS provider used.
# File or key used for certificates storage.
#
# Required
#
# provider = "digitalocean"
storage = "acme.json"
# 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.
# CA server to use.
# Uncomment the line to use Let's Encrypt's staging server,
# leave commented to go to prod.
#
# Optional
# Default: 0
# Default: "https://acme-v02.api.letsencrypt.org/directory"
#
# delayBeforeCheck = 0
# caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# Use following DNS servers to resolve the FQDN authority.
# KeyType to use.
#
# Optional
# Default: empty
# Default: "RSA4096"
#
# resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
# keyType = "RSA4096"
# Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
# Use a TLS-ALPN-01 ACME challenge.
#
# NOT RECOMMENDED:
# Increase the risk of reaching Let's Encrypt's rate limits.
# Optional (but recommended)
#
[certificatesResolvers.sample.acme.tlsChallenge]
# Use a HTTP-01 ACME challenge.
#
# Optional
# Default: false
#
# disablePropagationCheck = true
# [certificatesResolvers.sample.acme.httpChallenge]
# Domains list.
# Only domains defined here can generate wildcard certificates.
# The certificates for these domains are negotiated at traefik startup only.
#
# [[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"]
# 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
#
# [certificatesResolvers.sample.acme.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

89
docs/content/https/ref-acme.txt Normal file
View file

@ -0,0 +1,89 @@
# Enable ACME (Let's Encrypt): automatic SSL.
--certificatesResolvers.sample.acme
# Email address used for registration.
#
# Required
#
--certificatesResolvers.sample.acme.email="test@traefik.io"
# File or key used for certificates storage.
#
# Required
#
--certificatesResolvers.sample.acme.storage="acme.json"
# 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"
#
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
--certificatesResolvers.sample.acme.keyType=RSA4096
# Use a TLS-ALPN-01 ACME challenge.
#
# Optional (but recommended)
#
--certificatesResolvers.sample.acme.tlsChallenge
# Use a HTTP-01 ACME challenge.
#
# Optional
#
--certificatesResolvers.sample.acme.httpChallenge
# EntryPoint to use for the HTTP-01 challenges.
#
# Required
#
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web
# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
--certificatesResolvers.sample.acme.dnsChallenge
# DNS provider used.
#
# Required
#
--certificatesResolvers.sample.acme.dnsChallenge.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
#
--certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0
# Use following DNS servers to resolve the FQDN authority.
#
# Optional
# Default: empty
#
--certificatesResolvers.sample.acme.dnsChallenge.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
#
--certificatesResolvers.sample.acme.dnsChallenge.disablePropagationCheck=true

196
docs/content/https/ref-acme.yaml
View file

@ -1,127 +1,93 @@
# Enable ACME (Let's Encrypt): automatic SSL.
acme:
certificatesResolvers:
sample:
# Enable ACME (Let's Encrypt): automatic SSL.
acme:
# Email address used for registration.
#
# Required
#
email: "test@traefik.io"
# Email address used for registration.
#
# Required
#
email: "test@traefik.io"
# File or key used for certificates storage.
#
# Required
#
storage: "acme.json"
# 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
# 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"
# If true, override certificates in key-value store when using storeconfig.
#
# Optional
# Default: false
#
# overrideCertificates: true
# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
# keyType: RSA4096
# Enable certificate generation on routers host rules.
#
# Optional
# Default: false
#
# onHostRule: true
# Use a TLS-ALPN-01 ACME challenge.
#
# Optional (but recommended)
#
tlsChallenge:
# 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"
# Use a HTTP-01 ACME challenge.
#
# Optional
#
# httpChallenge:
# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
# KeyType: RSA4096
# EntryPoint to use for the HTTP-01 challenges.
#
# Required
#
# entryPoint: web
# Use a TLS-ALPN-01 ACME challenge.
#
# Optional (but recommended)
#
tlsChallenge:
# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
# dnsChallenge:
# Use a HTTP-01 ACME challenge.
#
# Optional
#
# httpChallenge:
# DNS provider used.
#
# Required
#
# provider: digitalocean
# EntryPoint to use for the HTTP-01 challenges.
#
# Required
#
# entryPoint: web
# 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 a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
# dnsChallenge:
# Use following DNS servers to resolve the FQDN authority.
#
# Optional
# Default: empty
#
# resolvers
# - "1.1.1.1:53"
# - "8.8.8.8:53"
# 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"
# 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

93
docs/content/reference/static-configuration/cli-ref.md
View file

@ -36,60 +36,6 @@ Keep access logs with status codes in the specified range.
`--accesslog.format`:
Access log format: json | common (Default: ```common```)
`--acme.acmelogging`:
Enable debug logging of ACME actions. (Default: ```false```)
`--acme.caserver`:
CA server to use. (Default: ```https://acme-v02.api.letsencrypt.org/directory```)
`--acme.dnschallenge`:
Activate DNS-01 Challenge. (Default: ```false```)
`--acme.dnschallenge.delaybeforecheck`:
Assume DNS propagates after a delay in seconds rather than finding and querying nameservers. (Default: ```0```)
`--acme.dnschallenge.disablepropagationcheck`:
Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready. [not recommended] (Default: ```false```)
`--acme.dnschallenge.provider`:
Use a DNS-01 based challenge provider rather than HTTPS.
`--acme.dnschallenge.resolvers`:
Use following DNS servers to resolve the FQDN authority.
`--acme.domains`:
The list of domains for which certificates are generated on startup. Wildcard domains only accepted with DNSChallenge.
`--acme.domains[n].main`:
Default subject name.
`--acme.domains[n].sans`:
Subject alternative names.
`--acme.email`:
Email address used for registration.
`--acme.entrypoint`:
EntryPoint to use.
`--acme.httpchallenge`:
Activate HTTP-01 Challenge. (Default: ```false```)
`--acme.httpchallenge.entrypoint`:
HTTP challenge EntryPoint
`--acme.keytype`:
KeyType used for generating certificate private key. Allow value 'EC256', 'EC384', 'RSA2048', 'RSA4096', 'RSA8192'. (Default: ```RSA4096```)
`--acme.onhostrule`:
Enable certificate generation on router Host rules. (Default: ```false```)
`--acme.storage`:
Storage to use. (Default: ```acme.json```)
`--acme.tlschallenge`:
Activate TLS-ALPN-01 Challenge. (Default: ```true```)
`--api`:
Enable api/dashboard. (Default: ```false```)
@ -111,6 +57,45 @@ Enable more detailed statistics. (Default: ```false```)
`--api.statistics.recenterrors`:
Number of recent errors logged. (Default: ```10```)
`--certificatesresolvers.<name>`:
Certificates resolvers configuration. (Default: ```false```)
`--certificatesresolvers.<name>.acme.caserver`:
CA server to use. (Default: ```https://acme-v02.api.letsencrypt.org/directory```)
`--certificatesresolvers.<name>.acme.dnschallenge`:
Activate DNS-01 Challenge. (Default: ```false```)
`--certificatesresolvers.<name>.acme.dnschallenge.delaybeforecheck`:
Assume DNS propagates after a delay in seconds rather than finding and querying nameservers. (Default: ```0```)
`--certificatesresolvers.<name>.acme.dnschallenge.disablepropagationcheck`:
Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready. [not recommended] (Default: ```false```)
`--certificatesresolvers.<name>.acme.dnschallenge.provider`:
Use a DNS-01 based challenge provider rather than HTTPS.
`--certificatesresolvers.<name>.acme.dnschallenge.resolvers`:
Use following DNS servers to resolve the FQDN authority.
`--certificatesresolvers.<name>.acme.email`:
Email address used for registration.
`--certificatesresolvers.<name>.acme.httpchallenge`:
Activate HTTP-01 Challenge. (Default: ```false```)
`--certificatesresolvers.<name>.acme.httpchallenge.entrypoint`:
HTTP challenge EntryPoint
`--certificatesresolvers.<name>.acme.keytype`:
KeyType used for generating certificate private key. Allow value 'EC256', 'EC384', 'RSA2048', 'RSA4096', 'RSA8192'. (Default: ```RSA4096```)
`--certificatesresolvers.<name>.acme.storage`:
Storage to use. (Default: ```acme.json```)
`--certificatesresolvers.<name>.acme.tlschallenge`:
Activate TLS-ALPN-01 Challenge. (Default: ```true```)
`--entrypoints.<name>`:
Entry points definition. (Default: ```false```)

93
docs/content/reference/static-configuration/env-ref.md
View file

@ -36,60 +36,6 @@ Keep access logs with status codes in the specified range.
`TRAEFIK_ACCESSLOG_FORMAT`:
Access log format: json | common (Default: ```common```)
`TRAEFIK_ACME_ACMELOGGING`:
Enable debug logging of ACME actions. (Default: ```false```)
`TRAEFIK_ACME_CASERVER`:
CA server to use. (Default: ```https://acme-v02.api.letsencrypt.org/directory```)
`TRAEFIK_ACME_DNSCHALLENGE`:
Activate DNS-01 Challenge. (Default: ```false```)
`TRAEFIK_ACME_DNSCHALLENGE_DELAYBEFORECHECK`:
Assume DNS propagates after a delay in seconds rather than finding and querying nameservers. (Default: ```0```)
`TRAEFIK_ACME_DNSCHALLENGE_DISABLEPROPAGATIONCHECK`:
Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready. [not recommended] (Default: ```false```)
`TRAEFIK_ACME_DNSCHALLENGE_PROVIDER`:
Use a DNS-01 based challenge provider rather than HTTPS.
`TRAEFIK_ACME_DNSCHALLENGE_RESOLVERS`:
Use following DNS servers to resolve the FQDN authority.
`TRAEFIK_ACME_DOMAINS`:
The list of domains for which certificates are generated on startup. Wildcard domains only accepted with DNSChallenge.
`TRAEFIK_ACME_DOMAINS[n]_MAIN`:
Default subject name.
`TRAEFIK_ACME_DOMAINS[n]_SANS`:
Subject alternative names.
`TRAEFIK_ACME_EMAIL`:
Email address used for registration.
`TRAEFIK_ACME_ENTRYPOINT`:
EntryPoint to use.
`TRAEFIK_ACME_HTTPCHALLENGE`:
Activate HTTP-01 Challenge. (Default: ```false```)
`TRAEFIK_ACME_HTTPCHALLENGE_ENTRYPOINT`:
HTTP challenge EntryPoint
`TRAEFIK_ACME_KEYTYPE`:
KeyType used for generating certificate private key. Allow value 'EC256', 'EC384', 'RSA2048', 'RSA4096', 'RSA8192'. (Default: ```RSA4096```)
`TRAEFIK_ACME_ONHOSTRULE`:
Enable certificate generation on router Host rules. (Default: ```false```)
`TRAEFIK_ACME_STORAGE`:
Storage to use. (Default: ```acme.json```)
`TRAEFIK_ACME_TLSCHALLENGE`:
Activate TLS-ALPN-01 Challenge. (Default: ```true```)
`TRAEFIK_API`:
Enable api/dashboard. (Default: ```false```)
@ -111,6 +57,45 @@ Enable more detailed statistics. (Default: ```false```)
`TRAEFIK_API_STATISTICS_RECENTERRORS`:
Number of recent errors logged. (Default: ```10```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>`:
Certificates resolvers configuration. (Default: ```false```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_CASERVER`:
CA server to use. (Default: ```https://acme-v02.api.letsencrypt.org/directory```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_DNSCHALLENGE`:
Activate DNS-01 Challenge. (Default: ```false```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_DNSCHALLENGE_DELAYBEFORECHECK`:
Assume DNS propagates after a delay in seconds rather than finding and querying nameservers. (Default: ```0```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_DNSCHALLENGE_DISABLEPROPAGATIONCHECK`:
Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready. [not recommended] (Default: ```false```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_DNSCHALLENGE_PROVIDER`:
Use a DNS-01 based challenge provider rather than HTTPS.
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_DNSCHALLENGE_RESOLVERS`:
Use following DNS servers to resolve the FQDN authority.
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_EMAIL`:
Email address used for registration.
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_HTTPCHALLENGE`:
Activate HTTP-01 Challenge. (Default: ```false```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_HTTPCHALLENGE_ENTRYPOINT`:
HTTP challenge EntryPoint
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_KEYTYPE`:
KeyType used for generating certificate private key. Allow value 'EC256', 'EC384', 'RSA2048', 'RSA4096', 'RSA8192'. (Default: ```RSA4096```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_STORAGE`:
Storage to use. (Default: ```acme.json```)
`TRAEFIK_CERTIFICATESRESOLVERS_<NAME>_ACME_TLSCHALLENGE`:
Activate TLS-ALPN-01 Challenge. (Default: ```true```)
`TRAEFIK_ENTRYPOINTS_<NAME>`:
Entry points definition. (Default: ```false```)

2
docs/content/reference/static-configuration/file.toml
View file

@ -221,12 +221,10 @@
[acme]
email = "foobar"
acmeLogging = true
caServer = "foobar"
storage = "foobar"
entryPoint = "foobar"
keyType = "foobar"
onHostRule = true
[acme.dnsChallenge]
provider = "foobar"
delayBeforeCheck = 42

2
docs/content/reference/static-configuration/file.yaml
View file

@ -230,12 +230,10 @@ hostResolver:
resolvDepth: 42
acme:
email: foobar
acmeLogging: true
caServer: foobar
storage: foobar
entryPoint: foobar
keyType: foobar
onHostRule: true
dnsChallenge:
provider: foobar
delayBeforeCheck: 42

130
docs/content/routing/routers/index.md
View file

@ -325,9 +325,9 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
service: service-id
```
#### `Options`
#### `options`
The `Options` field enables fine-grained control of the TLS parameters.
The `options` field enables fine-grained control of the TLS parameters.
It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied only if a `Host` rule is defined.
!!! note "Server Name Association"
@ -384,13 +384,13 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
[http.routers.routerfoo]
rule = "Host(`snitest.com`) && Path(`/foo`)"
[http.routers.routerfoo.tls]
options="foo"
options = "foo"
[http.routers]
[http.routers.routerbar]
rule = "Host(`snitest.com`) && Path(`/bar`)"
[http.routers.routerbar.tls]
options="bar"
options = "bar"
```
```yaml tab="YAML"
@ -409,6 +409,76 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
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.
```toml tab="TOML"
[http.routers]
[http.routers.routerfoo]
rule = "Host(`snitest.com`) && Path(`/foo`)"
[http.routers.routerfoo.tls]
certResolver = "foo"
```
```yaml tab="YAML"
http:
routers:
routerfoo:
rule: "Host(`snitest.com`) && Path(`/foo`)"
tls:
certResolver: foo
```
!!! note "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.
```toml tab="TOML"
[http.routers]
[http.routers.routerbar]
rule = "Host(`snitest.com`) && Path(`/bar`)"
[http.routers.routerbar.tls]
certResolver = "bar"
[[http.routers.routerbar.tls.domains]]
main = "snitest.com"
sans = "*.snitest.com"
```
```yaml tab="YAML"
http:
routers:
routerbar:
rule: "Host(`snitest.com`) && Path(`/bar`)"
tls:
certResolver: "bar"
domains:
- main: "snitest.com"
sans: "*.snitest.com"
```
[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](./../../https/acme.md#dnschallenge).
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](https://community.letsencrypt.org/t/wildcard-issuance-two-txt-records-for-the-same-name/54528/2) 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](https://github.com/go-acme/lego) supports some but not all DNS providers to work around this issue.
The [Supported `provider` table](./../../https/acme.md#providers) 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.
!!! note "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com`).
## Configuring TCP Routers
### General
@ -593,9 +663,9 @@ Services are the target for the router.
In the current version, with [ACME](../../https/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section.
#### `Options`
#### `options`
The `Options` field enables fine-grained control of the TLS parameters.
The `options` field enables fine-grained control of the TLS parameters.
It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied only if a `HostSNI` rule is defined.
??? example "Configuring the tls options"
@ -636,3 +706,51 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
- "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
- "TLS_RSA_WITH_AES_256_GCM_SHA384"
```
#### `certResolver`
See [`certResolver` for HTTP router](./index.md#certresolver) for more information.
```toml tab="TOML"
[tcp.routers]
[tcp.routers.routerfoo]
rule = "HostSNI(`snitest.com`)"
[tcp.routers.routerfoo.tls]
certResolver = "foo"
```
```yaml tab="YAML"
tcp:
routers:
routerfoo:
rule: "HostSNI(`snitest.com`)"
tls:
certResolver: foo
```
#### `domains`
See [`domains` for HTTP router](./index.md#domains) for more information.
```toml tab="TOML"
[tcp.routers]
[tcp.routers.routerbar]
rule = "HostSNI(`snitest.com`)"
[tcp.routers.routerbar.tls]
certResolver = "bar"
[[tcp.routers.routerbar.tls.domains]]
main = "snitest.com"
sans = "*.snitest.com"
```
```yaml tab="YAML"
tcp:
routers:
routerbar:
rule: "HostSNI(`snitest.com`)"
tls:
certResolver: "bar"
domains:
- main: "snitest.com"
sans: "*.snitest.com"
```

13
docs/content/user-guides/crd-acme/03-deployments.yml
View file

@ -33,16 +33,13 @@ spec:
- --entrypoints.web.Address=:8000
- --entrypoints.websecure.Address=:4443
- --providers.kubernetescrd
- --acme
- --acme.acmelogging
- --acme.tlschallenge
- --acme.onhostrule
- --acme.email=foo@you.com
- --acme.entrypoint=websecure
- --acme.storage=acme.json
- --certificatesresolvers.default.acme.tlschallenge
- --certificatesresolvers.default.acme.email=foo@you.com
- --certificatesresolvers.default.acme.entrypoint=websecure
- --certificatesresolvers.default.acme.storage=acme.json
# Please note that this is the staging Let's Encrypt server.
# Once you get things working, you should remove that whole line altogether.
- --acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
- --certificatesresolvers.default.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
ports:
- name: web
containerPort: 8000

4
docs/content/user-guides/crd-acme/04-ingressroutes.yml
View file

@ -26,5 +26,5 @@ spec:
services:
- name: whoami
port: 80
# Please note the use of an empty TLS object to enable TLS with Let's Encrypt.
tls: {}
tls:
certResolver: default