summaryrefslogtreecommitdiffstats
path: root/bin/confgen/rndc-confgen.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--bin/confgen/rndc-confgen.rst121
1 files changed, 121 insertions, 0 deletions
diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst
new file mode 100644
index 0000000..0a91489
--- /dev/null
+++ b/bin/confgen/rndc-confgen.rst
@@ -0,0 +1,121 @@
+.. 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
+
+.. iscman:: rndc-confgen
+.. program:: rndc-confgen
+.. _man_rndc-confgen:
+
+rndc-confgen - rndc key generation tool
+---------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`rndc-confgen` [**-a**] [**-A** algorithm] [**-b** keysize] [**-c** keyfile] [**-h**] [**-k** keyname] [**-p** port] [**-s** address] [**-t** chrootdir] [**-u** user]
+
+Description
+~~~~~~~~~~~
+
+:program:`rndc-confgen` generates configuration files for :iscman:`rndc`. It can be
+used as a convenient alternative to writing the :iscman:`rndc.conf` file and
+the corresponding ``controls`` and ``key`` statements in :iscman:`named.conf`
+by hand. Alternatively, it can be run with the :option:`-a` option to set up a
+``rndc.key`` file and avoid the need for a :iscman:`rndc.conf` file and a
+``controls`` statement altogether.
+
+Options
+~~~~~~~
+
+.. option:: -a
+
+ This option sets automatic :iscman:`rndc` configuration, which creates a file
+ |rndc_key| that is read by both :iscman:`rndc` and :iscman:`named` on startup.
+ The ``rndc.key`` file defines a default command channel and
+ authentication key allowing :iscman:`rndc` to communicate with :iscman:`named` on
+ the local host with no further configuration.
+
+ If a more elaborate configuration than that generated by
+ :option:`rndc-confgen -a` is required, for example if rndc is to be used
+ remotely, run :program:`rndc-confgen` without the :option:`-a` option
+ and set up :iscman:`rndc.conf` and :iscman:`named.conf` as directed.
+
+.. option:: -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.
+
+.. option:: -b keysize
+
+ This option specifies the size of the authentication key in bits. The size must be between
+ 1 and 512 bits; the default is the hash size.
+
+.. option:: -c keyfile
+
+ This option is used with the :option:`-a` option to specify an alternate location for
+ ``rndc.key``.
+
+.. option:: -h
+
+ This option prints a short summary of the options and arguments to
+ :program:`rndc-confgen`.
+
+.. option:: -k keyname
+
+ This option specifies the key name of the :iscman:`rndc` authentication key. This must be a
+ valid domain name. The default is ``rndc-key``.
+
+.. option:: -p port
+
+ This option specifies the command channel port where :iscman:`named` listens for
+ connections from :iscman:`rndc`. The default is 953.
+
+.. option:: -q
+
+ This option prevets printing the written path in automatic configuration mode.
+
+.. option:: -s address
+
+ This option specifies the IP address where :iscman:`named` listens for command-channel
+ connections from :iscman:`rndc`. The default is the loopback address
+ 127.0.0.1.
+
+.. option:: -t chrootdir
+
+ This option is used with the :option:`-a` option to specify a directory where :iscman:`named`
+ runs chrooted. An additional copy of the ``rndc.key`` is
+ written relative to this directory, so that it is found by the
+ chrooted :iscman:`named`.
+
+.. option:: -u user
+
+ This option is used with the :option:`-a` option to set the owner of the generated ``rndc.key`` file.
+ If :option:`-t` is also specified, only the file in the chroot
+ area has its owner changed.
+
+Examples
+~~~~~~~~
+
+To allow :iscman:`rndc` to be used with no manual configuration, run:
+
+``rndc-confgen -a``
+
+To print a sample :iscman:`rndc.conf` file and the corresponding ``controls`` and
+``key`` statements to be manually inserted into :iscman:`named.conf`, run:
+
+:program:`rndc-confgen`
+
+See Also
+~~~~~~~~
+
+:iscman:`rndc(8) <rndc>`, :iscman:`rndc.conf(5) <rndc.conf>`, :iscman:`named(8) <named>`, BIND 9 Administrator Reference Manual.