summaryrefslogtreecommitdiffstats
path: root/bin/python/dnssec-coverage.rst
diff options
context:
space:
mode:
Diffstat (limited to 'bin/python/dnssec-coverage.rst')
-rw-r--r--bin/python/dnssec-coverage.rst152
1 files changed, 152 insertions, 0 deletions
diff --git a/bin/python/dnssec-coverage.rst b/bin/python/dnssec-coverage.rst
new file mode 100644
index 0000000..e2658cb
--- /dev/null
+++ b/bin/python/dnssec-coverage.rst
@@ -0,0 +1,152 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. _man_dnssec-coverage:
+
+dnssec-coverage - checks future DNSKEY coverage for a zone
+----------------------------------------------------------
+
+Synopsis
+~~~~~~~~
+
+``dnssec-coverage`` [**-K**\ *directory*] [**-l**\ *length*]
+[**-f**\ *file*] [**-d**\ *DNSKEY TTL*] [**-m**\ *max TTL*]
+[**-r**\ *interval*] [**-c**\ *compilezone path*] [**-k**] [**-z**]
+[zone...]
+
+Description
+~~~~~~~~~~~
+
+``dnssec-coverage`` verifies that the DNSSEC keys for a given zone or a
+set of zones have timing metadata set properly to ensure no future
+lapses in DNSSEC coverage.
+
+If ``zone`` is specified, then keys found in the key repository matching
+that zone are scanned, and an ordered list is generated of the events
+scheduled for that key (i.e., publication, activation, inactivation,
+deletion). The list of events is walked in order of occurrence. Warnings
+are generated if any event is scheduled which could cause the zone to
+enter a state in which validation failures might occur: for example, if
+the number of published or active keys for a given algorithm drops to
+zero, or if a key is deleted from the zone too soon after a new key is
+rolled, and cached data signed by the prior key has not had time to
+expire from resolver caches.
+
+If ``zone`` is not specified, then all keys in the key repository will
+be scanned, and all zones for which there are keys will be analyzed.
+(Note: This method of reporting is only accurate if all the zones that
+have keys in a given repository share the same TTL parameters.)
+
+Options
+~~~~~~~
+
+**-K** *directory*
+
+ Sets the directory in which keys can be found. Defaults to the
+ current working directory.
+
+**-f** *file*
+
+ If a ``file`` is specified, then the zone is read from that file; the
+ largest TTL and the DNSKEY TTL are determined directly from the zone
+ data, and the ``-m`` and ``-d`` options do not need to be specified
+ on the command line.
+
+**-l** *duration*
+
+ The length of time to check for DNSSEC coverage. Key events scheduled
+ further into the future than ``duration`` will be ignored, and
+ assumed to be correct.
+
+ The value of ``duration`` can be set in seconds, or in larger units
+ of time by adding a suffix: mi for minutes, h for hours, d for days,
+ w for weeks, mo for months, y for years.
+
+**-m** *maximum TTL*
+
+ Sets the value to be used as the maximum TTL for the zone or zones
+ being analyzed when determining whether there is a possibility of
+ validation failure. When a zone-signing key is deactivated, there
+ must be enough time for the record in the zone with the longest TTL
+ to have expired from resolver caches before that key can be purged
+ from the DNSKEY RRset. If that condition does not apply, a warning
+ will be generated.
+
+ The length of the TTL can be set in seconds, or in larger units of
+ time by adding a suffix: mi for minutes, h for hours, d for days, w
+ for weeks, mo for months, y for years.
+
+ This option is not necessary if the ``-f`` has been used to specify a
+ zone file. If ``-f`` has been specified, this option may still be
+ used; it will override the value found in the file.
+
+ If this option is not used and the maximum TTL cannot be retrieved
+ from a zone file, a warning is generated and a default value of 1
+ week is used.
+
+**-d** *DNSKEY TTL*
+
+ Sets the value to be used as the DNSKEY TTL for the zone or zones
+ being analyzed when determining whether there is a possibility of
+ validation failure. When a key is rolled (that is, replaced with a
+ new key), there must be enough time for the old DNSKEY RRset to have
+ expired from resolver caches before the new key is activated and
+ begins generating signatures. If that condition does not apply, a
+ warning will be generated.
+
+ The length of the TTL can be set in seconds, or in larger units of
+ time by adding a suffix: mi for minutes, h for hours, d for days, w
+ for weeks, mo for months, y for years.
+
+ This option is not necessary if ``-f`` has been used to specify a
+ zone file from which the TTL of the DNSKEY RRset can be read, or if a
+ default key TTL was set using ith the ``-L`` to ``dnssec-keygen``. If
+ either of those is true, this option may still be used; it will
+ override the values found in the zone file or the key file.
+
+ If this option is not used and the key TTL cannot be retrieved from
+ the zone file or the key file, then a warning is generated and a
+ default value of 1 day is used.
+
+**-r** *resign interval*
+
+ Sets the value to be used as the resign interval for the zone or
+ zones being analyzed when determining whether there is a possibility
+ of validation failure. This value defaults to 22.5 days, which is
+ also the default in ``named``. However, if it has been changed by the
+ ``sig-validity-interval`` option in named.conf, then it should also
+ be changed here.
+
+ The length of the interval can be set in seconds, or in larger units
+ of time by adding a suffix: mi for minutes, h for hours, d for days,
+ w for weeks, mo for months, y for years.
+
+**-k**
+
+ Only check KSK coverage; ignore ZSK events. Cannot be used with
+ ``-z``.
+
+**-z**
+
+ Only check ZSK coverage; ignore KSK events. Cannot be used with
+ ``-k``.
+
+**-c** *compilezone path*
+
+ Specifies a path to a ``named-compilezone`` binary. Used for testing.
+
+See Also
+~~~~~~~~
+
+``dnssec-checkds``\ (8), ``dnssec-dsfromkey``\ (8),
+``dnssec-keygen``\ (8), ``dnssec-signzone``\ (8)