Stapler is a Perl application developed by Angelo Babudro since 2000 to simplify server DNS zone file maintenance in a small hosting company that has multiple domains with a fixed set of server names across all domains. If you do not want all of your servers showing up in all of your DNS zone files, then this tool is not for you. On the other hand, if you find yourself changing all of your zone files every time you add a new server or change an IP address, then you may find this tool to be quite a time-saver.

Every time I added a server to my network I changed the zone files by hand for all of the domains in which that server would be used. If it was a web or e-mail server, I might have a dozen zone files to edit. If I changed IP addressing schemes, I had to edit all the zone files. Half the time I would forget to change the serial number in one or more zone files. Other than making simple changes, like adding one new server, it was a lot of repetitive work.

Stapler makes this all very easy by keeping your primary and secondary domains, machines, CNAME aliases for subdomains, and configuration in simple ASCII text files. You can add a new web server and have the zone files for a hundred domains re-written in seconds. Add a new subdomain for a customer and Stapler will re-write the zone files and refresh BIND's cache in the blink of an eye.

February 2017: Stapler 4.28 now supports single dynamic IP addresses, such as on a residential Internet service, that can be updated using a Cron job on the dynamic host and a simple web page on the DNS server that has Stapler on it. Running the Cron job every four hours, for example, would check your server's IP address every four hours and reload the DNS server if any IP addresses have changed.

March 2017: Stapler 4.29 significant update with revision of several areas of logic. Now supports DKIM and TXT records. Forwarders support completed (was in config file but not implemented). Domains may have multiple records in domain.primary, e.g., a domain could have alternate servers, TXT, DKIM, and SPF record lines, whereas previously it could only be listed once.

October 2017: Stapler 4.30 offers an improved configuration file format that is easier to maintain and offers new features. See the comments inside stapler.conf for descriptions of the new format and features. There are also several minor improvements in the appearance of the screen and file outputs, and much improved validation of data before writing DNS files.

June 2021: Stapler 4.39 brings a lot of updates that have been needed for a while due to changes in BIND.

To use Stapler you need to be using BIND for DNS resolution (it does not work with things like TinyDNS).

Stapler was initially developed in Perl 5 version 8 and is currently being used in Perl 5 version 22, so I expect that any version of Perl 5 will work properly, although I am only testing on the current Gentoo release at any given time.

Perl CPAN modules required:

• Term::ANSIColor
• Switch

As of April 2017 the Gentoo emerge command to install or verify installation of these modules is:

emerge -va perl-Term-ANSIColor dev-perl/Switch

As of June 2021 Stapler works with Arch Linux standard installation (i.e., no special packages needed).

1. Download the MD5 checksums for the files below.

2. Get the version you want.

3. Validate the download against the checksums:

md5sum --check --ignore-missing stapler.md5

Prior to version 4.42 the files were stored without a path, but from version 4.42 there is now a directory that will be created with the version number, e.g., ./stapler-4.42/.

The Perl script can be placed in a directory in your PATH, such as /usr/local/bin/, by symbolically linking it, e.g.

ln -s /etc/stapler/stapler-4.42/stapler /usr/local/bin/

Run the stapler command from the directory where you have your configuration files. So if you put your config files under /etc/stapler organised by project then you would do something like:

cd /etc/stapler/projectA
stapler

… to build the DNS files for projectA.

Install the file as root from your downloads directory. For a simple installation you can just do this:

sudo mkdir /etc/stapler
sudo tar -C /etc/stapler -xPpzf stapler-YYYY-MM-DD.tgz

The above will put everything in /etc/stapler where you can edit and create your configuration files. This is the simplest setup, suitable for a single non-Production server.

