diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index de4420e299..52ae412c58 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -11,34 +11,30 @@ .. highlight: console +.. BEWARE: Do not forget to edit also tsig-keygen.rst! + .. _man_ddns-confgen: -ddns-confgen - ddns key generation tool +ddns-confgen - TSIG key generation tool --------------------------------------- Synopsis ~~~~~~~~ -:program:`tsig-keygen` [**-a** algorithm] [**-h**] [name] - :program:`ddns-confgen` [**-a** algorithm] [**-h**] [**-k** keyname] [**-q**] [**-s** name] [**-z** zone] Description ~~~~~~~~~~~ -``tsig-keygen`` and ``ddns-confgen`` are invocation methods for a -utility that generates keys for use in TSIG signing. The resulting keys -can be used, for example, to secure dynamic DNS updates to a zone or for -the ``rndc`` command channel. +``ddns-confgen`` is an utility that generates keys for use in TSIG signing. +The resulting keys can be used, for example, to secure dynamic DNS updates +to a zone, or for the ``rndc`` command channel. -When run as ``tsig-keygen``, a domain name can be specified on the -command line to be used as the name of the generated key. If no -name is specified, the default is ``tsig-key``. - -When run as ``ddns-confgen``, the generated key is accompanied by -configuration text and instructions that can be used with ``nsupdate`` -and ``named`` when setting up dynamic DNS, including an example -``update-policy`` statement. (This usage is similar to the ``rndc-confgen`` -command for setting up command-channel security.) +The key name can specified using ``-k`` parameter and defaults to ``ddns-key``. +The generated key is accompanied by configuration text and instructions that +can be used with ``nsupdate`` and ``named`` when setting up dynamic DNS, +including an example ``update-policy`` statement. +(This usage is similar to the ``rndc-confgen`` command for setting up +command-channel security.) Note that ``named`` itself can configure a local DDNS key for use with ``nsupdate -l``; it does this when a zone is configured with @@ -50,37 +46,36 @@ Options ~~~~~~~ ``-a algorithm`` - This option specifies the algorithm to use for the TSIG key. Available choices - are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and - hmac-sha512. The default is hmac-sha256. Options are + This option specifies the algorithm to use for the TSIG key. Available + choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, + and hmac-sha512. The default is hmac-sha256. Options are case-insensitive, and the "hmac-" prefix may be omitted. ``-h`` This option prints a short summary of options and arguments. ``-k keyname`` - This option specifies the key name of the DDNS authentication key. The default is - ``ddns-key`` when neither the ``-s`` nor ``-z`` option is specified; - otherwise, the default is ``ddns-key`` as a separate label followed - by the argument of the option, e.g., ``ddns-key.example.com.`` The - key name must have the format of a valid domain name, consisting of + This option specifies the key name of the DDNS authentication key. The + default is ``ddns-key`` when neither the ``-s`` nor ``-z`` option is + specified; otherwise, the default is ``ddns-key`` as a separate label + followed by the argument of the option, e.g., ``ddns-key.example.com.`` + The key name must have the format of a valid domain name, consisting of letters, digits, hyphens, and periods. -``-q`` (``ddns-confgen`` only) +``-q`` This option enables quiet mode, which prints only the key, with no explanatory text or usage examples. This is essentially identical to ``tsig-keygen``. -``-s name`` (``ddns-confgen`` only) - This option generates a configuration example to allow - dynamic updates of a single hostname. The example ``named.conf`` text - shows how to set an update policy for the specified name using the - "name" nametype. The default key name is ``ddns-key.name``. Note that the - "self" nametype cannot be used, since the name to be updated may - differ from the key name. This option cannot be used with the ``-z`` - option. +``-s name`` + This option generates a configuration example to allow dynamic updates + of a single hostname. The example ``named.conf`` text shows how to set + an update policy for the specified name using the "name" nametype. The + default key name is ``ddns-key.name``. Note that the "self" nametype + cannot be used, since the name to be updated may differ from the key + name. This option cannot be used with the ``-z`` option. -``-z zone`` (``ddns-confgen`` only) +``-z zone`` This option generates a configuration example to allow dynamic updates of a zone. The example ``named.conf`` text shows how to set an update policy for the specified zone using the "zonesub" diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst new file mode 100644 index 0000000000..a1274079de --- /dev/null +++ b/bin/confgen/tsig-keygen.rst @@ -0,0 +1,50 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. highlight: console + +.. BEWARE: Do not forget to edit also ddns-confgen.rst! + +.. _man_tsig-keygen: + +tsig-keygen - TSIG key generation tool +-------------------------------------- + +Synopsis +~~~~~~~~ +:program:`tsig-keygen` [**-a** algorithm] [**-h**] [name] + +Description +~~~~~~~~~~~ + +``tsig-keygen`` is an utility that generates keys for use in TSIG signing. +The resulting keys can be used, for example, to secure dynamic DNS updates +to a zone, or for the ``rndc`` command channel. + +A domain name can be specified on the command line to be used as the name +of the generated key. If no name is specified, the default is ``tsig-key``. + +Options +~~~~~~~ + +``-a algorithm`` + This option specifies the algorithm to use for the TSIG key. Available + choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, + and hmac-sha512. The default is hmac-sha256. Options are + case-insensitive, and the "hmac-" prefix may be omitted. + +``-h`` + This option prints a short summary of options and arguments. + +See Also +~~~~~~~~ + +:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual. diff --git a/doc/arm/manpages.rst b/doc/arm/manpages.rst index baf0bb13bb..8b1c220f1a 100644 --- a/doc/arm/manpages.rst +++ b/doc/arm/manpages.rst @@ -15,7 +15,6 @@ Manual Pages ============ .. include:: ../../bin/tools/arpaname.rst -.. include:: ../../bin/confgen/ddns-confgen.rst .. include:: ../../bin/delv/delv.rst .. include:: ../../bin/dig/dig.rst .. include:: ../../bin/dnssec/dnssec-cds.rst @@ -51,3 +50,5 @@ Manual Pages .. include:: ../../bin/confgen/rndc-confgen.rst .. include:: ../../bin/rndc/rndc.conf.rst .. include:: ../../bin/rndc/rndc.rst +.. include:: ../../bin/confgen/ddns-confgen.rst +.. include:: ../../bin/confgen/tsig-keygen.rst diff --git a/doc/man/Makefile.in b/doc/man/Makefile.in index 7e46b4cdc6..6731f02091 100644 --- a/doc/man/Makefile.in +++ b/doc/man/Makefile.in @@ -53,7 +53,8 @@ man8_MANS = \ named.8 \ nsec3hash.8 \ rndc-confgen.8 \ - rndc.8 + rndc.8 \ + tsig-keygen.8 MANPAGES_RST = \ arpaname.rst \ @@ -89,6 +90,7 @@ MANPAGES_RST = \ rndc-confgen.rst \ rndc.conf.rst \ rndc.rst \ + tsig-keygen.rst \ pkcs11-destroy.rst \ pkcs11-keygen.rst \ pkcs11-list.rst \ @@ -128,6 +130,7 @@ MANPAGES_IN = \ rndc-confgen.8in \ rndc.conf.5in \ rndc.8in \ + tsig-keygen.8in \ pkcs11-destroy.8in \ pkcs11-keygen.8in \ pkcs11-list.8in \ @@ -248,8 +251,6 @@ install:: installdirs for m in $(man1_MANS); do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man1/; done for m in $(man5_MANS); do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man5/; done for m in $(man8_MANS); do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man8/; done - ( cd ${DESTDIR}${mandir}/man8/; rm -f named-compilezone.8; ${LINK_PROGRAM} named-checkzone.8 named-compilezone.8 ) - ( cd ${DESTDIR}${mandir}/man8/; rm -f tsig-keygen.8; ${LINK_PROGRAM} ddns-confgen.8 tsig-keygen.8 ) for m in @DNSTAP_MANS@; do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man1/; done for m in @NZD_MANS@; do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man8/; done for m in @PKCS11_MANS@; do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man8/; done @@ -258,8 +259,6 @@ uninstall:: for m in $(man1_MANS); do rm -f ${DESTDIR}${mandir}/man1/$$m; done for m in $(man5_MANS); do rm -f ${DESTDIR}${mandir}/man5/$$m; done for m in $(man8_MANS); do rm -f ${DESTDIR}${mandir}/man8/$$m; done - rm -f ${DESTDIR}${mandir}/man8/named-compilezone.8 - rm -f ${DESTDIR}${mandir}/man8/tsig-keygen.8 for m in @DNSTAP_MANS@; do rm -f ${DESTDIR}${mandir}/man1/$$m; done for m in @NZD_MANS@; do rm -f ${DESTDIR}${mandir}/man8/$$m; done for m in @PKCS11_MANS@; do rm -f ${DESTDIR}${mandir}/man8/$$m; done diff --git a/doc/man/conf.py b/doc/man/conf.py index 994e66cf7b..27b1ca4ecf 100644 --- a/doc/man/conf.py +++ b/doc/man/conf.py @@ -103,4 +103,5 @@ man_pages = [ ('rndc-confgen', 'rndc-confgen', 'rndc key generation tool', author, 8), ('rndc.conf', 'rndc.conf', 'rndc configuration file', author, 5), ('rndc', 'rndc', 'name server control utility', author, 8), + ('tsig-keygen', 'tsig-keygen', 'TSIG key generation tool', author, 8), ] diff --git a/doc/man/ddns-confgen.8in b/doc/man/ddns-confgen.8in index ed5872ea97..158bc6b2eb 100644 --- a/doc/man/ddns-confgen.8in +++ b/doc/man/ddns-confgen.8in @@ -32,25 +32,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] ddns-confgen \- ddns key generation tool .SH SYNOPSIS .sp -\fBtsig\-keygen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [name] -.sp \fBddns\-confgen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-k\fP keyname] [\fB\-q\fP] [\fB\-s\fP name] [\fB\-z\fP zone] .SH DESCRIPTION .sp -\fBtsig\-keygen\fP and \fBddns\-confgen\fP are invocation methods for a -utility that generates keys for use in TSIG signing. The resulting keys -can be used, for example, to secure dynamic DNS updates to a zone or for -the \fBrndc\fP command channel. +\fBddns\-confgen\fP is an utility that generates keys for use in TSIG signing. +The resulting keys can be used, for example, to secure dynamic DNS updates +to a zone, or for the \fBrndc\fP command channel. .sp -When run as \fBtsig\-keygen\fP, a domain name can be specified on the -command line to be used as the name of the generated key. If no -name is specified, the default is \fBtsig\-key\fP\&. -.sp -When run as \fBddns\-confgen\fP, the generated key is accompanied by -configuration text and instructions that can be used with \fBnsupdate\fP -and \fBnamed\fP when setting up dynamic DNS, including an example -\fBupdate\-policy\fP statement. (This usage is similar to the \fBrndc\-confgen\fP -command for setting up command\-channel security.) +The key name can specified using \fB\-k\fP parameter and defaults to \fBddns\-key\fP\&. +The generated key is accompanied by configuration text and instructions that +can be used with \fBnsupdate\fP and \fBnamed\fP when setting up dynamic DNS, +including an example \fBupdate\-policy\fP statement. +(This usage is similar to the \fBrndc\-confgen\fP command for setting up +command\-channel security.) .sp Note that \fBnamed\fP itself can configure a local DDNS key for use with \fBnsupdate \-l\fP; it does this when a zone is configured with @@ -61,37 +55,36 @@ be used from a remote system. .INDENT 0.0 .TP .B \fB\-a algorithm\fP -This option specifies the algorithm to use for the TSIG key. Available choices -are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, and -hmac\-sha512. The default is hmac\-sha256. Options are +This option specifies the algorithm to use for the TSIG key. Available +choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, +and hmac\-sha512. The default is hmac\-sha256. Options are case\-insensitive, and the "hmac\-" prefix may be omitted. .TP .B \fB\-h\fP This option prints a short summary of options and arguments. .TP .B \fB\-k keyname\fP -This option specifies the key name of the DDNS authentication key. The default is -\fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-z\fP option is specified; -otherwise, the default is \fBddns\-key\fP as a separate label followed -by the argument of the option, e.g., \fBddns\-key.example.com.\fP The -key name must have the format of a valid domain name, consisting of +This option specifies the key name of the DDNS authentication key. The +default is \fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-z\fP option is +specified; otherwise, the default is \fBddns\-key\fP as a separate label +followed by the argument of the option, e.g., \fBddns\-key.example.com.\fP +The key name must have the format of a valid domain name, consisting of letters, digits, hyphens, and periods. .TP -.B \fB\-q\fP (\fBddns\-confgen\fP only) +.B \fB\-q\fP This option enables quiet mode, which prints only the key, with no explanatory text or usage examples. This is essentially identical to \fBtsig\-keygen\fP\&. .TP -.B \fB\-s name\fP (\fBddns\-confgen\fP only) -This option generates a configuration example to allow -dynamic updates of a single hostname. The example \fBnamed.conf\fP text -shows how to set an update policy for the specified name using the -"name" nametype. The default key name is \fBddns\-key.name\fP\&. Note that the -"self" nametype cannot be used, since the name to be updated may -differ from the key name. This option cannot be used with the \fB\-z\fP -option. +.B \fB\-s name\fP +This option generates a configuration example to allow dynamic updates +of a single hostname. The example \fBnamed.conf\fP text shows how to set +an update policy for the specified name using the "name" nametype. The +default key name is \fBddns\-key.name\fP\&. Note that the "self" nametype +cannot be used, since the name to be updated may differ from the key +name. This option cannot be used with the \fB\-z\fP option. .TP -.B \fB\-z zone\fP (\fBddns\-confgen\fP only) +.B \fB\-z zone\fP This option generates a configuration example to allow dynamic updates of a zone. The example \fBnamed.conf\fP text shows how to set an update policy for the specified zone using the "zonesub" diff --git a/doc/man/ddns-confgen.rst b/doc/man/ddns-confgen.rst index a83f6a011a..891102f407 100644 --- a/doc/man/ddns-confgen.rst +++ b/doc/man/ddns-confgen.rst @@ -11,4 +11,4 @@ :orphan: -.. include:: ../../bin/confgen/ddns-confgen.rst \ No newline at end of file +.. include:: ../../bin/confgen/ddns-confgen.rst diff --git a/doc/man/tsig-keygen.8in b/doc/man/tsig-keygen.8in new file mode 100644 index 0000000000..dda1fab6aa --- /dev/null +++ b/doc/man/tsig-keygen.8in @@ -0,0 +1,64 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TSIG-KEYGEN" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +tsig-keygen \- TSIG key generation tool +.SH SYNOPSIS +.sp +\fBtsig\-keygen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [name] +.SH DESCRIPTION +.sp +\fBtsig\-keygen\fP is an utility that generates keys for use in TSIG signing. +The resulting keys can be used, for example, to secure dynamic DNS updates +to a zone, or for the \fBrndc\fP command channel. +.sp +A domain name can be specified on the command line to be used as the name +of the generated key. If no name is specified, the default is \fBtsig\-key\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-a algorithm\fP +This option specifies the algorithm to use for the TSIG key. Available +choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, +and hmac\-sha512. The default is hmac\-sha256. Options are +case\-insensitive, and the "hmac\-" prefix may be omitted. +.TP +.B \fB\-h\fP +This option prints a short summary of options and arguments. +.UNINDENT +.SH SEE ALSO +.sp +\fBnsupdate(1)\fP, \fBnamed.conf(5)\fP, \fBnamed(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2022, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/tsig-keygen.rst b/doc/man/tsig-keygen.rst new file mode 100644 index 0000000000..fbd957d314 --- /dev/null +++ b/doc/man/tsig-keygen.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/confgen/tsig-keygen.rst