Let’s Encrypt

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

    Let’s Encrypt and Rate Limiting

    Note that Let’s Encrypt API has rate limiting. These last up to one week, and can not 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 configuration.

    Use Let’s Encrypt staging server with the caServer configuration option when experimenting to avoid hitting this limit too fast.

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

    Then, each 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 .

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

    Defining an is a requirement for a certificate resolver to be functional.

    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.

    Configuration Reference

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

    File (YAML)

    File (TOML)

    1. # Enable ACME (Let's Encrypt): automatic SSL.
    2. [certificatesResolvers.myresolver.acme]
    4.   # Email address used for registration.
    5.   #
    6.   # Required
    7.   #
    8.   email = "[email protected]"
    10.   # File or key used for certificates storage.
    11.   #
    12.   # Required
    13.   #
    14.   storage = "acme.json"
    16.   # CA server to use.
    17.   # Uncomment the line to use Let's Encrypt's staging server,
    18.   # leave commented to go to prod.
    19.   #
    20.   # Optional
    21.   # Default: "https://acme-v02.api.letsencrypt.org/directory"
    22.   #
    23.   # caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
    25.   # The certificates' duration in hours.
    26.   # It defaults to 2160 (90 days) to follow Let's Encrypt certificates' duration.
    27.   #
    28.   # Optional
    29.   # Default: 2160
    30.   #
    31.   # certificatesDuration=2160
    33.   # Preferred chain to use.
    34.   #
    35.   # If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name.
    36.   # If no match, the default offered chain will be used.
    37.   #
    38.   # Optional
    39.   # Default: ""
    40.   #
    41.   # preferredChain = "ISRG Root X1"
    43.   # KeyType to use.
    44.   #
    45.   # Optional
    46.   # Default: "RSA4096"
    47.   #
    48.   # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
    49.   #
    50.   # keyType = "RSA4096"
    52.   # Use a TLS-ALPN-01 ACME challenge.
    53.   #
    54.   # Optional (but recommended)
    55.   #
    56.   [certificatesResolvers.myresolver.acme.tlsChallenge]
    58.   # Use a HTTP-01 ACME challenge.
    59.   #
    60.   # Optional
    61.   #
    62.   # [certificatesResolvers.myresolver.acme.httpChallenge]
    64.     # EntryPoint to use for the HTTP-01 challenges.
    65.     #
    66.     # Required
    67.     #
    68.     # entryPoint = "web"
    70.   # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
    71.   # Note: mandatory for wildcard certificate generation.
    72.   #
    73.   # Optional
    74.   #
    75.   # [certificatesResolvers.myresolver.acme.dnsChallenge]
    77.     # DNS provider used.
    78.     #
    79.     # Required
    80.     #
    81.     # provider = "digitalocean"
    83.     # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
    84.     # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
    85.     # Useful if internal networks block external DNS queries.
    86.     #
    87.     # Optional
    88.     # Default: 0
    89.     #
    90.     # delayBeforeCheck = 0
    92.     # Use following DNS servers to resolve the FQDN authority.
    93.     #
    94.     # Optional
    95.     # Default: empty
    96.     #
    97.     # resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
    99.     # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
    100.     #
    101.     # NOT RECOMMENDED:
    102.     # Increase the risk of reaching Let's Encrypt's rate limits.
    103.     #
    104.     # Optional
    105.     # Default: false
    106.     #
    107.     # disablePropagationCheck = true

    CLI

    1. # Enable ACME (Let's Encrypt): automatic SSL.
    3. # Email address used for registration.
    4. #
    5. # Required
    6. #
    7. [email protected]
    9. # File or key used for certificates storage.
    10. #
    11. # Required
    12. #
    13. --certificatesresolvers.myresolver.acme.storage=acme.json
    15. # CA server to use.
    16. # Uncomment the line to use Let's Encrypt's staging server,
    17. # leave commented to go to prod.
    18. #
    19. # Optional
    20. # Default: "https://acme-v02.api.letsencrypt.org/directory"
    21. #
    22. --certificatesresolvers.myresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
    24. # The certificates' duration in hours.
    25. # It defaults to 2160 (90 days) to follow Let's Encrypt certificates' duration.
    26. #
    27. # Optional
    28. # Default: 2160
    29. #
    30. --certificatesresolvers.myresolver.acme.certificatesDuration=2160
    32. # Preferred chain to use.
    33. #
    34. # If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name.
    35. # If no match, the default offered chain will be used.
    36. #
    37. # Optional
    38. # Default: ""
    39. #
    40. --certificatesresolvers.myresolver.acme.preferredchain="ISRG Root X1"
    42. # KeyType to use.
    43. #
    44. # Optional
    45. # Default: "RSA4096"
    46. #
    47. # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
    48. #
    49. --certificatesresolvers.myresolver.acme.keytype=RSA4096
    51. # Use a TLS-ALPN-01 ACME challenge.
    52. #
    53. # Optional (but recommended)
    54. #
    55. --certificatesresolvers.myresolver.acme.tlschallenge=true
    57. # Use a HTTP-01 ACME challenge.
    58. #
    59. # Optional
    60. #
    61. --certificatesresolvers.myresolver.acme.httpchallenge=true
    63. # EntryPoint to use for the HTTP-01 challenges.
    64. #
    65. # Required
    66. #
    67. --certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web
    69. # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
    70. # Note: mandatory for wildcard certificate generation.
    71. #
    72. # Optional
    73. #
    74. --certificatesresolvers.myresolver.acme.dnschallenge=true
    75. # DNS provider used.
    76. #
    77. # Required
    78. #
    79. --certificatesresolvers.myresolver.acme.dnschallenge.provider=digitalocean
    81. # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
    82. # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
    83. # Useful if internal networks block external DNS queries.
    84. #
    85. # Optional
    86. # Default: 0
    87. #
    88. --certificatesresolvers.myresolver.acme.dnschallenge.delaybeforecheck=0
    90. # Use following DNS servers to resolve the FQDN authority.
    91. #
    92. # Optional
    93. # Default: empty
    94. #
    95. --certificatesresolvers.myresolver.acme.dnschallenge.resolvers=1.1.1.1:53,8.8.8.8:53
    97. # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
    98. #
    99. # NOT RECOMMENDED:
    100. # Increase the risk of reaching Let's Encrypt's rate limits.
    101. #
    102. # Optional
    103. # Default: false
    104. #
    105. --certificatesresolvers.myresolver.acme.dnschallenge.disablepropagationcheck=true

    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 option is set, then the certificate resolver uses the router’s rule, by checking the Host() matchers. Please note that ) 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 , any router can provide a wildcard domain name, as “main” domain or as “SAN” domain.

    Please check the for more details.

    Configuration Examples

    Enabling ACME

    File (YAML)

    1. entryPoints:
    2.   web:
    3.     address: ":80"
    5.   websecure:
    6.     address: ":443"
    8. certificatesResolvers:
    9.   myresolver:
    10.     acme:
    11.       email: [email protected]
    12.       storage: acme.json
    13.       httpChallenge:
    14.         # used during the challenge
    15.         entryPoint: web

    File (TOML)

    1. [entryPoints]
    2.   [entryPoints.web]
    3.     address = ":80"
    5.   [entryPoints.websecure]
    6.     address = ":443"
    8. [certificatesResolvers.myresolver.acme]
    9.   email = "[email protected]"
    10.   storage = "acme.json"
    11.   [certificatesResolvers.myresolver.acme.httpChallenge]
    12.     # used during the challenge
    13.     entryPoint = "web"

    CLI

    1. --entrypoints.web.address=:80
    2. --entrypoints.websecure.address=:443
    3. # ...
    4. [email protected].com
    5. --certificatesresolvers.myresolver.acme.storage=acme.json
    6. # used during the challenge
    7. --certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web

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

    Single Domain from Router’s Rule Example

    • A certificate for the domain example.com is requested:

    Docker

    1. ## Dynamic configuration
    2. labels:
    3.   - traefik.http.routers.blog.rule=Host(`example.com`) && Path(`/blog`)
    4.   - traefik.http.routers.blog.tls=true
    5.   - traefik.http.routers.blog.tls.certresolver=myresolver

    Docker (Swarm)

    1. ## Dynamic configuration
    2. deploy:
    3.   labels:
    4.     - traefik.http.routers.blog.rule=Host(`example.com`) && Path(`/blog`)
    5.     - traefik.http.routers.blog.tls=true
    6.     - traefik.http.routers.blog.tls.certresolver=myresolver
    7.     - traefik.http.services.blog-svc.loadbalancer.server.port=8080"

    Kubernetes

    1. apiVersion: traefik.io/v1alpha1
    2. kind: IngressRoute
    3. metadata:
    4.   name: blogtls
    5. spec:
    6.   entryPoints:
    7.     - websecure
    8.   routes:
    9.   - match: Host(`example.com`) && Path(`/blog`)
    10.     kind: Rule
    11.     services:
    12.     - name: blog
    13.       port: 8080
    14.   tls:
    15.     certResolver: myresolver

    Marathon

    1. labels: {
    2.   "traefik.http.routers.blog.rule": "Host(`example.com`) && Path(`/blog`)",
    3.   "traefik.http.routers.blog.tls": "true",
    4.   "traefik.http.routers.blog.tls.certresolver": "myresolver",
    5.   "traefik.http.services.blog-svc.loadbalancer.server.port": "8080"
    6. }

    Rancher

    1. ## Dynamic configuration
    2. labels:
    3.   - traefik.http.routers.blog.rule=Host(`example.com`) && Path(`/blog`)
    4.   - traefik.http.routers.blog.tls=true
    5.   - traefik.http.routers.blog.tls.certresolver=myresolver

    File (YAML)

    1. ## Dynamic configuration
    2. http:
    3.   routers:
    4.     blog:
    5.       rule: "Host(`example.com`) && Path(`/blog`)"
    6.       tls:
    7.         certResolver: myresolver

    File (TOML)

    1. ## Dynamic configuration
    2. [http.routers]
    3.   [http.routers.blog]
    4.   rule = "Host(`example.com`) && Path(`/blog`)"
    5.   [http.routers.blog.tls]
    6.     certResolver = "myresolver"

    Multiple Domains from Router’s Rule Example

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

    Docker

    1. ## Dynamic configuration
    2. labels:
    3.   - traefik.http.routers.blog.rule=(Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)
    4.   - traefik.http.routers.blog.tls=true
    5.   - traefik.http.routers.blog.tls.certresolver=myresolver

    Docker (Swarm)

    1. ## Dynamic configuration
    2. deploy:
    3.   labels:
    4.     - traefik.http.routers.blog.rule=(Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)
    5.     - traefik.http.routers.blog.tls=true
    6.     - traefik.http.routers.blog.tls.certresolver=myresolver
    7.     - traefik.http.services.blog-svc.loadbalancer.server.port=8080"

    Kubernetes

    1. apiVersion: traefik.io/v1alpha1
    3. metadata:
    4.   name: blogtls
    5. spec:
    6.   entryPoints:
    7.     - websecure
    8.   routes:
    9.   - match: (Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)
    10.     kind: Rule
    11.     services:
    12.     - name: blog
    13.       port: 8080
    14.   tls:
    15.     certResolver: myresolver

    Marathon

    1. labels: {
    2.   "traefik.http.routers.blog.rule": "(Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)",
    3.   "traefik.http.routers.blog.tls": "true",
    4.   "traefik.http.routers.blog.tls.certresolver": "myresolver",
    5.   "traefik.http.services.blog-svc.loadbalancer.server.port": "8080"
    6. }

    Rancher

    1. ## Dynamic configuration
    2. labels:
    3.   - traefik.http.routers.blog.rule=(Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)
    4.   - traefik.http.routers.blog.tls=true
    5.   - traefik.http.routers.blog.tls.certresolver=myresolver

    File (YAML)

    1. ## Dynamic configuration
    2. http:
    3.   routers:
    4.     blog:
    5.       rule: "(Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)"
    6.       tls:
    7.         certResolver: myresolver

    File (TOML)

    1. ## Dynamic configuration
    2. [http.routers]
    3.   [http.routers.blog]
    4.     rule = "(Host(`example.com`) && Path(`/blog`)) || Host(`blog.example.org`)"
    5.     [http.routers.blog.tls]
    6.       certResolver = "myresolver"

    Multiple Domains from Router’s tls.domain Example

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

    Docker

    1. ## Dynamic configuration
    2. deploy:
    3.   labels:
    4.     - traefik.http.routers.blog.rule=Host(`example.com`) && Path(`/blog`)
    5.     - traefik.http.services.blog-svc.loadbalancer.server.port=8080"
    6.     - traefik.http.routers.blog.tls=true
    7.     - traefik.http.routers.blog.tls.certresolver=myresolver
    8.     - traefik.http.routers.blog.tls.domains[0].main=example.org
    9.     - traefik.http.routers.blog.tls.domains[0].sans=*.example.org

    Kubernetes

    1. apiVersion: traefik.io/v1alpha1
    2. kind: IngressRoute
    3. metadata:
    4.   name: blogtls
    5. spec:
    6.   entryPoints:
    7.     - websecure
    8.   routes:
    9.   - match: Host(`example.com`) && Path(`/blog`)
    10.     kind: Rule
    11.     services:
    12.     - name: blog
    13.       port: 8080
    14.   tls:
    15.     certResolver: myresolver
    16.     domains:
    17.     - main: example.org
    18.       - '*.example.org'

    Marathon

    1. labels: {
    2.   "traefik.http.routers.blog.rule": "Host(`example.com`) && Path(`/blog`)",
    3.   "traefik.http.routers.blog.tls": "true",
    4.   "traefik.http.routers.blog.tls.certresolver": "myresolver",
    5.   "traefik.http.routers.blog.tls.domains[0].main": "example.com",
    6.   "traefik.http.routers.blog.tls.domains[0].sans": "*.example.com",
    7.   "traefik.http.services.blog-svc.loadbalancer.server.port": "8080"
    8. }

    Rancher

    1. ## Dynamic configuration
    2. labels:
    3.   - traefik.http.routers.blog.rule=Host(`example.com`) && Path(`/blog`)
    4.   - traefik.http.routers.blog.tls=true
    5.   - traefik.http.routers.blog.tls.certresolver=myresolver
    6.   - traefik.http.routers.blog.tls.domains[0].main=example.org
    7.   - traefik.http.routers.blog.tls.domains[0].sans=*.example.org

    File (YAML)

    1. ## Dynamic configuration
    2. http:
    3.   routers:
    4.     blog:
    5.       rule: "Host(`example.com`) && Path(`/blog`)"
    6.       tls:
    7.         certResolver: myresolver
    8.         domains:
    9.           - main: "example.org"
    10.             sans:
    11.               - "*.example.org"

    File (TOML)

    1. ## Dynamic configuration
    2. [http.routers]
    3.   [http.routers.blog]
    4.     rule = "Host(`example.com`) && Path(`/blog`)"
    5.     [http.routers.blog.tls]
    6.       certResolver = "myresolver" # From static configuration
    7.       [[http.routers.blog.tls.domains]]
    8.         main = "example.org"
    9.         sans = ["*.example.org"]

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

    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 and crd providers.

    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

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

    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.

    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.

    Configuring the tlsChallenge

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       tlsChallenge: {}

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   [certificatesResolvers.myresolver.acme.tlsChallenge]

    CLI

    1. # ...
    2. --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.

    Using an EntryPoint Called web for the httpChallenge

    File (YAML)

    1. entryPoints:
    2.   web:
    3.     address: ":80"
    5.   websecure:
    6.     address: ":443"
    8. certificatesResolvers:
    9.   myresolver:
    10.     acme:
    11.       # ...
    12.       httpChallenge:
    13.         entryPoint: web

    File (TOML)

    1. [entryPoints]
    2.   [entryPoints.web]
    3.     address = ":80"
    5.   [entryPoints.websecure]
    6.     address = ":443"
    8. [certificatesResolvers.myresolver.acme]
    9.   # ...
    10.   [certificatesResolvers.myresolver.acme.httpChallenge]
    11.     entryPoint = "web"

    CLI

    1. --entrypoints.web.address=:80
    2. --entrypoints.websecure.address=:443
    3. # ...
    4. --certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web

    Redirection is fully compatible with the HTTP-01 challenge.

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

    Configuring a dnsChallenge with the DigitalOcean Provider

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       dnsChallenge:
    6.         provider: digitalocean
    7.         delayBeforeCheck: 0
    8.     # ...

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   [certificatesResolvers.myresolver.acme.dnsChallenge]
    4.     provider = "digitalocean"
    5.     delayBeforeCheck = 0
    6. # ...

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.dnschallenge.provider=digitalocean
    3. --certificatesresolvers.myresolver.acme.dnschallenge.delaybeforecheck=0
    4. # ...

    CNAME support

    CNAME are supported (and sometimes even encouraged), but there are a few cases where they can be .

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

    1. LEGO_DISABLE_CNAME_SUPPORT=true

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

    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.

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       dnsChallenge:
    6.         # ...
    7.         resolvers:
    8.           - "1.1.1.1:53"
    9.           - "8.8.8.8:53"

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   [certificatesResolvers.myresolver.acme.dnsChallenge]
    4.     # ...
    5.     resolvers = ["1.1.1.1:53", "8.8.8.8:53"]

    CLI

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

    Wildcard Domains

    ACME V2 supports wildcard certificates. As described in wildcard certificates can only be generated through a DNS-01 challenge.

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

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   [certificatesResolvers.myresolver.acme.eab]
    4.     kid = "abc-keyID-xyz"
    5.     hmacEncoded = "abc-hmac-xyz"

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.eab.kid=abc-keyID-xyz
    3. --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:

    Using the Let’s Encrypt staging server

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       caServer: https://acme-staging-v02.api.letsencrypt.org/directory
    6.       # ...

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
    4.   # ...

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
    3. # ...

    Required, Default=”acme.json”

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

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       storage: acme.json
    6.       # ...

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   storage = "acme.json"
    4.   # ...

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.storage=acme.json
    3. # ...

    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:

    1. docker run -v "/my/host/acme.json:/acme.json" traefik
    1. 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

    The certificatesDuration option defines the certificates’ duration in hours. It defaults to 2160 (90 days) to follow Let’s Encrypt certificates’ duration.

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

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       certificatesDuration: 72
    6.       # ...

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   certificatesDuration=72
    4.   # ...

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.certificatesduration=72
    3. # ...

    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.
    Certificate DurationRenew PeriodRenew Interval
    >= 1 year4 months1 week
    >= 90 days30 days1 day
    >= 7 days1 day1 hour
    >= 24 hours6 hours10 min
    < 24 hours20 min1 min

    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.

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       preferredChain: 'ISRG Root X1'
    6.       # ...

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   preferredChain = "ISRG Root X1"
    4.   # ...

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.preferredChain=ISRG Root X1
    3. # ...

    keyType

    Optional, Default=”RSA4096”

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

    File (YAML)

    1. certificatesResolvers:
    2.   myresolver:
    3.     acme:
    4.       # ...
    5.       keyType: 'RSA4096'
    6.       # ...

    File (TOML)

    1. [certificatesResolvers.myresolver.acme]
    2.   # ...
    3.   keyType = "RSA4096"
    4.   # ...

    CLI

    1. # ...
    2. --certificatesresolvers.myresolver.acme.keyType=RSA4096
    3. # ...

    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.

    Using Traefik for Business Applications?

    If you are using Traefik in your organization, consider Traefik Enterprise. You can use it as your:

    Traefik Enterprise simplifies the discovery, security, and deployment of APIs and microservices across any environment. See it in action in this short video walkthrough.

    1. More information about the HTTP message format can be found . ↩

    2. . ↩

    3. ↩

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

    5. The Global API Key needs to be used, not the . ↩