KEYMGR(8)

📦
version 3.6.2 · 16 versions
, in nixpkgs unstable, opensuse-leap 16.0

okay so this is KEYMGR(8) — the Knot DNS key management utility, and she is literally the main character of your DNSSEC setup 💅. Section 8, system administration, and yes bestie, that means she's got range.

🌸 NAME 🌸

keymgr — Knot DNS key management utility 💖

That's it, that's the tweet. She manages keys. For Knot DNS. Iconic behaviour, no notes 🎀

🦋 SYNOPSIS 🦋

okay so there are four whole ways to call her and the vibe check is: pick the one that matches what you're doing 😌

keymgr [config_option] [options] zone_name command
keymgr [config_option] [options] keystore_id command
keymgr [config_option] [-j] -l
keymgr -t parameter...

Breaking that down for you, bestie 🫶:

  • keymgr [config_option] [options] zone_name command — you're targeting a zone_name and giving her a command to run on it ✨
  • keymgr [config_option] [options] keystore_id command — same shape, except you're aiming at a keystore_id instead of a zone name 🔑
  • keymgr [config_option] [-j] -l — the -j and -l combo, no zone, no keystore, no command. Just vibes 🌈
  • keymgr -t parameter... — the -t form, where you feed her one or more parameter values 🌸
ngl the square brackets are doing a lot of heavy lifting here — they mean "optional", so don't type them fr fr 😭

<divider>

and yeah, config_option and options show up in like all of these — she's flexible like that 💜

💖 DESCRIPTION 💖

Okay so keymgr is the utility for manual key management in the Knot DNS server. It's giving "I know my way around a keystore" energy, fr fr.

It provides functions for DNSSEC keys and KASP (Key And Signature Policy) management. Iconic behavior.

The DNSSEC and KASP configuration is stored in a so called KASP database. The database is backed by LMDB. Lowkey important, bestie.

💅 Parameters 💅

  • zone_name — Name of the zone the command is executed for. That's the zone you're doing the thing for, obviously.

🎀 Config options 🎀

  • -c, --config file — Use a textual configuration file (default is /etc/knot/knot.conf). The classic.
  • -C, --confdb directory — Use a binary configuration database directory (default is /var/lib/knot/confdb). The default configuration database, if exists, has a preference to the default configuration file. Noted. 💅
  • -D, --dir path — Use specified KASP database path and default configuration.

🌸 Options 🌸

  • -t, --tsig tsig_name [tsig_algorithm [tsig_bits]] — Generates a TSIG key for the given name. Optionally the key algorithm can be specified by its name (default: hmac-sha256) and a bit length of the key (default: optimal length given by algorithm). The generated TSIG key is only displayed on stdout: the command does not create a file, nor include the key in a keystore. So don't go looking for a file, bestie — it's stdout only. ✨
  • -e, --extended — Extended output (listing of keys with full description). More deets, more slay.
  • -j, --json — Print the zones or keys (not TSIG keys) in JSON format. JSON girlies rise.
  • -l, --list — Print the list of zones that have at least one key stored in the configured KASP database.
  • -x, --mono — Don't generate colorized output. Monochrome moment.
  • -X, --color — Force colorized output in the normal mode. For when you need the drama. 🎀
  • -h, --help — Print the program help.
  • -V, --version — Print the program version. The option -VV makes the program print the compile time configuration summary. Double V for the extra info, iykyk.
NOTE: Keymgr runs with the same user privileges as configured for knotd. For example, if keymgr is run as root, but the configured user is knot, it won't be able to read files (PEM files, KASP database, ...) readable only by root. 💀 So yeah, privilege vibes are real — don't forget who you're running as.

