I, Gopakumar H. Pillai (Gopu), am dedicating the software dnsupdate to my country, INDIA. This project was entirely created from my home on my own time.

In search for a program that would help me create and maintain the DNS databases, my efforts were in vain. The nearest ones I could find were written in perl. The last thing I wanted to do from my program was to do a "system" call. I started playing with BIND 8.2.2 P7 and converted the nsupdate program to a function. That actually made me write the rest of the program.

My benchmark program was the famous h2n perl script. dnsupdate seems to be much faster than h2n. I have given a timing comparison table between dnsupdate and h2n in Appendix B.

With my highly limited knowledge about DNS or its configuration files (DNS tables or DNS databases) I am requesting users of this program to pinpoint any errors or suggestions to make dnsupdate a better one.

2 Introduction

BIND is the most widely used implementation of DNS. For an explanation of the abbreviations, please check Appendix D. The configuration and data files to BIND named have a very complex format.

The objective was to create software that can be used with ease without knowing the format of the DNS tables. Also write it in a language other than scripts so that one can make use of it by calling a function instead of executing an external program (bad for security reasons). This also should make it faster than a script doing the same thing. In short the objective was to create and maintain the DNS tables (database) in an easy, fast and efficient manner.

All said one can't get away without knowing anything about the concepts of DNS and still get it to work.

3 Requirements

The basic requirement of dnsupdate is that it should be able to create all DNS tables from a hosts file and a configuration file and should be able to maintain it. After creating if any changes are made to the tables through dnsupdate, a future recreation of the tables should reflect it.

4 Design

Looking at single entry addition/deletion to the DNS tables, dnsupdate should be using the Dynamic update feature of BIND 8 or higher as much as possible. Since dynamic update happens over a UDP connection, it is slow to be used for recreation of the DNS databases (tables). Recreation could be made much faster by carefully writing directly to the files. Figure 3.1.1 illustrates the overall design of dnsupdate.

Figure 3.1.1

4.1 Dynamic Update

dnsupdate program should use the dynamic update feature of BIND (version 8 or higher). A request could be sent to the DNS server (named) for adding or deleting a host or alias. The server would update its memory and at particular intervals, it would update the DNS databases. Adding/deleting a name server could also be done dynamically, but BIND 8 has some limitations. Future releases supporting BIND 9 or higher should have it that way.

4.2 dnsupdate

dnsupdate should use a configuration file, so that, with the information from the configuration file and the hosts file provided, it should be able to recreate the DNS databases. A request for certain single entry updations should also be added to the configuration file so that it could be used for the next recreation of the entire databases.

Only one copy of the program should be running on the system at any given instance. This can avoid any problems with synchronization, thus save the databases from getting corrupted.

5 Compilation

dnsupdate is written so that it can be used in any system running a DNS server (BIND version 8 or above).

It can be compiled in Solaris 8 and FreeBSD 4.2. I am sure it can be compiled in a variety of operating systems with the minimal change.

Use make utility to compile the software. Here are the different commands one can use to compile dnsupdate:

"make clean" would clean all the object files and executables.

"make" or "make all" would compile the related libraries and source for dnsupdate.

"make nsupdatelib" would compile nsupdate.c and create libnsupdate.a.

"make nsupdtest" would compile nsupdate.c and create nsupdtest executable to test the nsupdate functio.

"make Dprintf" would create the library libDprintf.a.

"make dnsupdate" would compile dnsupdate sources and give out dnsupdate executable. If you have already compiled libraries, this might be the command you would want to use.

There are SYSTYPE lines in the Makefile. Ensure that the line containing the operating system you use should come as the last line in that bunch. For example, SYSTYPE = freebsd line appearing as the last line that section would give compilation errors if compiled on a Solaris system.

5.1 libnsupdate.a

To create libnsupdate.a one needs to have the compiled code for BIND 8.2.2 P7. In the Makefile, specify the BINDDIR as the directory containing the compiled BIND code. If it is difficult for you to compile BIND, I have provided the libraries for Solaris 8 and FreeBSD 4.2 with the Release 1.0. libnsupdate.a need libbind.a and libbind_r.a to link without errors.

6 Implementation

dnsupdate has two different modes - create mode and update mode. In create mode, it creates the DNS databases from a hosts file and the configuration file. Create mode can be invoked with the -f option. In update mode it adds or deletes individual entries. In update mode, it doesn't necessarily need the configuration file, unless one wants to override the default values.

The default configuration file is /etc/dnsupdate.cfg. One can use an alternate configuration file with the -c option. Default values for all parameters in dnsupdate are specified in Appendix A.

