RubyDNS Documentation

  1. Installation
  2. Basic DNS Server
  3. Asynchronous DNS Resolution
  4. DNS Verification
  5. DNS Testing
  6. API Documentation

rd-dns-check is a tool to help migrate data from one DNS server to another and assist with DNS auditing. It assists by providing a comprehensive framework for retrieving and verifying sets of records. It has several main functions:

  • fetch: Pull down a list of hosts. Filters TXT and HINFO records. DNS transfers must be enabled.
  • check: Check that the DNS server returns results as specified by the file.
  • query: Query the remote DNS server with all hostnames in the given file, and checks the IP addresses are consistent.
  • ping: Ping all hosts to check if they are available or not.
  • reverse: Check that all address records have appropriate reverse entries.

This tool relies heavily on dig and ping so ensure these are installed and working correctly before trying to use this tool.

For the examples, assume the following DNS servers:

HostnamePurposeAddress
ns1.mydomain.comCurrent Primary DNS Server10.0.0.10
ns1-new.mydomain.comNew Primary DNS Server10.0.0.20

Pulling Down Data

Your DNS server will need to be configured for zone transfers in order for this to work.

$ rd-dns-check -s ns1.mydomain.com -d mydomain.com. -f mydomain.com.yml
112 record(s) retrieved.

The file mydomain.com.yml now contains a bunch of records. This command ignores the following records: TXT, HINFO, SOA, NS, so they won't be in the file. There is currently no way to change this behavior. However, this command cannot check those types of records anyway. The data in this file is stored using YAML, hence if you want to change some names or addresses, or remove addresses, you can just edit this file directly using a text editor.

Here is an example of the data generated:

--- 
- !ruby/object:DNSRecord 
  record: 
  - alias.mydomain.com.
  - IN
  - CNAME
  - host.mydomain.com.
- !ruby/object:DNSRecord 
  record: 
  - host.mydomain.com.
  - IN
  - A
  - 10.0.0.100

