2024-11-12 16:24:22 +01:00

73 KiB

Raw Permalink Blame History

title	description
Traefik Let's Encrypt Documentation	Learn how to configure Traefik Proxy to use an ACME provider like Let's Encrypt for automatic certificate generation. Read the technical documentation.

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. These last up to one week, and cannot be overridden.

When running Traefik in a container this file should be persisted across restarts. 
If Traefik requests new certificates each time it starts up, a crash-looping container can quickly reach Let's Encrypt's ratelimits.
To configure where certificates are stored, please take a look at the [storage](#storage) configuration.

Use Let's Encrypt staging server with the [`caServer`](#caserver) configuration option
when experimenting to avoid hitting this limit too fast.

Certificate Resolvers

Traefik requires you to define "Certificate Resolvers" in the static configuration, which are responsible for retrieving certificates from an ACME server.

Then, each "router" is configured to enable TLS, and is associated to a certificate resolver through the tls.certresolver configuration option.

Certificates are requested for domain names retrieved from the router's dynamic configuration.

You can read more about this retrieval mechanism in the following section: ACME Domain Definition.

!!! warning "Defining an ACME challenge type is a requirement for a certificate resolver to be functional."

!!! important "Defining a certificate 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:

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

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

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

Domain Definition

Certificate resolvers request certificates for a set of the domain names inferred from routers, with the following logic:

If the router has a tls.domains option set, then the certificate resolver uses the main (and optionally sans) option of tls.domains to know the domain names for this router.
If no tls.domains option is set, then the certificate resolver uses the router's rule, by checking the Host() matchers. Please note that multiple Host() matchers can be used) for specifying multiple domain names for this router.

Please note that:

When multiple domain names are inferred from a given router, only one certificate is requested with the first domain name as the main domain, and the other domains as "SANs" (Subject Alternative Name).
As ACME V2 supports "wildcard domains", any router can provide a wildcard domain name, as "main" domain or as "SAN" domain.

Please check the configuration examples below for more details.

Configuration Examples

??? example "Enabling ACME"

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

  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      email: your-email@example.com
      storage: acme.json
      httpChallenge:
        # used during the challenge
        entryPoint: web
```

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

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  email = "your-email@example.com"
  storage = "acme.json"
  [certificatesResolvers.myresolver.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"
```

```bash tab="CLI"
--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
# ...
--certificatesresolvers.myresolver.acme.email=your-email@example.com
--certificatesresolvers.myresolver.acme.storage=acme.json
# used during the challenge
--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web
```

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

??? example "Single Domain from Router's Rule Example"

* A certificate for the domain `example.com` is requested:

--8<-- "content/https/include-acme-single-domain-example.md"

??? example "Multiple Domains from Router's Rule Example"

* A certificate for the domains `example.com` (main) and `blog.example.org`
  is requested:

--8<-- "content/https/include-acme-multiple-domains-from-rule-example.md"

??? example "Multiple Domains from Router's tls.domain Example"

* A certificate for the domains `example.com` (main) and `*.example.org` (SAN)
  is requested:

--8<-- "content/https/include-acme-multiple-domains-example.md"

Automatic Renewals

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

By default, Traefik manages 90 days certificates, and starts to renew certificates 30 days before their expiry.

When using a certificate resolver that issues certificates with custom durations, one can configure the certificates' duration with the certificatesDuration option.

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

Using LetsEncrypt with Kubernetes

When using LetsEncrypt with kubernetes, there are some known caveats with both the ingress and crd providers.

!!! info "" If you intend to run multiple instances of Traefik with LetsEncrypt, please ensure you read the sections on those provider pages.

The Different ACME Challenges

!!! warning "Defining one ACME challenge is a requirement for a certificate resolver to be functional."

!!! important "Defining a certificate 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"

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

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

```bash tab="CLI"
# ...
--certificatesresolvers.myresolver.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.myresolver.acme.httpchallenge.entrypoint must be reachable by Let's Encrypt through port 80.

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

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

  websecure:
    address: ":443"

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

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

  [entryPoints.websecure]
    address = ":443"

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

```bash tab="CLI"
--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
# ...
--certificatesresolvers.myresolver.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"

```yaml tab="File (YAML)"
certificatesResolvers:
  myresolver:
    acme:
      # ...
      dnsChallenge:
        provider: digitalocean
        delayBeforeCheck: 0
    # ...
```

```toml tab="File (TOML)"
[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...
```

```bash tab="CLI"
# ...
--certificatesresolvers.myresolver.acme.dnschallenge.provider=digitalocean
--certificatesresolvers.myresolver.acme.dnschallenge.delaybeforecheck=0
# ...
```

!!! warning "CNAME support"

`CNAME` are supported (and sometimes even [encouraged](https://letsencrypt.org/2019/10/09/onboarding-your-customers-with-lets-encrypt-and-acme.html#the-advantages-of-a-cname)),
but there are a few cases where they can be [problematic](../../getting-started/faq/#why-does-lets-encrypt-wildcard-certificate-renewalgeneration-with-dns-challenge-fail).

If needed, `CNAME` support can be disabled with the following environment variable:

```bash
LEGO_DISABLE_CNAME_SUPPORT=true
```

!!! warning "Multiple DNS Challenge provider"

Multiple DNS challenge provider are not supported with Traefik, but you can use `CNAME` to handle that.
For example, if you have `example.org` (account foo) and `example.com` (account bar) you can create a CNAME on `example.org` called `_acme-challenge.example.org` pointing to `challenge.example.com`.
This way, you can obtain certificates for `example.org` with the `bar` account.

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

Many lego environment variables 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.

For complete details, refer to your provider's Additional configuration link.

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
all-inkl	`allinkl`	`ALL_INKL_LOGIN`, `ALL_INKL_PASSWORD`	Additional configuration
ArvanCloud	`arvancloud`	`ARVANCLOUD_API_KEY`	Additional configuration
Auroradns	`auroradns`	`AURORA_USER_ID`, `AURORA_KEY`, `AURORA_ENDPOINT`	Additional configuration
Autodns	`autodns`	`AUTODNS_API_USER`, `AUTODNS_API_PASSWORD`	Additional configuration
Azure (DEPRECATED)	`azure`	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_RESOURCE_GROUP`, `[AZURE_METADATA_ENDPOINT]`	Additional configuration
AzureDNS	`azuredns`	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `[AZURE_ENVIRONMENT]`, `[AZURE_PRIVATE_ZONE]`, `[AZURE_ZONE_NAME]`	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
Brandit (DEPRECATED)	`brandit`	`BRANDIT_API_USERNAME`, `BRANDIT_API_KEY`	Additional configuration
Bunny	`bunny`	`BUNNY_API_KEY`	Additional configuration
Checkdomain	`checkdomain`	`CHECKDOMAIN_TOKEN`,	Additional configuration
Civo	`civo`	`CIVO_TOKEN`	Additional configuration
Cloud.ru	`cloudru`	`CLOUDRU_SERVICE_INSTANCE_ID`, `CLOUDRU_KEY_ID`, `CLOUDRU_SECRET`	Additional configuration
CloudDNS	`clouddns`	`CLOUDDNS_CLIENT_ID`, `CLOUDDNS_EMAIL`, `CLOUDDNS_PASSWORD`	Additional configuration
Cloudflare	`cloudflare`	`CF_API_EMAIL`, `CF_API_KEY` ¹ or `CF_DNS_API_TOKEN`, `[CF_ZONE_API_TOKEN]`	Additional configuration
ClouDNS	`cloudns`	`CLOUDNS_AUTH_ID`, `CLOUDNS_AUTH_PASSWORD`	Additional configuration
CloudXNS (DEPRECATED)	`cloudxns`	`CLOUDXNS_API_KEY`, `CLOUDXNS_SECRET_KEY`	Additional configuration
ConoHa	`conoha`	`CONOHA_TENANT_ID`, `CONOHA_API_USERNAME`, `CONOHA_API_PASSWORD`	Additional configuration
Constellix	`constellix`	`CONSTELLIX_API_KEY`, `CONSTELLIX_SECRET_KEY`	Additional configuration
Core-Networks	`corenetworks`	`CORENETWORKS_LOGIN`, `CORENETWORKS_PASSWORD`	Additional configuration
CPanel and WHM	`cpanel`	`CPANEL_MODE`, `CPANEL_USERNAME`, `CPANEL_TOKEN`, `CPANEL_BASE_URL`	Additional configuration
Derak Cloud	`derak`	`DERAK_API_KEY`	Additional configuration
deSEC	`desec`	`DESEC_TOKEN`	Additional configuration
DigitalOcean	`digitalocean`	`DO_AUTH_TOKEN`	Additional configuration
DirectAdmin	`directadmin`	`DIRECTADMIN_API_URL` , `DIRECTADMIN_USERNAME`, `DIRECTADMIN_PASSWORD`	Additional configuration
DNS Made Easy	`dnsmadeeasy`	`DNSMADEEASY_API_KEY`, `DNSMADEEASY_API_SECRET`, `DNSMADEEASY_SANDBOX`	Additional configuration
dnsHome.de	`dnsHomede`	`DNSHOMEDE_CREDENTIALS`	Additional configuration
DNSimple	`dnsimple`	`DNSIMPLE_OAUTH_TOKEN`, `DNSIMPLE_BASE_URL`	Additional configuration
DNSPod	`dnspod`	`DNSPOD_API_KEY`	Additional configuration
Domain Offensive (do.de)	`dode`	`DODE_TOKEN`	Additional configuration
Domeneshop	`domeneshop`	`DOMENESHOP_API_TOKEN`, `DOMENESHOP_API_SECRET`	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
Dynu	`dynu`	`DYNU_API_KEY`	Additional configuration
EasyDNS	`easydns`	`EASYDNS_TOKEN`, `EASYDNS_KEY`	Additional configuration
EdgeDNS	`edgedns`	`AKAMAI_CLIENT_TOKEN`, `AKAMAI_CLIENT_SECRET`, `AKAMAI_ACCESS_TOKEN`	Additional configuration
Efficient IP	`efficientip`	`EFFICIENTIP_USERNAME`, `EFFICIENTIP_PASSWORD`, `EFFICIENTIP_HOSTNAME`, `EFFICIENTIP_DNS_NAME`	Additional configuration
Epik	`epik`	`EPIK_SIGNATURE`	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
Freemyip.com	`freemyip`	`FREEMYIP_TOKEN`	Additional configuration
G-Core	`gcore`	`GCORE_PERMANENT_API_TOKEN`	Additional configuration
Gandi v5	`gandiv5`	`GANDIV5_PERSONAL_ACCESS_TOKEN`	Additional configuration
Gandi	`gandi`	`GANDI_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 ² ³, [`GCE_SERVICE_ACCOUNT_FILE`]	Additional configuration
Google Domains	`googledomains`	`GOOGLE_DOMAINS_ACCESS_TOKEN`	Additional configuration
Hetzner	`hetzner`	`HETZNER_API_KEY`	Additional configuration
hosting.de	`hostingde`	`HOSTINGDE_API_KEY`, `HOSTINGDE_ZONE_NAME`	Additional configuration
Hosttech	`hosttech`	`HOSTTECH_API_KEY`	Additional configuration
http.net	`httpnet`	`HTTPNET_API_KEY`	Additional configuration
Huawei Cloud	`huaweicloud`	`HUAWEICLOUD_ACCESS_KEY_ID`, `HUAWEICLOUD_SECRET_ACCESS_KEY`, `HUAWEICLOUD_REGION`	Additional configuration
Hurricane Electric	`hurricane`	`HURRICANE_TOKENS` ⁴	Additional configuration
HyperOne	`hyperone`	`HYPERONE_PASSPORT_LOCATION`, `HYPERONE_LOCATION_ID`	Additional configuration
IBM Cloud (SoftLayer)	`ibmcloud`	`SOFTLAYER_USERNAME`, `SOFTLAYER_API_KEY`	Additional configuration
IIJ DNS Platform Service	`iijdpf`	`IIJ_DPF_API_TOKEN` , `IIJ_DPF_DPM_SERVICE_CODE`	Additional configuration
IIJ	`iij`	`IIJ_API_ACCESS_KEY`, `IIJ_API_SECRET_KEY`, `IIJ_DO_SERVICE_CODE`	Additional configuration
Infoblox	`infoblox`	`INFOBLOX_USERNAME`, `INFOBLOX_PASSWORD`, `INFOBLOX_HOST`	Additional configuration
Infomaniak	`infomaniak`	`INFOMANIAK_ACCESS_TOKEN`	Additional configuration
Internet.bs	`internetbs`	`INTERNET_BS_API_KEY`, `INTERNET_BS_PASSWORD`	Additional configuration
INWX	`inwx`	`INWX_USERNAME`, `INWX_PASSWORD`	Additional configuration
ionos	`ionos`	`IONOS_API_KEY`	Additional configuration
IPv64	`ipv64`	`IPV64_API_KEY`	Additional configuration
iwantmyname	`iwantmyname`	`IWANTMYNAME_USERNAME` , `IWANTMYNAME_PASSWORD`	Additional configuration
Joker.com	`joker`	`JOKER_API_MODE` with `JOKER_API_KEY` or `JOKER_USERNAME`, `JOKER_PASSWORD`	Additional configuration
Liara	`liara`	`LIARA_API_KEY`	Additional configuration
Lightsail	`lightsail`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `DNS_ZONE`	Additional configuration
Lima-City	`limacity`	`LIMACITY_API_KEY`	Additional configuration
Linode v4	`linode`	`LINODE_TOKEN`	Additional configuration
Liquid Web	`liquidweb`	`LIQUID_WEB_PASSWORD`, `LIQUID_WEB_USERNAME`, `LIQUID_WEB_ZONE`	Additional configuration
Loopia	`loopia`	`LOOPIA_API_PASSWORD`, `LOOPIA_API_USER`	Additional configuration
LuaDNS	`luadns`	`LUADNS_API_USERNAME`, `LUADNS_API_TOKEN`	Additional configuration
Mail-in-a-Box	`mailinabox`	`MAILINABOX_EMAIL`, `MAILINABOX_PASSWORD`, `MAILINABOX_BASE_URL`	Additional configuration
Metaname	`metaname`	`METANAME_ACCOUNT_REFERENCE`, `METANAME_API_KEY`	Additional configuration
mijn.host	`mijnhost`	`MIJNHOST_API_KEY`	Additional configuration
Mittwald	`mittwald`	`MITTWALD_TOKEN`	Additional configuration
MyDNS.jp	`mydnsjp`	`MYDNSJP_MASTER_ID`, `MYDNSJP_PASSWORD`	Additional configuration
Mythic Beasts	`mythicbeasts`	`MYTHICBEASTS_USER_NAME`, `MYTHICBEASTS_PASSWORD`	Additional configuration
name.com	`namedotcom`	`NAMECOM_USERNAME`, `NAMECOM_API_TOKEN`, `NAMECOM_SERVER`	Additional configuration
Namecheap	`namecheap`	`NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY`	Additional configuration
Namesilo	`namesilo`	`NAMESILO_API_KEY`	Additional configuration
NearlyFreeSpeech.NET	`nearlyfreespeech`	`NEARLYFREESPEECH_API_KEY`, `NEARLYFREESPEECH_LOGIN`	Additional configuration
Netcup	`netcup`	`NETCUP_CUSTOMER_NUMBER`, `NETCUP_API_KEY`, `NETCUP_API_PASSWORD`	Additional configuration
Netlify	`netlify`	`NETLIFY_TOKEN`	Additional configuration
Nicmanager	`nicmanager`	`NICMANAGER_API_EMAIL`, `NICMANAGER_API_PASSWORD`	Additional configuration
NIFCloud	`nifcloud`	`NIFCLOUD_ACCESS_KEY_ID`, `NIFCLOUD_SECRET_ACCESS_KEY`	Additional configuration
Njalla	`njalla`	`NJALLA_TOKEN`	Additional configuration
Nodion	`nodion`	`NODION_API_TOKEN`	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
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
OVH	`ovh`	`OVH_ENDPOINT`, `OVH_APPLICATION_KEY`, `OVH_APPLICATION_SECRET`, `OVH_CONSUMER_KEY`, `OVH_CLIENT_ID`, `OVH_CLIENT_SECRET`	Additional configuration
Plesk	`plesk`	`PLESK_SERVER_BASE_URL`, `PLESK_USERNAME`, `PLESK_PASSWORD`	Additional configuration
Porkbun	`porkbun`	`PORKBUN_SECRET_API_KEY`, `PORKBUN_API_KEY`	Additional configuration
PowerDNS	`pdns`	`PDNS_API_KEY`, `PDNS_API_URL`	Additional configuration
Rackspace	`rackspace`	`RACKSPACE_USER`, `RACKSPACE_API_KEY`	Additional configuration
RcodeZero	`rcodezero`	`RCODEZERO_API_TOKEN`	Additional configuration
reg.ru	`regru`	`REGRU_USERNAME`, `REGRU_PASSWORD`	Additional configuration
Regfish	`regfish`	`regfish`	Additional configuration
RFC2136	`rfc2136`	`RFC2136_TSIG_KEY`, `RFC2136_TSIG_SECRET`, `RFC2136_TSIG_ALGORITHM`, `RFC2136_NAMESERVER`	Additional configuration
RimuHosting	`rimuhosting`	`RIMUHOSTING_API_KEY`	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
Scaleway	`scaleway`	`SCW_API_TOKEN`	Additional configuration
Selectel v2	`selectelv2`	`SELECTELV2_ACCOUNT_ID`, `SELECTELV2_PASSWORD`, `SELECTELV2_PROJECT_ID`, `SELECTELV2_USERNAME`	Additional configuration
Selectel	`selectel`	`SELECTEL_API_TOKEN`	Additional configuration
SelfHost.(de/eu)	`selfhostde`	`SELFHOSTDE_USERNAME`, `SELFHOSTDE_PASSWORD`, `SELFHOSTDE_RECORDS_MAPPING`	Additional configuration
Servercow	`servercow`	`SERVERCOW_USERNAME`, `SERVERCOW_PASSWORD`	Additional configuration
Shellrent	`shellrent`	`SHELLRENT_USERNAME`, `SHELLRENT_TOKEN`	Additional configuration
Simply.com	`simply`	`SIMPLY_ACCOUNT_NAME`, `SIMPLY_API_KEY`	Additional configuration
Sonic	`sonic`	`SONIC_USER_ID`, `SONIC_API_KEY`	Additional configuration
Stackpath	`stackpath`	`STACKPATH_CLIENT_ID`, `STACKPATH_CLIENT_SECRET`, `STACKPATH_STACK_ID`	Additional configuration
Technitium	`technitium`	`TECHNITIUM_SERVER_BASE_URL`, `TECHNITIUM_API_TOKEN`	Additional configuration
Tencent Cloud DNS	`tencentcloud`	`TENCENTCLOUD_SECRET_ID`, `TENCENTCLOUD_SECRET_KEY`	Additional configuration
Timeweb Cloud	`timewebcloud`	`TIMEWEBCLOUD_AUTH_TOKEN`	Additional configuration
TransIP	`transip`	`TRANSIP_ACCOUNT_NAME`, `TRANSIP_PRIVATE_KEY_PATH`	Additional configuration
UKFast SafeDNS	`safedns`	`SAFEDNS_AUTH_TOKEN`	Additional configuration
Ultradns	`ultradns`	`ULTRADNS_USERNAME`, `ULTRADNS_PASSWORD`	Additional configuration
Variomedia	`variomedia`	`VARIOMEDIA_API_TOKEN`	Additional configuration
VegaDNS	`vegadns`	`SECRET_VEGADNS_KEY`, `SECRET_VEGADNS_SECRET`, `VEGADNS_URL`	Additional configuration
Vercel	`vercel`	`VERCEL_API_TOKEN`	Additional configuration
Versio	`versio`	`VERSIO_USERNAME`, `VERSIO_PASSWORD`	Additional configuration
VinylDNS	`vinyldns`	`VINYLDNS_ACCESS_KEY`, `VINYLDNS_SECRET_KEY`, `VINYLDNS_HOST`	Additional configuration
VK Cloud	`vkcloud`	`VK_CLOUD_PASSWORD`, `VK_CLOUD_PROJECT_ID`, `VK_CLOUD_USERNAME`	Additional configuration
Volcano Engine	`volcengine`	`VOLC_ACCESSKEY`, `VOLC_SECRETKEY`	Additional configuration
Vscale	`vscale`	`VSCALE_API_TOKEN`	Additional configuration
VULTR	`vultr`	`VULTR_API_KEY`	Additional configuration
Webnames	`webnames`	`WEBNAMES_API_KEY`	Additional configuration
Websupport	`websupport`	`WEBSUPPORT_API_KEY`, `WEBSUPPORT_SECRET`	Additional configuration
WEDOS	`wedos`	`WEDOS_USERNAME`, `WEDOS_WAPI_PASSWORD`	Additional configuration
Yandex 360	`yandex360`	`YANDEX360_OAUTH_TOKEN`, `YANDEX360_ORG_ID`	Additional configuration
Yandex Cloud	`yandexcloud`	`YANDEX_CLOUD_FOLDER_ID`, `YANDEX_CLOUD_IAM_TOKEN`	Additional configuration
Yandex	`yandex`	`YANDEX_PDD_TOKEN`	Additional configuration
Zone.ee	`zoneee`	`ZONEEE_API_USER`, `ZONEEE_API_KEY`	Additional configuration
Zonomi	`zonomi`	`ZONOMI_API_KEY`	Additional configuration
External Program	`exec`	`EXEC_PATH`	Additional configuration
HTTP request	`httpreq`	`HTTPREQ_ENDPOINT`, `HTTPREQ_MODE`, `HTTPREQ_USERNAME`, `HTTPREQ_PASSWORD` ⁵	Additional configuration
manual	`manual`	none, but you need to run Traefik interactively ⁶, turn on debug log to see instructions and press `Enter`.

`resolvers`

Use custom DNS servers to resolve the FQDN authority.

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

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

# ...
--certificatesresolvers.myresolver.acme.dnschallenge.resolvers=1.1.1.1:53,8.8.8.8:53

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

certificatesResolvers:
  myresolver:
    acme:
      # ...
      dnsChallenge:
        # ...
        delayBeforeCheck: 2s

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.dnsChallenge]
    # ...
    delayBeforeCheck = "2s"

# ...
--certificatesresolvers.myresolver.acme.dnschallenge.delayBeforeCheck=2s

`disablePropagationCheck`

Not recommended

Disable the TXT records propagation checks before notifying ACME that the DNS challenge is ready.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      dnsChallenge:
        # ...
        disablePropagationCheck: true

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.dnsChallenge]
    # ...
    disablePropagationCheck = true

# ...
--certificatesresolvers.myresolver.acme.dnschallenge.disablePropagationCheck=true

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.

External Account Binding

kid: Key identifier from External CA
hmacEncoded: HMAC key from External CA, should be in Base64 URL Encoding without padding format

certificatesResolvers:
  myresolver:
    acme:
      # ...
      eab:
        kid: abc-keyID-xyz
        hmacEncoded: abc-hmac-xyz

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.eab]
    kid = "abc-keyID-xyz"
    hmacEncoded = "abc-hmac-xyz"

# ...
--certificatesresolvers.myresolver.acme.eab.kid=abc-keyID-xyz
--certificatesresolvers.myresolver.acme.eab.hmacencoded=abc-hmac-xyz

More Configuration

`caServer`

Required, Default="https://acme-v02.api.letsencrypt.org/directory"

The CA server to use:

Let's Encrypt production server: https://acme-v02.api.letsencrypt.org/directory
Let's Encrypt staging server: https://acme-staging-v02.api.letsencrypt.org/directory

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

```yaml tab="File (YAML)"
certificatesResolvers:
  myresolver:
    acme:
      # ...
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory
      # ...
```

```toml tab="File (TOML)"
[certificatesResolvers.myresolver.acme]
  # ...
  caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  # ...
```

```bash tab="CLI"
# ...
--certificatesresolvers.myresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
# ...
```

`storage`

Required, Default="acme.json"

The storage option sets the location where your ACME certificates are saved to.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      storage: acme.json
      # ...

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

# ...
--certificatesresolvers.myresolver.acme.storage=acme.json
# ...

ACME certificates are 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 reasons, this file cannot be shared across multiple instances of Traefik.

`certificatesDuration`

Optional, Default=2160

certificatesDuration is used to calculate two durations:

Renew Period: the period before the end of the certificate duration, during which the certificate should be renewed.
Renew Interval: the interval between renew attempts.

It defaults to 2160 (90 days) to follow Let's Encrypt certificates' duration.

Certificate Duration	Renew Period	Renew Interval
>= 1 year	4 months	1 week
>= 90 days	30 days	1 day
>= 30 days	10 days	12 hours
>= 7 days	1 day	1 hour
>= 24 hours	6 hours	10 min
< 24 hours	20 min	1 min

!!! warning "Traefik cannot manage certificates with a duration lower than 1 hour."

certificatesResolvers:
  myresolver:
    acme:
      # ...
      certificatesDuration: 72
      # ...

[certificatesResolvers.myresolver.acme]
  # ...
  certificatesDuration=72
  # ...

# ...
--certificatesresolvers.myresolver.acme.certificatesduration=72
# ...

`preferredChain`

Optional, Default=""

Preferred chain to use.

If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      preferredChain: 'ISRG Root X1'
      # ...

[certificatesResolvers.myresolver.acme]
  # ...
  preferredChain = "ISRG Root X1"
  # ...

# ...
--certificatesresolvers.myresolver.acme.preferredChain=ISRG Root X1
# ...

`keyType`

Optional, Default="RSA4096"

KeyType used for generating certificate private key. Allow value 'EC256', 'EC384', 'RSA2048', 'RSA4096', 'RSA8192'.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      keyType: 'RSA4096'
      # ...

[certificatesResolvers.myresolver.acme]
  # ...
  keyType = "RSA4096"
  # ...

# ...
--certificatesresolvers.myresolver.acme.keyType=RSA4096
# ...

`caCertificates`

Optional, Default=[]

The caCertificates option specifies the paths to PEM encoded CA Certificates that can be used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      caCertificates:
        - path/certificates1.pem
        - path/certificates2.pem
      # ...

[certificatesResolvers.myresolver.acme]
  # ...
  caCertificates = [ "path/certificates1.pem", "path/certificates2.pem" ]
  # ...

# ...
--certificatesresolvers.myresolver.acme.caCertificates="path/certificates1.pem,path/certificates2.pem"
# ...

??? note "LEGO Environment Variable"

It can be defined globally by using the environment variable `LEGO_CA_CERTIFICATES`.
This environment variable is neither a fallback nor an override of the configuration option.

`caSystemCertPool`

Optional, Default=false

The caSystemCertPool option defines if the certificates pool must use a copy of the system cert pool.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      caSystemCertPool: true
      # ...

[certificatesResolvers.myresolver.acme]
  # ...
  caSystemCertPool = true
  # ...

# ...
--certificatesresolvers.myresolver.acme.caSystemCertPool=true
# ...

??? note "LEGO Environment Variable"

It can be defined globally by using the environment variable `LEGO_CA_SYSTEM_CERT_POOL`.
`LEGO_CA_SYSTEM_CERT_POOL` is ignored if `LEGO_CA_CERTIFICATES` is not set or empty.
This environment variable is neither a fallback nor an override of the configuration option.

`caServerName`

Optional, Default=""

The caServerName option specifies the CA server name that can be used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list.

certificatesResolvers:
  myresolver:
    acme:
      # ...
      caServerName: "my-server"
      # ...

[certificatesResolvers.myresolver.acme]
  # ...
  caServerName = "my-server"
  # ...

# ...
--certificatesresolvers.myresolver.acme.caServerName="my-server"
# ...

??? note "LEGO Environment Variable"

It can be defined globally by using the environment variable `LEGO_CA_SERVER_NAME`.
`LEGO_CA_SERVER_NAME` is ignored if `LEGO_CA_CERTIFICATES` is not set or empty.
This environment variable is neither a fallback nor an override of the configuration option.

Fallback

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

Previously generated ACME certificates (before downtime)
Expired ACME certificates
Provided certificates

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

{!traefik-for-business-applications.md!}

The Global API Key needs to be used, not the Origin CA Key. ↩︎
Providing credentials to your application. ↩︎
google/default.go ↩︎
As explained in the LEGO hurricane configuration, each domain or wildcard (record name) needs a token. So each update of record name must be followed by an update of the HURRICANE_TOKENS variable, and a restart of Traefik. ↩︎
More information about the HTTP message format can be found here. ↩︎
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. ↩︎

73 KiB Raw Permalink Blame History

Let's Encrypt

Certificate Resolvers

Domain Definition

Configuration Examples

Automatic Renewals

Using LetsEncrypt with Kubernetes

The Different ACME Challenges

tlsChallenge

httpChallenge

dnsChallenge

providers

resolvers

delayBeforeCheck

disablePropagationCheck

Wildcard Domains

External Account Binding

More Configuration

caServer

storage

certificatesDuration

preferredChain

keyType

caCertificates

caSystemCertPool

caServerName

Fallback

73 KiB

Raw Permalink Blame History

`tlsChallenge`

`httpChallenge`

`dnsChallenge`

`providers`

`resolvers`

`delayBeforeCheck`

`disablePropagationCheck`

`caServer`

`storage`

`certificatesDuration`

`preferredChain`

`keyType`

`caCertificates`

`caSystemCertPool`

`caServerName`