6.1 Source Structure

Table 4.1.1 describes the source files. All functions would have a brief explanation about what it does, above their definitions in their source files.

File Name	Description
dnsupdate.c	Main source file which parses the user parameters, checks for another copy etc..
dnsupdate.h	Main header file which has all dnsupdate related defines and declarations.
config.c	Contains functions to manipulate or read the configuration file.
config.h	Configuration related defines and declarations.
processcmd.c	The brain of dnsupdate. This file has all functions, which does the real work.
util.c	Utility functions. These are mostly used by functions in processcmd.c
nsupdate.c	This file contains the nsupdate function, copied from BIND source. This file has been edited and formatted.
dnsupdate.cfg	The configuration file to dnsupdate.

Table 3.1.1

Logging is done using the static library named libDprintf.a. The library is a result of two files that are described in Table 4.1.2

File Name	Description
Dprintf.c	Source file for the logging interface.
Dprintf.h	Header file for the logging interface.

Table 4.1.2

6.2 nsupdate

The key portion of dnsupdate is the dynamic update to the name server. BIND 8 and above supports dynamic update. I have used nsupdate.c from the BIND distribution (BIND 8.2.2 P7) and created a nsupdate function. The nsupdate function can be used to update a single line of command or to update from a file specified.

Usage:

nsupdate( cmd, flag);

flag - if TRUE (other than 0) cmd should be a filename with the update strings

else cmd should be a single string (with or without trailing newline).

If TEST_UPDATE is defined, nsupdate can be tested as a standalone program.

6.3 dnsupdate

dnsupdate, when executed, checks for another copy of itself running. This checking is done using a semaphore with the key 492743 (0x784c7). If another copy is found, in create mode (-f option), dnsupdate would wait until other program exits. In update mode it would exit immediately, but can be made to wait with the -w option.

Then it reads the configuration file and checks whether named is running or not. In case of a failure the program exits immediately.

In create mode, updates are written to the DNS databases directly. In update mode, adding/deleting hosts and aliases (CNAME) are done using dynamic update. Rest all is directly written to databases.

All direct writings are done on temporary files in the same directory as the file being worked on. Then the temporary file is moved to the original file.

In create mode, dnsupdate restarts named, since the dynamic update cannot be triggered on with a HUP signal. But in update mode a HUP signal is sent to named after updating the databases, so that, named can re-read the DNS tables. If the update is only for a host or alias no signals are sent to named.

In create mode, dnsupdate creates /etc/resolv.conf file too. It overwrites the existing /etc/resolv.conf file.

In update mode, dnsupdate adds the requested information to the configuration file so that it can be used for the next run with -f option. It adds or deletes the NETWORK, NAMESERVER and ALIAS lines dynamically.

6.4 dnsupdate.cfg

/etc/dnsupdate.cfg is the default configuration file used by dnsupdate. It could be overridden with the -c option. Appendix C displays a copy of the configuration file. Here is an explanation of all fields that can be found in the cfg file:

Key	Description
DOMAIN	The domain name. If not specified it would read from /etc/defaultdomain file.
DNSDIR	Directory where DNS databases reside. Default is /var/named in case of Solaris and /etc/namedb for FreeBSD.
NAMEDCONF	Full path name of named.conf file. If not specified DNSDIR/named.conf would be used.
LOGFILE	Full path name of the log file. Default is /tmp/dnsupdate.log.
LOGLEVEL	Log level. 0 = None. 1 = Minimum. 9 = Maximum.
NETWORK	Network addresses. Format is NetworkAddress:Netmask. e.g. 166.117.12:255.255.255.0
NAMESERVER	Additional name servers. Format is NameServerHostName:NameServerIPAddress. e.g. ns1.gopu.com:192.168.0.1
CONTACT	Contact address to be added to the DNS databases. Default is root.DOMAIN, where DOMAIN is the domain name.
NAMEDPID	Full path of the named PID file. Default is /etc/named.pid in case of Solaris and /var/run/named.pid in case of FreeBSD.
NAMEDEXE	Full path of the named executable. Default is /usr/sbin/named in case of FreeBSD and /usr/sbin/in.named in case of Solaris.
HOSTSFILE	Hosts file to create the DNS databases from. Default is /etc/hosts
ALIAS	Alias name for an existing host. Fomat is AliasName:HostName. e.g. www:gopu.com

Comment lines start with a # character.

Blank lines are ignored.

File follows a format of KEY=VALUE

There should not be any spaces before or after the = sign.

