> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Change records with DNS UPDATE

You can create, change and delete records in your zone programmatically with
the standard DNS UPDATE protocol (RFC 2136). Changes are signed with a TSIG
key that only applies to your zone. It works with `nsupdate`,
Terraform/OpenTofu, ACME clients and most automation tools.

In the examples below the zone is `example.se` and the key is
`example-dnsupdate`. Replace them with your own values.

## Step 1: Request a key \{#steg-1-bestall-en-nyckel}

Open a ticket in the portal and say which zone the key should apply to. We
create the key and add it to your domain. For now this is done manually by
us. We are working on letting you manage keys yourself in the portal.

You receive three values:

| Value     | Example             |
| --------- | ------------------- |
| Key name  | `example-dnsupdate` |
| Algorithm | `hmac-sha512`       |
| Secret    | a base64 string     |

:::warning The secret is a password
Anyone who has the secret can change every record in your zone. Do not store
it in a git repository in plain text, and do not forward it by email. If you
think it has leaked, contact us and we will replace it right away.
:::

## Step 2: Save the key \{#steg-2-spara-nyckeln}

Most tools read the key in BIND format. Save it in a file, for example
`example.se.key`:

```
key "example-dnsupdate" {
  algorithm hmac-sha512;
  secret "<the secret>";
};
```

Make sure only you can read the file:

```bash
chmod 600 example.se.key
```

## Connection details \{#anslutningsuppgifter}

| Setting   | Value                                           |
| --------- | ----------------------------------------------- |
| Server    | `ns1.getgeek.se` (IPv4 and IPv6)                |
| Port      | 53, UDP and TCP                                 |
| Zone      | your domain, e.g. `example.se`                  |
| Key       | the name you received, e.g. `example-dnsupdate` |
| Algorithm | `hmac-sha512`                                   |

Always send updates to `ns1.getgeek.se`. The other name servers do not
accept DNS UPDATE.

## nsupdate \{#nsupdate}

`nsupdate` is part of the BIND tools: the package `bind9-dnsutils` on Debian
and Ubuntu, `bind-utils` on Rocky, Alma and Fedora, and `bind` in Homebrew.

Add a record:

```bash
nsupdate -k example.se.key <<EOF
server ns1.getgeek.se
zone example.se
update add www.example.se. 3600 A 192.0.2.10
send
EOF
```

Change a record. Delete the old one and add the new one in the same request,
so that either both happen or neither does:

```bash
nsupdate -k example.se.key <<EOF
server ns1.getgeek.se
zone example.se
update delete www.example.se. A
update add www.example.se. 3600 A 192.0.2.20
send
EOF
```

Delete a record:

```bash
nsupdate -k example.se.key <<EOF
server ns1.getgeek.se
zone example.se
update delete www.example.se. AAAA
send
EOF
```

`update delete <name> <type>` deletes every record of that type on the name.
To delete only one of several, give the value as well:
`update delete www.example.se. A 192.0.2.10`.

No output means the change went through. Check it with `dig`:

```bash
dig +short www.example.se A @ns1.getgeek.se
```

It can take up to a few minutes before `dig` shows the change, even against
`ns1.getgeek.se`. The change itself is already saved, but the name servers
may still answer from their cache.

## Terraform and OpenTofu \{#terraform-och-opentofu}

Use the [`hashicorp/dns`](https://registry.terraform.io/providers/hashicorp/dns/latest/docs)
provider. The key name and the zone are written with a trailing dot:

```hcl
terraform {
  required_providers {
    dns = {
      source = "hashicorp/dns"
    }
  }
}

variable "tsig_secret" {
  type      = string
  sensitive = true
}

provider "dns" {
  update {
    server        = "ns1.getgeek.se"
    key_name      = "example-dnsupdate."
    key_algorithm = "hmac-sha512"
    key_secret    = var.tsig_secret
  }
}

resource "dns_a_record_set" "www" {
  zone      = "example.se."
  name      = "www"
  addresses = ["192.0.2.10"]
  ttl       = 3600
}
```

Pass the secret in the environment variable `TF_VAR_tsig_secret` instead of
writing it to a file in the repository.

`dns_a_record_set` owns every A record on the name. If `www` already has A
records that are not listed in `addresses`, Terraform removes them, and
`terraform destroy` removes every A record on the name.

## Certificates with DNS-01 \{#certifikat-med-dns-01}

ACME clients that support RFC 2136 can create the `_acme-challenge` record
themselves. With [lego](https://go-acme.github.io/lego/dns/dnsupdate/) (version 5) you
can use the key file from step 2 directly:

```bash
DNSUPDATE_NAMESERVER=ns1.getgeek.se \
DNSUPDATE_TSIG_FILE=example.se.key \
lego run -m you@example.se --dns dnsupdate -d example.se -d '*.example.se'
```

In lego 4 the provider is called `rfc2136` and the variables start with
`RFC2136_`.

acme.sh (`dns_nsupdate`), certbot (`certbot-dns-rfc2136`) and cert-manager
(`rfc2136`) work the same way, with the values under
[Connection details](#anslutningsuppgifter).

## Tools that need to read the whole zone \{#verktyg-som-behover-lasa-hela-zonen}

Some tools, for example external-dns in Kubernetes, fetch the whole zone (a
zone transfer, AXFR) to see which records exist. This is not enabled by
default. Say in your ticket that you need it, and we will give your key read
access to the zone.

## How fast is a change visible? \{#hur-snabbt-syns-andringen}

The change usually shows on all our name servers within a minute,
sometimes after a few minutes. Resolvers
that have already cached the old answer keep showing it until the record's
TTL has expired. Lower the TTL in advance if you are planning a move.

## Troubleshooting \{#felsokning}

| Response                                                                  | Likely cause                                                                                                                                                                                                            |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update failed: REFUSED`                                                  | The request was not signed, the key does not apply to this zone, or the update was sent to a server other than `ns1.getgeek.se`.                                                                                        |
| `TSIG error with server: expected a TSIG or SIG(0)` followed by `REFUSED` | The server did not accept the signature: wrong secret, wrong algorithm or wrong key name. It can also be caused by a wrong clock on your computer, since TSIG requires the clock to be correct to within a few minutes. |
| `update failed: NXDOMAIN` or `YXDOMAIN`                                   | A condition (`prereq`) in the request was not met. Nothing was changed.                                                                                                                                                 |
| `Communication with … failed: timed out`                                  | Outgoing traffic on port 53 is blocked, usually by a firewall in your network.                                                                                                                                          |

If none of that helps, open a ticket with the command you ran (without the
secret) and the full response.
