.. 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.