---
title: "Records"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Records

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.

```sh
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](/dns-api/ChangeRecordSets/) takes up to 1,000 upserts and deletes in one
request, and either all of them apply or none do:

```json
{
  "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](/dns-api/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:

```sh
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:

```json
{ "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:

```sh
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](/dns/dnssec) makes when it signs the
  zone.
- Types not listed under [Types](#types).
- Names outside the zone.
- Anything that breaks the [rules](#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:

```sh
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](/dns-api/ExportRecordSets/) answers the zone file.
[ParseZoneFile](/dns-api/ParseZoneFile/) and [ScanRecordSets](/dns-api/ScanRecordSets/)
change nothing: each answers a proposal, which you review and apply with
[ChangeRecordSets](/dns-api/ChangeRecordSets/):

```json
{
  "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.

Source: https://docs.ezghcloud.com/dns/records/index.mdx
