24 KiB
ACME
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
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
[acme] # every router with TLS enabled will now be able to use ACME for its certificates
email = "your-email@your-domain.org"
storage = "acme.json"
onHostRule = true # dynamic generation based on the Host() & HostSNI() matchers
[acme.httpChallenge]
entryPoint = "web" # used during the challenge
```
??? example "Configuring Wildcard Certificates"
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
[acme]
email = "your-email@your-domain.org"
storage = "acme.json"
[acme.dnsChallenge]
provider = "xxx"
[[acme.domains]]
main = "*.mydomain.com"
sans = ["mydomain.com"]
```
??? note "Configuration Reference"
There are many available options for ACME. For a quick glance at what's possible, browse the configuration reference:
```toml
--8<-- "content/https-tls/ref-acme.toml"
```
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 rewnew 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
[acme]
[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
[acme]
# ...
[acme.httpChallenge]
entryPoint = "http"
```
!!! 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
[acme]
# ...
[acme.dnsChallenge]
provider = "digitalocean"
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 | Wildcard & Root Domain Support |
|---|---|---|---|
| ACME DNS | acme-dns |
ACME_DNS_API_BASE, ACME_DNS_STORAGE_PATH |
Not tested yet |
| Alibaba Cloud | alidns |
ALICLOUD_ACCESS_KEY, ALICLOUD_SECRET_KEY, ALICLOUD_REGION_ID |
Not tested yet |
| Auroradns | auroradns |
AURORA_USER_ID, AURORA_KEY, AURORA_ENDPOINT |
Not tested yet |
| Azure | azure |
AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_RESOURCE_GROUP, [AZURE_METADATA_ENDPOINT] |
Not tested yet |
| Blue Cat | bluecat |
BLUECAT_SERVER_URL, BLUECAT_USER_NAME, BLUECAT_PASSWORD, BLUECAT_CONFIG_NAME, BLUECAT_DNS_VIEW |
Not tested yet |
| ClouDNS | cloudns |
CLOUDNS_AUTH_ID, CLOUDNS_AUTH_PASSWORD |
YES |
| Cloudflare | cloudflare |
CF_API_EMAIL, CF_API_KEY - The Global API Key needs to be used, not the Origin CA Key |
YES |
| CloudXNS | cloudxns |
CLOUDXNS_API_KEY, CLOUDXNS_SECRET_KEY |
Not tested yet |
| ConoHa | conoha |
CONOHA_TENANT_ID, CONOHA_API_USERNAME, CONOHA_API_PASSWORD |
YES |
| DigitalOcean | digitalocean |
DO_AUTH_TOKEN |
YES |
| DNSimple | dnsimple |
DNSIMPLE_OAUTH_TOKEN, DNSIMPLE_BASE_URL |
YES |
| DNS Made Easy | dnsmadeeasy |
DNSMADEEASY_API_KEY, DNSMADEEASY_API_SECRET, DNSMADEEASY_SANDBOX |
Not tested yet |
| DNSPod | dnspod |
DNSPOD_API_KEY |
Not tested yet |
| Domain Offensive (do.de) | dode |
DODE_TOKEN |
YES |
| DreamHost | dreamhost |
DREAMHOST_API_KEY |
YES |
| Duck DNS | duckdns |
DUCKDNS_TOKEN |
YES |
| Dyn | dyn |
DYN_CUSTOMER_NAME, DYN_USER_NAME, DYN_PASSWORD |
Not tested yet |
| External Program | exec |
EXEC_PATH |
YES |
| Exoscale | exoscale |
EXOSCALE_API_KEY, EXOSCALE_API_SECRET, EXOSCALE_ENDPOINT |
YES |
| Fast DNS | fastdns |
AKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET, AKAMAI_ACCESS_TOKEN |
YES |
| Gandi | gandi |
GANDI_API_KEY |
Not tested yet |
| Gandi v5 | gandiv5 |
GANDIV5_API_KEY |
YES |
| Glesys | glesys |
GLESYS_API_USER, GLESYS_API_KEY, GLESYS_DOMAIN |
Not tested yet |
| GoDaddy | godaddy |
GODADDY_API_KEY, GODADDY_API_SECRET |
Not tested yet |
| Google Cloud DNS | gcloud |
GCE_PROJECT, Application Default Credentials 1 2, [GCE_SERVICE_ACCOUNT_FILE] |
YES |
| hosting.de | hostingde |
HOSTINGDE_API_KEY, HOSTINGDE_ZONE_NAME |
YES |
| HTTP request | httpreq |
HTTPREQ_ENDPOINT, HTTPREQ_MODE, HTTPREQ_USERNAME, HTTPREQ_PASSWORD 3 |
YES |
| IIJ | iij |
IIJ_API_ACCESS_KEY, IIJ_API_SECRET_KEY, IIJ_DO_SERVICE_CODE |
Not tested yet |
| INWX | inwx |
INWX_USERNAME, INWX_PASSWORD |
YES |
| Lightsail | lightsail |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, DNS_ZONE |
Not tested yet |
| Linode | linode |
LINODE_API_KEY |
Not tested yet |
| Linode v4 | linodev4 |
LINODE_TOKEN |
Not tested yet |
| manual | - | none, but you need to run Traefik interactively 4, turn on acmeLogging to see instructions and press Enter. |
YES |
| MyDNS.jp | mydnsjp |
MYDNSJP_MASTER_ID, MYDNSJP_PASSWORD |
YES |
| Namecheap | namecheap |
NAMECHEAP_API_USER, NAMECHEAP_API_KEY |
YES |
| name.com | namedotcom |
NAMECOM_USERNAME, NAMECOM_API_TOKEN, NAMECOM_SERVER |
Not tested yet |
| Netcup | netcup |
NETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, NETCUP_API_PASSWORD |
Not tested yet |
| NIFCloud | nifcloud |
NIFCLOUD_ACCESS_KEY_ID, NIFCLOUD_SECRET_ACCESS_KEY |
Not tested yet |
| Ns1 | ns1 |
NS1_API_KEY |
Not tested yet |
| Open Telekom Cloud | otc |
OTC_DOMAIN_NAME, OTC_USER_NAME, OTC_PASSWORD, OTC_PROJECT_NAME, OTC_IDENTITY_ENDPOINT |
Not tested yet |
| OVH | ovh |
OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY |
YES |
| Openstack Designate | designate |
OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_TENANT_NAME, OS_REGION_NAME |
YES |
| Oracle Cloud | oraclecloud |
OCI_COMPARTMENT_OCID, OCI_PRIVKEY_FILE, OCI_PRIVKEY_PASS, OCI_PUBKEY_FINGERPRINT, OCI_REGION, OCI_TENANCY_OCID, OCI_USER_OCID |
YES |
| PowerDNS | pdns |
PDNS_API_KEY, PDNS_API_URL |
Not tested yet |
| Rackspace | rackspace |
RACKSPACE_USER, RACKSPACE_API_KEY |
Not tested yet |
| RFC2136 | rfc2136 |
RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_TSIG_ALGORITHM, RFC2136_NAMESERVER |
Not tested yet |
| Route 53 | route53 |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, [AWS_REGION], [AWS_HOSTED_ZONE_ID] or a configured user/instance IAM profile. |
YES |
| Sakura Cloud | sakuracloud |
SAKURACLOUD_ACCESS_TOKEN, SAKURACLOUD_ACCESS_TOKEN_SECRET |
Not tested yet |
| Selectel | selectel |
SELECTEL_API_TOKEN |
YES |
| Stackpath | stackpath |
STACKPATH_CLIENT_ID, STACKPATH_CLIENT_SECRET, STACKPATH_STACK_ID |
Not tested yet |
| TransIP | transip |
TRANSIP_ACCOUNT_NAME, TRANSIP_PRIVATE_KEY_PATH |
YES |
| VegaDNS | vegadns |
SECRET_VEGADNS_KEY, SECRET_VEGADNS_SECRET, VEGADNS_URL |
Not tested yet |
| Vscale | vscale |
VSCALE_API_TOKEN |
YES |
| VULTR | vultr |
VULTR_API_KEY |
Not tested yet |
| Zone.ee | zoneee |
ZONEEE_API_USER, ZONEEE_API_KEY |
YES |
!!! 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.
[acme]
# ...
[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.
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
!!! note "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example *.*.local.com).
Most likely the root domain should receive a certificate too, so it needs to be specified as SAN and 2 DNS-01 challenges are executed.
In this case the generated DNS TXT record for both domains is the same.
Even though this behavior is DNS RFC compliant,
it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the DNS-01 challenge fail.
The Traefik ACME client library LEGO supports some but not all DNS providers to work around this issue.
The Supported provider table indicates if they allow generating certificates for a wildcard domain and its root domain.
Known Domains, SANs
You can set SANs (alternative domains) for each main domain. Every domain must have A/AAAA records pointing to Traefik. Each domain & SAN will lead to a certificate request.
[acme]
# ...
[[acme.domains]]
main = "local1.com"
sans = ["test1.local1.com", "test2.local1.com"]
[[acme.domains]]
main = "local2.com"
[[acme.domains]]
main = "*.local3.com"
sans = ["local3.com", "test1.test1.local3.com"]
# ...
!!! important
The certificates for the domains listed in acme.domains are negotiated at Traefik startup only.
!!! note
Wildcard certificates can only be verified through a DNS-01 challenge.
caServer
??? example "Using the Let's Encrypt staging server"
```toml
[acme]
# ...
caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
```
onHostRule
Enable certificate generation on routers Host & HostSNI rules.
This will request a certificate from Let's Encrypt for each router with a Host rule.
[acme]
# ...
onHostRule = true
# ...
!!! note "Multiple Hosts in a Rule"
The rule Host(test1.traefik.io,test2.traefik.io) will request a certificate with the main domain test1.traefik.io and SAN test2.traefik.io.
!!! warning
onHostRule option can not be used to generate wildcard certificates. Refer to wildcard generation for further information.
storage
The storage option sets the location where your ACME certificates are saved to.
[acme]
# ...
storage = "acme.json"
# ...
The value can refer to two kinds of storage:
- a JSON file
- a KV store entry
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.
In a a Key Value Store Entry
ACME certificates can be stored in a key-value store entry.
storage = "traefik/acme/account"
!!! note "Storage Size"
Because key-value stores have limited entry size, the certificates list is compressed _before_ it is saved.
For example, it is possible to store up to _approximately_ 100 ACME certificates in Consul.
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.