$Id$
INTRODUCTION
------------
This project contains tools to monitor a DNSSEC-signed zone,
including a NAGIOS plug-in.
INSTALLATION
------------
The tools can be run from the lib folder, or the contents of
the lib folder can be copied to the location of your choice.
It may be necessary to :
chmod +x dnssec_monitor.rb
RUNNING
-------
From the directory containing the code (e.g. lib), run :
./dnssec_monitor.rb -z <zone> [options]
where zone is the zone the be monitored. Additional options may be
viewed by running :
./dnssec_monitor.rb -?
(or -h, or --help)
Additional options include :
-n <ns1>[,<ns2>,<ns3>,...] Comma-separated list of nameservers
--nameservers to monitor for the zone. Defaults
to the nameservers listed in the public DNS
--kskwarn [n] Warn if KSK RRSIG expiry is within n days
Defaults to 14
--kskcritical [n] Error if KSK RRSIG expiry is within n days
Defaults to 7
--zskwarn [n] Warn if the ZSK RRSIG expiry is within n
days
Defaults to 3
--zskcritical [n] Error if ZSK RRSIG expiry is within n days
Defaults to 1
--dwarn [n] Warn if RRSIG expiry is within n days
Defaults to 3
Only useful when a list of domains
to check is supplied
--dcritical [n] Error if RRSIG expiry is within n days
Defaults to 1
Only useful when a list of domains to
check is supplied
--ods [ods_location] Load the OpenDNSSEC configuration files
from this location and use values for
InceptionOffset and ValidityPeriod
from them. Otherwise, defaults will
be used for these (3600 for
InceptionOffset, 3600 for ValidityPeriod).
OpenDNSSEC must have been installed on this
system if this option is used
--[no-]wilcard NXDomain checks will be disabled if
wildcards are enabled
--names name1,name2,name3... List of names to check in the zone
Note that there must be no whitespace
between the names
--namefile file Name of file containing list of names (and
optional types) to check in the zone
--zonefile file Name of zone file to load list of names to
check against zone
--[no-]validation Define whether to check parent DS records
and validation from the root
Defaults to true
--rootkey file Configure the key for the signed root
Defines file to load root key from
Validation from root will not be tested
if this is not configured
--dlv Configure the location of the DLV service
Defaults to dlv.isc.org.
DLV will only be used if dlvkey is set
--dlvkey file Configure the DLV key
Defines file to load DLV key from
DLV won't be used if this isn't set
--hints hint1,hint2,hint3... Configure the root hints
Defines the servers to use as root
Note that there must be no whitespace
between the names
-l, --log [FACILITY] Specify the syslog facility for results
Defaults to print to console
NAGIOS PLUG-IN
--------------
The nagios plug-in is provided in the same lib folder. It uses the same
options as dnssec_monitor, with an additional NAGIOS-specific option :
-v, --verbose [n] Set the NAGIOS verbosity to n
FUNCTIONALITY
-------------
Zone Apex Checks
The following records are checked at the zone apex : DNSKEY, SOA and NS.
For each of these RRSets, the RRSIGs are verified using one of the DNSKEYs at the apex.
For these RRSIGs, the signature expiration is checked to ensure it is a certain amount from the current time.
For these RRSIGs, the signature inception is checked to ensure it is a certain amount before the current time.
For these RRSIGs, the signature lifetime (expiration - inception) is checked for a minimum level.
Check that at least one DNSKEY matches DS in parent zone (or in the ISC DLV registry)
The inception/expiration tolerances may be obtained from the OpenDNSSEC configuration files, if available. Otherwise, command line options or defaults are used.
A list of names (or a zone file) may be specified, for which the RRSIGs should be checked as per the zone apex RRSIG checks. If found, DS records for the specified children are checked against the published children zones.
It is also possible to validate the zone from the signed root or ISC DLV registry.
TESTING
-------
The test code can be run from the main project folder :
sudo ruby -I lib test/tc_monitor.rb
Root privileges are required to start a test server on port 53.
Additionally, a tld is checked using the ISC DLV registry. This
can take some seconds to complete.
AUTHOR
------
alex@nominet.org.uk