DNS Guide

LNS runs an authoritative DNS server for the lthn. zone. It listens on both UDP and TCP and responds to standard DNS queries.

Querying .lthn Names

Use dig or any DNS client, pointing at the LNS server:

# A record (IPv4 address)
dig @localhost -p 5354 charon.lthn A

# AAAA record (IPv6 address)
dig @localhost -p 5354 charon.lthn AAAA

# TXT record (metadata, capabilities)
dig @localhost -p 5354 charon.lthn TXT

# NS record (nameserver delegation)
dig @localhost -p 5354 charon.lthn NS

# SOA record (zone authority)
dig @localhost -p 5354 charon.lthn SOA

# TCP query (for larger responses)
dig @localhost -p 5354 charon.lthn A +tcp

Supported Record Types

Type	Source	Description
A	`GLUE4` records on sidechain	IPv4 address of the named service
AAAA	`GLUE6` records on sidechain	IPv6 address of the named service
TXT	`TXT` records on sidechain	Metadata, capability strings, alias comments
NS	`NS` records on sidechain	Nameserver delegation
SOA	Generated by LNS	Zone authority (`ns1.lthn.`, `hostmaster.lthn.`)
PTR	Reverse lookup against cache	Maps IP back to `.lthn` name

SOA Details

LNS generates the SOA record dynamically:

Primary NS: ns1.lthn.
Responsible party: hostmaster.lthn.
Serial: Current Unix timestamp
Refresh: 3600s, Retry: 600s, Expire: 86400s, Minimum TTL: 300s

All records use a 300-second TTL.

Reverse DNS (PTR)

LNS supports reverse DNS lookups. Given an IP address, it scans the cache for matching A records and returns the corresponding .lthn name:

# Reverse lookup for 10.69.69.165
dig @localhost -p 5354 -x 10.69.69.165

This returns a PTR record pointing to the name (e.g., charon.lthn.).

Response Behaviour

Known name, matching type: Answer section contains the requested records
Known name, no records of that type: Empty answer, SOA in authority section
Unknown name: NXDOMAIN with SOA in authority section
Non-.lthn query: REFUSED
Zone apex (lthn.): Returns SOA for SOA/ANY queries; SOA in authority for other types
Empty question: FORMERR

Using LNS as a System Resolver

Linux (systemd-resolved)

Create a drop-in configuration to forward .lthn queries to LNS:

sudo mkdir -p /etc/systemd/resolved.conf.d
sudo tee /etc/systemd/resolved.conf.d/lthn.conf <<EOF
[Resolve]
DNS=127.0.0.1:5354
Domains=~lthn
EOF
sudo systemctl restart systemd-resolved

Linux (NetworkManager + dnsmasq)

If NetworkManager manages DNS through dnsmasq:

sudo tee /etc/NetworkManager/dnsmasq.d/lthn.conf <<EOF
server=/lthn/127.0.0.1#5354
EOF
sudo systemctl restart NetworkManager

macOS

Create a resolver file for the .lthn domain:

sudo mkdir -p /etc/resolver
sudo tee /etc/resolver/lthn <<EOF
nameserver 127.0.0.1
port 5354
EOF

Docker Containers

Pass the --dns flag or configure dns in compose:

services:
  myapp:
    dns: 172.17.0.1  # Docker host IP
    # Or use network_mode: host with LNS on 127.0.0.1

Verification

After configuring the resolver, test with:

# Should resolve without specifying @localhost
ping charon.lthn
nslookup charon.lthn