NETWORK, NAMESERVER and ALIAS key-value pairs are updated dynamically by dnsupdate.

6.5 Usage

dnsupdate <-a|-d> -n HostName -i IPAddress

dnsupdate <-a|-d> -z ForwardZone

dnsupdate <-a|-d> -r ReverseZone(NetworkAddress) -mNetMask

dnsupdate <-a|-d> -s NameServer -i IPAddressOfServer

dnsupdate <-a|-d> -p AliasName(CNAME) -n HostName

dnsupdate -f

dnsupdate -h

Additional options:

[-c ConfigFile] [-w]

Defaults:

Config File: /usr/hb/cfg/dnsupdate.cfg

DNS Directory: /var/named

Log File: /usr/hb/log/dnsupdate.log

Example:

dnsupdate -h

displays this help screen

dnsupdate -a -n foo -i 192.168.0.1

Add the host specified to the DNS table.

dnsupdate -d -i 192.168.0.1 -n foo -w

Delete the host specified from the DNS table.

But wait until any running dnsupdate exits instead of

quitting immediately.

dnsupdate -a -z gopu.com

Add the forward lookup zone, gopu.com.

dnsupdate -a -r 192.168.5 -m 255.255.255.0

Add the reverse zone 5.168.192.in-addr.arpa

dnsupdate -a -s ns1.gopu.com -i 192.168.0.1

Add the name server ns1.gopu.com

dnsupdate -a -p www.gopu.com -n gopu.com

Add the alias name (CNAME) www.gopu.com for gopu.com

dnsupdate -f

Recreate the whole DNS database from the hosts file

and the default configuration file.

Note:

1. DO NOT specify network address for a reverse lookup

in reverse order.

2. If specified -f option the program waits for any running

dnsupdate to exit. Without the -f option the program would exit

saying "Another copy running". This can be overridden with

with the -w option, which will force the program to wait

7 Known Issues

Does not roll back the DNS databases to its previous good state in case of a failure. As a work around, a script can do this work. If dnsupdate returns a non-zero value, then the database needs to be restored.

dnsupdate can support only one domain.

Normally named expects the named.conf file to be in /etc. But FreeBSD creates a symbolic link from /etc/named.conf to /etc/namedb/named.conf. So it solves the problem. Solaris does not. One has to do it manually or copy the file from /var/named each time it is modified.

dnsupdate, in update mode, does not add host details to the configuration file. So the hosts information should be maintained external to dnsupdate or a script could create a hosts file from the DNS databases.

8 Special Notes

For the first time one needs to run dnsupdate -f so that things are in place for a dynamic update.

To force writing the updated information, one can send the TERM signal to named. Don't forget to restart named after that.

To compile dnsupdate, one should get the source code for BIND 8.2.2 P7 and compile it first. Then edit the Makefile to specify the BIND dir. Alternatively, use the already compiled libraries found on the project home page.

Ideally Name servers could have been added dynamically. BIND 8 has some restrictions, so it adds/deletes only the first nameserver. But BIND 9 seems to support adding name servers dynamically. Currently dnsupdate directly write to the DNS database and later versions supporting BIND 9 can do it dynamically.

In nsupdate.c some variables have been moved to global variable section, since stack based arrays were failing.

While processing the hosts file with -f option, dnsupdate processes alias names (names from the third column in the hosts file) too and treats them as though they are valid host names. So an MX record is also added for each entry. Probably it would have been right to consider them as aliases.

9 Appendix A: Default Values

KEY/Description	FreeBSD	Solaris
Configuration File	/etc/dnsupdate.cfg	/etc/dnsupdate.cfg
DOMAIN	contents of /etc/defaultdomain	contents of /etc/defaultdomain
DNSDIR	/etc/namedb	/var/named
NAMEDCONF	$DNSDIR/named.conf	$DNSDIR/named.conf
LOGFILE	/tmp/dnsupdate.log	/tmp/dnsupdate.log
LOGLEVEL	MAX (9)	MAX (9)
CONTACT	root.$DOMAIN	root.$DOMAIN
NAMEDPID	/var/run/named.pid	/etc/named.pid
NAMEDEXE	/usr/sbin/named	/usr/sbin/in.named
HOSTSFILE	/etc/hosts	/etc/hosts
Semaphore Key	492743 (0x784c7)	492743 (0x784c7)

10 Appendix B: Timing comparison with h2n

Number of hosts	dnsupdate -f	h2n
100	0.132s	0.113s
1,000	0.300s	0.439s
5,000	0.862s	2.244s
10,000	1.626s	6.552s
50,000	7.807s	4m20.457s

