# DNS

keel DNS hosts the zones of your domains on keel's own nameservers: four nodes at two providers in four European cities, each answering from its last good state even if the rest of the platform is down. You manage zones in the dashboard, with the CLI, the API or an agent over MCP. DNSSEC is on by default.

keel DNS is not a registrar. You keep your domain where it is and point it at keel's nameservers.

## Create a zone

```bash
keel dns zone create example.com
keel dns zone create example.com --import example.com.zone   # with the export of your old provider
keel dns zone create shop.example.com --project shop --no-dnssec
```

The answer lists **four nameservers**, for example:

```
terbium.keeldns.net
dysprosium.keeldns.net
holmium.keeldns.net
erbium.keeldns.net
```

Every zone gets its own group of nameservers (the letter differs between zones). Set exactly these four at your registrar and remove all others. Until the delegation matches, the zone is `pending_delegation`: you can already add records and test them with `keel dns query`, but keel does not serve the zone yet.

### Why the zone waits for the delegation

All customers share the same nameservers. So that nobody can take over a domain by creating a zone for it, a zone is only served once the parent zone delegates to **its** nameserver group, which is chosen at random when the zone is created. Setting the nameservers at the registrar is what proves the domain is yours; no TXT record is needed.

keel checks the delegation every two minutes in the first hour, then every 15 minutes. To check now and see what the parent zone returns:

```bash
keel dns zone verify example.com
```

```
Delegation of example.com: status pending_delegation
  expected nameservers:
    terbium.keeldns.net          ok
    dysprosium.keeldns.net       ok
    holmium.keeldns.net          missing
    erbium.keeldns.net           missing
  other nameservers at the parent (remove them):
    ns1.oldprovider.example
```

Registrar changes can take up to a day to show. If the delegation of an active zone stops matching for seven days, the zone becomes `delegation_lost` (it is still served) and you get an e-mail.

### Registrars

| Registrar | Where to set nameservers | DNSSEC (DS record) |
|---|---|---|
| INWX | Domain → Nameserver → "Use other nameservers" | Domain → DNSSEC → add key (DS) |
| Namecheap | Domain List → Manage → Nameservers → "Custom DNS" | Advanced DNS → DNSSEC (Custom DNS only) |
| GoDaddy | Domain → DNS → Nameservers → "I'll use my own nameservers" | DNS → DNSSEC → add DS record |
| Strato | Domain → Domainverwaltung → Nameserver → "Externe Nameserver" | DNSSEC → DS-Eintrag hinzufügen |
| IONOS | Domains → Nameservers → "Use custom nameservers" | Domain → DNS → DNSSEC (external DS) |

Menu names change from time to time; your registrar's help has the current path.

## Records

keel DNS works with **RRsets**: all records of one name and type share a TTL. Names are relative to the zone (`www`, `@` for the apex, `*.dev` for a wildcard). Record data is written as in a zone file.

```bash
keel dns records example.com
keel dns record add example.com www A 192.0.2.1 --ttl 300
keel dns record add example.com @ MX "10 mx1.example.net." "20 mx2.example.net."
keel dns record set example.com @ TXT "v=spf1 include:_spf.example.net -all"   # replaces the RRset
keel dns record rm example.com old CNAME
```

`record add` fails if name and type exist; `record set` replaces them. TXT data without quotes is quoted for you. TTLs range from 60 seconds to one week; the zone's default is 3600 seconds (`keel dns zone update example.com --default-ttl 600`).

| Type | Notes |
|---|---|
| A, AAAA | |
| CNAME | alone at its name, never at the apex, one record |
| MX, SRV, CAA, TXT | TXT strings longer than 255 bytes are split automatically |
| NS, DS | only below the apex, to delegate a subdomain elsewhere |
| SVCB, HTTPS | RFC 9460 |
| TLSA | only under `_port._proto.name`; useful only with DNSSEC |
| ALIAS | at any name, typically the apex: points at a keel service (`svc_…` or its generated hostname) and is answered as A/AAAA |

PTR, NAPTR, SSHFP and other types are not supported; an import lists them as skipped.

Records created by keel – for a custom domain of a service, or for mail – are **managed**: you see them with the owner in the "managed by" column and change them through their owner. If you already have a record with the same name and type, keel does not overwrite it and shows a conflict instead.

Changes reach all nameservers within seconds. Test the current state of the zone, also before it is delegated:

```bash
keel dns query example.com www A
keel dns query example.com @ MX --dnssec
```

## Custom domains of services

When you add a custom domain to a service and the hostname is in one of your active zones, keel creates the records itself: a CNAME for subdomains, an ALIAS for the apex. The domain counts as verified (you own the zone), and certificates are issued over DNS-01, so wildcard domains like `*.example.com` work too. In the dashboard, the "Add domain" dialog offers this automatically.

## Import and export

