Because this problem cost me some time, I am sure someone else can get some value out of this. The old Hetzner-DNS-API is beeing phased out right now, so it’s time to hurry up…
Given be the following setup:
- You are using Hetzner for your domain, and are still on the old API (dns-hetzner as provider for the letsencrypt_core Homeassistant addon)
- You actually fetch LE-certs via DNS-API, and not via webroot or similar
- The hostname Homeassistant is using, is not publicly known (nor publicly rechable), and the public zonefile does not list an A/AAAA/CNAME record for that hostname (instead it is only reachable locally or via VPN, and is resolved by an internal DNS)
…then maybe you have run into Problems when trying to migrate to the new Hetzner DNS-API. Anyway, here’s how to solve this problem.
While the migration went somewhat smooth for me, migrating Homeassistant specifically gave me some true headache. But first let some technical details sink in for better understanding.
The old DNS-API of Hetzner (a large german VPS and domain provider) was/is listed as separate module within the letsencrypt-homeassistant-addon. While most appliances capable of fetching certificates by using ACME (like for Let’s Encrypt certs) already implemented a new provider-module for the new API (hetzner-dns-cloud, hetzner-cloud or similar), the Homeassistant-Addon did not (yet?) implemented those. So for let’s say „Nginx-Proxy-Manager“ or „pfSense“ everything is fine. As long as your acme/lets-encrypt-plugin is reasonably recent, everything is smooth sailing.
For everything that uses „lego“ (an acme-implementation written in go) as acme-fetcher, this is a little different. Because lego has not yet implemented dns-hetzner-cloud as standalone-provider, you have to pass the dns-provider by an environment-variable to lego, which then acts as a generic wrapper for that provider. This applies to said homeassistant-plugin, traekif (AFAIK) and of course lego itself (beside others). The core-problem is that lego tries to get authorative requests (SOA) for the hostname it is trying to fetch certificates for. Homelab-setups most likely won’t be able to statisfy this requirement, because the domain-zonefile does not know that hostname (if it is not publicly known), and the local DNS does know the hostname, but cannot answer authoratively. The result is, that you see something like unexpected response for the SOA-Section resulting in a SERVFAIL or FORBIDDEN as answer, depending on the configuration. In my case it looked like this (docker log from the letsencrypt_core-plugin in Homeassistant):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
[22:03:21] INFO: Selected DNS Provider: dns-lego [22:03:21] INFO: Use propagation seconds: 120 [22:03:21] INFO: Using certbot-dns-multi for dns-lego [22:03:21] INFO: Using custom lego provider from config: hetzner Saving debug log to /var/log/letsencrypt/letsencrypt.log Renewing an existing certificate for subdomain.mydomain.com Cleanup of subdomain.mydomain.com failed: hetzner: could not find zone for domain "subdomain.mydomain.com": [fqdn=_acme-challenge.subdomain.mydomain.com.] unexpected response for '_acme-challenge.subdomain.mydomain.com.' [question='_acme-challenge.subdomain.mydomain.com. IN SOA', code=SERVFAIL] hetzner: could not find zone for domain "subdomain.mydomain.com": [fqdn=_acme-challenge.subdomain.mydomain.com.] unexpected response for '_acme-challenge.subdomain.mydomain.com.' [question='_acme-challenge.subdomain.mydomain.com. IN SOA', code=SERVFAIL] Ask for help or search for solutions at https://community.letsencrypt.org. See the logfile /var/log/letsencrypt/letsencrypt.log or re-run Certbot with -v for more details. s6-rc: info: service legacy-services: stopping s6-rc: info: service legacy-services successfully stopped s6-rc: info: service legacy-cont-init: stopping s6-rc: info: service legacy-cont-init successfully stopped s6-rc: info: service fix-attrs: stopping s6-rc: info: service fix-attrs successfully stopped s6-rc: info: service s6rc-oneshot-runner: stopping s6-rc: info: service s6rc-oneshot-runner successfully stopped |
Instead of figuring out, how to cascade the local DNS so that it can answer authoratively for your domain, the easiest way is to use public DNS-Servers only for fetching the certificate and the authorative part. However, your homeassistant itself should keep using the local DNS, because otherwise it cannot resolve the hostnames of all the small devices it talks to. Lego luckily has options for specificly that. You however have to make sure, that homeassistant can reach public DNS servers (in my homelab I usually block public DNSses and DoT-Traffic for clients, and instead force them to use pi-hole, so that they cannot violate my DNS-settings to fetch Ads anyways).
If HA can reach public DNSses (I use Googles primary public DNS Server 8.8.8.8 and quad-one 1.1.1.1 as example here), for the first fetch you should enforce renewing and set the propagation time to 120 to let things settle. The Lets-Encrypt-Plugin-configuration should then look like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
keyfile: privkey.pem certfile: fullchain.pem challenge: dns dns: provider: dns-lego lego_provider: hetzner lego_env: - "HETZNER_API_TOKEN=your_api_token_here" propagation_seconds: 120 # give some more time to settle for the first fetch. dns_multi_nameservers: 1.1.1.1,8.8.8.8 domains: - your_fqdn_here email: your_email@here key_type: rsa verbose: true # for debugging force_renew: true # this should be deleted after initial fetch went through |
Note that this is the yaml-config and that yaml is sensitive to indentation and placement of dashes. the configuration must adhere to yaml standards. Homeassistant might automatically include an extra-line like „>-“ above the api-token. This is fine.
With that config I was finally able to fetch certificates with the new DNS-API. Hope you have had some success too, before the old API is going down (which will be in may of 2026)…