ACME (Let's Encrypt) configuration¶

Configuration¶

# Sample entrypoint configuration when using ACME.
[entryPoints]
  [entryPoints.http]
  address = ":80"
  [entryPoints.https]
  address = ":443"
    [entryPoints.https.tls]

# Enable ACME (Let's Encrypt): automatic SSL.
[acme]

# Email address used for registration.
#
# Required
#
email = "[email protected]"

# 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 apply certificates to.
# WARNING, if the TLS-SNI-01 challenge is used, it must point to an entrypoint on port 443
#
# Required
#
entryPoint = "https"

# Use a DNS-01 acme challenge rather than TLS-SNI-01 challenge
#
# Optional (Deprecated, replaced by [acme.dnsChallenge])
#
# 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 (Deprecated, replaced by [acme.dnsChallenge])
# Default: 0
#
# delayDontCheckDNS = 0

# If true, display debug log messages from the acme client library.
#
# Optional
# Default: false
#
# acmeLogging = true

# Enable on demand certificate generation.
#
# Optional (Deprecated)
# Default: false
#
# onDemand = true

# Enable certificate generation on frontends Host rules.
#
# Optional
# Default: false
#
# 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
# Default: "https://acme-v01.api.letsencrypt.org/directory"
#
# 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"

# Use a HTTP-01 acme challenge rather than TLS-SNI-01 challenge
#
# Optional but recommend
#
[acme.httpChallenge]

  # EntryPoint to use for the challenges.
  #
  # Required
  #
  entryPoint = "http"

# Use a DNS-01 acme challenge rather than TLS-SNI-01 challenge
#
# Optional
#
# [acme.dnsChallenge]

  # 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, avoid this & instead just wait so many seconds.
  # Useful if internal networks block external DNS queries.
  #
  # Optional
  # Default: 0
  #
  # delayBeforeCheck = 0

Note

Even if TLS-SNI-01 challenge is disabled for the moment, it stays the by default ACME Challenge in Træfik. If TLS-SNI-01 challenge is not re-enabled in the future, it we will be removed from Træfik.

Note

If TLS-SNI-01 challenge is used, acme.entryPoint has to be reachable by Let's Encrypt through the port 443. If HTTP-01 challenge is used, acme.httpChallenge.entryPoint has to be defined and reachable by Let's Encrypt through the port 80. These are Let's Encrypt limitations as described on the community forum.

Let's Encrypt downtime¶

Let's Encrypt functionality will be limited until Træfik is restarted.

If Let's Encrypt is not reachable, these certificates will be used :

ACME certificates already generated before downtime
Expired ACME certificates
Provided certificates

Note

Default Træfik certificate will be used instead of ACME certificates for new (sub)domains (which need Let's Encrypt challenge).

`storage`¶

[acme]
# ...
storage = "acme.json"
# ...

The storage option sets where are stored your ACME certificates.

There are two kind of storage :

a JSON file,
a KV store entry.

DEPRECATED

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.

Store data in a file¶

ACME certificates can be stored in a JSON file which with the 600 right mode.

There are two ways to store ACME certificates in a file from Docker:

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

Warning

This file cannot be shared per many instances of Træfik at the same time. If you have to use Træfik cluster mode, please use a KV Store entry.

Store data in a KV store entry¶

ACME certificates can be stored in a KV Store entry.

storage = "traefik/acme/account"

This kind of storage is mandatory in cluster mode.

Because KV stores (like Consul) have limited entries size, the certificates list is compressed before to be set in a KV store entry.

Note

It's possible to store up to approximately 100 ACME certificates in Consul.

`acme.httpChallenge`¶

Use HTTP-01 challenge to generate/renew ACME certificates.

The redirection is fully compatible with the HTTP-01 challenge. You can use redirection with HTTP-01 challenge without problem.

[acme]
# ...
entryPoint = "https"
[acme.httpChallenge]
  entryPoint = "http"

`entryPoint`¶

Specify the entryPoint to use during the challenges.

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 by Let's Encrypt through the port 80. It's a Let's Encrypt limitation as described on the community forum.

`acme.dnsChallenge`¶

Use DNS-01 challenge to generate/renew ACME certificates.

[acme]
# ...
[acme.dnsChallenge]
  provider = "digitalocean"
  delayBeforeCheck = 0
# ...

`provider`¶

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`

`delayBeforeCheck`¶

By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
If delayBeforeCheck is greater than zero, avoid this & instead just wait so many seconds.

Useful if internal networks block external DNS queries.

Note

This field has no sense if a provider is not defined.

`onDemand` (Deprecated)¶

DEPRECATED

This option is deprecated.

[acme]
# ...
onDemand = true
# ...

Enable on demand certificate.

This will request a certificate from Let's Encrypt during the first TLS handshake for a host name that does not yet have a certificate.

Warning

TLS handshakes will be slow when requesting a host name certificate for the first time, this can lead to DoS attacks.

Warning

Take note that Let's Encrypt have rate limiting.

`onHostRule`¶

[acme]
# ...
onHostRule = true
# ...

Enable certificate generation on frontends Host rules (for frontends wired on the acme.entryPoint).

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.

`acme.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.

`dnsProvider` (Deprecated)¶

DEPRECATED

This option is deprecated, use dnsChallenge.provider instead.

`delayDontCheckDNS` (Deprecated)¶

DEPRECATED

This option is deprecated, use dnsChallenge.delayBeforeCheck instead.

ACME (Let's Encrypt) configuration¶

Configuration¶

Let's Encrypt downtime¶

storage¶

Store data in a file¶

Store data in a KV store entry¶

acme.httpChallenge¶

entryPoint¶

acme.dnsChallenge¶

provider¶

delayBeforeCheck¶

onDemand (Deprecated)¶

onHostRule¶

caServer¶

acme.domains¶

dnsProvider (Deprecated)¶

delayDontCheckDNS (Deprecated)¶

`storage`¶

`acme.httpChallenge`¶

`entryPoint`¶

`acme.dnsChallenge`¶

`provider`¶

`delayBeforeCheck`¶

`onDemand` (Deprecated)¶

`onHostRule`¶

`caServer`¶

`acme.domains`¶

`dnsProvider` (Deprecated)¶

`delayDontCheckDNS` (Deprecated)¶