Using the dynamic DNS editor: nsupdate

Posted by rossen on Wed 9 Apr 2008 at 16:42

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/bind/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/bind/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 separate "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/bind/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/bind/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/

 

 


Posted by ajt (204.193.xx.xx) on Thu 10 Apr 2008 at 12:45
[ Send Message | View Weblogs ]
Hi,

That's really cool.

Shame that the man page is still borked, have you submitted a bug? It seems that your correction works, I wonder why it's not been fixed even in Lenny?

--
"It's Not Magic, It's Work"
Adam

[ Parent | Reply to this comment ]

Posted by rossen (84.72.xx.xx) on Thu 10 Apr 2008 at 13:18
[ Send Message | View Weblogs ]
If you look at http://bugs.debian.org/dnsutils, you will see that there are quite a few complaints about the state of the manpages, some going back many years. http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=470749 in particular talks about the problem with nsupdate's man page. Perhaps LaMont Jones needs some encouragement to clean up these old reports, but he is probably busy enough with the rest of bind9.

[ Parent | Reply to this comment ]

Posted by ajt (204.193.xx.xx) on Thu 10 Apr 2008 at 14:30
[ Send Message | View Weblogs ]
Yes, you are right, I spotted some bugs after I posted my comment (isn't it always the way). However I think there is nothing wrong with Debian applying a patch while upstream is busy.

--
"It's Not Magic, It's Work"
Adam

[ Parent | Reply to this comment ]

Posted by rossen (84.72.xx.xx) on Thu 10 Apr 2008 at 15:37
[ Send Message | View Weblogs ]
I have submitted a follow-up to bug #470749. We'll see what happens, but I will not hold my breath.

[ Parent | Reply to this comment ]

Posted by flatfoot (87.119.xx.xx) on Fri 11 Apr 2008 at 10:03
[ Send Message ]
1. rndc freeze example.com IN internal
2. edit your example.com zone file
3. rndc reload example.com IN internal
4. rndc thaw example.com IN internal

[ Parent | Reply to this comment ]

Posted by rossen (84.72.xx.xx) on Fri 11 Apr 2008 at 10:33
[ Send Message | View Weblogs ]
That certainly works, but during the time that the zone is frozen, no dynamic DNS updates can occur. If you have a ISC DHCP3 server that is doing dynamic DNS updates for every lease it gives out, is will refuse to give out leases during the time that the zone is frozen. Not a big deal for a small network and if you are reasonably fast with the editting, but it is a problem if there are several thousand machines requesting leases all of the time.

[ Parent | Reply to this comment ]

Posted by Anonymous (216.57.xx.xx) on Wed 21 Mar 2012 at 22:46
Which works great . . . unless you want to script or automate it.

The great thing about nsupdate is that you can automate and script a lot of functionality.

[ Parent | Reply to this comment ]

Posted by Anonymous (192.168.xx.xx) on Fri 22 Feb 2013 at 22:05
I would further add you may wish to append "." to all full names so as to ensure no suffixes are added. For example, in your update of a host and its PTR, you might want to specify "www.example.com." and "1.1.16.172.in-addr.arpa." in the update statements.

I'm also not sure why you'd want those as separate operations. I would think you'd want them either to succeed or to fail simultaneously, so you'd want both updates before only one "send." But of course, that's an implementation decision.

[ Parent | Reply to this comment ]

Sign In

Username:

Password:

[Register|Advanced]

 

Flattr

 

Current Poll

Which init system are you using in Debian?






( 1595 votes ~ 7 comments )