Getting started: DNS zone with site and mail

This walkthrough starts Everlock with DNS, site hosting, and inbound mail, then shows how one DNS zone can derive records automatically from:

a site vhost
a mail domain

At the end, jens.dev is authoritative in Everlock, wiki.jens.dev resolves through a derived site record, and jens.dev publishes an MX record through the mail backend.

1. Start Everlock with DNS, site, and mail enabled

For a local first pass:

everlock serve \
  --frontend-ssh \
  --backend-admin-ssh \
  --frontend-http \
  --frontend-http-listen-http 127.0.0.1:8080 \
  --frontend-dns \
  --frontend-dns-listen-udp 127.0.0.1:5353 \
  --frontend-dns-listen-tcp 127.0.0.1:5353 \
  --frontend-smtp \
  --frontend-smtp-listen 127.0.0.1:2525 \
  --backend-dns-dns \
  --backend-site-http \
  --backend-mail-smtp \
  --admin-user admin \
  --admin-password change-me

This gives you:

admin SSH on port 2222
HTTP on 127.0.0.1:8080
authoritative DNS on 127.0.0.1:5353
SMTP on 127.0.0.1:2525

2. Open the admin console

Connect:

ssh -p 2222 admin@127.0.0.1

Use the bootstrap password:

change-me

Inside the admin shell, grant the DNS permissions needed for this walkthrough:

/users grant admin ssh/dns/* owner

3. Create the zone

Create the authoritative zone:

/dns zones create jens.dev

At this point the zone exists, but there is no default target address yet for derived A and AAAA records.

The current implementation stores those defaults in data/everlock-system/config/dns.toml, so for a local test add:

default_ipv4 = "127.0.0.1"

The file should look roughly like this:

enabled = true
listen_udp = "127.0.0.1:5353"
listen_tcp = "127.0.0.1:5353"
default_ipv4 = "127.0.0.1"

Then pull the change into the running backend:

/dns reload

4. Add a site vhost inside the zone

Create one site and bind it to wiki.jens.dev:

/site create wiki store=wiki mode=markdown auth=public vhost=wiki.jens.dev

The DNS backend derives records from site vhosts inside owned zones, so after the site exists, list the DNS view:

/dns records list jens.dev

You should see a derived record for:

wiki.jens.dev A 127.0.0.1

Test it directly:

dig @127.0.0.1 -p 5353 wiki.jens.dev A

5. Add a mail domain inside the zone

Create a mail domain for the same zone:

/mail domains create jens.dev

Now list the DNS view again:

/dns records list jens.dev

You should now see derived mail records too:

jens.dev MX 10 mail.jens.dev
mail.jens.dev A 127.0.0.1

Test them with dig:

dig @127.0.0.1 -p 5353 jens.dev MX
dig @127.0.0.1 -p 5353 mail.jens.dev A

6. Override one derived record

If you want to override the derived site address, add an explicit record of the same name + type:

/users grant admin ssh/dns/jens.dev writer
/dns records create jens.dev name=wiki type=A value=198.51.100.7 ttl=300

List the zone again:

/dns records list jens.dev

The wiki.jens.dev A row should now show as explicit-override instead of derived.

That means:

Everlock still knows wiki.jens.dev came from the site backend
the explicit DNS record wins for the served answer

7. What Everlock is doing

Current DNS derivation rules used in this walkthrough:

site vhost wiki.jens.dev
- derive A from default_ipv4
mail domain jens.dev
- derive MX 10 mail.jens.dev
- derive A mail.jens.dev from default_ipv4

These derived records are rebuilt from current backend state. They are not stored as explicit DNS records.

Only explicit overrides land in:

data/everlock-dns/jens.dev.toml

8. What to test next

push content into the wiki site store and open http://wiki.jens.dev:8080 with a local host override
send a test message to alice@jens.dev through SMTP
add AAAA defaults and confirm dual-stack derived answers
remove the explicit override with:

/dns records delete jens.dev wiki A

Then check that wiki.jens.dev A falls back to the derived site record again.