```bash
keel dns import example.com example.com.zone            # adds what is missing, reports conflicts
keel dns import example.com example.com.zone --replace  # replaces all records not managed by keel
keel dns export example.com > example.com.zone
```

Imports take BIND zone files (RFC 1035, `$ORIGIN` and `$TTL`; `$INCLUDE` and `$GENERATE` are rejected), up to 4 MiB. SOA, the apex NS records and DNSSEC records of the old provider are skipped and listed. Exports are sorted deterministically and contain no DNSSEC records, so they are easy to keep in Git.

## DNSSEC

Zones are signed by default (ECDSA P-256, algorithm 13). To secure the domain, add the DS record at your registrar once the zone is active:

```bash
keel dns dnssec example.com
```

```
DNSSEC for example.com: signed_ds_missing

DS record for your registrar (key tag, algorithm 13, digest type 2, digest):
  2371 13 2 1F987CC6583E92DF0890718C4255C9D7B8B6F4C9D41E9FBE…
```

Some registrars ask for the DNSKEY instead; it is shown as well. Registries that scan CDS records (for example `.ch`, `.li`, `.se`, `.cz`) pick up the DS automatically. The state becomes `secure` when the DS at the parent matches; `ds_mismatch` means validating resolvers cannot resolve your domain – replace the DS with the one shown.

Zone-signing keys roll over automatically every 90 days without any change at the registrar. A key-signing key rollover (`keel dns dnssec rollover example.com --ksk`) needs a new DS record.

To turn DNSSEC off without breaking the domain, `keel dns dnssec disable example.com` publishes the delete signal and keeps signing until the DS is gone at the parent. `--force` (admin) switches off at once; the domain then fails for validating resolvers until you remove the DS.

## ACME DNS-01 and dynamic updates

keel DNS accepts RFC 2136 dynamic updates signed with a TSIG key, so cert-manager, certbot, lego, acme.sh, Caddy, Traefik and external-dns work without a keel-specific plugin.

```bash
keel dns tsig create example.com --acme
```

The key may only create TXT records under `_acme-challenge` (add `--name` to limit it to hostnames). The secret is shown once. The server is `update.dns.keel.run`, port 53, TCP only.

cert-manager:

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef: { name: letsencrypt-account }
    solvers:
      - dns01:
          rfc2136:
            nameserver: update.dns.keel.run:53
            tsigKeyName: tsig_01h….tsig.keeldns.net.
            tsigAlgorithm: HMACSHA256
            tsigSecretSecretRef: { name: keel-tsig, key: secret }
```

certbot (`certbot-dns-rfc2136`), with `rfc2136.ini`:

```ini
dns_rfc2136_server = update.dns.keel.run
dns_rfc2136_port = 53
dns_rfc2136_name = tsig_01h….tsig.keeldns.net.
dns_rfc2136_secret = <secret>
dns_rfc2136_algorithm = HMAC-SHA256
```

```bash
certbot certonly --dns-rfc2136 --dns-rfc2136-credentials rfc2136.ini -d example.com -d '*.example.com'
```

lego:

```bash
RFC2136_NAMESERVER=update.dns.keel.run:53 RFC2136_TSIG_KEY=tsig_01h….tsig.keeldns.net. \
RFC2136_TSIG_SECRET=<secret> RFC2136_TSIG_ALGORITHM=hmac-sha256. \
lego --dns rfc2136 -d example.com -d '*.example.com' --email you@example.com run
```

ACME TXT records older than 24 hours are removed automatically. List and delete keys with `keel dns tsig list example.com` and `keel dns tsig rm tsig_…`.

## Analytics

The dashboard and `keel dns analytics example.com --window 7d` show queries per hour by type and response code for the last 30 days. keel does not give out resolver IP addresses.

## Agents

Agents use the MCP tools `list_dns_zones`, `get_dns_zone`, `create_dns_zone`, `create_dns_record`, `set_dns_record` and the others listed in [Agents and MCP](/docs/agents). Creating zones and records needs the `dns:write` permission; deleting a zone needs `admin`. Replacing or deleting records is destructive: the agent shows you the old and new records and needs your confirmation, and with [approvals](/docs/agents) on, a person approves the change in the dashboard.

## Limits

| | Trial | Hobby | Pro |
|---|---|---|---|
| Zones | 1 | 10 | 100 |
| RRsets per zone | 200 | 2,000 | 50,000 |
| Records per RRset | 100 | 100 | 100 |
| TSIG keys per zone | 2 | 5 | 20 |
| New zones per day | 2 | 10 | 50 |

## Billing

You pay per active zone and per million queries; every plan includes some zones and queries. Zones waiting for their delegation are free. If a payment fails, your zones keep being served for 14 days, so mail and websites of the domain keep working while you sort it out. See [pricing](/pricing) for the current prices.
