Known issues

Rough edges we've run into ourselves, collected here so you don't have to rediscover them. Each entry lists the error you'll see, what to do, and a short note on why it helps so the fix isn't just a magic incantation.

To add an entry, copy the pattern below: a ## heading for the symptom, the literal error in a fenced block, then the fix and the reasoning.

DNS queries fail while the admin console shows records

The dns-dns backend is running and /dns records list shows every zone, but a direct query gets no answer:

dig @192.0.2.10 example.com SOA
;; communications error to 192.0.2.10#53: connection refused

On hosts with systemd-resolved (Ubuntu's default), port 53 is held by its stub listener:

ss -tulnp | grep ':53 '
udp  UNCONN  127.0.0.53%lo:53  …  users:(("systemd-resolve",…))

What to do: Disable the stub listener, point the host at the real upstream resolvers, then restart both services:

sed -i 's/^#\?DNSStubListener=.*/DNSStubListener=no/' /etc/systemd/resolved.conf
ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
systemctl restart systemd-resolved
systemctl restart everlock          # or however your everlock process runs

Verify with ss -tulnp | grep ':53 ' (Everlock on 0.0.0.0:53, UDP and TCP) and dig @127.0.0.1 <zone> SOA +short.

Why it helps: The DNS frontend binds the wildcard 0.0.0.0:53, and that bind collides with the stub already bound to 127.0.0.53:53. The frontend then exits — the startup log shows frontend 'frontend-dns' exited with error: … address already in use — while every other backend keeps serving, which is why the admin console still lists records with nothing answering on the wire. Relinking /etc/resolv.conf to /run/systemd/resolve/resolv.conf keeps the host's own outbound resolution working, which Everlock itself needs for ACME certificates, outbound mail, and the self-update check.

Container registry login fails with a TLS error

Pushing to or logging in to the registry fails before you're asked for — or despite entering — valid credentials:

docker login cr.example.com
Error response from daemon: Get "https://cr.example.com/v2/":
remote error: tls: access denied

What to do: Add the registry's hostname to its vhosts list in config/oci-http.toml, then restart Everlock so the OCI backend routes the new registry vhost (the OCI backend loads its registries at startup):

[registries.my-registry]
vhosts = ["cr.example.com"]

Why it helps: tls: access denied is a TLS handshake alert, not a login failure — your credentials are never even sent. Everlock issues and loads the certificate for a new public vhost automatically (no restart needed for the certificate). The OCI backend, however, only learns its registry vhosts at startup, so a restart is what makes it route the new registry; after that, login proceeds to the normal credential check.