diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst new file mode 100644 index 0000000000..52ae412c58 --- /dev/null +++ b/bin/confgen/ddns-confgen.rst @@ -0,0 +1,88 @@ +.. 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 tsig-keygen.rst! + +.. _man_ddns-confgen: + +ddns-confgen - TSIG key generation tool +--------------------------------------- + +Synopsis +~~~~~~~~ +:program:`ddns-confgen` [**-a** algorithm] [**-h**] [**-k** keyname] [**-q**] [**-s** name] [**-z** zone] + +Description +~~~~~~~~~~~ + +``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. + +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 +``update-policy local;``. ``ddns-confgen`` is only needed when a more +elaborate configuration is required: for instance, if ``nsupdate`` is to +be used from a remote system. + +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. + +``-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 + letters, digits, hyphens, and periods. + +``-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`` + 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`` + 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" + nametype, allowing updates to all subdomain names within that zone. + This option cannot be used with the ``-s`` option. + +See Also +~~~~~~~~ + +:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual. diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 41d1fc5ad4..a1274079de 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -11,39 +11,26 @@ .. highlight: console -tsig-keygen, ddns-confgen - TSIG key generation tool ----------------------------------------------------- +.. 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] -: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. +``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. -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 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 -``update-policy local;``. ``ddns-confgen`` is only needed when a more -elaborate configuration is required: for instance, if ``nsupdate`` is to -be used from a remote system. +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 ~~~~~~~ @@ -57,34 +44,6 @@ Options ``-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 - letters, digits, hyphens, and periods. - -``-q`` (``ddns-confgen`` only) - 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. - -``-z zone`` (``ddns-confgen`` only) - 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" - nametype, allowing updates to all subdomain names within that zone. - This option cannot be used with the ``-s`` option. - See Also ~~~~~~~~ diff --git a/doc/arm/advanced.rst b/doc/arm/advanced.rst index 70799e0f54..eeb807af00 100644 --- a/doc/arm/advanced.rst +++ b/doc/arm/advanced.rst @@ -417,8 +417,7 @@ email, etc.) ``tsig-keygen`` can also be run as ``ddns-confgen``, in which case its output includes additional configuration text for setting up dynamic DNS -in ``named``. See :ref:`tsig-keygen, ddns-confgen - TSIG key generation -tool ` for details. +in ``named``. See :ref:`man_ddns-confgen` for details. Loading a New Key ~~~~~~~~~~~~~~~~~ diff --git a/doc/arm/manpages.rst b/doc/arm/manpages.rst index 016bc931f4..7cab46186d 100644 --- a/doc/arm/manpages.rst +++ b/doc/arm/manpages.rst @@ -44,5 +44,5 @@ Manual Pages .. include:: ../../bin/confgen/rndc-confgen.rst .. include:: ../../bin/rndc/rndc.conf.rst .. include:: ../../bin/rndc/rndc.rst -.. _man_tsig-keygen_ddns-confgen: +.. include:: ../../bin/confgen/ddns-confgen.rst .. include:: ../../bin/confgen/tsig-keygen.rst diff --git a/doc/man/ddns-confgen.8in b/doc/man/ddns-confgen.8in index 57cad3eb5e..47261ab8c8 100644 --- a/doc/man/ddns-confgen.8in +++ b/doc/man/ddns-confgen.8in @@ -32,26 +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 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.) +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 @@ -78,12 +71,12 @@ 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) +.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 @@ -91,7 +84,7 @@ 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 fbd957d314..891102f407 100644 --- a/doc/man/ddns-confgen.rst +++ b/doc/man/ddns-confgen.rst @@ -11,4 +11,4 @@ :orphan: -.. include:: ../../bin/confgen/tsig-keygen.rst +.. include:: ../../bin/confgen/ddns-confgen.rst diff --git a/doc/man/tsig-keygen.8in b/doc/man/tsig-keygen.8in index 9ff9f3e2b8..868cc41d6f 100644 --- a/doc/man/tsig-keygen.8in +++ b/doc/man/tsig-keygen.8in @@ -33,31 +33,14 @@ tsig-keygen \- TSIG 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. +\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 -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 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 -\fBupdate\-policy local;\fP\&. \fBddns\-confgen\fP is only needed when a more -elaborate configuration is required: for instance, if \fBnsupdate\fP is to -be used from a remote system. +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 @@ -69,34 +52,6 @@ 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 -letters, digits, hyphens, and periods. -.TP -.B \fB\-q\fP (\fBddns\-confgen\fP only) -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. -.TP -.B \fB\-z zone\fP (\fBddns\-confgen\fP only) -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" -nametype, allowing updates to all subdomain names within that zone. -This option cannot be used with the \fB\-s\fP option. .UNINDENT .SH SEE ALSO .sp