It is generally expected that if one is using this tool to migrate to a new DNS server, modifications and removals will need to be made to the mydomain.com.yml file to remove old records that are no longer useful (servers that don't exist, for example), or to add or change records for equipment that still exists but has not had a consistent naming convention in the past.

Checking Records using Zone Transfer

The file we just pulled can now be used for a number of different purposes. This particular command lets us check whether a file is identical to another DNS server. Please note that the secondary DNS server must support transfer. If this is not possible, there are other checks you can use which provide a similar output, but are not as exact.

If we test it against the original DNS server that we pulled the data from we will get no errors (unless something is really screwy):

$ rd-dns-check -s ns1.mydomain.com -d mydomain.com. -c mydomain.com.yml
==========================[ Checking Records ]==========================
==============================[ Summary ]===============================
Checked 112 record(s). 0 errors.
Everything seemed okay.

If you check it against another server set up for the same domain, which is missing records, you will find they are output as errors. Here is an example from a real world DNS setup, however it is truncated and anonymized to protect the innocent:

$ rd-dns-check -s ns1-new.mydomain.com -d mydomain.com -c test.yml 
==========================[ Checking Records ]==========================
... snip ...
*** Records are different
   Primary: time.mydomain.com.                          IN CNAME abtime.mydomain.com.
 Secondary: time.mydomain.com.                          IN CNAME ab-time.mydomain.com.
*** Could not find record
   Primary: time2.mydomain.com.                         IN CNAME netboot.mydomain.com.
*** Could not find record
   Primary: winproxy.mydomain.com.                      IN     A 10.0.0.50
... snip ...
==============================[ Summary ]===============================
Checked 112 record(s). 71 errors.
The following records are okay:
... snip ...
            www.mydomain.com.                           IN     A 10.0.0.41
            linux.mydomain.com.                         IN     A 10.0.0.44
            webmail.mydomain.com.                       IN     A 10.0.0.45
            fc.mydomain.com.                            IN CNAME webmail.mydomain.com.
... snip ...

From this report we can see that the DNS servers are not identical. We can use this information to fix any problems, if we need them to be identical.

One use of this tool is to use it for auditing a DNS server. It can be run as part of a CRON job to check whether important DNS records exist and are returning the correct IP address.

Checking Records using Individual Queries

It is possible to query the DNS server for records based on the hostname given in the input file. We can then match this up to an IP address, and confirm that the addresses match. This is a useful test to check whether a DNS server will return the same address given the same hostname, but not necessarily via the same means - i.e. on one server a hostname might be a CNAME record, but on another it might be an A record. In this case, if the final address data is the same, there will be no error reported.

So, if you are migrating your DNS server and want to change the structure of some host records, but don't want to break anything, this tool will check to make sure that all original hostnames still resolve to the given IP addresses.

$ rd-dns-check -s ns1-new.mydomain.com -q mydomain.com.yml
==========================[ Checking Records ]==========================
... snip ...
*** Could not resolve hostname "aptcache.mydomain.com."
   Primary: aptproxy.mydomain.com.                      IN     A 10.0.0.100
*** Could not resolve hostname "printserver.mydomain.com."
   Primary: printserver1a.mydomain.com.                 IN     A 10.0.0.140
*** IP Address does not match
   Primary: abcproxy.mydomain.com.                      IN     A 123.x.x.x
 Secondary: abcproxy.mydomain.com.                      IN CNAME proxy.isp.net.
... snip ...
==============================[ Summary ]===============================
Checked 112 record(s). 36 errors.
The following records are okay:
... snip ...
            www.mydomain.com.                           IN     A 10.0.0.41
            linux.mydomain.com.                         IN     A 10.0.0.44
            webmail.mydomain.com.                       IN     A 10.0.0.45
            fc.mydomain.com.                            IN     A 10.0.0.45
... snip ...

Pinging All Hosts

In order to find hosts which no longer exist, there is the ping check. This will attempt to ping every A record and report back if there were any failures. Typically, if a failure was because the server/device no longer exists, then one would remove it from the mydomain.com.yml file.

$ rd-dns-check -p mydomain.com.yml 
==========================[ Pinging Records ]===========================
... snip ...
*** Could not ping host "aptcache.mydomain.com.": "ping -c 5 -t 5 -i 1 -o 10.0.0.100 > /dev/null"
            aptproxy.mydomain.com.                      IN     A 10.0.0.100
*** Could not ping host "printserver.mydomain.com.": "ping -c 5 -t 5 -i 1 -o 10.0.0.140 > /dev/null"
            printserver1a.mydomain.com.                 IN     A 10.0.0.140
... snip ...
==============================[ Summary ]===============================
Checked 112 record(s). 34 errors.
The following records are okay:
... snip ...
            www.mydomain.com.                           IN     A 10.0.0.41
            linux.mydomain.com.                         IN     A 10.0.0.44
            webmail.mydomain.com.                       IN     A 10.0.0.45
... snip ...

Checking the Reverse Records

In order to ensure that a DNS is set up correctly, we need to make sure all the reverse records are in place. This is done by resolving all the addresses in the input files to hostnames.

For example, to check if the server ns1.mydomain.com has a reverse record for 192.168.1.10 we can use dig:

$ dig +nottlid +nocmd +noall +answer -x 10.0.0.20
20.0.0.10.in-addr.arpa. IN	PTR	ns1-new.mydomain.com

N.B: The options +nottlid +nocmd +noall +answer simply make dig less verbose.

We can test all addresses in a given file:

$ rd-dns-check -s ns1.mydomain.com -d mydomain.com -r mydomain.com.yml 
======================[ Checking Reverse Lookups ]======================
... snip ...
*** Hostname does not match
   Primary: winproxy.mydomain.com.                      IN     A 10.0.0.50
 Secondary: 50.0.0.10.in-addr.arpa.                     IN   PTR win-proxy.mydomain.com
... snip ...
==============================[ Summary ]===============================
Checked 112 record(s). 3 errors.
The following records are okay:
... snip ...
    Primary: linux.mydomain.com.                        IN     A 10.0.0.44
  Secondary: 44.0.0.10.in-addr.arpa.                    IN   PTR linux.mydomain.com.
... snip ...