traefik/docs/configuration/acme.md

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.