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

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

``rndc-confgen`` generates configuration files for ``rndc``. It can be
used as a convenient alternative to writing the ``rndc.conf`` file and
the corresponding ``controls`` and ``key`` statements in ``named.conf``
by hand. Alternatively, it can be run with the ``-a`` option to set up a
``rndc.key`` file and avoid the need for a ``rndc.conf`` file and a
``controls`` statement altogether.

Options
~~~~~~~

``-a``
   This option sets automatic ``rndc`` configuration, which creates a file ``rndc.key``
   in ``/etc`` (or a different ``sysconfdir`` specified when BIND
   was built) that is read by both ``rndc`` and ``named`` on startup.
   The ``rndc.key`` file defines a default command channel and
   authentication key allowing ``rndc`` to communicate with ``named`` on
   the local host with no further configuration.

   If a more elaborate configuration than that generated by
   ``rndc-confgen -a`` is required, for example if rndc is to be used
   remotely, run ``rndc-confgen`` without the ``-a`` option
   and set up ``rndc.conf`` and ``named.conf`` as directed.

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

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

``-c keyfile``
   This option is used with the ``-a`` option to specify an alternate location for
   ``rndc.key``.

``-h``
   This option prints a short summary of the options and arguments to
   ``rndc-confgen``.

``-k keyname``
   This option specifies the key name of the ``rndc`` authentication key. This must be a
   valid domain name. The default is ``rndc-key``.

``-p port``
   This option specifies the command channel port where ``named`` listens for
   connections from ``rndc``. The default is 953.

``-s address``
   This option specifies the IP address where ``named`` listens for command-channel
   connections from ``rndc``. The default is the loopback address
   127.0.0.1.

``-t chrootdir``
   This option is used with the ``-a`` option to specify a directory where ``named``
   runs chrooted. An additional copy of the ``rndc.key`` is
   written relative to this directory, so that it is found by the
   chrooted ``named``.

``-u user``
   This option is used with the ``-a`` option to set the owner of the generated ``rndc.key`` file.
   If ``-t`` is also specified, only the file in the chroot
   area has its owner changed.

Examples
~~~~~~~~

To allow ``rndc`` to be used with no manual configuration, run:

``rndc-confgen -a``

To print a sample ``rndc.conf`` file and the corresponding ``controls`` and
``key`` statements to be manually inserted into ``named.conf``, run:

``rndc-confgen``

See Also
~~~~~~~~

:manpage:`rndc(8)`, :manpage:`rndc.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual.