Differences

This shows you the differences between two versions of the page.

--- software:stapler [01-Apr-2017 16:10] – [Recent updates] Angelo Babudro
+++ software:stapler [11-Jul-2023 16:04] (current) – [Known bugs and deficiencies] Angelo Babudro
@@ Line 1: / Line 1: @@
 ====== Stapler ======
-Stapler is a Perl application developed to simplify server DNS zone file maintenance.
+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.
 ===== Background =====
-Every time I added a server to my network, I had to change the zone files 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.  And half the time or more I would forget to change the serial number in one or more zone files.  What a pain.
+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, aliases (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.
+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.
 ===== Recent updates =====
-:!: 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.
+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.
+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.
-Stapler 4.30 is anticipated by the end of April, which will have better error-checking of the configuration files and some minor bug fixes and cosmetic improvements in the zone file outputs.
 ===== Requirements =====
 To use Stapler you need to be using BIND for DNS resolution (it does not work with things like TinyDNS).
@@ Line 26: / Line 30: @@
   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).
 ===== Download =====
-Download the script and sample configuration files.  The latest version is here:
+. Download the {{ :software:stapler.md5 |MD5 checksums}} for the files below.
-ftp://gloria.ixo.ca/stapler/stapler-latest.tgz
+. Get the version you want.
+|<100% 8em>|
+^ Release Date ^ Description ^
+| 03 Sept 2022| {{ :software:stapler-2022-09-03.tgz |Version 4.42}} added file permission check on remote server; alert on unknown parameter; ignore comments in aliases file; do not write www record unless nowhere else defined. |
+| 07 Jun 2021 | {{ :software:stapler-2021-06-07.tgz |Version 4.38}} rndc.key generation and validation, fixed handling of forwarders, and many other fixes and enhancements. |
+| 27 Nov 2018 | {{ :software:stapler-2018-11-27.tgz |Version 4.33}} with enhanced debugging messages and a couple of small bugs fixed. |
+| 02 Feb 2018 | {{ :software:stapler-2018-02-02.tgz |Version 4.32}} with enhancements to DDNS script. |
+| 18 Jan 2018 | {{ :software:stapler-2018-01-18.tgz |Version 4.31}} with Dynamic DNS support. |
+| 19 Oct 2017 | {{ :software:stapler-2017-10-19.tgz |Version 4.30}} with a new stapler.conf file format that is easier to maintain and adds new features. |
+| 11 Mar 2017 | {{ :software:stapler-2017-03-11.tgz |Version 4.29}} the last release with the old stapler.conf config file format.\\ Versions newer than this will require you to modify your config file. |
+. Validate the download against the checksums:
+  md5sum --check --ignore-missing stapler.md5
 ===== Installation =====
-Paths are preserved in the tar file.  The Perl script should placed in /usr/local/bin/ and the configuration files in /etc/stapler/.
+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.
+==== Unpack the archive ====
+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
-To view the archive you can use:<code>tar -tzf stapler-latest.tgz</code>To install the file as root do this:<code>tar -C / -xPpzf stapler-latest.tgz</code>
+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.  In your root Crontab put something like this:
+==== Weekly root cache update ====
+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  *  *  Sun wget -O /var/bind/root.cache ftp://ftp.internic.net/domain/named.cache
+==== Put executable in your path ====
+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/
 ===== Configuration =====
 You will find comments within the configuration files, which include:
-  - 192.168.1 --- a sample of a netblock configuration, you can have as many of these as you like.
+  - 192.168 --- a sample of a netblock configuration.  You can have as many of these as you like.
   - aliases.stapler --- machine aliases (a.k.a., sub-domains).
   - domain.primary --- domains for which this DNS server is authoritative (i.e., the master).
   - domain.secondary --- domains names for which this DNS server is a relay (i.e., a slave).
-  - named.root --- a copy of the root name servers that is publicly available.
   - stapler.conf --- the main configuration file.
+==== Edit the configuration ====
+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.
+==== Configure your domains ====
+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.
+==== Configure CNAME aliases ====
+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.
+===== Trial run =====
+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.
+===== Add Dynamic DNS support =====
+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:
+.2.3.4   host-one
+.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:
+* * *  * /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.
+===== Known bugs and deficiencies =====
+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.
-===== Tips =====
+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.