2018-06-05 08:36:03 +00:00
# ACME (Let's Encrypt) Configuration
2017-09-11 17:10:04 +00:00
2018-06-05 08:36:03 +00:00
See [Let's Encrypt examples ](/user-guide/examples/#lets-encrypt-support ) and [Docker & Let's Encrypt user guide ](/user-guide/docker-and-lets-encrypt ) as well.
2017-09-11 17:10:04 +00:00
## Configuration
2017-08-25 19:32:33 +00:00
```toml
2017-09-11 17:10:04 +00:00
# Sample entrypoint configuration when using ACME.
2017-08-25 19:32:33 +00:00
[entryPoints]
2018-01-15 15:04:05 +00:00
[entryPoints.http]
address = ":80"
2017-08-25 19:32:33 +00:00
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
2018-01-15 15:04:05 +00:00
```
2017-08-25 19:32:33 +00:00
2018-01-15 15:04:05 +00:00
```toml
2017-09-11 17:10:04 +00:00
# Enable ACME (Let's Encrypt): automatic SSL.
2017-08-25 19:32:33 +00:00
[acme]
2017-09-11 17:10:04 +00:00
# Email address used for registration.
2017-08-25 19:32:33 +00:00
#
# Required
#
email = "test@traefik.io"
2017-12-20 13:40:07 +00:00
# File used for certificates storage.
#
# Optional (Deprecated)
#
#storageFile = "acme.json"
2017-08-25 19:32:33 +00:00
# File or key used for certificates storage.
#
# Required
#
2017-09-11 17:10:04 +00:00
storage = "acme.json"
# or `storage = "traefik/acme/account"` if using KV store.
2017-08-25 19:32:33 +00:00
2018-01-15 15:04:05 +00:00
# Entrypoint to proxy acme apply certificates to.
2017-08-25 19:32:33 +00:00
#
# Required
#
entryPoint = "https"
2018-03-06 13:50:03 +00:00
# Deprecated, replaced by [acme.dnsChallenge].
2017-09-11 17:10:04 +00:00
#
2018-03-06 13:50:03 +00:00
# Optional.
2017-08-25 19:32:33 +00:00
#
# dnsProvider = "digitalocean"
2018-03-06 13:50:03 +00:00
# Deprecated, replaced by [acme.dnsChallenge.delayBeforeCheck].
2017-08-25 19:32:33 +00:00
#
2018-03-06 13:50:03 +00:00
# Optional
2018-01-15 15:04:05 +00:00
# Default: 0
2017-08-25 19:32:33 +00:00
#
# delayDontCheckDNS = 0
2017-09-11 17:10:04 +00:00
# If true, display debug log messages from the acme client library.
2017-08-25 19:32:33 +00:00
#
# Optional
2018-01-15 15:04:05 +00:00
# Default: false
2017-08-25 19:32:33 +00:00
#
# acmeLogging = true
2018-05-17 10:32:03 +00:00
# If true, override certificates in key-value store when using storeconfig.
#
# Optional
# Default: false
#
# overrideCertificates = true
2018-06-05 08:36:03 +00:00
# Deprecated. Enable on demand certificate generation.
2017-08-25 19:32:33 +00:00
#
2018-06-05 08:36:03 +00:00
# Optional
2018-01-15 15:04:05 +00:00
# Default: false
2017-08-25 19:32:33 +00:00
#
# onDemand = true
2018-06-05 08:36:03 +00:00
# Enable certificate generation on frontends host rules.
2017-08-25 19:32:33 +00:00
#
# Optional
2018-01-15 15:04:05 +00:00
# Default: false
2017-08-25 19:32:33 +00:00
#
2017-09-11 17:10:04 +00:00
# onHostRule = true
2017-08-25 19:32:33 +00:00
2017-09-11 17:10:04 +00:00
# CA server to use.
2018-06-05 08:36:03 +00:00
# Uncomment the line to use Let's Encrypt's staging server,
# leave commented to go to prod.
2017-08-25 19:32:33 +00:00
#
# Optional
2018-03-26 12:12:03 +00:00
# Default: "https://acme-v02.api.letsencrypt.org/directory"
2017-08-25 19:32:33 +00:00
#
2018-03-26 12:12:03 +00:00
# caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
2017-08-25 19:32:33 +00:00
2018-05-16 09:44:03 +00:00
# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
# KeyType = "RSA4096"
2018-08-13 06:46:02 +00:00
# Use a TLS-ALPN-01 ACME challenge.
2017-09-11 17:10:04 +00:00
#
2018-08-13 06:46:02 +00:00
# Optional (but recommended)
#
[acme.tlsChallenge]
2018-01-15 15:04:05 +00:00
2018-06-05 08:36:03 +00:00
# Use a HTTP-01 ACME challenge.
2018-01-15 15:04:05 +00:00
#
2018-08-13 06:46:02 +00:00
# Optional
2018-01-15 15:04:05 +00:00
#
2018-08-13 06:46:02 +00:00
# [acme.httpChallenge]
2018-01-15 15:04:05 +00:00
2018-03-06 13:50:03 +00:00
# EntryPoint to use for the HTTP-01 challenges.
2018-01-15 15:04:05 +00:00
#
# Required
#
2018-08-13 06:46:02 +00:00
# entryPoint = "http"
2018-02-12 17:10:05 +00:00
2018-06-05 08:36:03 +00:00
# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
2018-01-15 15:04:05 +00:00
#
# Optional
#
# [acme.dnsChallenge]
2018-06-05 08:36:03 +00:00
# DNS provider used.
2018-01-15 15:04:05 +00:00
#
# Required
#
# provider = "digitalocean"
# By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
2018-06-05 08:36:03 +00:00
# If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
2018-01-15 15:04:05 +00:00
# Useful if internal networks block external DNS queries.
#
# Optional
# Default: 0
#
# delayBeforeCheck = 0
2018-08-13 06:46:02 +00:00
2018-10-25 15:38:04 +00:00
# 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
2018-08-13 06:46:02 +00:00
# Domains list.
# Only domains defined here can generate wildcard certificates.
2018-10-17 14:30:04 +00:00
# The certificates for these domains are negotiated at traefik startup only.
2018-08-13 06:46:02 +00:00
#
# [[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"]
2017-08-25 19:32:33 +00:00
```
2018-02-16 09:32:03 +00:00
2018-06-05 08:36:03 +00:00
### `caServer`
2018-02-05 17:20:04 +00:00
2018-06-05 08:36:03 +00:00
The CA server to use.
2018-02-05 17:20:04 +00:00
2018-06-05 08:36:03 +00:00
This example shows the usage of Let's Encrypt's staging server:
2018-02-16 09:32:03 +00:00
2018-06-05 08:36:03 +00:00
```toml
[acme]
# ...
caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
```
2018-02-05 17:20:04 +00:00
2018-07-03 10:44:04 +00:00
### ACME Challenge
2018-08-13 06:46:02 +00:00
#### `tlsChallenge`
2018-07-03 10:44:04 +00:00
Use the `TLS-ALPN-01` challenge to generate and renew ACME certificates by provisioning a TLS certificate.
```toml
[acme]
# ...
entryPoint = "https"
[acme.tlsChallenge]
```
2018-10-25 14:50:05 +00:00
!!! note
If the `TLS-ALPN-01` challenge is used, `acme.entryPoint` has to be reachable by Let's Encrypt through port 443.
This is a Let's Encrypt limitation as described on the [community forum ](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72 ).
2018-07-03 10:44:04 +00:00
#### `httpChallenge`
Use the `HTTP-01` challenge to generate and renew ACME certificates by provisioning a HTTP resource under a well-known URI.
Redirection is fully compatible with the `HTTP-01` challenge.
```toml
[acme]
# ...
entryPoint = "https"
[acme.httpChallenge]
entryPoint = "http"
```
!!! note
If the `HTTP-01` challenge is used, `acme.httpChallenge.entryPoint` has to be defined and reachable by Let's Encrypt through port 80.
This is a Let's Encrypt limitation as described on the [community forum ](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72 ).
##### `entryPoint`
Specify the entryPoint to use during the challenges.
```toml
defaultEntryPoints = ["http", "https"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
# ...
[acme]
# ...
entryPoint = "https"
[acme.httpChallenge]
entryPoint = "http"
```
!!! note
`acme.httpChallenge.entryPoint` has to be reachable through port 80. It's a Let's Encrypt limitation as described on the [community forum ](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72 ).
#### `dnsChallenge`
2018-02-05 17:20:04 +00:00
2018-06-05 08:36:03 +00:00
Use the `DNS-01` challenge to generate and renew ACME certificates by provisioning a DNS record.
2017-09-11 17:10:04 +00:00
```toml
[acme]
# ...
2018-06-05 08:36:03 +00:00
[acme.dnsChallenge]
provider = "digitalocean"
delayBeforeCheck = 0
2017-09-11 17:10:04 +00:00
# ...
```
2018-07-03 10:44:04 +00:00
##### `delayBeforeCheck`
2018-02-16 09:32:03 +00:00
2018-06-05 08:36:03 +00:00
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.
2018-02-09 09:38:03 +00:00
2018-06-05 08:36:03 +00:00
Useful if internal networks block external DNS queries.
2018-02-09 09:38:03 +00:00
!!! note
2018-06-05 08:36:03 +00:00
A `provider` is mandatory.
2018-02-09 09:38:03 +00:00
2018-07-03 10:44:04 +00:00
##### `provider`
2018-02-09 09:38:03 +00:00
2018-06-05 08:36:03 +00:00
Here is a list of supported `provider` s, that can automate the DNS verification, along with the required environment variables and their [wildcard & root domain support ](/configuration/acme/#wildcard-domains ) for each. Do not hesitate to complete it.
2018-10-23 09:18:02 +00:00
| Provider Name | Provider Code | Environment Variables | Wildcard & Root Domain Support |
|--------------------------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
2018-11-19 15:40:03 +00:00
| [ACME DNS ](https://github.com/joohoi/acme-dns ) | `acme-dns` | `ACME_DNS_API_BASE` , `ACME_DNS_STORAGE_PATH` | Not tested yet |
2018-10-23 09:18:02 +00:00
| [Alibaba Cloud ](https://www.vultr.com ) | `alidns` | `ALICLOUD_ACCESS_KEY` , `ALICLOUD_SECRET_KEY` , `ALICLOUD_REGION_ID` | Not tested yet |
| [Auroradns ](https://www.pcextreme.com/aurora/dns ) | `auroradns` | `AURORA_USER_ID` , `AURORA_KEY` , `AURORA_ENDPOINT` | Not tested yet |
| [Azure ](https://azure.microsoft.com/services/dns/ ) | `azure` | `AZURE_CLIENT_ID` , `AZURE_CLIENT_SECRET` , `AZURE_SUBSCRIPTION_ID` , `AZURE_TENANT_ID` , `AZURE_RESOURCE_GROUP` , `[AZURE_METADATA_ENDPOINT]` | Not tested yet |
| [Blue Cat ](https://www.bluecatnetworks.com/ ) | `bluecat` | `BLUECAT_SERVER_URL` , `BLUECAT_USER_NAME` , `BLUECAT_PASSWORD` , `BLUECAT_CONFIG_NAME` , `BLUECAT_DNS_VIEW` | Not tested yet |
| [Cloudflare ](https://www.cloudflare.com ) | `cloudflare` | `CF_API_EMAIL` , `CF_API_KEY` - The `Global API Key` needs to be used, not the `Origin CA Key` | YES |
| [CloudXNS ](https://www.cloudxns.net ) | `cloudxns` | `CLOUDXNS_API_KEY` , `CLOUDXNS_SECRET_KEY` | Not tested yet |
2018-11-19 15:40:03 +00:00
| [ConoHa ](https://www.conoha.jp ) | `conoha` | `CONOHA_TENANT_ID` , `CONOHA_API_USERNAME` , `CONOHA_API_PASSWORD` | YES |
2018-10-23 09:18:02 +00:00
| [DigitalOcean ](https://www.digitalocean.com ) | `digitalocean` | `DO_AUTH_TOKEN` | YES |
| [DNSimple ](https://dnsimple.com ) | `dnsimple` | `DNSIMPLE_OAUTH_TOKEN` , `DNSIMPLE_BASE_URL` | Not tested yet |
| [DNS Made Easy ](https://dnsmadeeasy.com ) | `dnsmadeeasy` | `DNSMADEEASY_API_KEY` , `DNSMADEEASY_API_SECRET` , `DNSMADEEASY_SANDBOX` | Not tested yet |
2018-11-19 15:40:03 +00:00
| [DNSPod ](https://www.dnspod.com/ ) | `dnspod` | `DNSPOD_API_KEY` | Not tested yet |
2018-10-23 09:18:02 +00:00
| [DreamHost ](https://www.dreamhost.com/ ) | `dreamhost` | `DREAMHOST_API_KEY` | YES |
| [Duck DNS ](https://www.duckdns.org/ ) | `duckdns` | `DUCKDNS_TOKEN` | No |
| [Dyn ](https://dyn.com ) | `dyn` | `DYN_CUSTOMER_NAME` , `DYN_USER_NAME` , `DYN_PASSWORD` | Not tested yet |
2018-11-19 15:40:03 +00:00
| External Program | `exec` | `EXEC_PATH` | YES |
2018-10-29 13:20:03 +00:00
| [Exoscale ](https://www.exoscale.com ) | `exoscale` | `EXOSCALE_API_KEY` , `EXOSCALE_API_SECRET` , `EXOSCALE_ENDPOINT` | YES |
2018-10-23 09:18:02 +00:00
| [Fast DNS ](https://www.akamai.com/ ) | `fastdns` | `AKAMAI_CLIENT_TOKEN` , `AKAMAI_CLIENT_SECRET` , `AKAMAI_ACCESS_TOKEN` | Not tested yet |
| [Gandi ](https://www.gandi.net ) | `gandi` | `GANDI_API_KEY` | Not tested yet |
| [Gandi v5 ](http://doc.livedns.gandi.net ) | `gandiv5` | `GANDIV5_API_KEY` | YES |
| [Glesys ](https://glesys.com/ ) | `glesys` | `GLESYS_API_USER` , `GLESYS_API_KEY` , `GLESYS_DOMAIN` | Not tested yet |
| [GoDaddy ](https://godaddy.com/domains ) | `godaddy` | `GODADDY_API_KEY` , `GODADDY_API_SECRET` | Not tested yet |
| [Google Cloud DNS ](https://cloud.google.com/dns/docs/ ) | `gcloud` | `GCE_PROJECT` , `GCE_SERVICE_ACCOUNT_FILE` | YES |
| [hosting.de ](https://www.hosting.de ) | `hostingde` | `HOSTINGDE_API_KEY` , `HOSTINGDE_ZONE_NAME` | Not tested yet |
2019-01-04 16:24:04 +00:00
| HTTP request | `httpreq` | `HTTPREQ_ENDPOINT` , `HTTPREQ_MODE` , `HTTPREQ_USERNAME` , `HTTPREQ_PASSWORD` (1) | YES |
2018-10-23 09:18:02 +00:00
| [IIJ ](https://www.iij.ad.jp/ ) | `iij` | `IIJ_API_ACCESS_KEY` , `IIJ_API_SECRET_KEY` , `IIJ_DO_SERVICE_CODE` | Not tested yet |
2018-11-19 15:40:03 +00:00
| [INWX ](https://www.inwx.de/en ) | `inwx` | `INWX_USERNAME` , `INWX_PASSWORD` | YES |
2018-10-23 09:18:02 +00:00
| [Lightsail ](https://aws.amazon.com/lightsail/ ) | `lightsail` | `AWS_ACCESS_KEY_ID` , `AWS_SECRET_ACCESS_KEY` , `DNS_ZONE` | Not tested yet |
| [Linode ](https://www.linode.com ) | `linode` | `LINODE_API_KEY` | Not tested yet |
| [Linode v4 ](https://www.linode.com ) | `linodev4` | `LINODE_TOKEN` | Not tested yet |
| manual | - | none, but you need to run Traefik interactively, turn on `acmeLogging` to see instructions and press < kbd > Enter</ kbd > . | YES |
2018-11-19 15:40:03 +00:00
| [MyDNS.jp ](https://www.mydns.jp/ ) | `mydnsjp` | `MYDNSJP_MASTER_ID` , `MYDNSJP_PASSWORD` | YES |
2018-10-23 09:18:02 +00:00
| [Namecheap ](https://www.namecheap.com ) | `namecheap` | `NAMECHEAP_API_USER` , `NAMECHEAP_API_KEY` | YES |
| [name.com ](https://www.name.com/ ) | `namedotcom` | `NAMECOM_USERNAME` , `NAMECOM_API_TOKEN` , `NAMECOM_SERVER` | Not tested yet |
| [Netcup ](https://www.netcup.eu/ ) | `netcup` | `NETCUP_CUSTOMER_NUMBER` , `NETCUP_API_KEY` , `NETCUP_API_PASSWORD` | Not tested yet |
| [NIFCloud ](https://cloud.nifty.com/service/dns.htm ) | `nifcloud` | `NIFCLOUD_ACCESS_KEY_ID` , `NIFCLOUD_SECRET_ACCESS_KEY` | Not tested yet |
| [Ns1 ](https://ns1.com/ ) | `ns1` | `NS1_API_KEY` | Not tested yet |
| [Open Telekom Cloud ](https://cloud.telekom.de ) | `otc` | `OTC_DOMAIN_NAME` , `OTC_USER_NAME` , `OTC_PASSWORD` , `OTC_PROJECT_NAME` , `OTC_IDENTITY_ENDPOINT` | Not tested yet |
| [OVH ](https://www.ovh.com ) | `ovh` | `OVH_ENDPOINT` , `OVH_APPLICATION_KEY` , `OVH_APPLICATION_SECRET` , `OVH_CONSUMER_KEY` | YES |
| [PowerDNS ](https://www.powerdns.com ) | `pdns` | `PDNS_API_KEY` , `PDNS_API_URL` | Not tested yet |
| [Rackspace ](https://www.rackspace.com/cloud/dns ) | `rackspace` | `RACKSPACE_USER` , `RACKSPACE_API_KEY` | Not tested yet |
| [RFC2136 ](https://tools.ietf.org/html/rfc2136 ) | `rfc2136` | `RFC2136_TSIG_KEY` , `RFC2136_TSIG_SECRET` , `RFC2136_TSIG_ALGORITHM` , `RFC2136_NAMESERVER` | Not tested yet |
| [Route 53 ](https://aws.amazon.com/route53/ ) | `route53` | `AWS_ACCESS_KEY_ID` , `AWS_SECRET_ACCESS_KEY` , `[AWS_REGION]` , `[AWS_HOSTED_ZONE_ID]` or a configured user/instance IAM profile. | YES |
| [Sakura Cloud ](https://cloud.sakura.ad.jp/ ) | `sakuracloud` | `SAKURACLOUD_ACCESS_TOKEN` , `SAKURACLOUD_ACCESS_TOKEN_SECRET` | Not tested yet |
2018-11-19 15:40:03 +00:00
| [Selectel ](https://selectel.ru/en/ ) | `selectel` | `SELECTEL_API_TOKEN` | YES |
2018-10-23 09:18:02 +00:00
| [Stackpath ](https://www.stackpath.com/ ) | `stackpath` | `STACKPATH_CLIENT_ID` , `STACKPATH_CLIENT_SECRET` , `STACKPATH_STACK_ID` | Not tested yet |
2018-11-19 15:40:03 +00:00
| [TransIP ](https://www.transip.nl/ ) | `transip` | `TRANSIP_ACCOUNT_NAME` , `TRANSIP_PRIVATE_KEY_PATH` | YES |
2018-10-23 09:18:02 +00:00
| [VegaDNS ](https://github.com/shupp/VegaDNS-API ) | `vegadns` | `SECRET_VEGADNS_KEY` , `SECRET_VEGADNS_SECRET` , `VEGADNS_URL` | Not tested yet |
2018-11-19 15:40:03 +00:00
| [Vscale ](https://vscale.io/ ) | `vscale` | `VSCALE_API_TOKEN` | YES |
2018-10-23 09:18:02 +00:00
| [VULTR ](https://www.vultr.com ) | `vultr` | `VULTR_API_KEY` | Not tested yet |
2018-07-03 10:44:04 +00:00
2019-01-04 16:24:04 +00:00
- (1): more information about the HTTP message format can be found [here ](https://github.com/xenolf/lego/blob/master/providers/dns/httpreq/readme.md )
2018-10-25 15:38:04 +00:00
#### `resolvers`
Use custom DNS servers to resolve the FQDN authority.
2018-07-03 10:44:04 +00:00
2019-01-07 17:30:06 +00:00
```toml
[acme]
# ...
[acme.dnsChallenge]
# ...
resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
```
2018-06-05 08:36:03 +00:00
### `domains`
2018-02-09 09:38:03 +00:00
2018-06-05 08:36:03 +00:00
You can provide SANs (alternative domains) to each main domain.
2018-10-17 14:24:04 +00:00
All domains must have A/AAAA records pointing to Traefik.
2018-06-05 08:36:03 +00:00
Each domain & SAN will lead to a certificate request.
2017-09-11 17:10:04 +00:00
2018-10-17 14:30:04 +00:00
!!! note
The certificates for the domains listed in `acme.domains` are negotiated at traefik startup only.
2017-09-11 17:10:04 +00:00
```toml
2018-06-05 08:36:03 +00:00
[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"]
# ...
2017-09-11 17:10:04 +00:00
```
2018-02-09 09:38:03 +00:00
!!! warning
2018-06-05 08:36:03 +00:00
Take note that Let's Encrypt applies [rate limiting ](https://letsencrypt.org/docs/rate-limits ).
2017-12-20 13:40:07 +00:00
2018-06-05 08:36:03 +00:00
!!! note
Wildcard certificates can only be verified through a `DNS-01` challenge.
2017-12-20 13:40:07 +00:00
2018-06-05 08:36:03 +00:00
#### Wildcard Domains
[ACME V2 ](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579 ) allows wildcard certificate support.
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 ](/configuration/acme/#dnschallenge ).
2018-02-09 09:38:03 +00:00
```toml
2018-06-05 08:36:03 +00:00
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
2018-02-09 09:38:03 +00:00
```
2018-06-05 08:36:03 +00:00
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com` ).
Due to ACME limitation it is not possible to define wildcards in SANs (alternative domains). Thus, the wildcard domain has to be defined as a main domain.
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.
2018-10-30 11:34:00 +00:00
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 certain time (TTL) and this TTL can be superior to the challenge timeout making the `DNS-01` challenge fail.
2018-10-17 14:24:04 +00:00
The Traefik ACME client library [LEGO ](https://github.com/xenolf/lego ) supports some but not all DNS providers to work around this issue.
2018-06-05 08:36:03 +00:00
The [`provider` table ](/configuration/acme/#provider ) indicates if they allow generating certificates for a wildcard domain and its root domain.
2018-01-15 15:04:05 +00:00
2017-12-20 13:40:07 +00:00
### `onDemand` (Deprecated)
2017-09-11 17:10:04 +00:00
2018-02-09 09:38:03 +00:00
!!! danger "DEPRECATED"
2018-01-15 15:04:05 +00:00
This option is deprecated.
2017-09-11 17:10:04 +00:00
```toml
[acme]
# ...
onDemand = true
# ...
```
2018-06-05 08:36:03 +00:00
Enable on demand certificate generation.
2017-09-11 17:10:04 +00:00
2018-06-05 08:36:03 +00:00
This will request certificates from Let's Encrypt during the first TLS handshake for host names that do not yet have certificates.
2017-09-11 17:10:04 +00:00
!!! warning
2018-06-05 08:36:03 +00:00
TLS handshakes are slow when requesting a host name certificate for the first time. This can lead to DoS attacks!
2018-02-12 17:10:05 +00:00
2017-09-11 17:10:04 +00:00
!!! warning
2018-06-05 08:36:03 +00:00
Take note that Let's Encrypt applies [rate limiting ](https://letsencrypt.org/docs/rate-limits ).
2017-12-20 13:40:07 +00:00
2017-09-11 17:10:04 +00:00
### `onHostRule`
```toml
[acme]
# ...
onHostRule = true
# ...
```
2018-06-05 08:36:03 +00:00
Enable certificate generation on frontend `Host` rules (for frontends wired to the `acme.entryPoint` ).
2017-09-11 17:10:04 +00:00
This will request a certificate from Let's Encrypt for each frontend with a Host rule.
2018-06-05 08:36:03 +00:00
For example, the rule `Host:test1.traefik.io,test2.traefik.io` will request a certificate with main domain `test1.traefik.io` and SAN `test2.traefik.io` .
2017-09-11 17:10:04 +00:00
2018-03-26 12:12:03 +00:00
!!! warning
`onHostRule` option can not be used to generate wildcard certificates.
2018-07-12 16:26:03 +00:00
Refer to [wildcard generation ](/configuration/acme/#wildcard-domains ) for further information.
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
### `storage`
2017-09-11 17:10:04 +00:00
2018-06-05 08:36:03 +00:00
The `storage` option sets the location where your ACME certificates are saved to.
2017-09-11 17:10:04 +00:00
```toml
[acme]
# ...
2018-06-05 08:36:03 +00:00
storage = "acme.json"
2017-09-11 17:10:04 +00:00
# ...
```
2018-06-05 08:36:03 +00:00
The value can refer to two kinds of storage:
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
- a JSON file
- a KV store entry
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
!!! danger "DEPRECATED"
`storage` replaces `storageFile` which is deprecated.
2018-01-15 15:04:05 +00:00
2018-06-05 08:36:03 +00:00
!!! note
During migration to a KV store use both `storageFile` and `storage` to migrate ACME certificates too. See [`storeconfig` subcommand ](/user-guide/kv-config/#store-configuration-in-key-value-store ) for further information.
2018-01-15 15:04:05 +00:00
2018-06-05 08:36:03 +00:00
#### As a File
2018-01-15 15:04:05 +00:00
2018-06-05 08:36:03 +00:00
ACME certificates can be stored in a JSON file that needs to have file mode `600` .
2018-01-15 15:04:05 +00:00
2018-06-05 08:36:03 +00:00
In Docker you can either mount the JSON file or the folder containing it:
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
```bash
docker run -v "/my/host/acme.json:acme.json" traefik
```
```bash
docker run -v "/my/host/acme:/etc/traefik/acme" traefik
```
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
!!! warning
2018-10-17 14:24:04 +00:00
This file cannot be shared across multiple instances of Traefik at the same time. Please use a [KV Store entry ](/configuration/acme/#as-a-key-value-store-entry ) instead.
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
#### As a Key Value Store Entry
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
ACME certificates can be stored in a KV Store entry. This kind of storage is **mandatory in cluster mode** .
2018-03-26 12:12:03 +00:00
```toml
2018-06-05 08:36:03 +00:00
storage = "traefik/acme/account"
2018-03-26 12:12:03 +00:00
```
2018-06-05 08:36:03 +00:00
Because KV stores (like Consul) have limited entry size the certificates list is compressed before it is saved as KV store entry.
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
!!! note
It is possible to store up to approximately 100 ACME certificates in Consul.
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
#### ACME v2 Migration
2018-03-26 12:12:03 +00:00
2018-06-05 08:36:03 +00:00
During migration from ACME v1 to ACME v2, using a storage file, a backup of the original file is created in the same place as the latter (with a `.bak` extension).
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
For example: if `acme.storage` 's value is `/etc/traefik/acme/acme.json` , the backup file will be `/etc/traefik/acme/acme.json.bak` .
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
!!! note
2018-10-17 14:24:04 +00:00
When Traefik is launched in a container, the storage file's parent directory needs to be mounted to be able to access the backup file on the host.
Otherwise the backup file will be deleted when the container is stopped. Traefik will only generate it once!
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
### `dnsProvider` (Deprecated)
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
!!! danger "DEPRECATED"
This option is deprecated. Please use [dnsChallenge.provider ](/configuration/acme/#provider ) instead.
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
### `delayDontCheckDNS` (Deprecated)
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
!!! danger "DEPRECATED"
This option is deprecated. Please use [dnsChallenge.delayBeforeCheck ](/configuration/acme/#dnschallenge ) instead.
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
## Fallbacks
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
If Let's Encrypt is not reachable, these certificates will be used:
2018-04-11 15:16:07 +00:00
2018-06-05 08:36:03 +00:00
1. ACME certificates already generated before downtime
1. Expired ACME certificates
1. Provided certificates
2018-04-16 17:34:04 +00:00
!!! note
2018-10-17 14:24:04 +00:00
For new (sub)domains which need Let's Encrypt authentification, the default Traefik certificate will be used until Traefik is restarted.
