external/bsd/bind/dist/bin/python/dnssec-coverage.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2013, 2014  Internet Systems Consortium, Inc. ("ISC")
   6  -
   7  - Permission to use, copy, modify, and/or distribute this software for any
   8  - purpose with or without fee is hereby granted, provided that the above
   9  - copyright notice and this permission notice appear in all copies.
  10  -
  11  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  - PERFORMANCE OF THIS SOFTWARE.
  18 -->
  19
  20 <refentry id="man.dnssec-coverage">
  21   <refentryinfo>
  22     <date>January 11, 2014</date>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle><application>dnssec-coverage</application></refentrytitle>
  27     <manvolnum>8</manvolnum>
  28     <refmiscinfo>BIND9</refmiscinfo>
  29   </refmeta>
  30
  31   <refnamediv>
  32     <refname><application>dnssec-coverage</application></refname>
  33     <refpurpose>checks future DNSKEY coverage for a zone</refpurpose>
  34   </refnamediv>
  35
  36   <docinfo>
  37     <copyright>
  38       <year>2013</year>
  39       <year>2014</year>
  40       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  41     </copyright>
  42   </docinfo>
  43
  44   <refsynopsisdiv>
  45     <cmdsynopsis>
  46       <command>dnssec-coverage</command>
  47       <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
  48       <arg><option>-l <replaceable class="parameter">length</replaceable></option></arg>
  49       <arg><option>-f <replaceable class="parameter">file</replaceable></option></arg>
  50       <arg><option>-d <replaceable class="parameter">DNSKEY TTL</replaceable></option></arg>
  51       <arg><option>-m <replaceable class="parameter">max TTL</replaceable></option></arg>
  52       <arg><option>-r <replaceable class="parameter">interval</replaceable></option></arg>
  53       <arg><option>-c <replaceable class="parameter">compilezone path</replaceable></option></arg>
  54       <arg><option>-k</option></arg>
  55       <arg><option>-z</option></arg>
  56       <arg choice="opt">zone</arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>DESCRIPTION</title>
  62     <para><command>dnssec-coverage</command>
  63       verifies that the DNSSEC keys for a given zone or a set of zones
  64       have timing metadata set properly to ensure no future lapses in DNSSEC
  65       coverage.
  66     </para>
  67     <para>
  68       If <option>zone</option> is specified, then keys found in
  69       the key repository matching that zone are scanned, and an ordered
  70       list is generated of the events scheduled for that key (i.e.,
  71       publication, activation, inactivation, deletion).  The list of
  72       events is walked in order of occurrence.  Warnings are generated
  73       if any event is scheduled which could cause the zone to enter a
  74       state in which validation failures might occur: for example, if
  75       the number of published or active keys for a given algorithm drops
  76       to zero, or if a key is deleted from the zone too soon after a new
  77       key is rolled, and cached data signed by the prior key has not had
  78       time to expire from resolver caches.
  79     </para>
  80     <para>
  81       If <option>zone</option> is not specified, then all keys in the
  82       key repository will be scanned, and all zones for which there are
  83       keys will be analyzed.  (Note: This method of reporting is only
  84       accurate if all the zones that have keys in a given repository
  85       share the same TTL parameters.)
  86     </para>
  87   </refsect1>
  88
  89   <refsect1>
  90     <title>OPTIONS</title>
  91
  92     <variablelist>
  93       <varlistentry>
  94         <term>-K <replaceable class="parameter">directory</replaceable></term>
  95         <listitem>
  96           <para>
  97             Sets the directory in which keys can be found.  Defaults to the
  98             current working directory.
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term>-f <replaceable class="parameter">file</replaceable></term>
 105         <listitem>
 106           <para>
 107             If a <option>file</option> is specified, then the zone is
 108             read from that file; the largest TTL and the DNSKEY TTL are
 109             determined directly from the zone data, and the
 110             <option>-m</option> and <option>-d</option> options do
 111             not need to be specified on the command line.
 112           </para>
 113         </listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term>-l <replaceable class="parameter">duration</replaceable></term>
 118         <listitem>
 119           <para>
 120             The length of time to check for DNSSEC coverage.  Key events
 121             scheduled further into the future than <option>duration</option>
 122             will be ignored, and assumed to be correct.
 123           </para>
 124           <para>
 125             The value of <option>duration</option> can be set in seconds,
 126             or in larger units of time by adding a suffix: 'mi' for minutes,
 127             'h' for hours, 'd' for days, 'w' for weeks, 'mo' for months,
 128             'y' for years.
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term>-m <replaceable class="parameter">maximum TTL</replaceable></term>
 135         <listitem>
 136           <para>
 137             Sets the value to be used as the maximum TTL for the zone or
 138             zones being analyzed when determining whether there is a
 139             possibility of validation failure.  When a zone-signing key is
 140             deactivated, there must be enough time for the record in the
 141             zone with the longest TTL to have expired from resolver caches
 142             before that key can be purged from the DNSKEY RRset.  If that
 143             condition does not apply, a warning will be generated.
 144           </para>
 145           <para>
 146             The length of the TTL can be set in seconds, or in larger units
 147             of time by adding a suffix: 'mi' for minutes, 'h' for hours,
 148             'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
 149           </para>
 150           <para>
 151             This option is mandatory unless the <option>-f</option> has
 152             been used to specify a zone file.  (If <option>-f</option> has
 153             been specified, this option may still be used; it will override
 154             the value found in the file.)
 155           </para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term>-d <replaceable class="parameter">DNSKEY TTL</replaceable></term>
 161         <listitem>
 162           <para>
 163             Sets the value to be used as the DNSKEY TTL for the zone or
 164             zones being analyzed when determining whether there is a
 165             possibility of validation failure.  When a key is rolled (that
 166             is, replaced with a new key), there must be enough time
 167             for the old DNSKEY RRset to have expired from resolver caches
 168             before the new key is activated and begins generating
 169             signatures.  If that condition does not apply, a warning
 170             will be generated.
 171           </para>
 172           <para>
 173             The length of the TTL can be set in seconds, or in larger units
 174             of time by adding a suffix: 'mi' for minutes, 'h' for hours,
 175             'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
 176           </para>
 177           <para>
 178             This option is mandatory unless the <option>-f</option> has
 179             been used to specify a zone file, or a default key TTL was
 180             set with the <option>-L</option> to
 181             <command>dnssec-keygen</command>.  (If either of those is true,
 182             this option may still be used; it will override the value found
 183             in the zone or key file.)
 184           </para>
 185         </listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term>-r <replaceable class="parameter">resign interval</replaceable></term>
 190         <listitem>
 191           <para>
 192             Sets the value to be used as the resign interval for the zone
 193             or zones being analyzed when determining whether there is a
 194             possibility of validation failure.  This value defaults to
 195             22.5 days, which is also the default in
 196             <command>named</command>.  However, if it has been changed
 197             by the <option>sig-validity-interval</option> option in
 198             <filename>named.conf</filename>, then it should also be
 199             changed here.
 200           </para>
 201           <para>
 202             The length of the interval can be set in seconds, or in larger
 203             units of time by adding a suffix: 'mi' for minutes, 'h' for hours,
 204             'd' for days, 'w' for weeks, 'mo' for months, 'y' for years.
 205           </para>
 206         </listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term>-k</term>
 211         <listitem>
 212           <para>
 213             Only check KSK coverage; ignore ZSK events. Cannot be
 214             used with <option>-z</option>.
 215           </para>
 216         </listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term>-z</term>
 221         <listitem>
 222           <para>
 223             Only check ZSK coverage; ignore KSK events. Cannot be
 224             used with <option>-k</option>.
 225           </para>
 226         </listitem>
 227       </varlistentry>
 228
 229
 230       <varlistentry>
 231         <term>-c <replaceable class="parameter">compilezone path</replaceable></term>
 232         <listitem>
 233           <para>
 234             Specifies a path to a <command>named-compilezone</command> binary.
 235             Used for testing.
 236           </para>
 237         </listitem>
 238       </varlistentry>
 239     </variablelist>
 240   </refsect1>
 241
 242   <refsect1>
 243     <title>SEE ALSO</title>
 244     <para>
 245       <citerefentry>
 246         <refentrytitle>dnssec-checkds</refentrytitle><manvolnum>8</manvolnum>
 247       </citerefentry>,
 248       <citerefentry>
 249         <refentrytitle>dnssec-dsfromkey</refentrytitle><manvolnum>8</manvolnum>
 250       </citerefentry>,
 251       <citerefentry>
 252         <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 253       </citerefentry>,
 254       <citerefentry>
 255         <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
 256       </citerefentry>
 257     </para>
 258   </refsect1>
 259
 260   <refsect1>
 261     <title>AUTHOR</title>
 262     <para><corpauthor>Internet Systems Consortium</corpauthor>
 263     </para>
 264   </refsect1>
 265
 266 </refentry><!--
 267  - Local variables:
 268  - mode: sgml
 269  - End:
 270 -->