DNS Management

The platform holds the DNS records a deployment needs and publishes them itself, through whichever DNS host the deployment uses. *It never becomes a nameserver — it holds desired state and writes it through a host that stays responsible for answering queries.

The value is not saved keystrokes. It is that a class of failure disappears: the one where the platform knows the right answer, the deployment's DNS says something else, and nothing connects the two. A record simply never published; a record published in a same-named sibling zone; a TXT value over 255 bytes published unquoted, accepted, stored and then never served. Each of those is a visible diff here.

The shape

ttl is optional, and that matters: a record that omits it means provider default, and a live record whose only difference from the plan is a TTL the plan never asked for matches. A zone left on default TTLs never shows permanent diff noise. MX priority behaves the same way.

Values are compared canonically, never textually. TXT quoting and chunking is stripped both ways, hostnames lose case and the trailing dot, MX priority lives in its own field. A provider handing a long TXT back as "aaa" "bbb" and a provider handing it back joined are describing the same record.

Producing a plan

Any subsystem can produce one. There is no registration step.

require_once(PathHelper::getIncludePath('includes/dns/DnsRecordPlan.php'));

$plan = new DnsRecordPlan('example.com', 'myplugin');   // domain, owning subsystem
$plan->addRecord('MX', 'example.com', 'mail.example.com', null, 10, 'Inbound mail');
$plan->addRecord('TXT', 'example.com', 'v=spf1 ip4:1.2.3.4 -all', null, null, 'SPF');

The last argument is a note. It is rendered next to the record in the diff and never compared, so it is where you explain why the record exists in the operator's terms.

Two rules for a plan author:

• Stay inside the domain's own zone. A record whose name is not the domain or a name beneath it does not belong in that domain's plan — publishing it would ask a credential to write somewhere it has no business.
• Never plan a placeholder. If a value is not known yet (no public IP, no relay hostname), leave the record out. Publishing YOUR_SERVER_IP into someone's zone is worse than publishing nothing.

// Actions. Returns a LogicResult to redirect on, or null when the request
// was not one of ours. The plan factory is only called when it is needed.
require_once(PathHelper::getIncludePath('includes/dns/DnsPublishBox.php'));
$dns_redirect = DnsPublishBox::handle($input, function () use ($id) {
    return MyPlanSource::forThing($id);
}, $return_url);
if ($dns_redirect !== null) { return $dns_redirect; }

// Render vars.
$dns_box = DnsPublishBox::build(MyPlanSource::forThing($id), $input, $return_url);

// In the view.
require_once(PathHelper::getIncludePath('includes/dns/dns_publish_box.php'));
dns_publish_box_render($page, $dns_box);

A pending row is recognised from the write receipt in dnr_dns_records, not from a session flag: the receipt is durable, survives the browser, and is the same row that already decides what the platform may overwrite. It applies only to the public-DNS diff — the provider's own view has no propagation delay, so a record absent there really is absent — and only for PENDING_WINDOW_MINUTES (60). Past that, an unresolvable record goes back to reading as missing, because by then something really is wrong. A receipt whose value no longer matches the plan is drift, not flight, and does not qualify.

settled() is what the page asks: every row either matches or is pending, so there is nothing left to press. The box then shows a receipt — 3 DNS records written at Cloudflare on Jul 26, 2026 1:23 AM — and no form, because offering a submit button for records already in flight is what makes a successful publish look like a failed one.

Reporting the result

The banner after a publish carries a severity, and it is part of the contract rather than styling. DnsPublishBox::resultSeverity() returns success only when every planned record is in place, a warning when some landed and some did not, and an error when nothing reached the provider at all. A refused credential rendered in success green reads as published and sends an operator away believing their DNS is live.

A provider that restricts a credential by client IP sees whichever address the outbound connection used. A server holding both an IPv4 and an IPv6 address may reach the API over either, so an allowlist written from the IPv4 address alone refuses the request — Cloudflare's 403 for this names the address it saw, and the driver reports it as an address restriction rather than a permission problem, because the two need opposite fixes. Cloudflare mishandles /48 and /64 ranges in that filter; list an IPv6 address on its own. Namecheap's allowlist has the same shape.

Ownership

The platform manages only records it created or adopted, and dnr_dns_records is what makes that enforceable. It never modifies or deletes a record absent from that table, and removing a domain withdraws only what is listed — and offers to delete the zone only when it holds no records the platform does not own.

Ownership is acquired by agreement, not only by authorship. A record whose live value is already exactly what the plan wants is adopted on first publish without touching DNS: the platform and the zone already agree, so recording responsibility is bookkeeping, not a change. Ownership strictly from authorship was rejected for punishing the deployments that did the work by hand — every correct record they published would sit permanently unowned, showing as a conflict the platform could not act on.

A record that exists and differs is a conflict, shown with both values and resolved only by an explicit adopt and overwrite choice.

Cutovers

