For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/dns/dns-update.md.
  • English
  • 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

    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:

    ValueExample
    Key nameexample-dnsupdate
    Algorithmhmac-sha512
    Secreta base64 string
    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

    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:

    chmod 600 example.se.key

    Connection details

    SettingValue
    Serverns1.getgeek.se (IPv4 and IPv6)
    Port53, UDP and TCP
    Zoneyour domain, e.g. example.se
    Keythe name you received, e.g. example-dnsupdate
    Algorithmhmac-sha512

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

    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:

    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:

    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:

    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:

    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

    Use the hashicorp/dns provider. The key name and the zone are written with a trailing dot:

    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

    ACME clients that support RFC 2136 can create the _acme-challenge record themselves. With lego (version 5) you can use the key file from step 2 directly:

    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.

    Tools that need to read the whole zone

    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?

    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

    ResponseLikely cause
    update failed: REFUSEDThe 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 REFUSEDThe 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 YXDOMAINA condition (prereq) in the request was not met. Nothing was changed.
    Communication with … failed: timed outOutgoing 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.