DNS

Last updated

Operator workflow? See DNS Zones (Admin). Tenant workflow? See DNS Records (User).

Jabali ships two PowerDNS processes:

  • pdns-server (authoritative) — answers for hosted zones, MariaDB backend, listens on the server’s public IPs :53.
  • pdns-recursor — handles local . recursion for the server itself, listens on loopback 127.0.0.1:53.

Split-port setup: the recursor binds the loopback so local processes (the panel, certbot, Stalwart, etc.) can resolve external names without going through an upstream resolver, while the authoritative binds public IPs so the world can query hosted zones.

DNS is an optional module (the DNS module in Server Settings, server_settings.dns_enabled). With it off, the panel still keeps each domain’s zone records in its database, but it publishes nothing: no zone push to PowerDNS and no recursor forwarders. Turning the module on installs PowerDNS, and the panel publishes every zone once PowerDNS is up. While the module is off, jabali update masks pdns and pdns-recursor so they don’t show as failed; turning it on, or Retry, unmasks them before the install starts them. Leave it off when your domains’ DNS is hosted elsewhere (a registrar, Cloudflare, another provider).

The mail module needs DNS: its install stops without the server’s own zone. On the Modules card, Mail can be turned on only once DNS is on and shows active; until then the card says why. If a module’s install fails, the card shows the reason and the path of its install log under the module, and Retry runs the install again. status unknown means the panel got no status for that module from its agent; it doesn’t mean the module is missing, so there’s no Retry. Reload the page in a moment. If the card can’t read the module settings at all (for example while the panel restarts), it says so and offers Reload instead of showing the switches.

Zones

Each hosted domain gets an authoritative zone in PowerDNS. Default records:

  • @ A → server primary IP (or domain’s listen IP if set)
  • @ AAAA → server primary IPv6 (if configured)
  • www CNAME → @
  • @ MX 10 mail.<panel-hostname>. (if domain has mail enabled)
  • mail A → server primary IP (if mail enabled)
  • _dmarc TXT (if mail enabled)
  • DKIM TXT (if mail enabled)
  • SPF TXT (if mail enabled)
  • MTA-STS TXT (if mail enabled)

Add / edit / delete custom records on the DNS page: click the domain’s name to open its records.

Secondary nameservers

Server Settings → DNS sets ns2 and up to 16 more Secondary DNS servers (AXFR + NOTIFY): a secondary DNS provider’s transfer addresses, or the secondaries of a hidden-primary setup. Each listed address may transfer every zone and is sent a NOTIFY when a zone changes. Nobody else can transfer a zone, and NOTIFY never goes to the hosts in a zone’s NS records. CLI: jabali settings set dns_secondary_ips=<ip>,<ip>. Setup steps: the dns-secondary-nameserver runbook.

DNSSEC

Per-domain, from the domain’s ⋯ menu on the DNS page (Enable DNSSEC / Disable DNSSEC). When enabled:

  1. Agent calls pdnsutil secure-zone <domain> → KSK + ZSK generated and rectified.
  2. Panel persists key metadata in the DB so it survives PDNS rebuilds.
  3. ⋯ → View DS & keys shows the keys and the DS record to publish at the parent registrar.

Disable DNSSEC asks for confirmation first, because the DS record has to come off the registrar before signing stops. A signed zone cannot be deleted until DNSSEC is disabled.

Until the DS is published at the registrar, the zone is signed but not part of the chain of trust, that’s fine for testing; not fine for production.

CLI:

jabali pdns dnssec enable <domain>
jabali pdns dnssec status <domain>
jabali pdns dnssec ds <domain>      # prints DS for parent registrar
jabali pdns dnssec disable <domain>

See platform/dnssec.md for the architecture details.

Mail provider (per domain)

Each domain has a mail provider (Domains → Edit → Email → Mail provider, or chosen at domain-add). It is the single source of truth for the domain’s mail DNS and certificate posture — email_enabled and the cert’s mail SANs are derived from it:

ProviderMXSPF (apex)OtherJabali mail cert SANs
Jabali mail (default)mail.<domain>v=spf1 mx …DKIM, autoconfig/autodiscover, IMAP/submission SRVsyes (mail/autoconfig/autodiscover/mta-sts)
No mail——noneno
Microsoft 365<domain-dashed>.mail.protection.outlook.cominclude:spf.protection.outlook.com -allautodiscover → autodiscover.outlook.com; optional selector1/2._domainkey CNAMEs (set the tenant’s onmicrosoft name)no
Google Workspacesmtp.google.cominclude:_spf.google.com ~alloptional google._domainkey TXT (paste from Google Admin)no
Custom templatedefined by the templatedefined by the templateany records the template holds (A/AAAA/CNAME/MX/TXT/NS/SRV/CAA), seeded once at createno

Switching providers is reconciled like any other DNS change: the panel publishes the new set, prunes the previous one (scoped by managed_by — mail-apex for the apex MX/SPF/DMARC, mail-provider-<p> for the rest, m6 for the Jabali set), and re-issues the certificate without the mail SANs for external/none. There is always exactly one v=spf1 TXT at the apex. Operator-authored apex mail records are replaced when a provider is selected (pick a preset, or pick No mail and hand-manage the records yourself). DKIM for Microsoft 365 / Google is published only when you supply the token; MX / SPF / autodiscover are automatic.

Custom DNS templates

A custom DNS template is a named, admin-defined set of DNS records that is seeded into a new domain’s zone at create time — the “come up with my standard records already in place” shortcut for another mail platform, a verification record set, or any third-party service records. It is the general form of the built-in mail presets above: instead of Microsoft 365 or Google Workspace, an admin defines the exact records once and tenants pick that template when adding a domain.

Defining templates (admin). Server Settings → DNS → DNS templates. Each template has a name, an optional description, and an ordered set of records; each record is Type (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA), Name, Value, TTL, and Priority (used by MX and SRV). A template may hold up to 100 records. Every record is validated on save with the same ValidateDNSRecord rules a tenant’s own DNS records use, so a template can never carry a record the record API would reject; when the server rejects one, the exact reason (record 3: …) is shown inline.

Use the {domain} token in a record’s name or value and it is replaced with the zone’s own name when the template is seeded (e.g. an MX of mail.{domain}, or a CNAME whose value is {domain}).

Selecting a template (tenant or admin). When adding a Web Domain (with “Add Mail Domain” unchecked) or a DNS Zone, the admin-defined templates appear under a Custom templates group in the same Template / DNS Template select as the mail presets. Choosing one sets the domain’s mail posture to external (like Microsoft 365 / Google Workspace — the template, not Jabali, owns the apex mail records) and records mail_template_id on the domain. A template requires the panel to host the zone, so the template options are disabled while “Add DNS Zone” is unchecked. Over the API this is the dns_template_id field on POST /domains; on the CLI it is jabali domain create --dns-template <id> (mutually exclusive with --mail, requires --manage-dns).

Seeding is once, at bootstrap. The reconciler copies the template’s records into the fresh zone the first time it is built, substituting {domain}. The seeded records are tenant-owned (managed_by unset) — the tenant edits or deletes them afterwards like any hand-added record, and the panel never re-asserts them. Deleting or editing the template later does not touch domains already created from it. Templates are global: every tenant sees every admin-defined template (a template is a convenience — a tenant can already type any of those records into their own zone by hand — so there is no per-package entitlement on it).

Cache invalidation

PowerDNS auth caches answers for cache-ttl (default 60 s). After any panel-side mutation (record add/update/delete, zone create/delete) the agent runs pdns_control purge <zone>$ so callers don’t see stale data for up to 60 s. This is the “PDNS cache after backend write” rule, without it, fresh records appear stuck.

Recursor forwarders

The recursor uses /etc/powerdns/recursor.forwards, populated by jabali pdns backfill from the panel DB. Use this if you want to forward specific zones to an internal resolver (e.g. for split-horizon DNS).

  • dns.zone.upsert, create or update a zone.
  • dns.zone.delete, drop a zone.
  • dns.dnssec.enable / dns.dnssec.disable, per-domain DNSSEC.

All zone mutations go through the agent so the cache purge is automatic and atomic.