traefik/docs/content/https/acme.md

Let's Encrypt

Automatic HTTPS {: .subtitle }

You can configure Traefik to use an ACME provider (like Let's Encrypt) for automatic certificate generation.

!!! warning "Let's Encrypt and Rate Limiting" Note that Let's Encrypt API has rate limiting.

Configuration Examples

??? example "Enabling ACME"

```toml tab="File (TOML)"
[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.sample.acme]
  email = "your-email@your-domain.org"
  storage = "acme.json"
  [certificatesResolvers.sample.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"
```

```yaml tab="File (YAML)"
entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      email: your-email@your-domain.org
      storage: acme.json
      httpChallenge:
        # used during the challenge
        entryPoint: web
```

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

!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must reference it."

??? note "Configuration Reference"

There are many available options for ACME.
For a quick glance at what's possible, browse the configuration reference:

```toml tab="File (TOML)"
--8<-- "content/https/ref-acme.toml"
```

```yaml tab="File (YAML)"
--8<-- "content/https/ref-acme.yaml"
```

```bash tab="CLI"
--8<-- "content/https/ref-acme.txt"
```

Automatic Renewals

Traefik automatically tracks the expiry date of ACME certificates it generates.

If there are less than 30 days remaining before the certificate expires, Traefik will attempt to renew it automatically.

!!! info "" Certificates that are no longer used may still be renewed, as Traefik does not currently check if the certificate is being used before renewing.

The Different ACME Challenges

!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must reference it."

tlsChallenge

Use the TLS-ALPN-01 challenge to generate and renew ACME certificates by provisioning a TLS certificate.

As described on the Let's Encrypt community forum, when using the TLS-ALPN-01 challenge, Traefik must be reachable by Let's Encrypt through port 443.

??? example "Configuring the tlsChallenge"

```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.tlsChallenge]
```

```yaml tab="File (YAML)"
certificatesResolvers:
  sample:
    acme:
      # ...
      tlsChallenge: {}
```

```bash tab="CLI"
# ...
--certificatesResolvers.sample.acme.tlsChallenge=true
```

httpChallenge

Use the HTTP-01 challenge to generate and renew ACME certificates by provisioning an HTTP resource under a well-known URI.

As described on the Let's Encrypt community forum, when using the HTTP-01 challenge, certificatesResolvers.sample.acme.httpChallenge.entryPoint must be reachable by Let's Encrypt through port 80.

??? example "Using an EntryPoint Called http for the httpChallenge"

```toml tab="File (TOML)"
[entryPoints]
  [entryPoints.web]
    address = ":80"
  
  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.httpChallenge]
    entryPoint = "web"
```

```yaml tab="File (YAML)"
entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      # ...
      httpChallenge:
        entryPoint: web
```

```bash tab="CLI"
--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web
```

!!! info "" Redirection is fully compatible with the HTTP-01 challenge.

dnsChallenge

Use the DNS-01 challenge to generate and renew ACME certificates by provisioning a DNS record.

??? example "Configuring a dnsChallenge with the DigitalOcean Provider"

```toml tab="File (TOML)"
[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.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
# ...
```

!!! important
    A `provider` is mandatory.

providers

Here is a list of supported providers, that can automate the DNS verification, along with the required environment variables and their wildcard & root domain support. Do not hesitate to complete it.

Every lego environment variable can be overridden by their respective _FILE counterpart, which should have a filepath to a file that contains the secret as its value. For example, CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email could be used to provide a Cloudflare API email address as a Docker secret named traefik_cf-api-email.

Provider Name	Provider Code	Environment Variables
ACME DNS	acme-dns	ACME_DNS_API_BASE, ACME_DNS_STORAGE_PATH	Additional configuration
Alibaba Cloud	alidns	ALICLOUD_ACCESS_KEY, ALICLOUD_SECRET_KEY, ALICLOUD_REGION_ID	Additional configuration
Auroradns	auroradns	AURORA_USER_ID, AURORA_KEY, AURORA_ENDPOINT	Additional configuration
Azure	azure	AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_RESOURCE_GROUP, [AZURE_METADATA_ENDPOINT]	Additional configuration
Bindman	bindman	BINDMAN_MANAGER_ADDRESS	Additional configuration
Blue Cat	bluecat	BLUECAT_SERVER_URL, BLUECAT_USER_NAME, BLUECAT_PASSWORD, BLUECAT_CONFIG_NAME, BLUECAT_DNS_VIEW	Additional configuration
ClouDNS	cloudns	CLOUDNS_AUTH_ID, CLOUDNS_AUTH_PASSWORD	Additional configuration
Cloudflare	cloudflare	CF_API_EMAIL, CF_API_KEY or CF_DNS_API_TOKEN, [CF_ZONE_API_TOKEN] 1	Additional configuration
CloudXNS	cloudxns	CLOUDXNS_API_KEY, CLOUDXNS_SECRET_KEY	Additional configuration
ConoHa	conoha	CONOHA_TENANT_ID, CONOHA_API_USERNAME, CONOHA_API_PASSWORD	Additional configuration
DigitalOcean	digitalocean	DO_AUTH_TOKEN	Additional configuration
DNSimple	dnsimple	DNSIMPLE_OAUTH_TOKEN, DNSIMPLE_BASE_URL	Additional configuration
DNS Made Easy	dnsmadeeasy	DNSMADEEASY_API_KEY, DNSMADEEASY_API_SECRET, DNSMADEEASY_SANDBOX	Additional configuration
DNSPod	dnspod	DNSPOD_API_KEY	Additional configuration
Domain Offensive (do.de)	dode	DODE_TOKEN	Additional configuration
DreamHost	dreamhost	DREAMHOST_API_KEY	Additional configuration
Duck DNS	duckdns	DUCKDNS_TOKEN	Additional configuration
Dyn	dyn	DYN_CUSTOMER_NAME, DYN_USER_NAME, DYN_PASSWORD	Additional configuration
EasyDNS	easydns	EASYDNS_TOKEN, EASYDNS_KEY	Additional configuration
External Program	exec	EXEC_PATH	Additional configuration
Exoscale	exoscale	EXOSCALE_API_KEY, EXOSCALE_API_SECRET, EXOSCALE_ENDPOINT	Additional configuration
Fast DNS	fastdns	AKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET, AKAMAI_ACCESS_TOKEN	Additional configuration
Gandi	gandi	GANDI_API_KEY	Additional configuration
Gandi v5	gandiv5	GANDIV5_API_KEY	Additional configuration
Glesys	glesys	GLESYS_API_USER, GLESYS_API_KEY, GLESYS_DOMAIN	Additional configuration
GoDaddy	godaddy	GODADDY_API_KEY, GODADDY_API_SECRET	Additional configuration
Google Cloud DNS	gcloud	GCE_PROJECT, Application Default Credentials 2 3, [GCE_SERVICE_ACCOUNT_FILE]	Additional configuration
hosting.de	hostingde	HOSTINGDE_API_KEY, HOSTINGDE_ZONE_NAME	Additional configuration
HTTP request	httpreq	HTTPREQ_ENDPOINT, HTTPREQ_MODE, HTTPREQ_USERNAME, HTTPREQ_PASSWORD 4	Additional configuration
IIJ	iij	IIJ_API_ACCESS_KEY, IIJ_API_SECRET_KEY, IIJ_DO_SERVICE_CODE	Additional configuration
INWX	inwx	INWX_USERNAME, INWX_PASSWORD	Additional configuration
Joker.com	joker	JOKER_API_KEY or JOKER_USERNAME, JOKER_PASSWORD	Additional configuration
Lightsail	lightsail	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, DNS_ZONE	Additional configuration
Linode	linode	LINODE_API_KEY	Additional configuration
Linode v4	linodev4	LINODE_TOKEN	Additional configuration
Liquid Web	liquidweb	LIQUID_WEB_PASSWORD, LIQUID_WEB_USERNAME, LIQUID_WEB_ZONE	Additional configuration
manual	-	none, but you need to run Traefik interactively 5, turn on debug log to see instructions and press Enter.
MyDNS.jp	mydnsjp	MYDNSJP_MASTER_ID, MYDNSJP_PASSWORD	Additional configuration
Namecheap	namecheap	NAMECHEAP_API_USER, NAMECHEAP_API_KEY	Additional configuration
name.com	namedotcom	NAMECOM_USERNAME, NAMECOM_API_TOKEN, NAMECOM_SERVER	Additional configuration
Namesilo	namesilo	NAMESILO_API_KEY	Additional configuration
Netcup	netcup	NETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, NETCUP_API_PASSWORD	Additional configuration
NIFCloud	nifcloud	NIFCLOUD_ACCESS_KEY_ID, NIFCLOUD_SECRET_ACCESS_KEY	Additional configuration
Ns1	ns1	NS1_API_KEY	Additional configuration
Open Telekom Cloud	otc	OTC_DOMAIN_NAME, OTC_USER_NAME, OTC_PASSWORD, OTC_PROJECT_NAME, OTC_IDENTITY_ENDPOINT	Additional configuration
OVH	ovh	OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY	Additional configuration
Openstack Designate	designate	OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_TENANT_NAME, OS_REGION_NAME	Additional configuration
Oracle Cloud	oraclecloud	OCI_COMPARTMENT_OCID, OCI_PRIVKEY_FILE, OCI_PRIVKEY_PASS, OCI_PUBKEY_FINGERPRINT, OCI_REGION, OCI_TENANCY_OCID, OCI_USER_OCID	Additional configuration
PowerDNS	pdns	PDNS_API_KEY, PDNS_API_URL	Additional configuration
Rackspace	rackspace	RACKSPACE_USER, RACKSPACE_API_KEY	Additional configuration
RFC2136	rfc2136	RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_TSIG_ALGORITHM, RFC2136_NAMESERVER	Additional configuration
Route 53	route53	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, [AWS_REGION], [AWS_HOSTED_ZONE_ID] or a configured user/instance IAM profile.	Additional configuration
Sakura Cloud	sakuracloud	SAKURACLOUD_ACCESS_TOKEN, SAKURACLOUD_ACCESS_TOKEN_SECRET	Additional configuration
Selectel	selectel	SELECTEL_API_TOKEN	Additional configuration
Stackpath	stackpath	STACKPATH_CLIENT_ID, STACKPATH_CLIENT_SECRET, STACKPATH_STACK_ID	Additional configuration
TransIP	transip	TRANSIP_ACCOUNT_NAME, TRANSIP_PRIVATE_KEY_PATH	Additional configuration
VegaDNS	vegadns	SECRET_VEGADNS_KEY, SECRET_VEGADNS_SECRET, VEGADNS_URL	Additional configuration
Versio	versio	VERSIO_USERNAME, VERSIO_PASSWORD	Additional configuration
Vscale	vscale	VSCALE_API_TOKEN	Additional configuration
VULTR	vultr	VULTR_API_KEY	Additional configuration
Zone.ee	zoneee	ZONEEE_API_USER, ZONEEE_API_KEY	Additional configuration

!!! info "delayBeforeCheck" By default, the provider verifies the TXT record before letting ACME verify. You can delay this operation by specifying a delay (in seconds) with delayBeforeCheck (value must be greater than zero). This option is useful when internal networks block external DNS queries.

resolvers

Use custom DNS servers to resolve the FQDN authority.

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.dnsChallenge]
    # ...
    resolvers = ["1.1.1.1:53", "8.8.8.8:53"]

certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        # ...
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"

# ...
--certificatesResolvers.sample.acme.dnsChallenge.resolvers:="1.1.1.1:53,8.8.8.8:53"

Wildcard Domains

ACME V2 supports wildcard certificates. As described in Let's Encrypt's post wildcard certificates can only be generated through a DNS-01 challenge.

caServer

??? example "Using the Let's Encrypt staging server"

```toml tab="File (TOML)"
[certificatesResolvers.sample.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
      # ...
```

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

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

certificatesResolvers:
  sample:
    acme:
      # ...
      storage: acme.json
      # ...

# ...
--certificatesResolvers.sample.acme.storage=acme.json
# ...

The value can refer to some kinds of storage:

• a JSON file

In a File

ACME certificates can be stored in a JSON file that needs to have a 600 file mode .

In Docker you can mount either the JSON file, or the folder containing it:

docker run -v "/my/host/acme.json:acme.json" traefik

docker run -v "/my/host/acme:/etc/traefik/acme" traefik

!!! warning For concurrency reason, this file cannot be shared across multiple instances of Traefik. Use a key value store entry instead.

Fallback

If Let's Encrypt is not reachable, the following certificates will apply:

1. Previously generated ACME certificates (before downtime)
2. Expired ACME certificates
3. Provided certificates

!!! important For new (sub)domains which need Let's Encrypt authentication, the default Traefik certificate will be used until Traefik is restarted.

---

1. The Global API Key needs to be used, not the Origin CA Key. ↩︎

2. providing_credentials_to_your_application ↩︎

3. google/default.go ↩︎

4. more information about the HTTP message format can be found here ↩︎

5. docker stack remark: there is no way to support terminal attached to container when deploying with docker stack, so you might need to run container with docker run -it to generate certificates using manual provider. ↩︎