From 5b463539b79bd1cc397d678ef20956173359398a Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Fri, 13 Mar 2026 15:42:57 +0100 Subject: [PATCH] Add documentation about dnst-ldnsutils package and update man pages (#165) * Update man pages * Fix typo * Note where differences are documented * Fix cargo install instruction * Document ldns emulation mode on RtD index page * Document dnst-ldnsutils package installation --- README.md | 10 +++++----- doc/manual/build/man/dnst-key2ds.1 | 2 +- doc/manual/build/man/dnst-keygen.1 | 2 +- doc/manual/build/man/dnst-keyset.1 | 4 ++-- doc/manual/build/man/dnst-notify.1 | 2 +- doc/manual/build/man/dnst-nsec3-hash.1 | 2 +- doc/manual/build/man/dnst-signzone.1 | 2 +- doc/manual/build/man/dnst-update.1 | 2 +- doc/manual/build/man/dnst.1 | 2 +- doc/manual/build/man/ldns-key2ds.1 | 2 +- doc/manual/build/man/ldns-keygen.1 | 2 +- doc/manual/build/man/ldns-notify.1 | 2 +- doc/manual/build/man/ldns-nsec3-hash.1 | 2 +- doc/manual/build/man/ldns-signzone.1 | 2 +- doc/manual/build/man/ldns-update.1 | 2 +- doc/manual/source/building.rst | 2 +- doc/manual/source/index.rst | 18 ++++++++++++++++++ doc/manual/source/installation.rst | 12 ++++++++++++ 18 files changed, 51 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index f15c6e1..cc9fab9 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ dnst :: Domain Name System Tools - a toolset to assist DNS operators with zone and nameserver maintenance. dnst is intended to offer both: -- a supported drop-in (see below) replacement and upgrade path for a subset of the popular NLnet Labs LDNS example tools, re-implemented in the Rust prpgramming language powered by the NLnet Labs [domain](https://github.com/NLnetLabs/domain) Rust library +- a supported drop-in (see below) replacement and upgrade path for a subset of the popular NLnet Labs LDNS example tools, re-implemented in the Rust programming language powered by the NLnet Labs [domain](https://github.com/NLnetLabs/domain) Rust library - an evolving toolbox of commands to aid DNS operators in the maintenance and operation of their zones and nameservers. dnst is not intended perform dig and drill-like functions; for this NLnet Labs offers [dnsi](https://github.com/NLnetLabs/dnsi). @@ -23,9 +23,9 @@ dnst supports two modes of operation: - key2ds - keygen -- nsec3hash -- signzone -- notify +- nsec3hash +- signzone +- notify - update ## Installation and documentation @@ -34,7 +34,7 @@ See https://dnst.docs.nlnetlabs.nl/. ## Compatibility with supported LDNS examples -ldns mode allows for one-to-one replacement of the ldns example utilities by dnst, without having to change existing scripts. In this mode, the supported ldns examples are very closely emulated by dnst, though there are some exceptions. Please see the documentation for details. +ldns mode allows for one-to-one replacement of the ldns example utilities by dnst, without having to change existing scripts. In this mode, the supported ldns examples are very closely emulated by dnst, though there are some exceptions. Please see the documentation for details (differences are noted in the relevant man page). Because of a radically different achitechture and programming language, please note that the domain library is not intended as a drop-in replacement for the ldns library. diff --git a/doc/manual/build/man/dnst-key2ds.1 b/doc/manual/build/man/dnst-key2ds.1 index 18ab21f..52c3f8c 100644 --- a/doc/manual/build/man/dnst-key2ds.1 +++ b/doc/manual/build/man/dnst-key2ds.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-KEY2DS" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST-KEY2DS" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-key2ds \- Generate DS RRs from the DNSKEYs in a keyfile .SH SYNOPSIS diff --git a/doc/manual/build/man/dnst-keygen.1 b/doc/manual/build/man/dnst-keygen.1 index e294a97..4edbfdb 100644 --- a/doc/manual/build/man/dnst-keygen.1 +++ b/doc/manual/build/man/dnst-keygen.1 @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-KEYGEN" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST-KEYGEN" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-keygen \- Generate a new key pair for a domain name .SH SYNOPSIS diff --git a/doc/manual/build/man/dnst-keyset.1 b/doc/manual/build/man/dnst-keyset.1 index 682bf17..56cf827 100644 --- a/doc/manual/build/man/dnst-keyset.1 +++ b/doc/manual/build/man/dnst-keyset.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-KEYSET" "1" "Mar 02, 2026" "0.1.1-dev" "dnst" +.TH "DNST-KEYSET" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-keyset \- Manage DNSSEC signing keys for a domain .SH SYNOPSIS @@ -35,7 +35,7 @@ dnst-keyset \- Manage DNSSEC signing keys for a domain \fBdnst keyset\fP \fB\-c \fP \fB[OPTIONS]\fP \fB\fP \fB[ARGS]\fP .SH DESCRIPTION .sp -The \fBkeyset\fP subcommand manages a set of DNSSEC (\fI\%RFC 9364\fP) signing keys. +The \fBkeyset\fP subcommand manages a set of DNSSEC (\X'tty: link https://www.rfc-editor.org/rfc/rfc9364'\fI\%RFC 9364\fP\X'tty: link') signing keys. This subcommand is meant to be part of a DNSSEC signing solution. The \fBkeyset\fP subcommand manages signing keys and generates a signed DNSKEY RRset. A separate zone signer (not part of dnst) is expected to use the zone diff --git a/doc/manual/build/man/dnst-notify.1 b/doc/manual/build/man/dnst-notify.1 index 3ea25b3..4592328 100644 --- a/doc/manual/build/man/dnst-notify.1 +++ b/doc/manual/build/man/dnst-notify.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-NOTIFY" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST-NOTIFY" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-notify \- Send a NOTIFY message to a list of name servers .SH SYNOPSIS diff --git a/doc/manual/build/man/dnst-nsec3-hash.1 b/doc/manual/build/man/dnst-nsec3-hash.1 index 1924b4e..53e317d 100644 --- a/doc/manual/build/man/dnst-nsec3-hash.1 +++ b/doc/manual/build/man/dnst-nsec3-hash.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-NSEC3-HASH" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST-NSEC3-HASH" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-nsec3-hash \- Print out the NSEC3 hash of a domain name .SH SYNOPSIS diff --git a/doc/manual/build/man/dnst-signzone.1 b/doc/manual/build/man/dnst-signzone.1 index 269af5f..a104a03 100644 --- a/doc/manual/build/man/dnst-signzone.1 +++ b/doc/manual/build/man/dnst-signzone.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-SIGNZONE" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST-SIGNZONE" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-signzone \- Sign the zone with the given key(s) .SH SYNOPSIS diff --git a/doc/manual/build/man/dnst-update.1 b/doc/manual/build/man/dnst-update.1 index 15ef24c..7ea7131 100644 --- a/doc/manual/build/man/dnst-update.1 +++ b/doc/manual/build/man/dnst-update.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST-UPDATE" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST-UPDATE" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst-update \- Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name .SH SYNOPSIS diff --git a/doc/manual/build/man/dnst.1 b/doc/manual/build/man/dnst.1 index 3f49fe7..db09372 100644 --- a/doc/manual/build/man/dnst.1 +++ b/doc/manual/build/man/dnst.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "DNST" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "DNST" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME dnst \- DNS Management Tools .SH SYNOPSIS diff --git a/doc/manual/build/man/ldns-key2ds.1 b/doc/manual/build/man/ldns-key2ds.1 index 8a6a05f..f9f1463 100644 --- a/doc/manual/build/man/ldns-key2ds.1 +++ b/doc/manual/build/man/ldns-key2ds.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LDNS-KEY2DS" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "LDNS-KEY2DS" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME ldns-key2ds \- Generate DS RRs from the DNSKEYs in a keyfile .SH SYNOPSIS diff --git a/doc/manual/build/man/ldns-keygen.1 b/doc/manual/build/man/ldns-keygen.1 index 8617ca4..726d706 100644 --- a/doc/manual/build/man/ldns-keygen.1 +++ b/doc/manual/build/man/ldns-keygen.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LDNS-KEYGEN" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "LDNS-KEYGEN" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME ldns-keygen \- Generate a new key pair for a domain name .SH SYNOPSIS diff --git a/doc/manual/build/man/ldns-notify.1 b/doc/manual/build/man/ldns-notify.1 index 1906d30..9e7b85e 100644 --- a/doc/manual/build/man/ldns-notify.1 +++ b/doc/manual/build/man/ldns-notify.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LDNS-NOTIFY" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "LDNS-NOTIFY" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME ldns-notify \- Send a NOTIFY message to a list of name servers .SH SYNOPSIS diff --git a/doc/manual/build/man/ldns-nsec3-hash.1 b/doc/manual/build/man/ldns-nsec3-hash.1 index a54a671..fd70257 100644 --- a/doc/manual/build/man/ldns-nsec3-hash.1 +++ b/doc/manual/build/man/ldns-nsec3-hash.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LDNS-NSEC3-HASH" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "LDNS-NSEC3-HASH" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME ldns-nsec3-hash \- Print out the NSEC3 hash of a domain name .SH SYNOPSIS diff --git a/doc/manual/build/man/ldns-signzone.1 b/doc/manual/build/man/ldns-signzone.1 index d92cef3..5619344 100644 --- a/doc/manual/build/man/ldns-signzone.1 +++ b/doc/manual/build/man/ldns-signzone.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LDNS-SIGNZONE" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "LDNS-SIGNZONE" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME ldns-signzone \- Sign the zone with the given key(s) .SH SYNOPSIS diff --git a/doc/manual/build/man/ldns-update.1 b/doc/manual/build/man/ldns-update.1 index b69f785..3d23c68 100644 --- a/doc/manual/build/man/ldns-update.1 +++ b/doc/manual/build/man/ldns-update.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LDNS-UPDATE" "1" "Feb 25, 2026" "0.1.1-dev" "dnst" +.TH "LDNS-UPDATE" "1" "Mar 05, 2026" "0.2.0-alpha1" "dnst" .SH NAME ldns-update \- Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name .SH SYNOPSIS diff --git a/doc/manual/source/building.rst b/doc/manual/source/building.rst index 9ee5789..e587e4a 100644 --- a/doc/manual/source/building.rst +++ b/doc/manual/source/building.rst @@ -94,7 +94,7 @@ specific branch, include the ``--branch`` option as well: .. code-block:: text - cargo install --git https://github.com/NLnetLabs/dnst.git --branch main + cargo install dnst --bin dnst --git https://github.com/NLnetLabs/dnst.git --branch main .. Seealso:: For more installation options refer to the `Cargo book `_. diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 9609cd2..61f0473 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -8,6 +8,24 @@ coming soon. It depends on OpenSSL for its cryptography related functions. +**dnst** supports two modes of operation: + +* dnst mode: the default. +* ldns emulation mode: activated by invoking dnst using the name of a supported ldns example, e.g. ldns-keygen. + +**dnst** currently offers drop-in replacement of the following ldns examples: + +* key2ds +* keygen +* nsec3hash +* signzone +* notify +* update + +In ldns emulation mode, the supported ldns examples are very closely emulated +by dnst, though there are some exceptions. Differences are noted in the +relevant man pages of individual commands. + .. toctree:: :maxdepth: 2 :hidden: diff --git a/doc/manual/source/installation.rst b/doc/manual/source/installation.rst index 77de4af..c6927d8 100644 --- a/doc/manual/source/installation.rst +++ b/doc/manual/source/installation.rst @@ -370,3 +370,15 @@ a specific version, if needed. .. code-block:: text sudo docker run nlnetlabs/dnst:v0.1.1-rc1 + +Replacing LDNS with dnst +------------------------ + +To replace the installed ldns examples with dnst in ldns emulation mode, we +provide the ``dnst-ldnsutils`` package. When installing this package, ``dnst`` +will automatically get installed alongside it, existing ``ldns-utils`` will be +uninstalled, and supported ldns examples get replaced with dnst. + +To install ``dnst-ldnsutils``, simply follow the steps `above `_ to install ``dnst``, but install ``dnst-ldnsutils`` (e.g. ``sudo +apt install dnst-ldnsutils``) instead of ``dnst``.