Creating a TXT record breaks nothing. Replacing MX moves live mail. Records whose change redirects traffic that already flows — MX, and A/AAAA/CNAME for a name already resolving — are flagged, and each needs its own confirmation stating what currently receives and that it will stop. Ticking adopt on a conflicting record is not enough; a cutover is a separate decision.

The box configures a domain where it already lives

Before offering anything, the box works out where the domain's DNS actually is — it reads the domain's NS records and matches them against each driver's nameserverSuffixes(). That host becomes the provider it leads with. A domain on Cloudflare gets Configure DNS at Cloudflare, whatever the deployment default says.

A subdomain almost never has NS records of its own (mail.example.com lives in example.com's zone), so the lookup walks up the label chain until something answers. It stops before a bare TLD; a registry's nameservers match no driver, so an over-long walk identifies nothing rather than identifying something wrong.

Identification is a case-insensitive substring match, not an exact name, because most vendors assign per-zone nameservers — Cloudflare answers chuck.ns.cloudflare.com, Route 53 ns-123.awsdns-45.org. The fragments ns.cloudflare.com and awsdns- identify those hosts whatever the per-zone prefix is. When several drivers match, the longest fragment wins.

Moving a domain's nameservers is not something the platform offers. Configuring a domain at the host it already uses has no blast radius: the diff covers a handful of records and touches nothing else. Moving a zone takes the website and every other name with it, which is a decision that belongs with whoever runs that domain, made in their registrar — not a button next to a mail setup checklist. So the box never prompts for it and never shows a whole-zone warning, because there is no path here that would trigger one.

The consequence: the platform only ever writes into a zone someone else already runs, which is where the ownership, adoption and conflict machinery earns its keep — the zone is full of records the platform did not create.

When the domain's DNS host has no driver here, the box does not render at all — no empty panel, no explanation of what cannot happen. The page is the one it has always been: each check carrying the record to publish. That is a supported state, not a degraded one, and it needs no announcement.

The same is true when a page supplies no plan. dns_publish_box_render() returns before opening a box in both cases, so a caller can hand it whatever it has without guarding first.

Writing a driver

Drop a class into includes/dns/drivers/ implementing DnsProvider — usually by extending DnsDriverBase, or DnsRrsetDriverBase when the vendor stores record sets rather than individual records. The registry discovers it by interface and the provider chooser picks it up with no page change.

The static half declares capability, read before any credential exists:

public static function credentialGuide(): ?array {
    return array(
        'title'     => 'Create a Cloudflare API token',
        'url'       => 'https://dash.cloudflare.com/profile/api-tokens',
        'url_label' => 'Open Cloudflare API tokens',
        'steps'     => array('Sign in to Cloudflare and open My Profile, then API Tokens.', /* … */),
        'copy'      => array(),
    );
}

The shape is FormWriter's help_modal option, so the box passes it straight through and the kit modal renders it. copy rows are values the vendor's form needs from us — an allowlist IP, a callback URL — rendered as click-to-copy buttons, because a mistyped one fails in a way that looks like our bug. A credential never travels in a copy row; nothing there is ours to give.

Three rules for writing one:

• Steps are what the operator clicks, in order, in the vendor's own words for its buttons and menus.
• Name the exact scope. "Zone · DNS · Edit", not "DNS permissions".
• Say what not to pick where a wrong-but-adjacent credential exists — Cloudflare's Global API Key, GoDaddy's OTE environment, an AWS root key. That goes in caution, not in steps: a warning numbered among the clicks reads as an instruction to go and do it.

The detected host wins, so dns_default_provider is a fallback rather than the usual answer. It applies when the domain's host cannot be identified and* the resolver returned nothing at all — a brand-new domain, or a lookup that failed — because silence is not evidence that a host is unsupported.

It is a settings value holding a provider name, never a secret, and defaults to linode with no configuration. The chooser is populated from the driver registry, so making a different provider canonical is one setting change and adding a driver is one file.

An operator can always override both with "use another provider". The box then says plainly that the domain's DNS is hosted elsewhere and that records written to the chosen provider will not be answered — it does not silently accept the mismatch.

DNS hosting is independent of where compute runs: a Cloudflare zone can hold the A record for a node on Linode — the record simply points at that node's IP. Adding VPS providers changes nothing here.

Tests

• tests/dns/dns_records_test.php — the vocabulary, TXT canonicalization and splitting across every driver, zone longest-suffix matching, the TTL rule, Cloudflare's forced DNS-only, host identification for all fifteen providers, and that no driver's credential can be serialized, printed or stored.
• tests/dns/dns_reconciler_test.php — the four outcomes, adoption on exact match with no DNS write, conflicts and cutovers requiring their own choice, per-record best-effort apply, convergence on re-run, and withdrawal touching only owned records.
• tests/dns/dns_publish_banner_test.php — the severity of the banner a publish leaves behind: green only when the whole plan is in place, amber when it is partial, red when nothing reached the provider.