Custom domains
domains manages a team's DNS zones and attaches host names to pages aliases,
apps, status pages and other services, with certificates issued automatically.
Choose who serves DNS
Connect a Cloudflare account in domains → Accounts with an API token that can read zones and edit DNS
(sealed, never shown again), then import the zones you want. Records are read live and changed through
Cloudflare.
Add a zone on the instance's own name servers (ns1 and ns2, xvii-node on two servers). Records are kept
in domains: A, AAAA, CNAME, TXT, MX, NS, SRV, CAA. Change the registrar's name servers only once both
servers answer correctly; the panel shows when the delegation is in place.
Move a zone from Cloudflare
Use the zone's Move action. Every record is copied except Cloudflare's NS; proxied records become DNS
only; anything the name servers can't serve is listed. Cloudflare keeps its copy until you delete it
there. Before switching the registrar, check MX, TXT, DKIM, DMARC, CAA and service records, not just the
site's A record.
If the name servers' own domain is run by the same registry as the zone you delegate (both under
Identity Digital, say), the registrar may ask for registered name server hosts (glue). Register them at
the instance domain's registrar first.
Run the name servers
Each name server is a server running
xvii-node dns https://domains.xvii.network TOKEN
with its own token from domains → Accounts (superusers; a new token stops the old one). It pulls the
zones every five seconds and keeps its last copy on disk, so it keeps answering when the control plane is
away. Open UDP and TCP port 53. When a server stops pulling, superusers get nameserver.stale: its old
records still answer, but changes don't reach it.
Attach a name
domains → Names → Attach, then pick the target: a pages alias, an app, a status page, a team's
share links, an analytics dashboard, a hooks endpoint, a tunnel name, mail's set-up hosts. domains creates
the record (an A record to the instance, or to an edge node for an app there), registers the name with the
service and the certificate is issued on demand. The panel shows pending → serving.
Other panels open the same dialog from their own pages. Don't put a second proxy with a different
certificate challenge in front of an attached name.
Cache
On a name's shield button, turn on Cache. Shared Cache-Control responses and static assets are kept
in memory; private, no-store and cookie-setting responses never are. Check X-Cache: MISS on the first
request and HIT afterwards; purge after changing assets whose URLs didn't change. Content-hashed file
names make purging unnecessary. A restart empties the cache.
Protection
The same dialog controls, per name:
- requests per second per IP, with a burst of five times the rate;
- concurrent requests per IP;
- IP and CIDR bans (IPv6 too), and automatic temporary bans after sustained violations;
- under attack: a JavaScript proof-of-work before browser pages, then an IP-bound pass cookie.
Start above normal traffic and watch what is rejected before lowering the limits: many visitors can share
one IP behind a NAT. Under attack breaks API clients and webhook senders, so don't turn it on for names
only machines call. This is application-layer protection: it can't help when the server's link itself is
saturated; that needs your provider's mitigation.
DNSSEC
DNSSEC lets resolvers reject forged answers. It doesn't encrypt queries or stop DDoS.
Sign the zone
On a zone on xvii's name servers, open DNSSEC and turn signing on. Both name servers need a node
version that signs.
Check the answers
Confirm DNSKEY and signed answers (including for names that don't exist) from both servers.
Publish the DS
Copy the panel's DS record (key tag, algorithm 13, digest type 2, digest) into the registrar's DNSSEC
settings, or the public key if the registrar takes DNSKEY.
Wait for activation
domains checks every ten minutes and moves the zone from waiting to active when the parent's DS
matches.
A wrong DS makes the whole domain fail for validating resolvers, and zone.dnssec_mismatch is an
outage, not a warning. To turn DNSSEC off, remove the DS at the registrar first, wait at least a day,
then stop signing. Never delete the key while the parent still publishes a DS for it.
Zones on Cloudflare use Cloudflare's own DNSSEC.
Limits and events
Limits domains.zones, domains.attachments. Events zone.delegated, zone.signed,
zone.dnssec_mismatch, nameserver.stale.