check-soa-serials 0.3.0

check_soa_serials is an Icinga2/Nagios plugin which compares the SOA serial numbers for the same DNS zone(s) from two different servers to ensure they are in sync

check_soa_serials

check_soa_serials is a Nagios/Icinga2 plugin that compares the SOA serial numbers for the same DNS zone(s) from two different servers to ensure they are in sync

Requires Python 3.6+

Installation

You can install with pip:

python3 -m pip install check_soa_serials

Or install from source:

git clone <url>
pip install check_soa_serials

Usage

usage: check_soa_serials [-h] [--proto {tcp,udp}] [--zones-file zones_file] [--critical CRITICAL] [--warning WARNING] [--zone ZONES_FROM_ARGS] [--verbose] host host

The simplest case:

# Check that the SOA serial for the zone `myzone.domain.tld` is the same on
both `dnsserver1.domain.tld` and `dnsserver2.domain.tld.
# Alert critical if they are not the same.
check_soa_serials --zone myzone.domain.tld dnsserver1.domain.tld dnsserver2.domain.tld

The same as the preceding example, but WARNING instead of CRITICAL by altering the critical threshold to be impossible to match:

check_soa_serials --zone myzone.domain.tld --critical=~: dnsserver1.domain.tld dnsserver2.domain.tld

Allow some leeway for the SOA serials to be a value of 99 apart before alerting:

check_soa_serials --zone myzone.domain.tld --critical=99 --warning=99 dnsserver1.domain.tld dnsserver2.domain.tld

For more on Nagios plugin ranges, thresholds, perfdata, and return codes, see Nagios Plugin Development Guidelines.

Using the --warning and --critical flags

When setting the --warning and --critical flags, you should know how your DNS servers increase their SOA serial values when setting warning or critical ranges.

The DNS standards require only (RFC 1982) that a server increase the value by a reasonable interval that avoids wrapping around in a way that would confuse secondary servers. The rest is up to the implementation to decide.

Most(?) implementations follow the recommendation of RFC 1912 and use what amounts to a timestamp and revision field:

YYYYMMDDnn (YYYY=year, MM=month, DD=day, nn=revision number).

With a reasonable implementation (e.g. bind), the default threshold values (any nonzero value will alert) could be fine in a quiet environment.

In a busy DNS environment with constantly-updating zones you might need to set the values higher to avoid getting alerts about every single zone transfer before it completes.

Icinga2

Here is an Icinga2 CheckCommand object for this plugin:

object CheckCommand "soa_serials" {
  command = [ PluginDir + "/check_soa_serials", ]
  arguments = {
    "--critical" = {
      description = "Critical range for number of zones not in sync"
      key = "--critical"
      value = "$soa_serials_critical$"
    }
    "--proto" = {
      description = "Protocol to use for DNS queries"
      key = "--proto"
      value = "$soa_serials_proto$"
    }
    "--warning" = {
      description = "Warning range for number of zones not in sync"
      key = "--warning"
      value = "$soa_serials_warning$"
    }
    "--zone" = {
      description = "A zone to compare the serials for between DNS hosts"
      key = "--zone"
      repeat_key = true
      value = "$soa_serials_zone$"
    }
    "--zones-file" = {
      description = "Protocol to use for DNS queries"
      key = "--zones-file"
      value = "$soa_serials_zones_file$"
    }
    secondary = {
      description = "DNS host to check"
      required = true
      skip_key = true
      value = "$soa_serials_secondary$"
    }
    primary = {
      description = "DNS host to check against"
      required = true
      skip_key = true
      value = "$soa_serials_primary$"
    }
  }
  vars.soa_serials_secondary = "$address$"
}

And a minimal example Icinga Service:

object Service "host.domain.tld_check_soa" {
  import "generic-service"
  display_name = "DNS Zone SOA serials in sync"
  host_name = "host.domain.tld"
  check_command = "soa_serials"
  notes = "`check_soa_serials` is a custom plugin which compares the SOA serial numbers for the same DNS zone from two different servers to ensure they are in sync"
  notes_url = "https://github.com/theias/check_soa_serials"
  vars.soa_serials_primary = "primarydns.domain.tld"
  vars.zone = "_dnszone.domain.tld"
}

Note on the command path: the above Icinga2 configuration object points to the command in Icinga2's configured PluginDir, but this can be configured however you like. For instance:

• point it to wherever it is installed by its full path
• symlink from the specified path to the actual script.

Up to you!

Limitations

DNSSEC is not supported, but it could be.

Run-time could be decreased by running multiple checks concurrently. My use case did not call for this, but I'm open to the idea.

Contributing

Merge requests are welcome. For major changes, open an issue first to discuss what you want to change.

To run the test suite:

# Dependent targets create venv and install dependencies
make

Please make sure to update tests along with any changes.

License

License :: OSI Approved :: MIT License