Docs › Certificates

Wildcard certificates with Traefik

Traefik delegates DNS challenges to lego, so the provider name is acme-dns with a hyphen. Credentials are read from the JSON file named by ACME_DNS_STORAGE_PATH.

Where the configuration lives

traefik.yml and an acme-dns credentials file

Configuration

traefik.yml

certificatesResolvers:
  homenetwork:
    acme:
      email: you@example.com
      storage: /acme.json
      dnsChallenge:
        provider: acme-dns
        # ACME_DNS_API_BASE=https://api.home.network/acmedns
        # ACME_DNS_API_BASE=https://api.home.network/acmedns
        # ACME_DNS_STORAGE_PATH=/acme-dns.json holding:
        # {"alice.home.network":{"username":"<your username>",
        #  "password":"<your key>",
        #  "fulldomain":"_acme-challenge.alice.home.network",
        #  "subdomain":"<your subdomain>","allowfrom":[]}}

The username, password and subdomain come from the setup wizard, which shows them once. They are stored hashed, so a lost set is replaced rather than recovered.

Worth knowing. Write the credentials file yourself before first run. Given an empty or missing entry, lego registers a brand new acme-dns account instead of using yours, then stops. On Traefik 3 the propagation options moved: delayBeforeCheck is now propagation.delayBeforeChecks.

Ask for both names

A wildcard does not cover the name it sits under, so a certificate for *.alice.home.network alone leaves alice.home.network without one. Request both in a single certificate.

Check it worked

verify

# the challenge value your client published
dig +short TXT _acme-challenge.alice.home.network @ns1.home.network

# what the certificate ended up covering
echo | openssl s_client -servername nas.alice.home.network \
  -connect nas.alice.home.network:443 2>/dev/null \
  | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

Why only wildcards

Challenge records are writable only at your label apex, so the only certificates obtainable are the wildcard and the label itself. Your individual device names never reach Certificate Transparency logs, which is a consequence of the design rather than a setting to remember.

← All documentation