DNS record derivation and address-mode reference

DNS is global, not multi-instance.

Its state is split across:

• everlock-system/config/dns.toml
• everlock-dns/<zone>.toml

The backend combines:

• derived records from other Everlock services
• explicit records stored in zone files
• generated SOA and ns1 / ns2 NS records for each owned zone

Explicit records override derived records by name + type.

What it derives

Everlock derives DNS records from:

• site vhosts
• image vhosts
• OCI registry vhosts
• calendar and contacts vhosts
• mail domains

Every vhost inside an owned zone gets address records for the public address.

Mail domains also derive:

• MX <zone> -> 10 mail.<zone>
• address records for mail.<zone>
• SRV records for mail client setup

Calendar and contacts vhosts also carry SRV and TXT records for CalDAV and CardDAV client setup.

Derived records follow the rest of the server. Saving a vhost or a mail domain, the HTTP frontend switching to HTTPS, or a mail frontend binding its listeners rebuilds them within moments, and the SOA serial advances.

Client setup records

Mail, calendar and contacts clients find their server through SRV records: given an email address or a server name, they look up the host, the port and, for CalDAV and CardDAV, the path. Every SRV record Everlock derives carries the port the frontend listens on, so custom listen ports reach the clients too. A service Everlock leaves out carries 0 0 0 ., which tells clients to use the services listed beside it.

Per mail domain:

Name	Value
_imaps._tcp.<domain>	0 1 <IMAPS port> mail.<domain>.
_imap._tcp.<domain>	10 1 <IMAP STARTTLS port> mail.<domain>.
_submission._tcp.<domain>	0 1 <submission port> mail.<domain>.
_submissions._tcp.<domain>	0 0 0 .
_pop3s._tcp.<domain>, _pop3._tcp.<domain>	0 0 0 .

The first three carry 0 0 0 . while their listener is switched off. The IMAP STARTTLS listener is off by default, and _imap ranks behind _imaps, so clients prefer TLS from the first byte.

Per calendar vhost, and the same with carddav and path=/carddav per contacts vhost:

Name	Type	Value
_caldavs._tcp.<vhost>	SRV	0 1 <HTTPS port> <vhost>.
_caldavs._tcp.<vhost>	TXT	path=/caldav
_caldav._tcp.<vhost>	SRV	0 0 0 .

CalDAV and CardDAV run over HTTPS, so the plain-HTTP names carry 0 0 0 .. While the HTTP frontend serves plain HTTP alone, _caldavs and _carddavs carry 0 0 0 . as well, and the TXT record accompanies the HTTPS form. An explicit TXT path=… record at one of these names replaces the derived path.

Address resolution

The address used for synthesised A and AAAA records — vhost records, mail.<zone>, and the ns1 / ns2 glue — is selected at runtime by the address_mode key in config/dns.toml:

Mode	Where the address comes from	When to use
static	default_ipv4 / default_ipv6 from dns.toml	Datacenter VM, VPS, paid static line
interface	First public address on a local interface	Hosts where the routable IP is on the LAN interface
discover	Hourly probe against public DNS services	NAT or residential lines
localhost	127.0.0.1 / ::1	Containers and dev machines
manual	Operator pushes values via `/dns ip set v4	v6 `
auto	Picks one of the above at startup based on what's around	Default if address_mode is unset

In discover mode the loop talks to myip.opendns.com against OpenDNS and whoami.cloudflare against 1.1.1.1 once per hour. When the public address changes, Everlock updates the synthesised records and bumps the SOA serial.

Three environment variables override the equivalent TOML keys:

• EVERLOCK_PUBLIC_IPV4
• EVERLOCK_PUBLIC_IPV6
• EVERLOCK_ADDRESS_MODE

listen_udp and listen_tcp in config/dns.toml accept comma-separated bind addresses, so you can bind explicit IPv4 and IPv6 addresses instead of the default 0.0.0.0:53,[::]:53. The --frontend-dns-listen-udp and --frontend-dns-listen-tcp flags, and their environment variables, win over the file.

Admin commands

In addition to the zone and record commands, the admin SSH backend exposes two commands for managing the address overlay:

• /dns ip refresh wakes the discovery loop for an out-of-band probe
• /dns ip set v4|v6 <addr> pushes a value into the manual overlay

/dns info shows the resolved mode and the effective address values currently used in synthesised records.

Current gaps

Still missing:

• warning and reporting for suppressed derived records
• SSH public-host derived records
• ACME DNS-01 integration

For the internal design and deeper rationale, see the internal DNS backend doc.