mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-25 11:38:29 +00:00
e80ce6cfe2
The Debian 11 (bullseye) Docker image, which GitLab CI uses for building documentation, currently contains the following package versions: - Sphinx 4.5.0 - sphinx-rtd-theme 1.0.0 - docutils 0.17.1 Regenerate the man pages to match contents produced in a Sphinx environment using the above package versions. This is necessary to prevent the "docs" GitLab CI job from failing.
257 lines
8.8 KiB
Plaintext
257 lines
8.8 KiB
Plaintext
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "DNSSEC-CDS" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9"
|
|
.SH NAME
|
|
dnssec-cds \- change DS records for a child zone based on CDS/CDNSKEY
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fBdnssec\-cds\fP [\fB\-a\fP alg...] [\fB\-c\fP class] [\fB\-D\fP] {\fB\-d\fP dsset\-file} {\fB\-f\fP child\-file} [\fB\-i**[extension]] [\fP\-s** start\-time] [\fB\-T\fP ttl] [\fB\-u\fP] [\fB\-v\fP level] [\fB\-V\fP] {domain}
|
|
.SH DESCRIPTION
|
|
.sp
|
|
The \fBdnssec\-cds\fP command changes DS records at a delegation point
|
|
based on CDS or CDNSKEY records published in the child zone. If both CDS
|
|
and CDNSKEY records are present in the child zone, the CDS is preferred.
|
|
This enables a child zone to inform its parent of upcoming changes to
|
|
its key\-signing keys (KSKs); by polling periodically with \fBdnssec\-cds\fP, the
|
|
parent can keep the DS records up\-to\-date and enable automatic rolling
|
|
of KSKs.
|
|
.sp
|
|
Two input files are required. The \fI\%\-f child\-file\fP option specifies a
|
|
file containing the child\(aqs CDS and/or CDNSKEY records, plus RRSIG and
|
|
DNSKEY records so that they can be authenticated. The \fI\%\-d path\fP option
|
|
specifies the location of a file containing the current DS records. For
|
|
example, this could be a \fBdsset\-\fP file generated by
|
|
\fI\%dnssec\-signzone\fP, or the output of \fI\%dnssec\-dsfromkey\fP, or the
|
|
output of a previous run of \fBdnssec\-cds\fP\&.
|
|
.sp
|
|
The \fBdnssec\-cds\fP command uses special DNSSEC validation logic
|
|
specified by \fI\%RFC 7344\fP\&. It requires that the CDS and/or CDNSKEY records
|
|
be validly signed by a key represented in the existing DS records. This
|
|
is typically the pre\-existing KSK.
|
|
.sp
|
|
For protection against replay attacks, the signatures on the child
|
|
records must not be older than they were on a previous run of
|
|
\fBdnssec\-cds\fP\&. Their age is obtained from the modification time of the
|
|
\fBdsset\-\fP file, or from the \fI\%\-s\fP option.
|
|
.sp
|
|
To protect against breaking the delegation, \fBdnssec\-cds\fP ensures that
|
|
the DNSKEY RRset can be verified by every key algorithm in the new DS
|
|
RRset, and that the same set of keys are covered by every DS digest
|
|
type.
|
|
.sp
|
|
By default, replacement DS records are written to the standard output;
|
|
with the \fI\%\-i\fP option the input file is overwritten in place. The
|
|
replacement DS records are the same as the existing records, when no
|
|
change is required. The output can be empty if the CDS/CDNSKEY records
|
|
specify that the child zone wants to be insecure.
|
|
.sp
|
|
\fBWARNING:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Be careful not to delete the DS records when \fBdnssec\-cds\fP fails!
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Alternatively, :option\(gadnssec\-cds \-u\(ga writes an \fI\%nsupdate\fP script to the
|
|
standard output. The \fI\%\-u\fP and \fI\%\-i\fP options can be used together to
|
|
maintain a \fBdsset\-\fP file as well as emit an \fI\%nsupdate\fP script.
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-a algorithm
|
|
When converting CDS records to DS records, this option specifies
|
|
the acceptable digest algorithms. This option can be repeated, so
|
|
that multiple digest types are allowed. If none of the CDS records
|
|
use an acceptable digest type, \fBdnssec\-cds\fP will try to use CDNSKEY
|
|
records instead; if there are no CDNSKEY records, it reports an error.
|
|
.sp
|
|
When converting CDNSKEY records to DS records, this option specifies the
|
|
digest algorithm to use. It can be repeated, so that multiple DS records
|
|
are created for each CDNSKEY records.
|
|
.sp
|
|
The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values
|
|
are case\-insensitive, and the hyphen may be omitted. If no algorithm
|
|
is specified, the default is SHA\-256 only.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-c class
|
|
This option specifies the DNS class of the zones.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-D
|
|
This option generates DS records from CDNSKEY records if both CDS and CDNSKEY
|
|
records are present in the child zone. By default CDS records are
|
|
preferred.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-d path
|
|
This specifies the location of the parent DS records. The path can be the name of a file
|
|
containing the DS records; if it is a directory, \fBdnssec\-cds\fP
|
|
looks for a \fBdsset\-\fP file for the domain inside the directory.
|
|
.sp
|
|
To protect against replay attacks, child records are rejected if they
|
|
were signed earlier than the modification time of the \fBdsset\-\fP
|
|
file. This can be adjusted with the \fI\%\-s\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-f child\-file
|
|
This option specifies the file containing the child\(aqs CDS and/or CDNSKEY records, plus its
|
|
DNSKEY records and the covering RRSIG records, so that they can be
|
|
authenticated.
|
|
.sp
|
|
The examples below describe how to generate this file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-i extension
|
|
This option updates the \fBdsset\-\fP file in place, instead of writing DS records to
|
|
the standard output.
|
|
.sp
|
|
There must be no space between the \fI\%\-i\fP and the extension. If
|
|
no extension is provided, the old \fBdsset\-\fP is discarded. If an
|
|
extension is present, a backup of the old \fBdsset\-\fP file is kept
|
|
with the extension appended to its filename.
|
|
.sp
|
|
To protect against replay attacks, the modification time of the
|
|
\fBdsset\-\fP file is set to match the signature inception time of the
|
|
child records, provided that it is later than the file\(aqs current
|
|
modification time.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-s start\-time
|
|
This option specifies the date and time after which RRSIG records become
|
|
acceptable. This can be either an absolute or a relative time. An
|
|
absolute start time is indicated by a number in YYYYMMDDHHMMSS
|
|
notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A
|
|
time relative to the \fBdsset\-\fP file is indicated with \fB\-N\fP, which is N
|
|
seconds before the file modification time. A time relative to the
|
|
current time is indicated with \fBnow+N\fP\&.
|
|
.sp
|
|
If no start\-time is specified, the modification time of the
|
|
\fBdsset\-\fP file is used.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-T ttl
|
|
This option specifies a TTL to be used for new DS records. If not specified, the
|
|
default is the TTL of the old DS records. If they had no explicit TTL,
|
|
the new DS records also have no explicit TTL.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-u
|
|
This option writes an \fI\%nsupdate\fP script to the standard output, instead of
|
|
printing the new DS reords. The output is empty if no change is
|
|
needed.
|
|
.sp
|
|
Note: The TTL of new records needs to be specified: it can be done in the
|
|
original \fBdsset\-\fP file, with the \fI\%\-T\fP option, or using the
|
|
\fI\%nsupdate\fP \fBttl\fP command.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-V
|
|
This option prints version information.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-v level
|
|
This option sets the debugging level. Level 1 is intended to be usefully verbose
|
|
for general users; higher levels are intended for developers.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \fBdomain\fP
|
|
This indicates the name of the delegation point/child zone apex.
|
|
.UNINDENT
|
|
.SH EXIT STATUS
|
|
.sp
|
|
The \fBdnssec\-cds\fP command exits 0 on success, or non\-zero if an error
|
|
occurred.
|
|
.sp
|
|
If successful, the DS records may or may not need to be
|
|
changed.
|
|
.SH EXAMPLES
|
|
.sp
|
|
Before running \fI\%dnssec\-signzone\fP, ensure that the delegations
|
|
are up\-to\-date by running \fBdnssec\-cds\fP on every \fBdsset\-\fP file.
|
|
.sp
|
|
To fetch the child records required by \fBdnssec\-cds\fP, invoke
|
|
\fI\%dig\fP as in the script below. It is acceptable if the \fI\%dig\fP fails, since
|
|
\fBdnssec\-cds\fP performs all the necessary checking.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
for f in dsset\-*
|
|
do
|
|
d=${f#dsset\-}
|
|
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
|
|
dnssec\-cds \-i \-f /dev/stdin \-d $f $d
|
|
done
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
When the parent zone is automatically signed by \fI\%named\fP,
|
|
\fBdnssec\-cds\fP can be used with \fI\%nsupdate\fP to maintain a delegation as follows.
|
|
The \fBdsset\-\fP file allows the script to avoid having to fetch and
|
|
validate the parent DS records, and it maintains the replay attack
|
|
protection time.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
|
|
dnssec\-cds \-u \-i \-f /dev/stdin \-d $f $d |
|
|
nsupdate \-l
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fI\%dig(1)\fP, \fI\%dnssec\-settime(8)\fP, \fI\%dnssec\-signzone(8)\fP, \fI\%nsupdate(1)\fP, BIND 9 Administrator
|
|
Reference Manual, \fI\%RFC 7344\fP\&.
|
|
.SH AUTHOR
|
|
Internet Systems Consortium
|
|
.SH COPYRIGHT
|
|
2022, Internet Systems Consortium
|
|
.\" Generated by docutils manpage writer.
|
|
.
|