Using the dynamic DNS editor, nsupdate

Introduction

nsupdate is the little-known brother of nslookup. It is used to make edits on a dynamic DNS without the need to edit zone files and restart the DNS server. If you have declared a zone dynamic, this is the way that you should be making edits.

The man page of nsupdate is broken

The first thing to do is read the man page of nsupdate. It is well-written with common examples of usage at the end, but the version that is commonly distributed with BIND version 9.x (in Debian etch and SuSE at least) is a bit broken. It can be fixed by deleting all instances (about 15) of the Perl regex pattern '.HP (\d+) '. I do this on any system that I install with a command like:

        gunzip /usr/share/man/man8/nsupdate.8.gz ; \
        perl -p -i -e 's/.HP (\d+) //gs' /usr/share/man/man8/nsupdate.8 ; \
        gzip /usr/share/man/man8/nsupdate.8

Invoking nsupdate

If one just types "nsupdate" one arrives in a basic command-line environment for sending "update" commands to DNS, but there are two options that you probably want to use when you invoke nsupdate.

The first option "-v" is to specify that communication with the DNS is to be done with TCP, not UDP. This is a good idea if the update requests are potentially longer than 512 bytes, which is often the case.

The second option "-k" is to specify where the encryption key files are to be found. A securely-configured DNS will not accept updates from just anyone - the update requests must be cryptographically signed with an appropriate key. There may be several keys that permit one to update a DNS. One may have created a root-readable key for manual administration of the DNS contained in the files /etc/named.d/admin-updater.{key,private}. Note that it is important that the "key" file and "private" file have the same stem path since one cannot be used without the other.

Therefore, the way to invoke nsupdate is:

        nsupdate -v -k /etc/named.d/admin-updater.key

To quit an nsupdate session, just hit CTRL-D or type "quit" and hit RETURN.

Deleting a record

Unconditionally deleting a DNS record (eg. the CNAME record www.example.com) is straight-forward. At the nsupdate ">" prompt, type:

        > update delete www.example.com cname
        > send

When one types "send" and hits RETURN, the update request is built, signed, and sent to the appropriate DNS server. If your key was authorised to make the request, the DNS will update its database, update its journal files, increment the serial number of the SOA record, and send a change notification to any slave DNSes. The slaves will start AXFRs (or IXFRs) to collect the updates from the master DNS.

Multiple updates

To save time and reduce DNS traffic (due to excessive slave DNS AXFR/IXFR requests), multiple update requests can be sent simultaneously in one batch:

        > update delete www.example.com cname
        > update delete www1.example.com a
        > update delete www2.example.com a
        > update delete www3.example.com a
        > send

There are a couple of points to keep in mind. All updates in one "send" batch must be for the same zone. For example, one cannot mix changes for example.com and 1.16.172.in-addr.arpa in the same "send".

In addition, there seems to be an undocumented limit in nsupdate of how many updates can be in one batch, probably due to a fixed input buffer. I have found that 2000 requests at a time sometimes do not pass. I no longer attempt more than 1000 for every "send", just to be safe.

Adding records

Here are examples of how to add A, CNAME, and PTR records. One must specify the TTL (time-to-live) of records (in seconds) when they are added.

        > update add www1.example.com 86400 a 172.16.1.1
        > update add www.example.com 600 cname www1.example.com.
        > send
        > update add 1.1.16.172.in-addr.arpa 86400 ptr www1.example.com.
        > send

Note that I have taken care to use two seperate "send" commands to handle the A and PTR updates of www1.example.com since the changes apply to two different zones, example.com and 1.16.172.in-addr.arpa.

Conditional updates

It is possible to program an update conditional on the presence or absence of DNS records (prerequisites), but I have never needed this for manual administration of a DNS. See "man nsupdate" and/or RFC2136 for more information on the possibilities.

Non-interactive usage

One of the most interesting ways of using nsupdate is non-interactive, by specifying a file containing a batch of commands or simply piping them in on STDIN. For example, one could use a text editor or a script to create a file "batch.txt" with the contents:

        update delete www.example.com cname
        update delete www1.example.com a
        update delete www2.example.com a
        update delete www3.example.com a
        send

and then run it by doing:

        nsupdate -v -k /etc/named.d/admin-updater.key batch.txt

Here is another non-interactive example using pipelines. Suppose that we want to delete all of the A records in example.com starting with "www". We could do:

        ( host -t a -l example.com | grep -i '^www' | awk '{ print "update delete "$1" a" }' ; echo send ) | nsupdate -v -k /etc/named.d/admin-updater.key

About this document

URL: http://www.rtfm-sarl.ch/articles/using-nsupdate.txt

HTML-conversion: txt2html --titlefirst --noanchors --nomake_links --preformat_trigger_lines 1 using-nsupdate.txt > using-nsupdate.html

Title: Using the dynamic DNS editor, nsupdate

Version: 2008-03-30-001

Author: Erik Rossen <rossen@rossen.ch>

Licence: Creative Commons Attribution-Share Alike 2.5 Switzerland, http://creativecommons.org/licenses/by-sa/2.5/ch/