dnssec-coverage.docbook revision 2eeb74d1cf5355dd98f6d507a10086e16bb08c4b
f70a10508f030b097a9b8afe907a06f9a1e2c4d4Tinderbox User - Copyright (C) 2013, 2014 Internet Systems Consortium, Inc. ("ISC")
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - Permission to use, copy, modify, and/or distribute this software for any
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - purpose with or without fee is hereby granted, provided that the above
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - copyright notice and this permission notice appear in all copies.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt - PERFORMANCE OF THIS SOFTWARE.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-coverage">
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </refentryinfo>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refentrytitle><application>dnssec-coverage</application></refentrytitle>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refnamediv>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refname><application>dnssec-coverage</application></refname>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refpurpose>checks future DNSKEY coverage for a zone</refpurpose>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </refnamediv>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </copyright>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-l <replaceable class="parameter">length</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-f <replaceable class="parameter">file</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-d <replaceable class="parameter">DNSKEY TTL</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-m <replaceable class="parameter">max TTL</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-r <replaceable class="parameter">interval</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">compilezone path</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-k</option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg choice="opt" rep="norepeat"><option>-z</option></arg>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </cmdsynopsis>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt verifies that the DNSSEC keys for a given zone or a set of zones
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt have timing metadata set properly to ensure no future lapses in DNSSEC
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt If <option>zone</option> is specified, then keys found in
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt the key repository matching that zone are scanned, and an ordered
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt list is generated of the events scheduled for that key (i.e.,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt publication, activation, inactivation, deletion). The list of
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt events is walked in order of occurrence. Warnings are generated
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt if any event is scheduled which could cause the zone to enter a
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt state in which validation failures might occur: for example, if
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt the number of published or active keys for a given algorithm drops
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt to zero, or if a key is deleted from the zone too soon after a new
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt key is rolled, and cached data signed by the prior key has not had
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt time to expire from resolver caches.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt If <option>zone</option> is not specified, then all keys in the
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt key repository will be scanned, and all zones for which there are
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt keys will be analyzed. (Note: This method of reporting is only
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt accurate if all the zones that have keys in a given repository
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt share the same TTL parameters.)
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <variablelist>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt <varlistentry>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt <term>-K <replaceable class="parameter">directory</replaceable></term>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt Sets the directory in which keys can be found. Defaults to the
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt current working directory.
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <term>-f <replaceable class="parameter">file</replaceable></term>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt If a <option>file</option> is specified, then the zone is
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt read from that file; the largest TTL and the DNSKEY TTL are
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt determined directly from the zone data, and the
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <option>-m</option> and <option>-d</option> options do
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt not need to be specified on the command line.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <varlistentry>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt <term>-l <replaceable class="parameter">duration</replaceable></term>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt The length of time to check for DNSSEC coverage. Key events
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt scheduled further into the future than <option>duration</option>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt will be ignored, and assumed to be correct.
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt The value of <option>duration</option> can be set in seconds,
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt or in larger units of time by adding a suffix: 'mi' for minutes,
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt 'h' for hours, 'd' for days, 'w' for weeks, 'mo' for months,
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt 'y' for years.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <term>-m <replaceable class="parameter">maximum TTL</replaceable></term>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt Sets the value to be used as the maximum TTL for the zone or
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt zones being analyzed when determining whether there is a
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt possibility of validation failure. When a zone-signing key is
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt deactivated, there must be enough time for the record in the
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt zone with the longest TTL to have expired from resolver caches
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt before that key can be purged from the DNSKEY RRset. If that
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt condition does not apply, a warning will be generated.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt The length of the TTL can be set in seconds, or in larger units
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt of time by adding a suffix: 'mi' for minutes, 'h' for hours,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt This option is mandatory unless the <option>-f</option> has
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt been used to specify a zone file. (If <option>-f</option> has
821350367e2c7313c02eb275e8e05d5193b47cfdJeremy C. Reed been specified, this option may still be used; it will override
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt the value found in the file.)
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <term>-d <replaceable class="parameter">DNSKEY TTL</replaceable></term>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt Sets the value to be used as the DNSKEY TTL for the zone or
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt zones being analyzed when determining whether there is a
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt possibility of validation failure. When a key is rolled (that
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt is, replaced with a new key), there must be enough time
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt for the old DNSKEY RRset to have expired from resolver caches
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt before the new key is activated and begins generating
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt signatures. If that condition does not apply, a warning
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt will be generated.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt The length of the TTL can be set in seconds, or in larger units
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt of time by adding a suffix: 'mi' for minutes, 'h' for hours,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt This option is mandatory unless the <option>-f</option> has
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt been used to specify a zone file, or a default key TTL was
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <command>dnssec-keygen</command>. (If either of those is true,
821350367e2c7313c02eb275e8e05d5193b47cfdJeremy C. Reed this option may still be used; it will override the value found
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt in the zone or key file.)
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <term>-r <replaceable class="parameter">resign interval</replaceable></term>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt Sets the value to be used as the resign interval for the zone
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt or zones being analyzed when determining whether there is a
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt possibility of validation failure. This value defaults to
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt 22.5 days, which is also the default in
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <command>named</command>. However, if it has been changed
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt by the <option>sig-validity-interval</option> option in
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <filename>named.conf</filename>, then it should also be
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt changed here.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt The length of the interval can be set in seconds, or in larger
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt units of time by adding a suffix: 'mi' for minutes, 'h' for hours,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt 'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </varlistentry>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt <varlistentry>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt Only check KSK coverage; ignore ZSK events. Cannot be
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt </varlistentry>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt <varlistentry>
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt Only check ZSK coverage; ignore KSK events. Cannot be
7d2b185f16b165e311e5b451324fe9ab9898dcedEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <term>-c <replaceable class="parameter">compilezone path</replaceable></term>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt Specifies a path to a <command>named-compilezone</command> binary.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt Used for testing.
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </varlistentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </variablelist>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <citerefentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refentrytitle>dnssec-checkds</refentrytitle><manvolnum>8</manvolnum>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </citerefentry>,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <citerefentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refentrytitle>dnssec-dsfromkey</refentrytitle><manvolnum>8</manvolnum>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </citerefentry>,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <citerefentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </citerefentry>,
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <citerefentry>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
831f59eb43b56642b00f82e07722836d2f9593abEvan Hunt </citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>