🫶 Commands 🫶

  • list [timestamp_format] — Prints the list of key IDs and parameters of keys belonging to the zone. The lil inventory check.
  • generate [arguments...] — 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 -c or -C options used) or from Knot policy defaults. New key just dropped. 🔥
  • import-bind BIND_key_file — 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). Capital-M MUST, bestie.
  • import-pub BIND_pubkey_file — Imports a public key into KASP database. This key won't be rolled over nor used for signing. Takes one argument: path to BIND public key file.
  • import-pem PEM_file [arguments...] — 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. PEM is not gonna spill the tea for you.
  • import-pkcs11 key_id [arguments...] — 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. Metadata only, no cap.
  • nsec3-salt [new_salt] — Prints the current NSEC3 salt used for signing. If new_salt is specified, the salt is overwritten. The salt is printed and expected in hexadecimal, or dash if empty.
  • master-serial [new_serial] — Print SOA serial of the remote master stored in KASP database when using on-secondary DNSSEC signing. If new_serial is specified, the serial is overwritten (not recommended). They said not recommended, so… listen. 🙈
  • set key_spec [arguments...] — Changes a timing argument (or ksk/zsk) of an existing key to a new value. Key_spec is either the key tag or a prefix of the key ID, with an optional [id=|keytag=] prefix; arguments are like for generate, but just the related ones. A lil key glow-up.
  • ds [key_spec...] [[digest=]digest_alg...] — Generate DS record for specified keys. Key_spec is like for set, if unspecified, all KSKs are used. Digest_alg is either a digest algorithm name or an algorithm code. Use specified or all supported digest algorithms.
  • dnskey [key_spec...] — Generate DNSKEY record for specified keys. Key_spec is like for ds, if unspecified, all KSKs are used.
  • delete key_spec — Remove the specified key from zone. If the key was not shared, it is also deleted from keystore. Bye bestie. 💅
  • share key_ID zone_from — Import a key (specified by full key ID) from another zone as shared. After this, the key is owned by both zones equally. Shared custody, but make it DNSSEC.
  • trash-list [timestamp_format] — Prints the list of key IDs and parameters of deleted keys kept in the "trash bin" belonging to the zone. For a list of all deleted keys without respect to zones, use -- or - as zone_name. The deleted-key archives are right there.
  • trash-discard key_ID — Remove the specified key from the "trash bin", discarding it. Removal of a single key doesn't depend on zone_name. If -- or - is specified as key_ID, remove all trash keys belonging to zone_name. If -- or - is specified both as zone_name and key_ID, empty the entire "trash bin". Taking out the trash, literally. 🗑️
  • import-trash key_ID [arguments...] — Re-import (recover) deleted DNSSEC key from the "trash bin". Some of the original key's parameters (algorithm, size, and zsk, ksk, for-later flags) are re-used and can be overridden, the rest must be set manually anew in the same way as in the generate command. Deleted key may be re-imported to a different zone than what was the original zone. Original keystore and new keystore must match. Recovery era. 🦋

🔑 Keystore commands 🔑

  • keystore-test — Conduct some tests on the specified keystore. For each algorithm, key generation, import, removal, and use (signing and verification) are tested. Use a configured keystore_id or - for the default. Test the vibes before committing.
  • keystore-bench [num_threads] [alg_name] — Conduct a signing benchmark on the specified keystore (and optionally algorithm). 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 keystore_id or - for the default. Benchmark girlies, assemble. ⚡
  • pregenerate [timestamp-from] timestamp-to — 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.
  • show-offline [timestamp-from] [timestamp-to] — Print pre-generated offline key-related records for specified time interval. If timestamp_to is omitted, it will be to infinity. If timestamp-from is omitted, it will start from the beginning. Infinity and beyond, lowkey.
  • del-offline timestamp-from timestamp-to — Delete pre-generated offline key-related records in specified time interval.
  • del-all-old — Delete old keys that are in state 'removed'. This function also applies to non-offline KSK keys. Cleanup era.
  • generate-ksr [timestamp-from] timestamp-to — Print to stdout KeySigningRequest based on pre-generated ZSKs for specified time period. If timestamp-from is omitted, timestamp of the last offline records set is used or now if no records available. KSR goes brrr to stdout.
  • sign-ksr ksr_file — Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout.
  • validate-skr skr_file — Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt. Valid check, no corrupt nonsense allowed.
  • import-skr skr_file — 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. Out with the old sigs, in with the new.

