10 KiB
ACME (Let's Encrypt) configuration
See also Let's Encrypt examples and Docker & Let's Encrypt user guide.
Configuration
# Sample entrypoint configuration when using ACME.
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
# Enable ACME (Let's Encrypt): automatic SSL.
[acme]
# Email address used for registration.
#
# Required
#
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.
# Entrypoint to proxy acme challenge/apply certificates to.
# WARNING, must point to an entrypoint on port 443
#
# Required
#
entryPoint = "https"
# Use a DNS based acme challenge rather than external HTTPS access
#
#
# Optional
#
# dnsProvider = "digitalocean"
# By default, the dnsProvider will verify the TXT DNS challenge record before letting ACME verify.
# If delayDontCheckDNS is greater than zero, avoid this & instead just wait so many seconds.
# Useful if internal networks block external DNS queries.
#
# Optional
#
# delayDontCheckDNS = 0
# If true, display debug log messages from the acme client library.
#
# Optional
#
# acmeLogging = true
# Enable on demand certificate. (Deprecated)
#
# Optional
#
# onDemand = true
# Enable certificate generation on frontends Host rules.
#
# Optional
#
# onHostRule = true
# CA server to use.
# - Uncomment the line to run on the staging let's encrypt server.
# - Leave comment to go to prod.
#
# Optional
#
# caServer = "https://acme-staging.api.letsencrypt.org/directory"
# Domains list.
#
# [[acme.domains]]
# main = "local1.com"
# sans = ["test1.local1.com", "test2.local1.com"]
# [[acme.domains]]
# main = "local2.com"
# sans = ["test1.local2.com", "test2.local2.com"]
# [[acme.domains]]
# main = "local3.com"
# [[acme.domains]]
# main = "local4.com"
!!! note ACME entryPoint has to be relied to the port 443, otherwise ACME Challenges can not be done. It's a Let's Encrypt limitation as described on the community forum.
storage
[acme]
# ...
storage = "acme.json"
# ...
File or key used for certificates storage.
WARNING If you use Træfik in Docker, you have 2 options:
- create a file on your host and mount it as a volume:
storage = "acme.json"
docker run -v "/my/host/acme.json:acme.json" traefik
- mount the folder containing the file as a volume
storage = "/etc/traefik/acme/acme.json"
docker run -v "/my/host/acme:/etc/traefik/acme" traefik
!!! note
storage replaces storageFile which is deprecated.
!!! note
During Træfik configuration migration from a configuration file to a KV store (thanks to storeconfig subcommand as described here), if ACME certificates have to be migrated too, use both storageFile and storage.
storageFile will contain the path to the acme.json file to migrate.
storage will contain the key where the certificates will be stored.
dnsProvider
[acme]
# ...
dnsProvider = "digitalocean"
# ...
Use a DNS based acme challenge rather than external HTTPS access, e.g. for a firewalled server.
Select the provider that matches the DNS domain that will host the challenge TXT record, and provide environment variables to enable setting it:
| Provider Name | Provider code | Configuration |
|---|---|---|
| Auroradns | auroradns |
AURORA_USER_ID, AURORA_KEY, AURORA_ENDPOINT |
| Azure | azure |
AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_RESOURCE_GROUP |
| Cloudflare | cloudflare |
CLOUDFLARE_EMAIL, CLOUDFLARE_API_KEY - The Cloudflare Global API Key needs to be used and not the Origin CA Key |
| DigitalOcean | digitalocean |
DO_AUTH_TOKEN |
| DNSimple | dnsimple |
DNSIMPLE_OAUTH_TOKEN, DNSIMPLE_BASE_URL |
| DNS Made Easy | dnsmadeeasy |
DNSMADEEASY_API_KEY, DNSMADEEASY_API_SECRET, DNSMADEEASY_SANDBOX |
| DNSPod | dnspod |
DNSPOD_API_KEY |
| Dyn | dyn |
DYN_CUSTOMER_NAME, DYN_USER_NAME, DYN_PASSWORD |
| Exoscale | exoscale |
EXOSCALE_API_KEY, EXOSCALE_API_SECRET, EXOSCALE_ENDPOINT |
| Gandi | gandi |
GANDI_API_KEY |
| GoDaddy | godaddy |
GODADDY_API_KEY, GODADDY_API_SECRET |
| Google Cloud DNS | gcloud |
GCE_PROJECT, GCE_SERVICE_ACCOUNT_FILE |
| Linode | linode |
LINODE_API_KEY |
| manual | - | none, but run Træfik interactively & turn on acmeLogging to see instructions & press Enter. |
| Namecheap | namecheap |
NAMECHEAP_API_USER, NAMECHEAP_API_KEY |
| Ns1 | ns1 |
NS1_API_KEY |
| Open Telekom Cloud | otc |
OTC_DOMAIN_NAME, OTC_USER_NAME, OTC_PASSWORD, OTC_PROJECT_NAME, OTC_IDENTITY_ENDPOINT |
| OVH | ovh |
OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY |
| PowerDNS | pdns |
PDNS_API_KEY, PDNS_API_URL |
| Rackspace | rackspace |
RACKSPACE_USER, RACKSPACE_API_KEY |
| RFC2136 | rfc2136 |
RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_TSIG_ALGORITHM, RFC2136_NAMESERVER |
| Route 53 | route53 |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_HOSTED_ZONE_ID or configured user/instance IAM profile. |
| VULTR | vultr |
VULTR_API_KEY |
delayDontCheckDNS
[acme]
# ...
delayDontCheckDNS = 0
# ...
By default, the dnsProvider will verify the TXT DNS challenge record before letting ACME verify.
If delayDontCheckDNS is greater than zero, avoid this & instead just wait so many seconds.
Useful if internal networks block external DNS queries.
onDemand (Deprecated)
[acme]
# ...
onDemand = true
# ...
Enable on demand certificate.
This will request a certificate from Let's Encrypt during the first TLS handshake for a hostname that does not yet have a certificate.
!!! warning TLS handshakes will be slow when requesting a hostname certificate for the first time, this can lead to DoS attacks.
!!! warning Take note that Let's Encrypt have rate limiting.
!!! warning This option is deprecated.
onHostRule
[acme]
# ...
onHostRule = true
# ...
Enable certificate generation on frontends Host rules.
This will request a certificate from Let's Encrypt for each frontend with a Host rule.
For example, a rule Host:test1.traefik.io,test2.traefik.io will request a certificate with main domain test1.traefik.io and SAN test2.traefik.io.
caServer
[acme]
# ...
caServer = "https://acme-staging.api.letsencrypt.org/directory"
# ...
CA server to use.
- Uncomment the line to run on the staging Let's Encrypt server.
- Leave comment to go to prod.
domains
[acme]
# ...
[[acme.domains]]
main = "local1.com"
sans = ["test1.local1.com", "test2.local1.com"]
[[acme.domains]]
main = "local2.com"
sans = ["test1.local2.com", "test2.local2.com"]
[[acme.domains]]
main = "local3.com"
[[acme.domains]]
main = "local4.com"
# ...
You can provide SANs (alternative domains) to each main domain. All domains must have A/AAAA records pointing to Træfik.
!!! warning Take note that Let's Encrypt have rate limiting.
Each domain & SANs will lead to a certificate request.