Co-authored-by: Julien Salleyron <julien.salleyron@gmail.com> Co-authored-by: Jean-Baptiste Doumenjou <jb.doumenjou@gmail.com>
26 KiB
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"
[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
```
??? 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.
!!! note 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
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
```
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, 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
```
!!! note
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 |
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 - The Global API Key needs to be used, not the Origin CA Key |
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 |
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 1 2, [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 3 |
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 |
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 |
manual | - | none, but you need to run Traefik interactively 4, 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 |
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 |
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 |
!!! note "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:
- Previously generated ACME certificates (before downtime)
- Expired ACME certificates
- Provided certificates
!!! note For new (sub)domains which need Let's Encrypt authentication, the default Traefik certificate will be used until Traefik is restarted.