🧚 Generate arguments 🧚

Arguments are separated by space, each of them is in format 'name=value'. A (bool) argument accepts values yes or no. If the value is omitted, it's interpreted as yes. Obsessed with a good default.

  • algorithm — Either an algorithm number (e.g. 14) or algorithm name (e.g. ecdsap256sha256). Name-drop or number-drop, your choice.
  • size — Key length in bits.
  • ksk — (bool) The key will be used for signing DNSKEY rrset. The generated key will also have the Secure Entry Point flag set to 1. Secure Entry Point says hiii.
  • zsk — (bool) The key will be used for signing zone (except DNSKEY rrset). This flag can be set concurrently with the ksk flag (for a CSK key). Can team up with ksk, cute.
  • sep — (bool) Overrides the standard setting of the Secure Entry Point flag.
  • adt — (bool) ADT bit signaling DELEG support.
  • for-later — (bool) The key will be determined for later use. It means once a new key ought to be generated, this one will be used instead if the key type and algorithm match. Saving it for later, like a good post. 💅

The following arguments are timestamps of key lifetime (see DNSSEC key states):

  • pre_active — Key started to be used for signing, not published (only for algorithm rollover).
  • publish — Key published.
  • ready — Key is waiting for submission (only for KSK).
  • active — Key used for signing.
  • retire_active — Key still used for signing, but another key is active (only for KSK or algorithm rollover).
  • retire — Key still published (only if ZSK), but no longer used for signing.
  • post_active — Key no longer published, but still used for signing (only for algorithm rollover).
  • revoke — Key revoked according to RFC 5011 trust anchor roll-over.
  • remove — Key deleted.

⏰ Timestamps ⏰

  • 0 — Zero timestamp means infinite future. Infinity, but make it key management.
  • UNIX_time — Positive number of seconds since 1970 UTC.
  • YYYYMMDDHHMMSS — Date and time in this format without any punctuation. No punctuation, just vibes.
  • relative_timestamp — A sign character (+, -), a number, and an optional time unit (y, mo, d, h, mi, s). The default unit is one second. E.g. +1mi, -2mo.

🎀 Output timestamp formats 🎀

  • (none) — The timestamps are printed as UNIX timestamp.
  • human — The timestamps are printed relatively to now using time units (e.g. -2y5mo, +1h13s). Human-readable, as the name suggests.
  • iso — The timestamps are printed in the ISO8601 format (e.g. 2016-12-31T23:59:00). Fancy and standardized.

✨ EXIT VALUES ✨

ok so when you're done running your little key operations, the exit status tells you the vibe:

  • 0 — slay 💅 everything worked, the key stuff happened, you're iconic, operation was successful.
  • any other number — nope, that's an error, something went sideways, bestie. 😭

no cap, that's the whole vibe check: zero = good, anything else = not good.

🎀 EXAMPLES 🎀

okay bestie, these are the actual real-life glow-up examples, copied exact so you can just yeet them into your terminal. 💖

  1. Generate new TSIG key:
$ keymgr -t my_name hmac-sha384
  1. Generate new DNSSEC key:
$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \
  ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y
  1. Import a DNSSEC key from BIND:
$ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key
  1. Import a CSK DNSSEC key from a PEM file:
$ keymgr example.com. import-pem 085d3890e8c22d854586678d9263933f2d02d795.pem ksk=yes zsk=yes
  1. Configure key timing:
$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi
  1. Share a KSK from another zone:
$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another-zone.com.

like, genuinely obsessed with how clean these are 🫶

🌈 SEE ALSO 🌈

go read these if you want the deep lore, iykyk:

👑 AUTHOR 👑

CZ.NIC, z.s.p.o. and contributors <https://www.knot-dns.cz/>

main character energy fr 🦋

Copyright (C) CZ.NIC, z.s.p.o. and contributors

so yeah, that's the whole page bestie — version 3.6.2, dated 2026-10-21, and that's the KEYMGR(8) footer, delivered with love. 💅✨ go forth and manage those keys, you absolute icon. 🎀🔥

📦 where this page comes from