Skip to content

Records

Record sets, the types EZGH DNS serves, TTLs, the rules a change must pass, zone file import and export, scanning for existing records, and how changes reach the internet.

Updated View as Markdown

A record set is the records at one name and type, with one TTL. name is relative to the zone, and @ is the zone itself.

ezgh dns records set example.com www A 192.0.2.10 192.0.2.11 --ttl 300
ezgh dns records delete example.com www A --yes

Setting a record set replaces all its values. With the API, ChangeRecordSets takes up to 1,000 upserts and deletes in one request, and either all of them apply or none do:

{
  "changes": [
    { "action": "upsert", "name": "www", "type": "A", "ttl": 300, "values": ["192.0.2.10"] },
    { "action": "delete", "name": "old", "type": "CNAME" }
  ]
}

Types

Type Value
A An IPv4 address: 192.0.2.10
AAAA An IPv6 address: 2001:db8::1
CNAME A hostname: target.example.net.
MX A preference and a hostname: 10 mail.example.com.
TXT Plain text, without surrounding quotes. A long value needs no splitting.
NS A hostname, to delegate a subdomain: ns1.example.net.
SRV Priority, weight, port and target: 10 5 443 server.example.com.
CAA Flags, a tag and a value: 0 issue "letsencrypt.org"
PTR A hostname: host.example.com.
DS A delegated subdomain’s DS: 12345 13 2 49FD46E6…

Rules

Rule Detail
TTL 60 to 86,400 seconds
CNAME Alone at its name, and never at @
DS Only with an NS at the same name
Apex SOA and NS Managed for you, and refused in a change. The zone’s nameservers lists the apex NS, and GetZoneSoa reads the SOA.
Names Stored in lowercase

Records managed by Web Certificates

A Web Certificates domain authorization linked to a zone keeps its validation records there: a TXT at _acme_request_ezgh.<domain> and a CNAME at _acme-challenge.<domain>. Link one when you create or change it, in the console or with the CLI, which needs dns.records.update on the zone:

ezgh certificates domains create example.com --dns-zone auto
ezgh certificates domains update dau_0123456789ab --no-dns-zone

auto picks the project’s zone that covers the domain. These record sets show Web Certificates in the console and a managedBy in the API:

{ "service": "certificates", "resourceName": "ezgh::org_0123456789ab:dau_0123456789ab" }
You Answer
Change or delete a managed record set, or add another type at a managed CNAME’s name 409 managed_record_set
Import a zone file or scan Managed names are listed in skipped
Delete the zone 409 zone_has_managed_records, naming the authorizations

Unlinking the authorization leaves the records in the zone as your own. Deleting the authorization removes them.

Zone files

ezgh dns zones export prints a zone as a complete BIND zone file, SOA included, and ezgh dns records import reads one:

ezgh dns zones export example.com > example.com.zone
ezgh dns records import example.com example.com.zone

In the console, Export and Import sit above a zone’s records, and Import ends on the same review. It can also scan your domain’s current nameservers, or add a mail provider’s records.

Import shows what it would change and what it left out, then asks; --yes confirms without asking. It creates or replaces the record sets in the file, and leaves the zone’s other record sets as they are. Applying them is one change: all of it applies, or none does.

Limit Detail
Size 256 KiB and 1,000 record sets
$ORIGIN The zone, unless the file sets it
$INCLUDE Refused
A file that doesn’t parse Refused, naming the line

Import leaves out, and lists:

  • The apex SOA and NS, which are managed for you.
  • RRSIG, NSEC, NSEC3 and DNSKEY records, which DNSSEC makes when it signs the zone.
  • Types not listed under Types.
  • Names outside the zone.
  • Anything that breaks the rules.

A TTL outside 60 to 86,400 seconds moves to the nearest bound. Records of one set with different TTLs take the lowest, and a repeated value is dropped. Import lists each of these too.

Scan for existing records

ezgh dns records scan finds what a domain answers now, from the nameservers its parent zone names, and loads it the way import does:

ezgh dns records scan example.com

DNS can’t list a zone, so a scan asks for common names: A, AAAA, MX, TXT and CAA at @, and names such as www, mail and api, DMARC and DKIM records, and common SRV names. It takes up to about 8 seconds, and shows what it found by then. A wildcard record is found as *, and names that only match it aren’t listed.

A scan can miss names, so compare the result with your current provider. A zone file from them, where they offer one, is complete. A domain that has no nameservers yet, or that already uses EZGH DNS, finds nothing.

With the API

ExportRecordSets answers the zone file. ParseZoneFile and ScanRecordSets change nothing: each answers a proposal, which you review and apply with ChangeRecordSets:

{
  "recordSets": [{ "name": "www", "type": "A", "ttl": 300, "values": ["192.0.2.10"] }],
  "skipped": [{ "name": "@", "type": "SOA", "reason": "the zone's own SOA is managed for you" }],
  "adjusted": [{ "name": "www", "type": "A", "reason": "TTL 30 moved to 60" }]
}

The record sets are valid together, so applying them as upserts is refused only for how they meet what’s already in the zone, such as a CNAME at a name that has other records. A scan that couldn’t ask everything in time adds a note to skipped with an empty type. Neither call takes an Idempotency-Key.

How changes reach the internet

A change reaches the zone’s nameservers in seconds. Resolvers keep what they’ve cached until its TTL runs out, so a TTL lowered ahead of time is what makes a change quick to take effect. A resolver can also remember that a name didn’t exist for up to 300 seconds, so a new name can take that long to appear for someone who looked it up just before.

Writes also work on a pending zone. Its records are served within seconds of it going active.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close