402 lines
12 KiB
Groff
402 lines
12 KiB
Groff
.\" 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 "KEYMGR" "8" "2025-04-10" "3.4.6" "Knot DNS"
|
||
.SH NAME
|
||
keymgr \- Knot DNS key management utility
|
||
.SH SYNOPSIS
|
||
.sp
|
||
\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP \fIcommand\fP
|
||
.sp
|
||
\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIkeystore_id\fP \fIcommand\fP
|
||
.sp
|
||
\fBkeymgr\fP [\fIconfig_option\fP] [\-j] \fB\-l\fP
|
||
.sp
|
||
\fBkeymgr\fP \fB\-t\fP \fIparameter\fP\&...
|
||
.SH DESCRIPTION
|
||
.sp
|
||
The \fBkeymgr\fP utility serves for manual key management in Knot DNS server.
|
||
.sp
|
||
Functions for DNSSEC keys and KASP (Key And Signature Policy)
|
||
management are provided.
|
||
.sp
|
||
The DNSSEC and KASP configuration is stored in a so called KASP database.
|
||
The database is backed by LMDB.
|
||
.SS Parameters
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fIzone_name\fP
|
||
Name of the zone the command is executed for.
|
||
.UNINDENT
|
||
.SS Config options
|
||
.INDENT 0.0
|
||
.TP
|
||
\fB\-c\fP, \fB\-\-config\fP \fIfile\fP
|
||
Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP).
|
||
.TP
|
||
\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP
|
||
Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP).
|
||
The default configuration database, if exists, has a preference to the default
|
||
configuration file.
|
||
.TP
|
||
\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP
|
||
Use specified KASP database path and default configuration.
|
||
.UNINDENT
|
||
.SS Options
|
||
.INDENT 0.0
|
||
.TP
|
||
\fB\-t\fP, \fB\-\-tsig\fP \fItsig_name\fP [\fItsig_algorithm\fP [\fItsig_bits\fP]]
|
||
Generates a TSIG key for the given name. Optionally the key algorithm can
|
||
be specified by its \fI\%name\fP (default: hmac\-sha256) and
|
||
a bit length of the key (default: optimal length given by algorithm).
|
||
The generated TSIG key is only displayed on \fIstdout\fP:
|
||
the command does not create a file, nor include the key in a keystore.
|
||
.TP
|
||
\fB\-e\fP, \fB\-\-extended\fP
|
||
Extended output (listing of keys with full description).
|
||
.TP
|
||
\fB\-j\fP, \fB\-\-json\fP
|
||
Print the zones or keys in JSON format.
|
||
.TP
|
||
\fB\-l\fP, \fB\-\-list\fP
|
||
Print the list of zones that have at least one key stored in the configured KASP
|
||
database.
|
||
.TP
|
||
\fB\-x\fP, \fB\-\-mono\fP
|
||
Don\(aqt generate colorized output.
|
||
.TP
|
||
\fB\-X\fP, \fB\-\-color\fP
|
||
Force colorized output in the normal mode.
|
||
.TP
|
||
\fB\-h\fP, \fB\-\-help\fP
|
||
Print the program help.
|
||
.TP
|
||
\fB\-V\fP, \fB\-\-version\fP
|
||
Print the program version. The option \fB\-VV\fP makes the program
|
||
print the compile time configuration summary.
|
||
.UNINDENT
|
||
.sp
|
||
\fBNOTE:\fP
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
Keymgr runs with the same user privileges as configured for \fI\%knotd\fP\&.
|
||
For example, if keymgr is run as \fBroot\fP, but the configured \fI\%user\fP
|
||
is \fBknot\fP, it won\(aqt be able to read files (PEM files, KASP database, ...) readable
|
||
only by \fBroot\fP\&.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Commands
|
||
.INDENT 0.0
|
||
.TP
|
||
\fBlist\fP [\fItimestamp_format\fP]
|
||
Prints the list of key IDs and parameters of keys belonging to the zone.
|
||
.TP
|
||
\fBgenerate\fP [\fIarguments\fP\&...]
|
||
Generates new DNSSEC key and stores it in KASP database. Prints the key ID.
|
||
This action takes some number of arguments (see below). Values for unspecified arguments are taken
|
||
from corresponding policy (if \fI\-c\fP or \fI\-C\fP options used) or from Knot policy defaults.
|
||
.TP
|
||
\fBimport\-bind\fP \fIBIND_key_file\fP
|
||
Imports a BIND\-style key into KASP database (converting it to PEM format).
|
||
Takes one argument: path to BIND key file (private or public, but both MUST exist).
|
||
.TP
|
||
\fBimport\-pub\fP \fIBIND_pubkey_file\fP
|
||
Imports a public key into KASP database. This key won\(aqt be rolled over nor used for signing.
|
||
Takes one argument: path to BIND public key file.
|
||
.TP
|
||
\fBimport\-pem\fP \fIPEM_file\fP [\fIarguments\fP\&...]
|
||
Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be
|
||
specified (mainly algorithm, timers...) because they are not contained in the PEM format.
|
||
.TP
|
||
\fBimport\-pkcs11\fP \fIkey_id\fP [\fIarguments\fP\&...]
|
||
Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be
|
||
specified (mainly algorithm, timers...) because they are not available. In fact, no key
|
||
data is imported, only KASP database metadata is created.
|
||
.TP
|
||
\fBnsec3\-salt\fP [\fInew_salt\fP]
|
||
Prints the current NSEC3 salt used for signing. If \fInew_salt\fP is specified, the salt is overwritten.
|
||
The salt is printed and expected in hexadecimal, or dash if empty.
|
||
.TP
|
||
\fBlocal\-serial\fP [\fInew_serial\fP]
|
||
Print SOA serial stored in KASP database when using on\-secondary DNSSEC signing.
|
||
If \fInew_serial\fP is specified, the serial is overwritten. After updating the serial, expire the zone
|
||
(\fBzone\-purge +expire +zonefile +journal\fP) if the server is running, or remove corresponding zone file
|
||
and journal contents if the server is stopped.
|
||
.TP
|
||
\fBmaster\-serial\fP [\fInew_serial\fP]
|
||
Print SOA serial of the remote master stored in KASP database when using on\-secondary DNSSEC signing.
|
||
If \fInew_serial\fP is specified, the serial is overwritten (not recommended).
|
||
.TP
|
||
\fBset\fP \fIkey_spec\fP [\fIarguments\fP\&...]
|
||
Changes a timing argument (or ksk/zsk) of an existing key to a new value. \fIKey_spec\fP is either the
|
||
key tag or a prefix of the key ID, with an optional \fI[id=|keytag=]\fP prefix; \fIarguments\fP
|
||
are like for \fBgenerate\fP, but just the related ones.
|
||
.TP
|
||
\fBds\fP [\fIkey_spec\fP]
|
||
Generate DS record (all digest algorithms together) for specified key. \fIKey_spec\fP
|
||
is like for \fBset\fP, if unspecified, all KSKs are used.
|
||
.TP
|
||
\fBdnskey\fP [\fIkey_spec\fP]
|
||
Generate DNSKEY record for specified key. \fIKey_spec\fP
|
||
is like for \fBds\fP, if unspecified, all KSKs are used.
|
||
.TP
|
||
\fBdelete\fP \fIkey_spec\fP
|
||
Remove the specified key from zone. If the key was not shared, it is also deleted from keystore.
|
||
.TP
|
||
\fBshare\fP \fIkey_ID\fP \fIzone_from\fP
|
||
Import a key (specified by full key ID) from another zone as shared. After this, the key is
|
||
owned by both zones equally.
|
||
.UNINDENT
|
||
.SS Keystore commands
|
||
.INDENT 0.0
|
||
.TP
|
||
\fBkeystore\-test\fP
|
||
Conduct some tests on the specified keystore. For each algorithm, key generation,
|
||
import, removal, and use (signing and verification) are tested.
|
||
Use a configured \fIkeystore_id\fP or \fB\-\fP for the default.
|
||
.TP
|
||
\fBkeystore\-bench\fP [\fInum_threads\fP]
|
||
Conduct a signing benchmark on the specified keystore.
|
||
Random blocks of data are signed by the selected number of threads
|
||
(default is 1) in a loop, and the average number of signing operations per
|
||
second for each algorithm is returned.
|
||
Use a configured \fIkeystore_id\fP or \fB\-\fP for the default.
|
||
.UNINDENT
|
||
.SS Commands related to Offline KSK feature
|
||
.INDENT 0.0
|
||
.TP
|
||
\fBpregenerate\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP
|
||
Pre\-generate ZSKs for use with offline KSK, for the specified period starting from now or specified time.
|
||
This function also applies to non\-offline KSK keys.
|
||
.TP
|
||
\fBshow\-offline\fP [\fItimestamp\-from\fP] [\fItimestamp\-to\fP]
|
||
Print pre\-generated offline key\-related records for specified time interval. If \fItimestamp_to\fP
|
||
is omitted, it will be to infinity. If \fItimestamp\-from\fP is omitted, it will start from the
|
||
beginning.
|
||
.TP
|
||
\fBdel\-offline\fP \fItimestamp\-from\fP \fItimestamp\-to\fP
|
||
Delete pre\-generated offline key\-related records in specified time interval.
|
||
.TP
|
||
\fBdel\-all\-old\fP
|
||
Delete old keys that are in state \(aqremoved\(aq. This function also applies to
|
||
non\-offline KSK keys.
|
||
.TP
|
||
\fBgenerate\-ksr\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP
|
||
Print to stdout KeySigningRequest based on pre\-generated ZSKs for specified time period.
|
||
If \fItimestamp\-from\fP is omitted, timestamp of the last offline records set is used
|
||
or now if no records available.
|
||
.TP
|
||
\fBsign\-ksr\fP \fIksr_file\fP
|
||
Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout.
|
||
.TP
|
||
\fBvalidate\-skr\fP \fIskr_file\fP
|
||
Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt.
|
||
.TP
|
||
\fBimport\-skr\fP \fIskr_file\fP
|
||
Read SignedKeyResponse from a text file and import the signatures for later use in zone. If some
|
||
signatures have already been imported, they will be deleted for the period from beginning of the SKR
|
||
to infinity.
|
||
.UNINDENT
|
||
.SS Generate arguments
|
||
.sp
|
||
Arguments are separated by space, each of them is in format \(aqname=value\(aq.
|
||
.INDENT 0.0
|
||
.TP
|
||
\fBalgorithm\fP
|
||
Either an algorithm number (e.g. 14) or \fI\%algorithm name\fP
|
||
(e.g. ecdsap256sha256).
|
||
.TP
|
||
\fBsize\fP
|
||
Key length in bits.
|
||
.TP
|
||
\fBksk\fP
|
||
If set to \fByes\fP, the key will be used for signing DNSKEY rrset. The generated key will also
|
||
have the Secure Entry Point flag set to 1.
|
||
.TP
|
||
\fBzsk\fP
|
||
If set to \fByes\fP, the key will be used for signing zone (except DNSKEY rrset). This flag can
|
||
be set concurrently with the \fBksk\fP flag (for a CSK key).
|
||
.TP
|
||
\fBsep\fP
|
||
Overrides the standard setting of the Secure Entry Point flag.
|
||
.UNINDENT
|
||
.sp
|
||
The following arguments are timestamps of key lifetime (see \fI\%DNSSEC key states\fP):
|
||
.INDENT 0.0
|
||
.TP
|
||
\fBpre_active\fP
|
||
Key started to be used for signing, not published (only for algorithm rollover).
|
||
.TP
|
||
\fBpublish\fP
|
||
Key published.
|
||
.TP
|
||
\fBready\fP
|
||
Key is waiting for submission (only for KSK).
|
||
.TP
|
||
\fBactive\fP
|
||
Key used for signing.
|
||
.TP
|
||
\fBretire_active\fP
|
||
Key still used for signing, but another key is active (only for KSK or algorithm rollover).
|
||
.TP
|
||
\fBretire\fP
|
||
Key still published (only if ZSK), but no longer used for signing.
|
||
.TP
|
||
\fBpost_active\fP
|
||
Key no longer published, but still used for signing (only for algorithm rollover).
|
||
.TP
|
||
\fBrevoke\fP
|
||
Key revoked according to \fI\%RFC 5011\fP trust anchor roll\-over.
|
||
.TP
|
||
\fBremove\fP
|
||
Key deleted.
|
||
.UNINDENT
|
||
.SS Timestamps
|
||
.INDENT 0.0
|
||
.TP
|
||
.B 0
|
||
Zero timestamp means infinite future.
|
||
.TP
|
||
.B \fIUNIX_time\fP
|
||
Positive number of seconds since 1970 UTC.
|
||
.TP
|
||
.B \fIYYYYMMDDHHMMSS\fP
|
||
Date and time in this format without any punctuation.
|
||
.TP
|
||
.B \fIrelative_timestamp\fP
|
||
A sign character (\fB+\fP, \fB\-\fP), a number, and an optional time unit
|
||
(\fBy\fP, \fBmo\fP, \fBd\fP, \fBh\fP, \fBmi\fP, \fBs\fP). The default unit is one second.
|
||
E.g. +1mi, \-2mo.
|
||
.UNINDENT
|
||
.SS Output timestamp formats
|
||
.INDENT 0.0
|
||
.TP
|
||
.B (none)
|
||
The timestamps are printed as UNIX timestamp.
|
||
.TP
|
||
\fBhuman\fP
|
||
The timestamps are printed relatively to now using time units (e.g. \-2y5mo, +1h13s).
|
||
.TP
|
||
\fBiso\fP
|
||
The timestamps are printed in the ISO8601 format (e.g. 2016\-12\-31T23:59:00).
|
||
.UNINDENT
|
||
.SH EXIT VALUES
|
||
.sp
|
||
Exit status of 0 means successful operation. Any other exit status indicates
|
||
an error.
|
||
.SH EXAMPLES
|
||
.INDENT 0.0
|
||
.IP 1. 3
|
||
Generate new TSIG key:
|
||
.INDENT 3.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ keymgr \-t my_name hmac\-sha384
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.IP 2. 3
|
||
Generate new DNSSEC key:
|
||
.INDENT 3.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \e
|
||
ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.IP 3. 3
|
||
Import a DNSSEC key from BIND:
|
||
.INDENT 3.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ keymgr example.com. import\-bind ~/bind/Kharbinge4d5.+007+63089.key
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.IP 4. 3
|
||
Import a CSK DNSSEC key from a PEM file:
|
||
.INDENT 3.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ keymgr example.com. import\-pem 085d3890e8c22d854586678d9263933f2d02d795.pem ksk=yes zsk=yes
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.IP 5. 3
|
||
Configure key timing:
|
||
.INDENT 3.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.IP 6. 3
|
||
Share a KSK from another zone:
|
||
.INDENT 3.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another\-zone.com.
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH SEE ALSO
|
||
.sp
|
||
\fI\%RFC 6781\fP \- DNSSEC Operational Practices.
|
||
\fI\%RFC 7583\fP \- DNSSEC Key Rollover Timing Considerations.
|
||
.sp
|
||
\fBknot.conf(5)\fP,
|
||
\fBknotc(8)\fP,
|
||
\fBknotd(8)\fP\&.
|
||
.SH AUTHOR
|
||
CZ.NIC Labs <https://www.knot-dns.cz>
|
||
.SH COPYRIGHT
|
||
Copyright 2010–2025, CZ.NIC, z.s.p.o.
|
||
.\" Generated by docutils manpage writer.
|
||
.
|