Documentation

Last updated: 2026-08-11

DNS address modes and public-IP discovery

backend-dns-dns now picks the address used in synthesised A / AAAA records (vhost records, mail.<zone>, and the ns1 / ns2 glue) at runtime, based on an address_mode key in dns.toml. The behaviour that used to be "guess from the local interface" is now one of six modes. The most important addition is discover, which runs an hourly probe against public DNS services so a node behind NAT can publish the right IPv4 in its own zone.

What changed

  • New TOML key address_mode in config/dns.toml with values auto, static, interface, discover, localhost, and manual. The previous behaviour is preserved as interface.
  • auto is the default and picks a concrete mode at startup based on whether default_ipv4 / default_ipv6 are configured, whether the local interface set already has a routable address, and whether any authoritative zone is owned.
  • In discover mode an hourly probe loop talks to myip.opendns.com (OpenDNS) and whoami.cloudflare (1.1.1.1), validates the answer, and updates the synthesised records. The SOA serial bumps on every change.
  • Records published in discover and manual mode use a 300-second TTL so resolvers don't pin the old value for the full hour.
  • Three environment variables for container deployments: EVERLOCK_PUBLIC_IPV4, EVERLOCK_PUBLIC_IPV6, EVERLOCK_ADDRESS_MODE — they override the equivalent TOML keys.
  • Two new admin SSH commands: /dns ip refresh (wake the discovery loop for an out-of-band probe) and /dns ip set v4|v6 <addr> (push a value into the manual overlay). /dns info now shows the resolved mode and the effective addresses.

Why this matters

The previous "look at the local interface" path was correct for IPv6 on a Fritz!Box (the LAN interface already carries the routable GUA) and for any datacenter VM with a routable v4 directly attached. It was wrong for the common residential case: behind NAT the interface only sees an RFC 1918 address, so backend-dns-dns would publish a useless private address. discover mode makes self-hosting an authoritative zone from a residential line actually work.

The other modes cover the rest of the landscape: static for operators who pin the value, localhost for containers and dev machines, manual for air-gapped or externally-managed setups, and interface for the historical behaviour when an operator wants to keep it exactly as it was.

What this does not do yet

The flip side of discover is that the parent zone — held by your domain registrar — still needs to learn about the new IP for the ns1 / ns2 glue. Pushing updates into the registrar from Everlock is a separate piece of work and is not part of this change.

For the full picture, including the design rationale for each mode and the provider list, see DNS backends → Address resolution or the internal backend doc.

updates dns networking