> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # DNS > Authoritative hosted zones signed with DNSSEC, with health-checked failover, geo-routed answers, and private zones scoped to a VPC. DNS hosts authoritative zones for your domains. Every zone is signed with DNSSEC from the moment it exists, records can fail over on a health check, and a zone can be made private so it answers only inside your VPCs. The service is **global** — one endpoint, `dns.basaltic.sh`, no region segment. The public namespace is not regional. Proving you own the domain, and the two ways to do it. RRsets, the values array, and the one rule that breaks zones silently. Priority tiers, what gets answered, and what `served` tells you. Answer variants scoped to client prefixes, and how they stay DNSSEC-valid. Always on. What to paste at your registrar to close the chain. ## Creating a zone Go to **DNS** and choose **Create Zone**. Under **Zone details**, enter the fully-qualified **Name** — `example.com`, not a hostname inside it. There is no DNSSEC switch to find. The create page describes itself as *signed with DNSSEC by default* and its summary row reads **DNSSEC**: **Enabled**. Once the zone exists, its **Settings** tab carries the **Nameservers** card with the names to copy into your registrar. ```bash theme={null} POST https://dns.basaltic.sh/v1/zones { "name": "example.com" } ``` The SOA and apex NS records are generated for you against the platform nameserver list, and the zone is queryable on success. The response carries a `nameservers` array — that is what you copy into your registrar to delegate the domain. A new zone with no zone above it on the platform **does not resolve** until you prove you own the domain. Creating it is not claiming it. ### Proving ownership The proof exists so nobody can create a zone for a subdomain of a domain they do not own and sit inside your subtree. Which method you use depends on where the domain points **right now**. The zone's `ownership` block names a TXT record. Publish it at your current provider — before you delegate anything — then call verify: ```dns theme={null} _basaltic-challenge.example.com. TXT "" ``` ```bash theme={null} POST /v1/zones/{zone_id}/verify-ownership ``` The call is idempotent, so you can poll it. There is nowhere to publish that TXT — we are the domain's DNS, and an unverified zone does not answer, so the record could never resolve. Use `ownership.claim_nameservers` instead: set those as the domain's nameservers at your registrar, then call verify. Those names reach the same servers as the zone's `nameservers`, but they are **unique to this zone**, and that is what makes them proof. Anyone can point a domain at our published nameservers, so a delegation naming those shows only that somebody did so at some point — possibly a previous owner who never updated their registrar. A delegation naming these can only have been set for this zone, by whoever holds the domain now. The delegation may stay on these names permanently. Nothing to do. A zone created underneath a zone you already own inherits its parent's proof and is verified on creation. Calling verify on one succeeds with nothing to do. `verify-ownership` is **API only**. The console creates zones and shows their nameservers, but has no button that runs the check — so a zone created there still needs this call before it answers. **The proof is a lease, not a deed.** It is re-confirmed periodically for as long as the zone is served, so a domain that lapses or changes hands stops being served from here. ### When re-confirmation starts failing A zone whose periodic re-proof is failing grows an `ownership.recheck_deadline` — the instant it stops answering unless the check passes again. Absent means healthy. Reaching that date takes sustained failure, not one bad afternoon: every pass re-checks a failing zone, so a transient resolver problem clears itself. Your organization's owner is emailed when the deadline is set, and again if the zone does stop resolving — a zone is never taken off the air before that message has gone out. To clear it deliberately, republish the challenge (or point the delegation back at our nameservers) and call `verify-ownership` again. That is the one case where an already-verified zone can answer `400`, because there the call runs the check for real. ## Records A record is an **RRset**: one name, one type, and a `values` array. Updating a record replaces the value list wholesale. Open the zone from **DNS** and choose **Add Record**. Give it a **Name** — a subdomain like `www`, or `@` for the apex — pick a **Type**, and put one entry per line in **Values**. That list is the RRset. **TTL** is optional. ```bash theme={null} POST /v1/zones/{zone_id}/records { "name": "www.example.com", "type": "A", "ttl": 300, "values": [ { "content": "203.0.113.10" }, { "content": "203.0.113.11" } ] } ``` A value can be `disabled: true` — retained but not served, which is useful for staging a change before it goes live. **A CNAME cannot share a name with any other record, and cannot sit at the zone apex.** The API refuses both, because the breakage is silent otherwise. The signer stamps each name's NSEC with a bitmap of the types that name holds. A CNAME beside an A yields a bitmap reading "CNAME and A", and a validating resolver treats that owner as bogus and answers SERVFAIL. The zone loads, the records look correct in the API, and the name simply stops resolving for anyone who validates. This is RFC 1034 §3.6.2 and RFC 2181 §10.1. At the apex the conflict is unavoidable — the SOA and NS sets are always there — so point the apex at addresses with `A`/`AAAA` records. ### Platform-managed records Records with `managed: true` are read-only: the SOA, the apex NS set, and the whole DNSSEC family. They appear in reads so you can see the zone as it really is, but they cannot be created, updated or deleted through the API. ## Importing a zone file `POST /v1/zones/{zone_id}/import` takes an RFC 1035 master file — the BIND format every provider exports. Open the zone from **DNS** and choose **Import zone file**. Paste the file into the box, or load one from disk with **Choose a file**, then choose **Import**. The dialog then reports how many record sets it added and how many it replaced, and lists anything it skipped with the reason. Send it as JSON in `zone_file`, or as the raw body under any other content type, so this works directly: ```bash theme={null} curl --data-binary @db.example.com \ -H 'Content-Type: text/plain' \ https://dns.basaltic.sh/v1/zones/{zone_id}/import ``` An RRset in the file replaces the RRset at the same name and type wholesale; an RRset the file does not mention is left exactly as it is. So an import **cannot delete a record**, and importing the same file twice is a no-op rather than an error — which is what makes it safe to retry. The whole file is validated before a single record is written: every record faces the same type, name, TTL and rdata checks that creating one does, the same CNAME rule, and the same record quota. One bad record refuses the file and the zone is untouched. The SOA and apex NS set are the platform's — the zone is served by our nameservers, and the apex NS is what the parent delegates to. The DNSSEC records (`RRSIG`, `DNSKEY`, `DS`, `NSEC`, `NSEC3`, `NSEC3PARAM`, `CDS`, `CDNSKEY`) are generated by our signer from keys your file cannot know. Records placed outside the zone are skipped too. Every one comes back in `skipped` with a reason. A file exported from a signed zone carries all of them, so refusing the file over them would make export/import unusable. The file is capped at **1 MiB**. On success the SOA serial advances once for the whole import. ## Health-checked failover Attach a check to an `A` or `AAAA` record and the nameservers stop answering with targets that are down. Health checks are **API only**. The console's zone page creates, edits and deletes records; it does not attach checks to them. ```bash theme={null} PUT /v1/zones/{zone_id}/records/{record_id}/health-check { "protocol": "https", "port": 443, "path": "/healthz", "matcher": "200-299", "targets": [ { "content": "203.0.113.10", "priority": 0 }, { "content": "203.0.113.20", "priority": 1 } ] } ``` **Lower priority wins.** Values sharing a priority form one tier and are answered together, so `0` and `1` is a failover pair while `0` and `0` is active/active. The nameservers answer with the healthy targets at the most-preferred tier, fall through to the next tier when those go unhealthy, and — if nothing is healthy anywhere — answer with every configured value rather than nothing. `GET` on the health check returns a `served` array: the values the nameservers are answering with *right now*. The record's own `values` stay whatever you configured. The difference between the two **is** the failover, so it is reported rather than left for you to infer. A UDP probe cannot tell a healthy target from a silent one. Only `http`, `https` and `tcp` are offered. The probe dials an address, not a name, so there is no name to validate against. It measures whether the target is serving, not who it is. The prober runs in the control plane and could never reach an address inside a tenant VPC, so a check on an RFC 1918 or unique-local address is rejected rather than accepted and left permanently unhealthy. A target no probe has reached a verdict on is `initial`, and `initial` is **answered**. A freshly created record resolves immediately instead of being dark until the first probe lands. Every health transition re-signs the whole zone. `healthy_threshold` and `unhealthy_threshold` (both default `3`) decide how many consecutive results it takes to move, and `timeout_sec` must stay below `interval_sec` or a slow target's probes overlap each other. ## Geo routing A record can carry named **answer variants**, each scoped to a set of client prefixes, so a query is answered with the values closest to whoever asked. Geo routing is **API only**. The console shows a record's default values, not its variants. ```bash theme={null} PUT /v1/zones/{zone_id}/records/{record_id}/geo-routing { "answers": [ { "label": "eu", "values": ["198.51.100.10"], "prefixes": ["185.0.0.0/8"] }, { "label": "apac", "values": ["203.0.113.10"], "prefixes": ["1.0.0.0/8", "14.0.0.0/8"] } ] } ``` The record's own `values` stay the **default** — what a query matching no prefix is answered with, which is most of the internet. So `answers` describes overrides, never the fallback; the fallback cannot be deleted, and `default` is a reserved label. `PUT` replaces the whole configuration, and `GET` reports the default alongside the variants rather than leaving it implicit. Only `A`, `AAAA` and `CNAME` records can carry variants — those are what "send this client somewhere closer" means. A variant only changes rdata, so nothing structural stops `MX` or `SRV`, but each brings its own question and none is what this is for. ### How a client is matched Selection is **longest-prefix match**, so overlapping prefixes of different lengths are meaningful rather than a conflict — a `/8` and a `/16` inside it do what you would expect. The same prefix on two variants is rejected, because that would make the answer depend on row order and let two nameservers disagree about one query. Matching uses the **EDNS Client Subnet** prefix when the resolver sends one, and the query's source address otherwise. A rule more specific than what the resolver actually asserted is skipped, not matched: beyond the ECS source netmask the address is zeros the resolver never claimed, and matching them would route a whole `/8` to whichever `/24` happens to sit at its base. Write prefixes as the **network address** — `185.0.0.0/8`, not `185.1.2.3/8`. Prefixes cannot be longer than **`/24`** for IPv4 or **`/56`** for IPv6. That is the ECS privacy convention, and it is also what keeps resolver caches correct: the scope length echoed back is the record's longest configured prefix, so an unbounded prefix would force per-host caching on every resolver that talks to us. ### Why the limits are what they are Each variant is signed separately, so a record with N variants is N+1 RRsets to mint on every re-sign of the zone — and a health flip or a record edit re-signs the whole zone. The prefix list is scanned per query, on an unauthenticated UDP packet. It is deliberately a short linear scan over a list sorted longest-first at load, rather than anything that grows with what was configured. Nothing routes to it, and it would cost a signature on every re-sign to never be answered. Refusing it is more useful than carrying it silently. A variant is still a CNAME RRset, and RFC 1034 §3.6.2 allows a CNAME RRset exactly one value. The constraint is on the answer, not on the row that configured it. **Geo answers stay DNSSEC-valid.** Each variant is signed at write time and a response carries exactly one variant's RRset together with *that variant's* signature. Filtering one signed RRset per query — the obvious implementation — would answer with data the shipped signature does not cover, which is SERVFAIL for every validating resolver. Because a variant changes only rdata and never which names or types exist, the NSEC denial chain is identical whichever variant is served. ## Private zones A zone is `public` or `private`, fixed at creation. ```bash theme={null} POST /v1/zones { "name": "internal.example.com", "visibility": "private", "vpc_ids": ["c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9"] } ``` A private zone answers only inside the VPCs associated with it, and needs at least one at creation. Attach or detach more later through the `vpc-associations` endpoints. `visibility` is **API only**. The console's **Create Zone** form takes a name and nothing else, so every zone made there is public — and because visibility is fixed at creation, that is not something you can change afterwards. The two mismatches are rejected rather than quietly corrected: a `private` zone with no `vpc_ids`, and a `public` zone that carries them, both answer `400`. ## DNSSEC DNSSEC is **on for every zone created through this API** — there is no switch, and no unsigned mode. The signer bootstraps the zone and the `dnssec` block appears on it, carrying the key tags, the algorithm (`13`, ECDSA P-256 SHA-256), and the DS records. To complete the chain of trust, paste the DS record at your **parent registrar**: ```bash theme={null} GET /v1/zones/{zone_id} ``` `dnssec.ds_records` holds them. Each also carries `rdata` — the zone-file form of the same record, for registrars that want a single string. This is the one DNSSEC step that cannot be done from here: only the parent zone's operator can publish a DS record, and for a public suffix that is your registrar. Once the DS is live, resolvers can validate the chain from the root down to your records. Until the DS record is published at the registrar, your zone is signed but **not validated** — resolvers have no way to reach your keys from the root. Signing without a DS buys nothing. ## Limits and behaviour Larger files are refused. Checked on both single-record creation and import, against your organization's quota. Minimum `0`. Deletes every record it owns, in a single cascading delete. ## Troubleshooting Check `ownership.verified`. A zone with no zone above it on the platform does not answer until ownership is proved — creating it is not claiming it. See [proving ownership](#proving-ownership) for which of the two methods applies to you. That pattern — works for non-validating resolvers, fails for validating ones — is the signature of a CNAME sharing a name with another record. The API refuses new ones, but a zone imported or migrated in unusual ways is worth checking. List the records at that name and make sure the CNAME is alone. Almost always a missing or stale DS record at the registrar. Compare what the registrar publishes against `dnssec.ds_records` on the zone — a DS left over from a previous provider breaks validation exactly as thoroughly as none at all. `GET` the health check and read `served` against the targets' `status`. A target still in `initial` has no verdict yet and is answered on purpose. Remember thresholds default to three consecutive results, so a flapping target takes three intervals to move in either direction. Most resolvers do not send EDNS Client Subnet, so selection falls back to the resolver's own source address — a client using a distant public resolver is matched where that resolver sits, not where the client is. Check `GET` on the geo routing: `default` is the answer the bulk of the internet receives, and it is the one to get right. Also confirm the prefix is written as a network address: `185.1.2.3/8` is not the same rule as `185.0.0.0/8`. Working as intended — import merges and never deletes. An RRset absent from the file is left alone. Delete records explicitly through the record endpoints. ## Next A zone on our DNS gets its ACME challenge CNAME created automatically. Every zone and record operation, with schemas.