diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index ffa9b5d4..a42d54e1 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. @@ -189,8 +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', 'DNS Management Tools', 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 8f8bcf0e..227ccffa 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 @@ -10,5 +15,22 @@ 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 + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: LDNS Tools reference + :name: toc-reference-ldns + 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-key2ds.rst b/doc/manual/source/man/dnst-key2ds.rst new file mode 100644 index 00000000..844880c4 --- /dev/null +++ b/doc/manual/source/man/dnst-key2ds.rst @@ -0,0 +1,45 @@ +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. + +.. option:: -f, --force + + Overwrite existing ``.ds`` files. + +.. option:: --ignore-sep + + 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/dnst-keygen.rst b/doc/manual/source/man/dnst-keygen.rst new file mode 100644 index 00000000..e47b7617 --- /dev/null +++ b/doc/manual/source/man/dnst-keygen.rst @@ -0,0 +1,74 @@ +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 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 + + 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``). diff --git a/doc/manual/source/man/dnst-notify.rst b/doc/manual/source/man/dnst-notify.rst new file mode 100644 index 00000000..1fa979ce --- /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/dnst-nsec3-hash.rst b/doc/manual/source/man/dnst-nsec3-hash.rst index 20014476..78d35dac 100644 --- a/doc/manual/source/man/dnst-nsec3-hash.rst +++ b/doc/manual/source/man/dnst-nsec3-hash.rst @@ -1,30 +1,39 @@ -dnst-nsec3-hash +dnst nsec3-hash =============== Synopsis -------- -:program:`dnst nsec3-hash` [``options``] :samp:`domain-name` +:program:`dnst nsec3-hash` ``[OPTIONS]`` ```` 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 number of additional iterations for the hash + calculation. Defaults to 1. + +.. 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 -.. option:: -i count, -t count, --iterations=count + Print the help text (short summary with ``-h``, long help with + ``--help``). - Use *count* iterations for the hash calculation. +.. option:: -V, --version + Print the version. diff --git a/doc/manual/source/man/dnst-signzone.rst b/doc/manual/source/man/dnst-signzone.rst new file mode 100644 index 00000000..606b33fe --- /dev/null +++ b/doc/manual/source/man/dnst-signzone.rst @@ -0,0 +1,118 @@ +dnst signzone +=============== + +Synopsis +-------- + +:program:`dnst signzone` ``[OPTIONS]`` ```` ``...`` + +Description +----------- + +**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. + +Arguments +--------- + +.. option:: + + The zonefile to sign. + +.. option:: ... + + The keys to sign the zonefile with. + +Options +------- + +.. option:: -b + + Add comments on DNSSEC records. Without this option only DNSKEY RRs + will have their key tag annotated in the comment. + +.. option:: -d + + Do not add used keys to the resulting zonefile. + +.. option:: -e + + Set the expiration date of signatures to this date (see + :ref:`dnst-signzone-dates`). 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 of signatures to this date (see + :ref:`dnst-signzone-dates`). Defaults to now. + +.. option:: -o + + Set the origin for the zone (only necessary 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. 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 + + 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 +-------------------------------- + +The following options can be used with ``-n`` to override the default NSEC3 +settings used. + +.. option:: -a + + Specify the hashing algorithm. Defaults to SHA-1. + +.. option:: -t + + Set the number of extra hash iterations. Defaults to 0. + +.. option:: -s + + Specify the salt as a hex string. Defaults to ``-``, meaning empty 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. + +.. _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/dnst-update.rst b/doc/manual/source/man/dnst-update.rst new file mode 100644 index 00000000..6d4752b5 --- /dev/null +++ b/doc/manual/source/man/dnst-update.rst @@ -0,0 +1,46 @@ +dnst update +=============== + +Synopsis +-------- + +:program:`dnst update` ```` ``[ZONE]`` ```` +``[ ]`` + +Description +----------- + +**dnst update** sends a dynamic update packet to update an IP (or delete all +existing IPs) for a domain name. + +Arguments +--------- + +.. 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/dnst.rst b/doc/manual/source/man/dnst.rst index f132f2d3..09b4bb7b 100644 --- a/doc/manual/source/man/dnst.rst +++ b/doc/manual/source/man/dnst.rst @@ -4,15 +4,15 @@ dnst Synopsis -------- -:program:`dnst` [``options``] ``command`` [``args``] +:program:`dnst` ``[OPTIONS]`` ```` ``[ARGS]`` 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. diff --git a/doc/manual/source/man/ldns-key2ds.rst b/doc/manual/source/man/ldns-key2ds.rst new file mode 100644 index 00000000..daf14b4a --- /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 diff --git a/doc/manual/source/man/ldns-keygen.rst b/doc/manual/source/man/ldns-keygen.rst new file mode 100644 index 00000000..6f3703dc --- /dev/null +++ b/doc/manual/source/man/ldns-keygen.rst @@ -0,0 +1,60 @@ +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 algorithm 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 + + 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 diff --git a/doc/manual/source/man/ldns-notify.rst b/doc/manual/source/man/ldns-notify.rst new file mode 100644 index 00000000..e9cfb81f --- /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. + 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 00000000..edfff6d5 --- /dev/null +++ b/doc/manual/source/man/ldns-nsec3-hash.rst @@ -0,0 +1,30 @@ +ldns-nsec3-hash +=============== + +Synopsis +-------- + +:program:`ldns-nsec3-hash` ``[OPTIONS]`` ```` + +Description +----------- + +**ldns-nsec3-hash** is used to print out the NSEC3 hash for the given domain name. + +Options +------- + +.. option:: -a + + Use the given algorithm number for the hash calculation. Defaults to + 1 (SHA-1). + +.. option:: -s + + Use the given salt for the hash calculation. The salt value should be + in hexadecimal format. Defaults to an empty salt. + +.. option:: -t + + Use the given number of additional iterations for the hash + calculation. Defaults to 1. diff --git a/doc/manual/source/man/ldns-signzone.rst b/doc/manual/source/man/ldns-signzone.rst new file mode 100644 index 00000000..a501a159 --- /dev/null +++ b/doc/manual/source/man/ldns-signzone.rst @@ -0,0 +1,109 @@ +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. + +Arguments +--------- + +.. option:: + + The zonefile to sign. + +.. option:: ... + + The keys to sign the zonefile with. + +Options +------- + +.. option:: -b + + Add comments on DNSSEC records. Without this option only DNSKEY RRs + will have their key tag annotated in the comment. + +.. option:: -d + + Do not add used keys to the resulting zonefile. + +.. option:: -e + + Set the expiration date of signatures to this date (see + :ref:`ldns-signzone-dates`). 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 of signatures to this date (see + :ref:`ldns-signzone-dates`). Defaults to now. + +.. option:: -o + + Set the origin for the zone (only necessary 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 +-------------------------------- + +The following options can be used with ``-n`` to override the default NSEC3 +settings used. + +.. option:: -a + + Specify the hashing algorithm. Defaults to SHA-1. + +.. option:: -t + + Set the number of extra hash iterations. Defaults to 1. + +.. option:: -s + + 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 ````. diff --git a/doc/manual/source/man/ldns-update.rst b/doc/manual/source/man/ldns-update.rst new file mode 100644 index 00000000..9d25ced3 --- /dev/null +++ b/doc/manual/source/man/ldns-update.rst @@ -0,0 +1,46 @@ +ldns-update +=============== + +Synopsis +-------- + +:program:`ldns-update` ```` ``[ZONE]`` ```` +``[ ]`` + +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``).