dnsconfig.js import and export

dnsconfig.js import and export evaluates the release runtime’s supported DNSControl declarations into managed-zone drafts and renders a saved zone back to JavaScript. Imports run in a three-second browser Worker with no network access. Exports contain records and settings but never connection credentials.

Export a saved zone#

Open Zones → a zone → Config as code. The dnsconfig.js section renders the saved zone and offers Download. Unsaved browser edits are excluded, so select Save changes first when they belong in the file.

The exporter converts each attached provider to its DNSControl type, derives a safe declaration key from the connection label, and emits no token, password, account secret, or service-account document. A small result looks like this:

// Generated by DNSMigrator. DNSControl-compatible dnsconfig.js.

var REG_NONE = NewRegistrar("none");
var DSP_PRODUCTION_DNS = NewDnsProvider("production_dns", "CLOUDFLAREAPI");

D("example.com", REG_NONE,
  DnsProvider(DSP_PRODUCTION_DNS),
  DefaultTTL(300),
  NO_PURGE,
  A("@", "192.0.2.10"),
  CNAME("www", "@"),
  MX("@", 10, "mx1.mail.example.net."),
  TXT("@", "v=spf1 include:_spf.example.net -all"),
  CAA("@", "issue", "letsencrypt.org")
);

The release exporter represents provider assignments and nameserver counts, default and per-record TTLs, explicit nameservers, ignore rules, external-dns ownership, purge and ignore-safety settings, DNSSEC intent, import transforms, absent markers, aliases, Cloudflare proxy/comment metadata, Hurricane Electric dynamic flags, and Route 53 weighted routing with an optional health-check ID.

Unsupported metadata or record functions produce warnings above the code. Keep the file in version control if useful, but configure credentials separately when running it with DNSControl.

Import dnsconfig.js#

A single import action accepts at most 100 zones and still enforces the workspace’s managed-zone limit.

Provider declarations should include a type, for example NewDnsProvider("production", "CLOUDFLAREAPI"). When it is absent, the runtime tries the declaration name and known name hints. A guessed type warns. Unknown and non-DNS declarations are not attached to the zone and also warn.

Load a config into an existing zone#

Inside a zone, select Config as code → Load from dnsconfig.js, evaluate the script, then select Load example.com into the editor. The button appears only when a D() name matches the current normalized zone.

This keeps the current zone name and attached provider connections while loading the declaration’s records and supported settings into the browser draft. Review it under Records, then select Save changes. Loading does not contact a provider.

Supported domain and control functions#

“Supported” below means the release runtime maps the call into its desired-zone model. Provider capability checks still happen later.

CLI_DEFAULTS() reports variables missing from the runtime options, but the web UI has no field for supplying them. PANIC() stops evaluation. getConfiguredDomains() returns names declared so far.

Supported record constructors#

The standard and extended constructors mapped into canonical records are:

A AAAA ALIAS CAA CNAME DHCID DNAME DNSKEY DS FRAME HTTPS LOC MX NAPTR NS
OPENPGPKEY PTR RP SMIMEA SOA SRV SSHFP SVCB TLSA TXT URL URL301

The provider-specific constructors mapped in this release are:

ADGUARDHOME_A_PASSTHROUGH ADGUARDHOME_AAAA_PASSTHROUGH
AKAMAICDN AKAMAITLC AZURE_ALIAS CF_REDIRECT CF_SINGLE_REDIRECT
CF_TEMP_REDIRECT CF_WORKER_ROUTE CLOUDNS_WR LUA MIKROTIK_FORWARDER
MIKROTIK_FWD MIKROTIK_NXDOMAIN R53_ALIAS

The obsolete DNS SPF() constructor is not registered; use TXT() or SPF_BUILDER. CERT(), URI(), and MXE() are also not runtime globals even though those canonical types exist elsewhere in the release model.

Three names are recognized for compatibility but are deliberately skipped during collection with a warning: BUNNY_DNS_PZ, BUNNY_DNS_RDR, and PORKBUN_URLFWD. They do not create managed-zone records in this release.

Cloudflare compatibility modifiers#

The Worker exposes these Cloudflare names:

CF_PROXY_OFF CF_PROXY_ON CF_PROXY_FULL
CF_CNAME_FLATTEN_OFF CF_CNAME_FLATTEN_ON
CF_PROXY_DEFAULT_OFF CF_PROXY_DEFAULT_ON
CF_UNIVERSALSSL_OFF CF_UNIVERSALSSL_ON
CF_MANAGE_COMMENTS CF_MANAGE_TAGS CF_COMMENT CF_TAGS

Their release behavior is not uniform:

• CF_PROXY_ON, CF_PROXY_FULL, and CF_PROXY_OFF map per-record proxy metadata.
• Domain-level CF_PROXY_DEFAULT_ON marks A, AAAA, and CNAME records proxied when they have no explicit proxy value.
• CF_COMMENT() maps to the canonical record comment and is emitted again by the exporter.
• Domain-level flattening, Universal SSL, and manage-comments/manage-tags values are retained as generic zone metadata, but the managed-zone planner does not act on them.
• Per-record CF_TAGS() has no canonical equivalent; collection warns and drops it. CF_MANAGE_TAGS does not make record tags round-trip.

Browser sandbox limits#

Each evaluation creates a new module Worker. The Worker passes only runtime globals as parameters to a strict Function, posts a JSON-cloned result, and is terminated after success, failure, or three seconds.

The worker removes fetch, XMLHttpRequest, WebSocket, EventSource, importScripts, IndexedDB, Cache Storage, broadcast channels, nested workers, WebTransport, navigator, and location. The runtime versions of FETCH() and lowercase fetch() also throw.

Known import deviations#

The release browser runtime intentionally differs from a full DNSControl process:

• require(), require_glob(), and glob() throw because there is no filesystem. Combine required content into one script.
• FETCH() and lowercase fetch() throw because network access is blocked.
• HASH() is exposed only as an unavailable function and throws.
• IGNORE_NAME_DISABLE_SAFETY_CHECK() throws with guidance to use domain-wide DISABLE_IGNORE_SAFETY_CHECK.
• SPF flattening in the synchronous browser collection path has no DNS resolver. It keeps the unflattened policy and warns. The interactive SPF builder can resolve includes.
• Provider and domain names are normalized to lowercase DNSMigrator names. Unknown provider types are warned about and not attached.
• Empty-value passthrough and NXDOMAIN constructors can be collected, but the managed-zone save guard later rejects their empty values.

Known export losses#

The generated callout reports these release exporter losses:

• routing policies other than Route 53 weighted routing are dropped with a warning;
• an HE dynamic-DNS key is withheld unless an internal caller explicitly enables secret export, which the web UI does not;
• a canonical SPF record is emitted as TXT();
• a CAA flag other than 0 or 128 is represented as CAA_CRITICAL and warns;
• the SOA serial is omitted because the constructor lets DNSControl manage it;
• records outside the zone are skipped;
• a canonical type with no constructor, including CERT, URI, or MXE, is left as a JavaScript comment; and
• record tags cannot be exported because the release canonical metadata has no tag field.

Resolve warnings before treating export followed by import as a round trip. For a data-only copy, use a BIND zone file; its parser has a separate, shorter record-type list.