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 --yesSetting 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-zoneauto 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.zoneIn 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
SOAandNS, which are managed for you. RRSIG,NSEC,NSEC3andDNSKEYrecords, 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.comDNS 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.