dnssec-coverage.docbook revision 1753d3c4d74241a847794f7e7cfd94cc79be6600
0075dcb5aeeee4864fe9f64db82c8a8202bbe6d6henning mueller<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
d8fe750649d3c87ea141981dde0182e879e27892Daniel Couto Vale "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
777277547289aa27dd829f34bfa8ae6900cadbe7Eugen Kuksa [<!ENTITY mdash "—">]>
d0e19b833d7f9c691a36342c365029720c095742henning mueller - Copyright (C) 2013, 2014 Internet Systems Consortium, Inc. ("ISC")
d8fe750649d3c87ea141981dde0182e879e27892Daniel Couto Vale - Permission to use, copy, modify, and/or distribute this software for any
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa - purpose with or without fee is hereby granted, provided that the above
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa - copyright notice and this permission notice appear in all copies.
c39fda5715a22fd5aca1f8aa0daa508c25a229c2Sascha Graef - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
c882cce4bd468bb3ac48c4d816307dcccad380b3Eugen Kuksa - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8909576a7720b882ab11c3916bd02154f2fa65fchenning mueller - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa - PERFORMANCE OF THIS SOFTWARE.
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa <refentryinfo>
cddb417c56f9919bcfac77232d6b54ddc003d54cEugen Kuksa </refentryinfo>
20c94fa632f5b9a5a1b2fbc28fa46f2afe7c65c2Tim Reddehase <refentrytitle><application>dnssec-coverage</application></refentrytitle>
772a71bcc07f7001f5cd3cb4c3dc2cf393ffe9beJulian Kornberger <refname><application>dnssec-coverage</application></refname>
d8fe750649d3c87ea141981dde0182e879e27892Daniel Couto Vale <refpurpose>checks future DNSKEY coverage for a zone</refpurpose>
0a467126135b44190e96e6dc57df4dc9e8312725Timo Kohorst </refnamediv>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <refsynopsisdiv>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <cmdsynopsis>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <arg><option>-l <replaceable class="parameter">length</replaceable></option></arg>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <arg><option>-f <replaceable class="parameter">file</replaceable></option></arg>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <arg><option>-d <replaceable class="parameter">DNSKEY TTL</replaceable></option></arg>
4ae600b01cda15be2d0ef49dc3fc4ad9006911d7Tim Reddehase <arg><option>-m <replaceable class="parameter">max TTL</replaceable></option></arg>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <arg><option>-r <replaceable class="parameter">interval</replaceable></option></arg>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller <arg><option>-c <replaceable class="parameter">compilezone path</replaceable></option></arg>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller </cmdsynopsis>
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller </refsynopsisdiv>
b997f0e2638f7b5e47f934e2f37c36767f7177d0Tim Reddehase verifies that the DNSSEC keys for a given zone or a set of zones
aa6a6b29584351c27210c27d29151fccbba61212Tim Reddehase have timing metadata set properly to ensure no future lapses in DNSSEC
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller If <option>zone</option> is specified, then keys found in
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller the key repository matching that zone are scanned, and an ordered
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller list is generated of the events scheduled for that key (i.e.,
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller publication, activation, inactivation, deletion). The list of
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller events is walked in order of occurrence. Warnings are generated
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller if any event is scheduled which could cause the zone to enter a
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller state in which validation failures might occur: for example, if
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller the number of published or active keys for a given algorithm drops
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller to zero, or if a key is deleted from the zone too soon after a new
777277547289aa27dd829f34bfa8ae6900cadbe7Eugen Kuksa key is rolled, and cached data signed by the prior key has not had
46dd7ca898be6d5dbdfda64fd90ce01e253c0878Julian Kornberger time to expire from resolver caches.
f3b8c4da2db512a2ad58709c1c6bb0d93d1866bbhenning mueller If <option>zone</option> is not specified, then all keys in the
61fdfd6e7ee93fca56a15fee37d9982528d85a60Sascha Graef key repository will be scanned, and all zones for which there are
61fdfd6e7ee93fca56a15fee37d9982528d85a60Sascha Graef keys will be analyzed. (Note: This method of reporting is only
985ad360b6abec4b1133f231e37c3163110f00c1Eugen Kuksa accurate if all the zones that have keys in a given repository
67ea9fccbdc154cf2418f16ab8883ccfcbc77b51Model Renamer share the same TTL parameters.)
985ad360b6abec4b1133f231e37c3163110f00c1Eugen Kuksa <variablelist>
67ea9fccbdc154cf2418f16ab8883ccfcbc77b51Model Renamer <varlistentry>
985ad360b6abec4b1133f231e37c3163110f00c1Eugen Kuksa <term>-K <replaceable class="parameter">directory</replaceable></term>
8ca8c974c5b60b881e5e509c33a7c2ab56eb4acfEugen Kuksa Sets the directory in which keys can be found. Defaults to the
ca86423fdf0e95c5ef6eb00c155991f8e3964533hardik current working directory.
296f03208bf82551e7ab646c8b874d618d9c44a4Eugen Kuksa </varlistentry>
ca86423fdf0e95c5ef6eb00c155991f8e3964533hardik <varlistentry>
a686bfa88234792b2dd2515da6a60aa110380916hardik <term>-f <replaceable class="parameter">file</replaceable></term>
8ca8c974c5b60b881e5e509c33a7c2ab56eb4acfEugen Kuksa If a <option>file</option> is specified, then the zone is
8ca8c974c5b60b881e5e509c33a7c2ab56eb4acfEugen Kuksa read from that file; the largest TTL and the DNSKEY TTL are
8ca8c974c5b60b881e5e509c33a7c2ab56eb4acfEugen Kuksa determined directly from the zone data, and the
8ca8c974c5b60b881e5e509c33a7c2ab56eb4acfEugen Kuksa <option>-m</option> and <option>-d</option> options do
d48ad500ac13e587c1d0d9b278ac9d86cde873efEugen Kuksa not need to be specified on the command line.
8ca8c974c5b60b881e5e509c33a7c2ab56eb4acfEugen Kuksa </varlistentry>
28042dd9ac50a328466a3dd0464b6e26a7c8796dEugen Kuksa <varlistentry>
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa <term>-l <replaceable class="parameter">duration</replaceable></term>
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa The length of time to check for DNSSEC coverage. Key events
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa scheduled further into the future than <option>duration</option>
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa will be ignored, and assumed to be correct.
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa The value of <option>duration</option> can be set in seconds,
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa or in larger units of time by adding a suffix: 'mi' for minutes,
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa 'h' for hours, 'd' for days, 'w' for weeks, 'mo' for months,
ac0d5f8866a6b0fd2c5b8b9f7a73090ce818d2feEugen Kuksa 'y' for years.
12499f46bb83dba7d8c5ef4ab9d9e5a592f99f12Tim Reddehase </varlistentry>
12499f46bb83dba7d8c5ef4ab9d9e5a592f99f12Tim Reddehase <varlistentry>
12499f46bb83dba7d8c5ef4ab9d9e5a592f99f12Tim Reddehase <term>-m <replaceable class="parameter">maximum TTL</replaceable></term>
fbe72315a0dc517cba60b5ec6f156d64139c1f3fTim Reddehase Sets the value to be used as the maximum TTL for the zone or
fbe72315a0dc517cba60b5ec6f156d64139c1f3fTim Reddehase zones being analyzed when determining whether there is a
fbe72315a0dc517cba60b5ec6f156d64139c1f3fTim Reddehase possibility of validation failure. When a zone-signing key is
b5513f660ba0c032a3667f9628e303e498e66b20Tim Reddehase deactivated, there must be enough time for the record in the
67ea9fccbdc154cf2418f16ab8883ccfcbc77b51Model Renamer zone with the longest TTL to have expired from resolver caches
bd870b52ef7afb26c0c6671c5ca4a620998ff57fTim Reddehase before that key can be purged from the DNSKEY RRset. If that
bd870b52ef7afb26c0c6671c5ca4a620998ff57fTim Reddehase condition does not apply, a warning will be generated.
12499f46bb83dba7d8c5ef4ab9d9e5a592f99f12Tim Reddehase The length of the TTL can be set in seconds, or in larger units
12499f46bb83dba7d8c5ef4ab9d9e5a592f99f12Tim Reddehase of time by adding a suffix: 'mi' for minutes, 'h' for hours,
12499f46bb83dba7d8c5ef4ab9d9e5a592f99f12Tim Reddehase 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
9b9d0de2b383747e766f7734b9de2521c6663e43Tim Reddehase This option is mandatory unless the <option>-f</option> has
9b9d0de2b383747e766f7734b9de2521c6663e43Tim Reddehase been used to specify a zone file. (If <option>-f</option> has
9b9d0de2b383747e766f7734b9de2521c6663e43Tim Reddehase been specified, this option may still be used; it will overrde
9b9d0de2b383747e766f7734b9de2521c6663e43Tim Reddehase the value found in the file.)
a45d3d730a4a0428b96460e0484513fc4219662bEugen Kuksa </varlistentry>
ae691abf44f1d6477ddb8bf5fd7e3b32457f3b7aEugen Kuksa <varlistentry>
9b9d0de2b383747e766f7734b9de2521c6663e43Tim Reddehase <term>-d <replaceable class="parameter">DNSKEY TTL</replaceable></term>
85740b8f9c770963a1fe3a993c1745fb4f4f5ea8Tim Reddehase Sets the value to be used as the DNSKEY TTL for the zone or
85740b8f9c770963a1fe3a993c1745fb4f4f5ea8Tim Reddehase zones being analyzed when determining whether there is a
85740b8f9c770963a1fe3a993c1745fb4f4f5ea8Tim Reddehase possibility of validation failure. When a key is rolled (that
85740b8f9c770963a1fe3a993c1745fb4f4f5ea8Tim Reddehase is, replaced with a new key), there must be enough time
85740b8f9c770963a1fe3a993c1745fb4f4f5ea8Tim Reddehase for the old DNSKEY RRset to have expired from resolver caches
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa before the new key is activated and begins generating
d19a4dc53e3507b5fba1308c531c9e81c4f67c4dEugen Kuksa signatures. If that condition does not apply, a warning
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa will be generated.
d19a4dc53e3507b5fba1308c531c9e81c4f67c4dEugen Kuksa The length of the TTL can be set in seconds, or in larger units
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa of time by adding a suffix: 'mi' for minutes, 'h' for hours,
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa This option is mandatory unless the <option>-f</option> has
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa been used to specify a zone file, or a default key TTL was
d19a4dc53e3507b5fba1308c531c9e81c4f67c4dEugen Kuksa <command>dnssec-keygen</command>. (If either of those is true,
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa this option may still be used; it will overrde the value found
9c3693f982b609b38e50b4246692b43b3d0a57a9Eugen Kuksa in the zone or key file.)
2ae84818de6541409f6c8f2b417b868325aed315Tim Reddehase </varlistentry>
81c8514bfc92d498e06a944ad19efc2c096b58b0Tim Reddehase <varlistentry>
81c8514bfc92d498e06a944ad19efc2c096b58b0Tim Reddehase <term>-r <replaceable class="parameter">resign interval</replaceable></term>
81c8514bfc92d498e06a944ad19efc2c096b58b0Tim Reddehase Sets the value to be used as the resign interval for the zone
81c8514bfc92d498e06a944ad19efc2c096b58b0Tim Reddehase or zones being analyzed when determining whether there is a
33d42e7c36aef2d703ed3e35536dca4cd4290470Tim Reddehase possibility of validation failure. This value defaults to
33d42e7c36aef2d703ed3e35536dca4cd4290470Tim Reddehase 22.5 days, which is also the default in
33d42e7c36aef2d703ed3e35536dca4cd4290470Tim Reddehase <command>named</command>. However, if it has been changed
33d42e7c36aef2d703ed3e35536dca4cd4290470Tim Reddehase by the <option>sig-validity-interval</option> option in
b299dbef5e70f4f78937112b19370a4d5d0e04e3Eugen Kuksa <filename>named.conf</filename>, then it should also be
b299dbef5e70f4f78937112b19370a4d5d0e04e3Eugen Kuksa changed here.
b299dbef5e70f4f78937112b19370a4d5d0e04e3Eugen Kuksa The length of the interval can be set in seconds, or in larger
b299dbef5e70f4f78937112b19370a4d5d0e04e3Eugen Kuksa units of time by adding a suffix: 'mi' for minutes, 'h' for hours,
b299dbef5e70f4f78937112b19370a4d5d0e04e3Eugen Kuksa 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
b88a97791a634e76770d150262f6b73ceacb5d91Eugen Kuksa </varlistentry>
b88a97791a634e76770d150262f6b73ceacb5d91Eugen Kuksa <varlistentry>
b88a97791a634e76770d150262f6b73ceacb5d91Eugen Kuksa Only check KSK coverage; ignore ZSK events. Cannot be
67ea9fccbdc154cf2418f16ab8883ccfcbc77b51Model Renamer </varlistentry>
985ad360b6abec4b1133f231e37c3163110f00c1Eugen Kuksa <varlistentry>
41a6f02b1f3a85f740ff745a49e7457d564162ebEugen Kuksa Only check ZSK coverage; ignore KSK events. Cannot be