Benchmark was done on a Sun Sparc system running Solaris 8, Perl 5.005_3 and h2n 1.29.

11 Appendix C: dnsupdate.cfg - Configuration File

# Configuration file for dnsupdate

# This is a comment, blank lines are ok.

# Your domain name. Only 1 DOMAIN line is allowed. If not specified

# /etc/defaultdomain would be read.

#DOMAIN=gopu.com

# named.conf file to be used. This is a must. Only one line is allowed.

# If not specified /var/named/named.conf would be used in case of Solaris

# systems or /etc/namedb/named.conf would be used in case of FreeBSD.

#NAMEDCONF=/var/named/named.conf

# DNS Directory. If not specified /var/named would be used in Solaris.

# /etc/namedb in FreeBSD. Only one such line is permitted.

#DNSDIR=/var/named

# Log file. If not specified /tmp/dnsupdate.log would be used. Only

# one line is allowed.

#LOGFILE=/users/gopu/dnsupdate/dnsupdate.log

# Log Level - NONE=0, MIN=1, MED=5, MAX=9. If not specified

# MED=5 would be used. Only one such line is allowed.

LOGLEVEL=9

# named.pid file. If not specified /var/run/named.pid would be used

# in FreeBSD systems and /etc/named.pid would be used in Solaris.

# Only one such line is permitted.

#NAMEDPID=/etc/named.pid

# named executable path. This is used to restart named.

# If not specified /usr/sbin/named would be used in FreeBSD systems and

# /usr/sbin/in.named would be used in Solaris systems.

# named restarts are done with -f option, to enable the dynamic

# update

NAMEDEXE=/usr/sbin/in.named

# Hosts file to read for -f option. If not specified, /etc/hosts file

# would be used. Only one such line is allowed.

HOSTSFILE=/tmp/hosts

# NETWORK : Network without the trailing zeros.

# Format NET:SUBNETMASK

# More than one line is allowed.

# These entries are dynamically updated by dnsupdate, hence would

# be moved to the bottom of the file.

NETWORK=192.168.2:255.255.255.0

NETWORK=10.1:255.255.0.0

# ALIAS - Alias for an existing host. Also known as CNAME record.

# Format: ALIASNAME:HOSTNAME

# Multiple lines are allowed.

# These entries are dynamically updated by dnsupdate, hence would

# be moved to the bottom of the file.

ALIAS=www:gopu.com

# NAMESERVER - Name server in each domain's NS records. No expansion

# of names would be done if a trailing dot is present. A colon separated

# IP address must be provided for each server.

# Format: HOSTNAME:IPADDRESS

# More than one line is allowed.

# These entries are dynamically updated by dnsupdate, hence would

# be moved to the bottom of the file.

NAMESERVER=ns1.gopu.com.:192.168.0.1

NAMESERVER=ns2:10.1.0.2

# CONTACT - Name or email address of the contact person in the SOA

# mail address. Default is root.DOMAIN. Only one line is allowed.

# If not specified, root.$DOMAIN would be used.

#CONTACT=root.gopu.com

12 Appendix D: Definitions, acronyms & abbreviations

DNS	Domain Name Service. The service which provides the IP address of a host given its name and vice-versa.
Name Server	DNS.
BIND	Berkeley Internet Name Domain. This is an implementation of DNS, a public domain software, which is used by almost all of the domain name servers around the world.
hosts file	/etc/hosts file. It contains the names of hosts and their IP addresses.
h2n	a public domain perl script which can be used to create the DNS databases (tables) from a hosts file.
named	DNS server executable
in.named	In solaris the name server is named in.named.
IP	Internet Protocol. The whole Internet communicates using this network protocol.
UDP	Unified Datagram Protocol. A connectionless protocol built over IP.
TCP/IP	Trasmission Control Protocol / Internet Protocol. The most common protocol used on the Internet.
IP Address	The addressing scheme used by systems on the Internet to communicate each other. It is of the form n.n.n.n where n could range from 0 to 255 (certain restrictions apply).
/etc/resolv.conf	The file which tells the system where the DNS is, so that a name like dnsupdate.sourceforge.net could be translated to its IP address.

13 Reference

Description	Author	Publication	ISBN
http://sourceforge.net/projects/dnsupdate	Project Home Page with downloads
http://dnsupdate.sourceforge.net	Project Web Page
http://www.dns.net/dnsrd	DNS Resources Directory
DNS and BIND, 3^rd edition	Paul Albitz, Cricket Liu, Mike Loukides	O'REILLY	1-56592-512-2