If you would like to use version control and/or the ability to have multiple configurations for Stapler (e.g., for multiple clients' DNS servers) you can instead do steps like this:

sudo su
mkdir -p /etc/stapler/trunk /etc/stapler/branches/$(hostname -s)
ln -s /etc/stapler/branches/$(hostname -s) /etc/stapler/active
tar -C /etc/stapler/trunk -xPpzf stapler-YYYY-MM-DD.tgz
cp -av /etc/stapler/trunk/* /etc/stapler/active
cd /etc/stapler/active
rm stapler                           <== only keep one copy of the Perl script in the trunk
mv stapler.conf.dist stapler.conf
mv checkin.php.dist checkin.php
ln -s /etc/stapler/trunk/stapler /usr/local/bin/

The above steps will make the active directory point to a branch for the hostname on which you unpack the software.

Make additional directories under branches for other DNS masters that you will be managing. Then create a repository for your DNS (e.g., with svnadmin create) and commit everything except the active symlink, e.g.:

svn add trunk branches

With this method you can set the active directory to point to whatever directory you want to use to create DNS zone files on a given server, and that way all of your DNS boxes can update from the same repository.

Configure a weekly Cron job to update your DNS root server cache. You probably already have this or a procedure similar, but in the event that you do not, you can keep your Internet root DNS cache updated with a line like this in your root Crontab:

00  00  *  *  Sun wget -O /var/bind/root.cache ftp://ftp.internic.net/domain/named.cache

Optional: create a symlink to the Perl script. If you always tend to change to the Stapler directory to run it, then you can skip this.

ln -s /etc/stapler/stapler /usr/local/bin/

You will find comments within the configuration files, which include:

1. 192.168 — a sample of a netblock configuration. You can have as many of these as you like.
2. aliases.stapler — machine aliases (a.k.a., sub-domains).
3. domain.primary — domains for which this DNS server is authoritative (i.e., the master).
4. domain.secondary — domains names for which this DNS server is a relay (i.e., a slave).
5. stapler.conf — the main configuration file.

Edit the stapler.conf file. You will find instructions inside it for all the variables. Each line contains a key=value pair. The values can be within quotation marks or not. Basically, everything from the first non-white-space character after the equals sign to the end of the line is used.

Edit the files domain.primary and domain.secondary as needed. You should have at least one domain in domain.primary, but you may have none in the secondary file.

• The primary file lists all the domains for which this DNS server is the authoritative master.
• The secondary file lists all of the domains for which this DNS server is a slave.

You could have many slaves, and you might have several masters.

Instructions are contained within each file.

Often you'll want a machine to have more than one name. ns1 might also be mail, dev, ops, whatever. You can give extra names (CNAME aliases) to boxes in the aliases.stapler file. You just put an alias, the real machine name that the alias points to, and the domain. The domain determines which zone file the entry will go into.

As with the other files, you will find examples and instructions when you open it.

At this point you should be able to type ./stapler and see if you get a set of DNS zone files or not. You may have some path permissions that need changing or some configuration elements that need adjusting. Just keep running it as you resolve each problem until it works.

Use the -n (dry run) flag to do everything except reload DNS, so you can examine the zone files and the named.conf file before putting them into effect.

There is a -h / –help command that lists the available options.

Dynamic DNS support is introduced in version 4.31. This permits you to make your DNS server support dynamically-changing IP addresses, somewhat like commercial services like DynDNS do.

Dynamic DNS support is optional. If you don't need to use it, then skip to the next section.

If you have servers at home or other locations where the IP addresses change, and you find yourself having to go to those boxes to retrieve their IP address whenever it changes, then you want to use Dynamic DNS. If you are paying for a Dynamic DNS service and are happy with it, then I am not suggesting you change. This solution is here for the people who have a public DNS server and want an internal DDNS solution.

The concept is rather simple. It began for me with the idea of creating a script that sent me an e-mail every time it was called, simply telling me the current address of the remote machine as perceived by a server that has a static public IP address. I had my home servers call the script every four hours so that wherever I was travelling I could always get to my home servers.

First, create a file named dynamic that will hold your public IP address(es) and host name(s). For example:

1.2.3.4   host-one
5.6.7.8   host-two

Now change ownership of that file so that Apache can manage it:

chown apache dynamic

Of course, replace “apache” with whatever user name your web server runs as.

Next, decide if you want to make a symlink to the checkin.php script for the web server or copy the file. Your web server will need to be permitted to follow symlinks, which it probably is not by default, so the simplest thing to do is copy the file. A symlink has the benefit of updating the web script whenever you udpate the source package.

So either make a symlink:

ln -s /etc/stapler/checkin.php /var/www/html/localhost/mywebsite/

…or else copy the script:

cp /etc/stapler/checkin.php /var/www/html/localhost/mywebsite/

You will also need to give permission to apache (or www or whatever user name your web server runs as) to run two commands using sudo. Put a line like this in your sudoers file in /etc/sudoers.d/:

apache  ALL = NOPASSWD: /usr/sbin/rndc, /usr/local/bin/stapler

Obviously, you need to really trust Stapler to not mess up your DNS, but there's no way around that if you want to have DNS entries that dynamically and automatically change. Due to the risk, you will certainly want to run this on a dev machine first, and then run it manually in production for a while before enabling each of the above automation steps.

The final step is to put your dynamic DNS into action by automating a call-out on your machines that have dynamic IP addresses. You do this by making an http (or https) call using wget. Here is a sample Cron entry that will validate the server's IP address once every hour:

0 * * *  * /usr/bin/wget -O - -q "http://example.com/checkin.php?host=myhostname&user=ab&verbose=0" >/dev/null

The user variable is optional. It is just the user name under which you are running the above cron line, to help you or another person remember this detail if you need to find where the cron job is running months or years later.

The host variable indicates which host to change inside the /etc/stapler/dynamic file.

When set to a non-zero value, the verbose variable causes you to get an e-mail even when nothing changes. You can leave this variable out entirely instead of setting it to zero.

Any output of the wget command is piped to /dev/null because we don't want the machine running the cron to generate an e-mail, but rather the remote host's checkin.php script.

The format of the config file needs a bit of an overhaul to be more consistent.

The handling of special records such as SPF and DKIM needs improvement.

DNSSEC configuration is not working properly.

There is no IPv6 support.

Stapler is not intended to manage a situation where each domain has different hosts defined. It would be easier to manually manage each domain file in that case.