Documentation
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:
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 hostname to the registry with /oci set, which applies
while the process runs:
/oci set my-registry vhost=cr.example.com
Editing config/oci-http.toml by hand works too, but nothing tells the running
backend to re-read it — /oci set is what rebuilds the routing map:
[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. A registry answers only on a
hostname it is mapped to, so until the hostname is in that registry's vhosts
there is nothing to present a certificate for. /oci set rebuilds the
vhost-to-registry map and republishes the host, which is what issues the
certificate and starts routing; after that, login proceeds to the normal
credential check.
Windows Explorer refuses to map a plain-HTTP file share
Mapping a WebDAV share from This PC → Map network drive fails on an
http:// address, with or without correct credentials:
The folder you entered does not appear to be valid. Please choose another.
What to do: Serve the share over HTTPS — on a public vhost Everlock issues the certificate itself over ACME:
For a LAN-only host, a third-party client mounts plain HTTP: Cyberduck, WinSCP, and RaiDrive all do.
Why it helps: Windows' built-in WebDAV client (WebClient) sends Basic
credentials over TLS only — its BasicAuthLevel policy defaults to
SSL-only — and refuses the mount before authentication is attempted, which is
why the message names the folder rather than the password. Every other client
(Finder, GNOME Files, Dolphin, rclone, the mobile DAV apps) mounts plain HTTP
as it stands, and all of them, Windows included, mount an HTTPS share.