From 80df5fae81b3cb21e3cd4f5ac55d1c7b4121594a Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 10:10:57 +0100 Subject: [PATCH 01/23] Fix sphinx default language --- doc/manual/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index ffa9b5d..205677a 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -100,7 +100,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. From 0d5712e4cc8c689f46cf0d9b4f47bd9b2faab4b2 Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Tue, 12 Nov 2024 12:50:16 +0100 Subject: [PATCH 02/23] Add ldns-nsec3-hash man page based on the original, and adjust the dnst-nsec3-hash page to match the current help output of the command. --- doc/manual/source/conf.py | 4 ++-- doc/manual/source/man/dnst-nsec3-hash.rst | 18 +++++++------- doc/manual/source/man/ldns-nsec3-hash.rst | 29 +++++++++++++++++++++++ 3 files changed, 40 insertions(+), 11 deletions(-) create mode 100644 doc/manual/source/man/ldns-nsec3-hash.rst diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index 205677a..9cda426 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -189,8 +189,8 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('man/dnst', 'dnst', 'DNS Management Tools', author, 1), - ('man/dnst-nsec3-hash', 'dnst-nsec3-hash', 'DNS Management Tools', author, - 1), + ('man/dnst-nsec3-hash', 'dnst-nsec3-hash', 'print out the NSEC3 hash for a domain name', author, 1), + ('man/ldns-nsec3-hash', 'ldns-nsec3-hash', 'print out the NSEC3 hash for a domain name', author, 1), ] diff --git a/doc/manual/source/man/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index 2001447..9f675c7 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -4,27 +4,27 @@ dnst-nsec3-hash Synopsis -------- -:program:`dnst nsec3-hash` [``options``] :samp:`domain-name` +:program:`dnst nsec3-hash` [``OPTIONS``] :samp:`` Description ----------- -**dnst nsec3-hash** prints the NSEC3 hash for the given domain name. +**dnst nsec3-hash** prints the NSEC3 hash of a given domain name. Options ------- -.. option:: -a number-or-mnemonic, --algorithm=number-or-mnemonic +.. option:: -a , --algorithm Use the given algorithm number for the hash calculation. Defaults to - ``sha1``. + 1 (SHA-1). -.. option:: -s salt, --salt=count +.. option:: -i , -t , --iterations - Use the given salt for the hash calculation. The salt value should be - in hexadecimal format. + Use the given number of additional iterations for the hash calculation. -.. option:: -i count, -t count, --iterations=count +.. option:: -s >, --salt > - Use *count* iterations for the hash calculation. + Use the given salt for the hash calculation. The salt value should be + in hexadecimal format. diff --git a/doc/manual/source/man/ldns-nsec3-hash.rst b/doc/manual/source/man/ldns-nsec3-hash.rst new file mode 100644 index 0000000..20c16e6 --- /dev/null +++ b/doc/manual/source/man/ldns-nsec3-hash.rst @@ -0,0 +1,29 @@ +ldns-nsec3-hash +=============== + +Synopsis +-------- + +:program:`ldns-nsec3-hash` :samp:`<{domain-name}>` + +Description +----------- + +**ldns-nsec3-hash** is used to print out the NSEC3 hash for the given domain name. + +Options +------- + +.. option:: -a number + + Use the given algorithm number for the hash calculation. Defaults to + 1 (SHA-1). + +.. option:: -s salt + + Use the given salt for the hash calculation. The salt value should be + in hexadecimal format. + +.. option:: -t count + + Use count iterations for the hash calculation. From 20902bbab7d111d8bb80bdae1f7f1d392a4d4679 Mon Sep 17 00:00:00 2001 From: Ximon Eighteen <3304436+ximon18@users.noreply.github.com> Date: Tue, 12 Nov 2024 20:28:54 +0100 Subject: [PATCH 03/23] Update dnst-nsec3-hash.rst Co-authored-by: Jannik --- doc/manual/source/man/dnst-nsec3-hash.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/man/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index 9f675c7..56e093b 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -23,7 +23,7 @@ Options Use the given number of additional iterations for the hash calculation. -.. option:: -s >, --salt > +.. option:: -s , --salt Use the given salt for the hash calculation. The salt value should be in hexadecimal format. From 83c3b6177bb887409116f382bd05e26fb73f5afd Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 11:36:04 +0100 Subject: [PATCH 04/23] Add key2ds manual --- doc/manual/source/conf.py | 2 ++ doc/manual/source/man/dnst-key2ds.rst | 42 ++++++++++++++++++++++++++ doc/manual/source/man/ldns-key2ds.rst | 43 +++++++++++++++++++++++++++ 3 files changed, 87 insertions(+) create mode 100644 doc/manual/source/man/dnst-key2ds.rst create mode 100644 doc/manual/source/man/ldns-key2ds.rst diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index 9cda426..a90a60e 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -191,6 +191,8 @@ ('man/dnst', 'dnst', 'DNS Management Tools', author, 1), ('man/dnst-nsec3-hash', 'dnst-nsec3-hash', 'print out the NSEC3 hash for a domain name', author, 1), ('man/ldns-nsec3-hash', 'ldns-nsec3-hash', 'print out the NSEC3 hash for a domain name', author, 1), + ('man/dnst-key2ds', 'dnst-key2ds', 'Generate DS RRs from the DNSKEYs in a keyfile', author, 1), + ('man/ldns-key2ds', 'ldns-key2ds', 'Generate DS RRs from the DNSKEYs in a keyfile', author, 1), ] diff --git a/doc/manual/source/man/dnst-key2ds.rst b/doc/manual/source/man/dnst-key2ds.rst new file mode 100644 index 0000000..5ba44e4 --- /dev/null +++ b/doc/manual/source/man/dnst-key2ds.rst @@ -0,0 +1,42 @@ +dnst-key2ds +=============== + +Synopsis +-------- + +:program:`dnst key2ds` [``OPTIONS``] ```` + +Description +----------- + +**dnst key2ds** generates a DS RR for each DNSKEY in ````. + +The following file will be created for each key: ``K++.ds``. The +base name ``K++`` will be printed to stdout. + + +Options +------- + +.. option:: -a , --algorithm + + Use the given algorithm for the digest. Defaults to the digest algorithm + used for the DNSKEY, and if it can't be determined SHA-1. + +.. might change to --ignore-sep when implemented +.. option:: -f + + Ignore the SEP flag and make DS records for any key. + +.. option:: -n + + Write the generated DS records to stdout instead of a file. + +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). + +.. option:: -V, --version + + Print the version. diff --git a/doc/manual/source/man/ldns-key2ds.rst b/doc/manual/source/man/ldns-key2ds.rst new file mode 100644 index 0000000..eb0f82a --- /dev/null +++ b/doc/manual/source/man/ldns-key2ds.rst @@ -0,0 +1,43 @@ +ldns-key2ds +=============== + +Synopsis +-------- + +:program:`ldns-key2ds` [``OPTIONS``] ```` + +Description +----------- + +**ldns-key2ds** is used to transform a public DNSKEY RR to a DS RR. When run +it will read ```` with a DNSKEY RR in it, and it will create a .ds +file with the DS RR in it. + +It prints out the basename for this file (``K++``). + +By default, it takes a pick of algorithm similar to the key algorithm, +SHA1 for RSASHA1, and so on. + + +Options +------- + +.. option:: -f + + Ignore SEP flag (i.e. make DS records for any key) + +.. option:: -n + + Write the result DS Resource Record to stdout instead of a file + +.. option:: -1 + + Use SHA1 as the hash function. + +.. option:: -2 + + Use SHA256 as the hash function + +.. option:: -4 + + Use SHA383 as the hash function From 33732c433288557dae3fd33570a2ef547d710123 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 14:04:54 +0100 Subject: [PATCH 05/23] Add dnst-keygen manual --- doc/manual/source/man/dnst-keygen.rst | 78 +++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 doc/manual/source/man/dnst-keygen.rst diff --git a/doc/manual/source/man/dnst-keygen.rst b/doc/manual/source/man/dnst-keygen.rst new file mode 100644 index 0000000..bb738c9 --- /dev/null +++ b/doc/manual/source/man/dnst-keygen.rst @@ -0,0 +1,78 @@ +dnst-keygen +=============== + +Synopsis +-------- + +:program:`dnst keygen` [``OPTIONS``] ``-a `` ```` + +Description +----------- + +**dnst keygen** generates a new key pair for a given domain name. + +The following files will be created: + +- ``K++.key``: The public key file containing a DNSKEY RR in + zone file format. + +- ``K++.private``: The private key file containing the private + key data fields in BIND's *Private-key-format*. + +- ``K++.ds``: The public key digest file containing the DS RR + in zone file format. It is only created for key signing keys. + +| ```` is the fully-qualified owner name for the key (with a trailing dot). +| ```` is the algorithm number of the key, zero-padded to 3 digits. +| ```` is the 16-bit tag of the key, zero-padded to 5 digits. + +Upon completion, ``K++`` will be printed. + +Options +------- + +.. option:: -a + + Use the given signing algorithm. + + Possible values: + + .. table:: + :widths: auto + + ==================== ======================== + **Mnemonic** **Description** + ==================== ======================== + ``list`` List all algorithms + ``RSASHA256`` RSA with SHA-256 + ``ECDSAP256SHA256`` ECDSA P-256 with SHA-256 + ``ECDSAP384SHA384`` ECDSA P-384 with SHA-384 + ``ED25519`` ED25519 + ``ED448`` ED448 + ==================== ======================== + + +.. option:: -k + + Generate a key signing key (KSK) instead of a zone signing key (ZSK). + +.. option:: -b + + The length of the key (for RSA keys only). Defaults to 2048. + +.. option:: -r + + The randomness source to use for generation. Defaults to ``/dev/urandom``. + +.. option:: -s + + Create symlinks ``.key`` and ``.private`` to the generated keys. + +.. option:: -f + + Overwrite existing symlinks (for use with ``-s``). + +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). From 29852ac979600dbff2abca96d768a4e973041cff Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 14:08:15 +0100 Subject: [PATCH 06/23] Change dnst-keygen algorithms to list from table --- doc/manual/source/man/dnst-keygen.rst | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/doc/manual/source/man/dnst-keygen.rst b/doc/manual/source/man/dnst-keygen.rst index bb738c9..5cc1062 100644 --- a/doc/manual/source/man/dnst-keygen.rst +++ b/doc/manual/source/man/dnst-keygen.rst @@ -35,22 +35,9 @@ Options Use the given signing algorithm. - Possible values: - - .. table:: - :widths: auto - - ==================== ======================== - **Mnemonic** **Description** - ==================== ======================== - ``list`` List all algorithms - ``RSASHA256`` RSA with SHA-256 - ``ECDSAP256SHA256`` ECDSA P-256 with SHA-256 - ``ECDSAP384SHA384`` ECDSA P-384 with SHA-384 - ``ED25519`` ED25519 - ``ED448`` ED448 - ==================== ======================== - + Possible values are ``RSASHA256``, ``ECDSAP256SHA256``, + ``ECDSAP384SHA384``, ``ED25519``, ``ED448``; or ``list`` to list all + available algorithms. .. option:: -k From d653ac6c270887a038d57fbda809e8f67ad1192e Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 14:40:20 +0100 Subject: [PATCH 07/23] Change dnst-keygen algorithms back to table --- doc/manual/source/man/dnst-keygen.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/manual/source/man/dnst-keygen.rst b/doc/manual/source/man/dnst-keygen.rst index 5cc1062..9a901a7 100644 --- a/doc/manual/source/man/dnst-keygen.rst +++ b/doc/manual/source/man/dnst-keygen.rst @@ -31,13 +31,22 @@ Upon completion, ``K++`` will be printed. Options ------- -.. option:: -a +.. option:: -a Use the given signing algorithm. - Possible values are ``RSASHA256``, ``ECDSAP256SHA256``, - ``ECDSAP384SHA384``, ``ED25519``, ``ED448``; or ``list`` to list all - available algorithms. + Possible values are: + + =================== ========== ========================= + **Mnemonic** **Number** **Description** + =================== ========== ========================= + ``list`` List available algorithms + ``RSASHA256`` 8 RSA with SHA-256 + ``ECDSAP256SHA256`` 13 ECDSA P-256 with SHA-256 + ``ECDSAP384SHA384`` 14 ECDSA P-384 with SHA-384 + ``ED25519`` 15 ED25519 + ``ED448`` 16 ED448 + =================== ========== ========================= .. option:: -k From 8401f97c1461bba34af6e7c281ced1aaf39d661c Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 14:40:32 +0100 Subject: [PATCH 08/23] Add ldns-keygen manual --- doc/manual/source/man/ldns-keygen.rst | 59 +++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 doc/manual/source/man/ldns-keygen.rst diff --git a/doc/manual/source/man/ldns-keygen.rst b/doc/manual/source/man/ldns-keygen.rst new file mode 100644 index 0000000..3dbff83 --- /dev/null +++ b/doc/manual/source/man/ldns-keygen.rst @@ -0,0 +1,59 @@ +ldns-keygen +=============== + +Synopsis +-------- + +:program:`ldns-keygen` [``OPTIONS``] ```` + +Description +----------- + +**ldns-keygen** is used to generate a private/public keypair. When run, it will +create 3 files; a .key file with the public DNSKEY, a .private file with the +private keydata and a .ds file with the DS record of the DNSKEY record. + +.. **ldns-keygen** can also be used to create symmetric keys (for TSIG) by +.. selecting the appropriate algorithm: hmac-md5.sig-alg.reg.int, hmac-sha1, +.. hmac-sha224, hmac-sha256, hmac-sha384 or hmac-sha512. In that case no DS record +.. will be created and no .ds file. + +ldns-keygen prints the basename for the key files: K++ + +Options +------- + +.. option:: -a + + Create a key with this algorithm. Specifying 'list' here gives a list of + supported algorithms. Several alias names are also accepted (from older + versions and other software), the list gives names from the RFC. Also the + plain algo number is accepted. + +.. option:: -b + + Use this many bits for the key length. + +.. option:: -k + + When given, generate a key signing key. This just sets the flag field to + 257 instead of 256 in the DNSKEY RR in the .key file. + +.. option:: -r device + + Make ldns-keygen use this file to seed the random generator with. This + will default to /dev/random. + +.. option:: -s + + ldns-keygen will create symbolic links named **.private** to the new + generated private key, **.key** to the public DNSKEY and **.ds** to the + file containing DS record data. + +.. option:: -f + + Force symlinks to be overwritten if they exist. + +.. option:: -v + + Show the version and exit From b3d63d820bab557d7e3b61fcda7c06431d3e1d42 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 15:06:47 +0100 Subject: [PATCH 09/23] Add notify manuals --- doc/manual/source/man/dnst-notify.rst | 50 ++++++++++++++++++++++ doc/manual/source/man/ldns-notify.rst | 60 +++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 doc/manual/source/man/dnst-notify.rst create mode 100644 doc/manual/source/man/ldns-notify.rst diff --git a/doc/manual/source/man/dnst-notify.rst b/doc/manual/source/man/dnst-notify.rst new file mode 100644 index 0000000..b4b2540 --- /dev/null +++ b/doc/manual/source/man/dnst-notify.rst @@ -0,0 +1,50 @@ +dnst-notify +=============== + +Synopsis +-------- + +:program:`dnst notify` [``OPTIONS``] ``-z `` ``...`` + +Description +----------- + +**dnst notify** sends a NOTIFY message to the specified name servers. A name +server can be specified as a domain name or IP address. + +This tells them that an updated zone is available at the primaries. It can +perform TSIG signatures, and it can add a SOA serial number of the updated +zone. If a server already has that serial number it will disregard the message. + +Options +------- + +.. option:: -z + + The zone to send the NOTIFY for. + +.. option:: -s + + SOA version number to include in the NOTIFY message. + +.. option:: -y, --tsig + + A base64 TSIG key and optional algorithm to use for the NOTIFY message. + The algorithm defaults to **hmac-sha512**. + +.. option:: -p, --port + + Destination port to send the UDP packet to. Defaults to 53. + +.. option:: -d, --debug + + Print debug information. + +.. option:: -r, --retries + + Max number of retries. Defaults to 15. + +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). diff --git a/doc/manual/source/man/ldns-notify.rst b/doc/manual/source/man/ldns-notify.rst new file mode 100644 index 0000000..5a0c7a6 --- /dev/null +++ b/doc/manual/source/man/ldns-notify.rst @@ -0,0 +1,60 @@ +ldns-notify +=============== + +Synopsis +-------- + +:program:`ldns-notify` [``OPTIONS``] ``-z `` ``...`` + +Description +----------- + +**ldns-notify** sends a NOTIFY packet to the specified name servers. A name +server can be specified as a domain name or IP address. + +This tells them that an updated zone is available at the primaries. It can +perform TSIG signatures, and it can add a SOA serial number of the updated +zone. If a server already has that serial number it will disregard the message. + +Options +------- + +.. option:: -z + + The zone that is updated. + +.. ..option:: -I
+.. +.. Source IP to send the message from. + +.. option:: -s + + Append a SOA record indicating the serial number of the updated zone. + +.. option:: -p + + Destination port to send the UDP packet to. Defaults to 53. + +.. option:: -y + + A base64 TSIG key and optional algorithm to use for the NOTIFY message. + The algorithm defaults to hmac-sha512. + +.. option:: -d + + Print verbose debug information. The query that is sent and the query + that is received. + +.. option:: -r + + Specify the maximum number of retries before notify gives up trying to + send the UDP packet. + +.. option:: -h + + Print the help text and exit. + +.. option:: -v + + Print the version and exit. + From 2690ad022d366455d2174eaa9d7796caca473a06 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 16:41:57 +0100 Subject: [PATCH 10/23] Add signzone manuals --- doc/manual/source/man/dnst-signzone.rst | 108 ++++++++++++++++++++++++ doc/manual/source/man/ldns-signzone.rst | 99 ++++++++++++++++++++++ 2 files changed, 207 insertions(+) create mode 100644 doc/manual/source/man/dnst-signzone.rst create mode 100644 doc/manual/source/man/ldns-signzone.rst diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst new file mode 100644 index 0000000..451c808 --- /dev/null +++ b/doc/manual/source/man/dnst-signzone.rst @@ -0,0 +1,108 @@ +dnst-signzone +=============== + +Synopsis +-------- + +:program:`dnst signzone` [``OPTIONS``] ```` ``...`` + +Description +----------- + +**dnst signzone** signs the zone with the given key(s). + +Keys must be specified by their base name (usually ``K++``), +i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and +``.key`` files are required. + +A date can be a timestamp (seconds since the epoch), or of the form +. + + +Options +------- + +.. option:: + + The zonefile to sign. + +.. option:: ... + + The keys to sign the zone with. + +.. option:: -b + + Use a more readable layout in the signed zone file and print comments on + DNSSEC records. + +.. option:: -d + + Do not add used keys to the resulting zone file. + +.. option:: -e + + Set the expiration date. Defaults to 4 weeks from now. + +.. option:: -f + + Write signed zone to file. Use ``-f -`` to output to stdout. Defaults to + ``.signed``. + +.. option:: -i + + Set the inception date. Defaults to now. + +.. option:: -o + + Set the origin for the zone (for zonefiles with relative names and no + $ORIGIN). + +.. option:: -u + + Set SOA serial to the number of seconds since Jan 1st 1970. + + If this would NOT result in the SOA serial increasing it will be + incremented instead. + +.. option:: -n + + Use NSEC3 instead of NSEC. If specified, you can use extra options (see + :ref:`dnst-signzone-nsec3-options`). + +.. option:: -H + + Hash only, don't sign. + +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). + + +.. _dnst-signzone-nsec3-options: + +NSEC3 options +-------------------------------- + +NSEC3 options for use with ``-n``. + +.. option:: -a + + Specify the hashing algorithm. Defaults to SHA-1. + +.. option:: -t + + Set the number of hash iterations. Defaults to 0. + +.. option:: -s + + Specify the salt. Defaults to ``-``, meaning no salt. + +.. option:: -p + + Set the opt-out flag on all NSEC3 RRs. + +.. option:: -A + + Set the opt-out flag on all NSEC3 RRs and skip unsigned delegations. + diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst new file mode 100644 index 0000000..2ec5b3c --- /dev/null +++ b/doc/manual/source/man/ldns-signzone.rst @@ -0,0 +1,99 @@ +ldns-signzone +=============== + +Synopsis +-------- + +:program:`ldns-signzone` [``OPTIONS``] ```` ``...`` + +Description +----------- + +**ldns-signzone** signs the zone with the given key(s). + +Keys must be specified by their base name (usually ``K++``), +i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and +``.key`` files are required. + +A date can be a timestamp (seconds since the epoch), or of the form +. + + +Options +------- + +.. option:: + + The zonefile to sign. + +.. option:: ... + + The keys to sign the zone with. + +.. option:: -b + + Use a more readable layout in the signed zone file and print comments on + DNSSEC records. + +.. option:: -d + + Do not add used keys to the resulting zone file. + +.. option:: -e + + Set the expiration date. Defaults to 4 weeks from now. + +.. option:: -f + + Write signed zone to file. Use ``-f -`` to output to stdout. Defaults to + ``.signed``. + +.. option:: -i + + Set the inception date. Defaults to now. + +.. option:: -o + + Set the origin for the zone (for zonefiles with relative names and no + $ORIGIN). + +.. option:: -u + + Set SOA serial to the number of seconds since Jan 1st 1970. + +.. option:: -n + + Use NSEC3 instead of NSEC. If specified, you can use extra options (see + :ref:`ldns-signzone-nsec3-options`). + +.. option:: -h + + Print the help text. + +.. option:: -v + + Print the version and exit. + + +.. _ldns-signzone-nsec3-options: + +NSEC3 options +-------------------------------- + +NSEC3 options for use with ``-n``. + +.. option:: -a + + Specify the hashing algorithm. Defaults to SHA-1. + +.. option:: -t + + Set the number of hash iterations. Defaults to 0. + +.. option:: -s + + Specify the salt. Defaults to ``-``, meaning no salt. + +.. option:: -p + + Set the opt-out flag on all NSEC3 RRs. From a9b36daa639dddc34ca27b71d185fce14212fbf9 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 16:44:24 +0100 Subject: [PATCH 11/23] Add subcommands to dnst manual and table of contents --- doc/manual/source/conf.py | 12 ++++++++++-- doc/manual/source/index.rst | 12 +++++++++++- doc/manual/source/man/dnst.rst | 25 ++++++++++++++++++++++--- 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index a90a60e..a42d54e 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -189,10 +189,18 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('man/dnst', 'dnst', 'DNS Management Tools', author, 1), - ('man/dnst-nsec3-hash', 'dnst-nsec3-hash', 'print out the NSEC3 hash for a domain name', author, 1), - ('man/ldns-nsec3-hash', 'ldns-nsec3-hash', 'print out the NSEC3 hash for a domain name', author, 1), ('man/dnst-key2ds', 'dnst-key2ds', 'Generate DS RRs from the DNSKEYs in a keyfile', author, 1), ('man/ldns-key2ds', 'ldns-key2ds', 'Generate DS RRs from the DNSKEYs in a keyfile', author, 1), + ('man/dnst-keygen', 'dnst-keygen', 'Generate a new key pair for a domain name', author, 1), + ('man/ldns-keygen', 'ldns-keygen', 'Generate a new key pair for a domain name', author, 1), + ('man/dnst-notify', 'dnst-notify', 'Send a NOTIFY message to a list of name servers', author, 1), + ('man/ldns-notify', 'ldns-notify', 'Send a NOTIFY message to a list of name servers', author, 1), + ('man/dnst-nsec3-hash', 'dnst-nsec3-hash', 'Print out the NSEC3 hash of a domain name', author, 1), + ('man/ldns-nsec3-hash', 'ldns-nsec3-hash', 'Print out the NSEC3 hash of a domain name', author, 1), + ('man/dnst-signzone', 'dnst-signzone', 'Sign the zone with the given key(s)', author, 1), + ('man/ldns-signzone', 'ldns-signzone', 'Sign the zone with the given key(s)', author, 1), + ('man/dnst-update', 'dnst-update', 'Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name', author, 1), + ('man/ldns-update', 'ldns-update', 'Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name', author, 1), ] diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 8f8bcf0..01a9ae9 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -10,5 +10,15 @@ The manual goes here ... :name: toc-reference man/dnst + man/dnst-key2ds + man/dnst-keygen + man/dnst-notify man/dnst-nsec3-hash - + man/dnst-signzone + man/dnst-update + man/ldns-key2ds + man/ldns-keygen + man/ldns-notify + man/ldns-nsec3-hash + man/ldns-signzone + man/ldns-update diff --git a/doc/manual/source/man/dnst.rst b/doc/manual/source/man/dnst.rst index f132f2d..937081b 100644 --- a/doc/manual/source/man/dnst.rst +++ b/doc/manual/source/man/dnst.rst @@ -11,8 +11,8 @@ Description Manage various aspects of the Domain Name System (DNS). -dnst provides a number of commands that perform various tasks related -managing DNS server and DNS zones. +**dnst** provides a number of commands that perform various tasks related to +managing DNS servers and DNS zones. Please consult the manual pages for these individual commands for more information. @@ -22,7 +22,26 @@ dnst Commands .. glossary:: + :doc:`dnst-key2ds ` (1) + + Generate DS RRs from the DNSKEYs in a keyfile. + + :doc:`dnst-keygen ` (1) + + Generate a new key pair for a domain name. + + :doc:`dnst-notify ` (1) + + Send a NOTIFY message to a list of name servers. + :doc:`dnst-nsec3-hash ` (1) - Prints the NSEC3 hash for a domain name. + Print out the NSEC3 hash of a domain name. + + :doc:`dnst-signzone ` (1) + + Sign the zone with the given key(s). + + :doc:`dnst-update ` (1) + Send a dynamic update packet to update an IP (or delete all existing IPs) for a domain name. From 37fc0c1a854774d0508c2c6f8c92f9d132349d72 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 16:44:42 +0100 Subject: [PATCH 12/23] Update dnst-nsec3-hash manual --- doc/manual/source/man/dnst-nsec3-hash.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/manual/source/man/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index 56e093b..8ab7d21 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -4,7 +4,7 @@ dnst-nsec3-hash Synopsis -------- -:program:`dnst nsec3-hash` [``OPTIONS``] :samp:`` +:program:`dnst nsec3-hash` [``OPTIONS``] ```` Description ----------- @@ -28,3 +28,11 @@ Options Use the given salt for the hash calculation. The salt value should be in hexadecimal format. +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). + +.. option:: -V, --version + + Print the version. From 35c7bc0c0869827dcfdf83ad4fa2fc77e7a60023 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Thu, 14 Nov 2024 16:52:43 +0100 Subject: [PATCH 13/23] Add update manual --- doc/manual/source/man/dnst-update.rst | 46 +++++++++++++++++++++++++++ doc/manual/source/man/ldns-update.rst | 46 +++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 doc/manual/source/man/dnst-update.rst create mode 100644 doc/manual/source/man/ldns-update.rst diff --git a/doc/manual/source/man/dnst-update.rst b/doc/manual/source/man/dnst-update.rst new file mode 100644 index 0000000..d74ded4 --- /dev/null +++ b/doc/manual/source/man/dnst-update.rst @@ -0,0 +1,46 @@ +dnst-update +=============== + +Synopsis +-------- + +:program:`dnst update` ```` ``[]`` ```` +``[ ]`` + +Description +----------- + +**dnst update** sends a dynamic update packet to update an IP (or delete all +existing IPs) for a domain name. + +Options +------- + +.. option:: + + The domain name to update the IP address of + +.. option:: + + The zone to send the update to (if omitted, derived from SOA record) + +.. option:: + + The IP to update the domain with (``none`` to remove any existing IPs) + +.. option:: + + TSIG key name + +.. option:: + + TSIG algorithm (e.g. "hmac-sha256") + +.. option:: + + Base64 encoded TSIG key data. + +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). diff --git a/doc/manual/source/man/ldns-update.rst b/doc/manual/source/man/ldns-update.rst new file mode 100644 index 0000000..de9b69d --- /dev/null +++ b/doc/manual/source/man/ldns-update.rst @@ -0,0 +1,46 @@ +ldns-update +=============== + +Synopsis +-------- + +:program:`ldns-update` ```` ``[]`` ```` +``[ ]`` + +Description +----------- + +**ldns-update** sends a dynamic update packet to update an IP (or delete all +existing IPs) for a domain name. + +Options +------- + +.. option:: + + The domain name to update the IP address of + +.. option:: + + The zone to send the update to (if omitted, derived from SOA record) + +.. option:: + + The IP to update the domain with (``none`` to remove any existing IPs) + +.. option:: + + TSIG key name + +.. option:: + + TSIG algorithm (e.g. "hmac-sha256") + +.. option:: + + Base64 encoded TSIG key data. + +.. option:: -h, --help + + Print the help text (short summary with ``-h``, long help with + ``--help``). From 5a1b3b970f7df7b3c031c575aa6c827d6b0bf21a Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Fri, 15 Nov 2024 10:52:07 +0100 Subject: [PATCH 14/23] Apply feedback --- doc/manual/source/index.rst | 7 +++++++ doc/manual/source/man/dnst-key2ds.rst | 4 ++-- doc/manual/source/man/dnst-keygen.rst | 4 ++-- doc/manual/source/man/dnst-notify.rst | 6 +++--- doc/manual/source/man/dnst-nsec3-hash.rst | 4 ++-- doc/manual/source/man/dnst-signzone.rst | 22 +++++++++++----------- doc/manual/source/man/dnst-update.rst | 2 +- doc/manual/source/man/dnst.rst | 2 +- doc/manual/source/man/ldns-key2ds.rst | 2 +- doc/manual/source/man/ldns-keygen.rst | 21 +++++++++++---------- doc/manual/source/man/ldns-notify.rst | 4 ++-- doc/manual/source/man/ldns-nsec3-hash.rst | 8 ++++---- doc/manual/source/man/ldns-signzone.rst | 22 +++++++++++----------- doc/manual/source/man/ldns-update.rst | 2 +- 14 files changed, 59 insertions(+), 51 deletions(-) diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 01a9ae9..1e558ca 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -16,6 +16,13 @@ The manual goes here ... man/dnst-nsec3-hash man/dnst-signzone man/dnst-update + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: LDNS Tools reference + :name: toc-reference-ldns + man/ldns-key2ds man/ldns-keygen man/ldns-notify diff --git a/doc/manual/source/man/dnst-key2ds.rst b/doc/manual/source/man/dnst-key2ds.rst index 5ba44e4..a7b6d58 100644 --- a/doc/manual/source/man/dnst-key2ds.rst +++ b/doc/manual/source/man/dnst-key2ds.rst @@ -1,10 +1,10 @@ -dnst-key2ds +dnst key2ds =============== Synopsis -------- -:program:`dnst key2ds` [``OPTIONS``] ```` +:program:`dnst key2ds` ``[OPTIONS]`` ```` Description ----------- diff --git a/doc/manual/source/man/dnst-keygen.rst b/doc/manual/source/man/dnst-keygen.rst index 9a901a7..e47b761 100644 --- a/doc/manual/source/man/dnst-keygen.rst +++ b/doc/manual/source/man/dnst-keygen.rst @@ -1,10 +1,10 @@ -dnst-keygen +dnst keygen =============== Synopsis -------- -:program:`dnst keygen` [``OPTIONS``] ``-a `` ```` +:program:`dnst keygen` ``[OPTIONS]`` ``-a `` ```` Description ----------- diff --git a/doc/manual/source/man/dnst-notify.rst b/doc/manual/source/man/dnst-notify.rst index b4b2540..1fa979c 100644 --- a/doc/manual/source/man/dnst-notify.rst +++ b/doc/manual/source/man/dnst-notify.rst @@ -1,10 +1,10 @@ -dnst-notify +dnst notify =============== Synopsis -------- -:program:`dnst notify` [``OPTIONS``] ``-z `` ``...`` +:program:`dnst notify` ``[OPTIONS]`` ``-z `` ``...`` Description ----------- @@ -27,7 +27,7 @@ Options SOA version number to include in the NOTIFY message. -.. option:: -y, --tsig +.. option:: -y, --tsig A base64 TSIG key and optional algorithm to use for the NOTIFY message. The algorithm defaults to **hmac-sha512**. diff --git a/doc/manual/source/man/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index 8ab7d21..77a4d6b 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -1,10 +1,10 @@ -dnst-nsec3-hash +dnst nsec3-hash =============== Synopsis -------- -:program:`dnst nsec3-hash` [``OPTIONS``] ```` +:program:`dnst nsec3-hash` ``[OPTIONS]`` ```` Description ----------- diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst index 451c808..92e5a91 100644 --- a/doc/manual/source/man/dnst-signzone.rst +++ b/doc/manual/source/man/dnst-signzone.rst @@ -1,22 +1,22 @@ -dnst-signzone +dnst signzone =============== Synopsis -------- -:program:`dnst signzone` [``OPTIONS``] ```` ``...`` +:program:`dnst signzone` ``[OPTIONS]`` ```` ``...`` Description ----------- -**dnst signzone** signs the zone with the given key(s). +**dnst signzone** signs the zonefile with the given key(s). Keys must be specified by their base name (usually ``K++``), i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and ``.key`` files are required. A date can be a timestamp (seconds since the epoch), or of the form -. +````. Options @@ -28,20 +28,20 @@ Options .. option:: ... - The keys to sign the zone with. + The keys to sign the zonefile with. .. option:: -b - Use a more readable layout in the signed zone file and print comments on - DNSSEC records. + Add comments on DNSSEC records. .. option:: -d - Do not add used keys to the resulting zone file. + Do not add used keys to the resulting zonefile. .. option:: -e - Set the expiration date. Defaults to 4 weeks from now. + Set the expiration date of signatures to this date. Defaults to + 4 weeks from now. .. option:: -f @@ -50,7 +50,7 @@ Options .. option:: -i - Set the inception date. Defaults to now. + Set the inception date of signatures to this date. Defaults to now. .. option:: -o @@ -96,7 +96,7 @@ NSEC3 options for use with ``-n``. .. option:: -s - Specify the salt. Defaults to ``-``, meaning no salt. + Specify the salt as a hex string. Defaults to ``-``, meaning no salt. .. option:: -p diff --git a/doc/manual/source/man/dnst-update.rst b/doc/manual/source/man/dnst-update.rst index d74ded4..3270fbe 100644 --- a/doc/manual/source/man/dnst-update.rst +++ b/doc/manual/source/man/dnst-update.rst @@ -1,4 +1,4 @@ -dnst-update +dnst update =============== Synopsis diff --git a/doc/manual/source/man/dnst.rst b/doc/manual/source/man/dnst.rst index 937081b..09b4bb7 100644 --- a/doc/manual/source/man/dnst.rst +++ b/doc/manual/source/man/dnst.rst @@ -4,7 +4,7 @@ dnst Synopsis -------- -:program:`dnst` [``options``] ``command`` [``args``] +:program:`dnst` ``[OPTIONS]`` ```` ``[ARGS]`` Description ----------- diff --git a/doc/manual/source/man/ldns-key2ds.rst b/doc/manual/source/man/ldns-key2ds.rst index eb0f82a..daf14b4 100644 --- a/doc/manual/source/man/ldns-key2ds.rst +++ b/doc/manual/source/man/ldns-key2ds.rst @@ -4,7 +4,7 @@ ldns-key2ds Synopsis -------- -:program:`ldns-key2ds` [``OPTIONS``] ```` +:program:`ldns-key2ds` ``[OPTIONS]`` ```` Description ----------- diff --git a/doc/manual/source/man/ldns-keygen.rst b/doc/manual/source/man/ldns-keygen.rst index 3dbff83..6f3703d 100644 --- a/doc/manual/source/man/ldns-keygen.rst +++ b/doc/manual/source/man/ldns-keygen.rst @@ -4,33 +4,34 @@ ldns-keygen Synopsis -------- -:program:`ldns-keygen` [``OPTIONS``] ```` +:program:`ldns-keygen` ``[OPTIONS]`` ```` Description ----------- **ldns-keygen** is used to generate a private/public keypair. When run, it will -create 3 files; a .key file with the public DNSKEY, a .private file with the -private keydata and a .ds file with the DS record of the DNSKEY record. +create 3 files; a ``.key`` file with the public DNSKEY, a ``.private`` file +with the private keydata and a ``.ds`` file with the DS record of the DNSKEY +record. .. **ldns-keygen** can also be used to create symmetric keys (for TSIG) by .. selecting the appropriate algorithm: hmac-md5.sig-alg.reg.int, hmac-sha1, .. hmac-sha224, hmac-sha256, hmac-sha384 or hmac-sha512. In that case no DS record .. will be created and no .ds file. -ldns-keygen prints the basename for the key files: K++ +ldns-keygen prints the basename for the key files: ``K++`` Options ------- -.. option:: -a +.. option:: -a Create a key with this algorithm. Specifying 'list' here gives a list of supported algorithms. Several alias names are also accepted (from older versions and other software), the list gives names from the RFC. Also the - plain algo number is accepted. + plain algorithm number is accepted. -.. option:: -b +.. option:: -b Use this many bits for the key length. @@ -39,15 +40,15 @@ Options When given, generate a key signing key. This just sets the flag field to 257 instead of 256 in the DNSKEY RR in the .key file. -.. option:: -r device +.. option:: -r Make ldns-keygen use this file to seed the random generator with. This will default to /dev/random. .. option:: -s - ldns-keygen will create symbolic links named **.private** to the new - generated private key, **.key** to the public DNSKEY and **.ds** to the + ldns-keygen will create symbolic links named ``.private`` to the new + generated private key, ``.key`` to the public DNSKEY and ``.ds`` to the file containing DS record data. .. option:: -f diff --git a/doc/manual/source/man/ldns-notify.rst b/doc/manual/source/man/ldns-notify.rst index 5a0c7a6..e9cfb81 100644 --- a/doc/manual/source/man/ldns-notify.rst +++ b/doc/manual/source/man/ldns-notify.rst @@ -4,7 +4,7 @@ ldns-notify Synopsis -------- -:program:`ldns-notify` [``OPTIONS``] ``-z `` ``...`` +:program:`ldns-notify` ``[OPTIONS]`` ``-z `` ``...`` Description ----------- @@ -35,7 +35,7 @@ Options Destination port to send the UDP packet to. Defaults to 53. -.. option:: -y +.. option:: -y A base64 TSIG key and optional algorithm to use for the NOTIFY message. The algorithm defaults to hmac-sha512. diff --git a/doc/manual/source/man/ldns-nsec3-hash.rst b/doc/manual/source/man/ldns-nsec3-hash.rst index 20c16e6..c8bed32 100644 --- a/doc/manual/source/man/ldns-nsec3-hash.rst +++ b/doc/manual/source/man/ldns-nsec3-hash.rst @@ -4,7 +4,7 @@ ldns-nsec3-hash Synopsis -------- -:program:`ldns-nsec3-hash` :samp:`<{domain-name}>` +:program:`ldns-nsec3-hash` ``[OPTIONS]`` ```` Description ----------- @@ -14,16 +14,16 @@ Description Options ------- -.. option:: -a number +.. option:: -a Use the given algorithm number for the hash calculation. Defaults to 1 (SHA-1). -.. option:: -s salt +.. option:: -s Use the given salt for the hash calculation. The salt value should be in hexadecimal format. -.. option:: -t count +.. option:: -t Use count iterations for the hash calculation. diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst index 2ec5b3c..e76eceb 100644 --- a/doc/manual/source/man/ldns-signzone.rst +++ b/doc/manual/source/man/ldns-signzone.rst @@ -4,7 +4,7 @@ ldns-signzone Synopsis -------- -:program:`ldns-signzone` [``OPTIONS``] ```` ``...`` +:program:`ldns-signzone` ``[OPTIONS]`` ```` ``...`` Description ----------- @@ -15,8 +15,8 @@ Keys must be specified by their base name (usually ``K++``), i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and ``.key`` files are required. -A date can be a timestamp (seconds since the epoch), or of the form -. +A date can be a unix timestamp (seconds since the epoch), or of the form +````. Options @@ -28,20 +28,20 @@ Options .. option:: ... - The keys to sign the zone with. + The keys to sign the zonefile with. .. option:: -b - Use a more readable layout in the signed zone file and print comments on - DNSSEC records. + Add comments on DNSSEC records. .. option:: -d - Do not add used keys to the resulting zone file. + Do not add used keys to the resulting zonefile. .. option:: -e - Set the expiration date. Defaults to 4 weeks from now. + Set the expiration date of signatures to this date. Defaults to + 4 weeks from now. .. option:: -f @@ -50,9 +50,9 @@ Options .. option:: -i - Set the inception date. Defaults to now. + Set the inception date of signatures to this date. Defaults to now. -.. option:: -o +.. option:: -o Set the origin for the zone (for zonefiles with relative names and no $ORIGIN). @@ -92,7 +92,7 @@ NSEC3 options for use with ``-n``. .. option:: -s - Specify the salt. Defaults to ``-``, meaning no salt. + Specify the salt as a hex string. Defaults to ``-``, meaning no salt. .. option:: -p diff --git a/doc/manual/source/man/ldns-update.rst b/doc/manual/source/man/ldns-update.rst index de9b69d..9d25ced 100644 --- a/doc/manual/source/man/ldns-update.rst +++ b/doc/manual/source/man/ldns-update.rst @@ -4,7 +4,7 @@ ldns-update Synopsis -------- -:program:`ldns-update` ```` ``[]`` ```` +:program:`ldns-update` ```` ``[ZONE]`` ```` ``[ ]`` Description From aca6910edb831f33bbdbee2acbc1d9d2c703d62e Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Fri, 15 Nov 2024 11:01:19 +0100 Subject: [PATCH 15/23] Apply further feedback --- doc/manual/source/man/dnst-signzone.rst | 19 +++++++++++-------- doc/manual/source/man/ldns-signzone.rst | 10 ++++++---- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst index 92e5a91..7167381 100644 --- a/doc/manual/source/man/dnst-signzone.rst +++ b/doc/manual/source/man/dnst-signzone.rst @@ -32,7 +32,8 @@ Options .. option:: -b - Add comments on DNSSEC records. + Add comments on DNSSEC records. Without this option only DNSKEY RRs + will have their key tag annotated in the comment. .. option:: -d @@ -52,10 +53,10 @@ Options Set the inception date of signatures to this date. Defaults to now. -.. option:: -o +.. option:: -o - Set the origin for the zone (for zonefiles with relative names and no - $ORIGIN). + Set the origin for the zone (only necessary for zonefiles with relative + names and no $ORIGIN). .. option:: -u @@ -66,8 +67,9 @@ Options .. option:: -n - Use NSEC3 instead of NSEC. If specified, you can use extra options (see - :ref:`dnst-signzone-nsec3-options`). + Use NSEC3 instead of NSEC. By default, RFC 9276 best practice settings + are used: SHA-1, no extra iterations, empty salt. To use different NSEC3 + settings see :ref:`dnst-signzone-nsec3-options`. .. option:: -H @@ -84,9 +86,10 @@ Options NSEC3 options -------------------------------- -NSEC3 options for use with ``-n``. +The following options can be used with ``-n`` to override the default NSEC3 +settings used. -.. option:: -a +.. option:: -a Specify the hashing algorithm. Defaults to SHA-1. diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst index e76eceb..26707ee 100644 --- a/doc/manual/source/man/ldns-signzone.rst +++ b/doc/manual/source/man/ldns-signzone.rst @@ -32,7 +32,8 @@ Options .. option:: -b - Add comments on DNSSEC records. + Add comments on DNSSEC records. Without this option only DNSKEY RRs + will have their key tag annotated in the comment. .. option:: -d @@ -54,8 +55,8 @@ Options .. option:: -o - Set the origin for the zone (for zonefiles with relative names and no - $ORIGIN). + Set the origin for the zone (only necessary for zonefiles with + relative names and no $ORIGIN). .. option:: -u @@ -80,7 +81,8 @@ Options NSEC3 options -------------------------------- -NSEC3 options for use with ``-n``. +The following options can be used with ``-n`` to override the default NSEC3 +settings used. .. option:: -a From 4ec90580b2d5eac70b57d1d6dd83c706db242391 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 09:14:48 +0100 Subject: [PATCH 16/23] Move signzone date description into own section --- doc/manual/source/man/dnst-signzone.rst | 20 +++++++++++------- doc/manual/source/man/ldns-signzone.rst | 28 ++++++++++++++++--------- 2 files changed, 30 insertions(+), 18 deletions(-) diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst index 7167381..2fefbbd 100644 --- a/doc/manual/source/man/dnst-signzone.rst +++ b/doc/manual/source/man/dnst-signzone.rst @@ -15,10 +15,6 @@ Keys must be specified by their base name (usually ``K++``), i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and ``.key`` files are required. -A date can be a timestamp (seconds since the epoch), or of the form -````. - - Options ------- @@ -41,8 +37,8 @@ Options .. option:: -e - Set the expiration date of signatures to this date. Defaults to - 4 weeks from now. + Set the expiration date of signatures to this date (see + :ref:`dnst-signzone-dates`). Defaults to 4 weeks from now. .. option:: -f @@ -51,7 +47,8 @@ Options .. option:: -i - Set the inception date of signatures to this date. Defaults to now. + Set the inception date of signatures to this date (see + :ref:`dnst-signzone-dates`). Defaults to now. .. option:: -o @@ -99,7 +96,7 @@ settings used. .. option:: -s - Specify the salt as a hex string. Defaults to ``-``, meaning no salt. + Specify the salt as a hex string. Defaults to ``-``, meaning empty salt. .. option:: -p @@ -109,3 +106,10 @@ settings used. Set the opt-out flag on all NSEC3 RRs and skip unsigned delegations. +.. _dnst-signzone-dates: + +DATES +----- + +A date can be a UNIX timestamp as seconds since the Epoch (1970-01-01 +00:00 UTC), or of the form ````. diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst index 26707ee..06dc068 100644 --- a/doc/manual/source/man/ldns-signzone.rst +++ b/doc/manual/source/man/ldns-signzone.rst @@ -15,12 +15,8 @@ Keys must be specified by their base name (usually ``K++``), i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and ``.key`` files are required. -A date can be a unix timestamp (seconds since the epoch), or of the form -````. - - -Options -------- +Arguments +--------- .. option:: @@ -30,6 +26,9 @@ Options The keys to sign the zonefile with. +Options +------- + .. option:: -b Add comments on DNSSEC records. Without this option only DNSKEY RRs @@ -41,8 +40,8 @@ Options .. option:: -e - Set the expiration date of signatures to this date. Defaults to - 4 weeks from now. + Set the expiration date of signatures to this date (see + :ref:`ldns-signzone-dates`). Defaults to 4 weeks from now. .. option:: -f @@ -51,7 +50,8 @@ Options .. option:: -i - Set the inception date of signatures to this date. Defaults to now. + Set the inception date of signatures to this date (see + :ref:`ldns-signzone-dates`). Defaults to now. .. option:: -o @@ -94,8 +94,16 @@ settings used. .. option:: -s - Specify the salt as a hex string. Defaults to ``-``, meaning no salt. + Specify the salt as a hex string. Defaults to ``-``, meaning empty salt. .. option:: -p Set the opt-out flag on all NSEC3 RRs. + +.. _ldns-signzone-dates: + +DATES +----- + +A date can be a UNIX timestamp as seconds since the Epoch (1970-01-01 +00:00 UTC), or of the form ````. From f5faebc07deb7585add23f9ef78c2ab39f61fc7d Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 09:35:45 +0100 Subject: [PATCH 17/23] Update signzone hash iterations manual text --- doc/manual/source/man/dnst-signzone.rst | 2 +- doc/manual/source/man/ldns-signzone.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst index 2fefbbd..acb30a9 100644 --- a/doc/manual/source/man/dnst-signzone.rst +++ b/doc/manual/source/man/dnst-signzone.rst @@ -92,7 +92,7 @@ settings used. .. option:: -t - Set the number of hash iterations. Defaults to 0. + Set the number of extra hash iterations. Defaults to 0. .. option:: -s diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst index 06dc068..cfec3cd 100644 --- a/doc/manual/source/man/ldns-signzone.rst +++ b/doc/manual/source/man/ldns-signzone.rst @@ -90,7 +90,7 @@ settings used. .. option:: -t - Set the number of hash iterations. Defaults to 0. + Set the number of extra hash iterations. Defaults to 0. .. option:: -s From 7492948417f2b7f0fb824c6ebc1add42b371ea9d Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 09:43:05 +0100 Subject: [PATCH 18/23] Add Arguments sections --- doc/manual/source/man/dnst-signzone.rst | 7 +++++-- doc/manual/source/man/dnst-update.rst | 6 +++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst index acb30a9..606b33f 100644 --- a/doc/manual/source/man/dnst-signzone.rst +++ b/doc/manual/source/man/dnst-signzone.rst @@ -15,8 +15,8 @@ Keys must be specified by their base name (usually ``K++``), i.e. WITHOUT the ``.private`` or ``.key`` extension. Both ``.private`` and ``.key`` files are required. -Options -------- +Arguments +--------- .. option:: @@ -26,6 +26,9 @@ Options The keys to sign the zonefile with. +Options +------- + .. option:: -b Add comments on DNSSEC records. Without this option only DNSKEY RRs diff --git a/doc/manual/source/man/dnst-update.rst b/doc/manual/source/man/dnst-update.rst index 3270fbe..6d4752b 100644 --- a/doc/manual/source/man/dnst-update.rst +++ b/doc/manual/source/man/dnst-update.rst @@ -4,7 +4,7 @@ dnst update Synopsis -------- -:program:`dnst update` ```` ``[]`` ```` +:program:`dnst update` ```` ``[ZONE]`` ```` ``[ ]`` Description @@ -13,8 +13,8 @@ Description **dnst update** sends a dynamic update packet to update an IP (or delete all existing IPs) for a domain name. -Options -------- +Arguments +--------- .. option:: From 7b8b5faa8c9802bbf959a38767082c29be18ebcc Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 10:05:14 +0100 Subject: [PATCH 19/23] Add basic intro text for dnst --- doc/manual/source/index.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 1e558ca..227ccff 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -1,7 +1,12 @@ dnst |version| ============== -The manual goes here ... +**dnst** is a DNS administration toolbox. It offers DNS and DNSSEC related +functions like key generation, zone signing, printing NSEC3 hashed domain +names, and sending UPDATE or NOTIFY messages to your name servers. More is +coming soon. + +It depends on OpenSSL for its cryptography related functions. .. toctree:: :maxdepth: 2 From bcfb44dfa6b2f867152a608fbb8abbae0f383dc2 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 10:20:00 +0100 Subject: [PATCH 20/23] Fix ldns-signzone default nsec3 hash iterations --- doc/manual/source/man/ldns-signzone.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst index cfec3cd..a501a15 100644 --- a/doc/manual/source/man/ldns-signzone.rst +++ b/doc/manual/source/man/ldns-signzone.rst @@ -90,7 +90,7 @@ settings used. .. option:: -t - Set the number of extra hash iterations. Defaults to 0. + Set the number of extra hash iterations. Defaults to 1. .. option:: -s From 1d32cf8be1b6b22e5a198a763919b11ecab44c62 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 10:27:58 +0100 Subject: [PATCH 21/23] Update nse3-hash defaults and wording --- doc/manual/source/man/dnst-nsec3-hash.rst | 5 +++-- doc/manual/source/man/ldns-nsec3-hash.rst | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/manual/source/man/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index 77a4d6b..a72450f 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -21,12 +21,13 @@ Options .. option:: -i , -t , --iterations - Use the given number of additional iterations for the hash calculation. + Use the given number of additional iterations for the hash + calculation. Defaults to 0. .. option:: -s , --salt Use the given salt for the hash calculation. The salt value should be - in hexadecimal format. + in hexadecimal format. Defaults to an empty salt. .. option:: -h, --help diff --git a/doc/manual/source/man/ldns-nsec3-hash.rst b/doc/manual/source/man/ldns-nsec3-hash.rst index c8bed32..edfff6d 100644 --- a/doc/manual/source/man/ldns-nsec3-hash.rst +++ b/doc/manual/source/man/ldns-nsec3-hash.rst @@ -22,8 +22,9 @@ Options .. option:: -s Use the given salt for the hash calculation. The salt value should be - in hexadecimal format. + in hexadecimal format. Defaults to an empty salt. .. option:: -t - Use count iterations for the hash calculation. + Use the given number of additional iterations for the hash + calculation. Defaults to 1. From 9d967578840f307b8be1cf9f0abd26dcba601a03 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 10:34:45 +0100 Subject: [PATCH 22/23] Update dnst-key2ds ignore-sep and force --- doc/manual/source/man/dnst-key2ds.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/manual/source/man/dnst-key2ds.rst b/doc/manual/source/man/dnst-key2ds.rst index a7b6d58..844880c 100644 --- a/doc/manual/source/man/dnst-key2ds.rst +++ b/doc/manual/source/man/dnst-key2ds.rst @@ -23,8 +23,11 @@ Options Use the given algorithm for the digest. Defaults to the digest algorithm used for the DNSKEY, and if it can't be determined SHA-1. -.. might change to --ignore-sep when implemented -.. option:: -f +.. option:: -f, --force + + Overwrite existing ``.ds`` files. + +.. option:: --ignore-sep Ignore the SEP flag and make DS records for any key. From 662cf25192819f14089e3ea1c0ef9e6b33e1f1d8 Mon Sep 17 00:00:00 2001 From: Jannik Peters Date: Tue, 19 Nov 2024 14:08:47 +0100 Subject: [PATCH 23/23] Update nse3-hash default to what it is currently in main --- doc/manual/source/man/dnst-nsec3-hash.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/source/man/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index a72450f..78d35da 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -22,7 +22,7 @@ Options .. option:: -i , -t , --iterations Use the given number of additional iterations for the hash - calculation. Defaults to 0. + calculation. Defaults to 1. .. option:: -s , --salt