1 files changed, 158 insertions, 0 deletions
diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst
new file mode 100644
index 0000000..20e6bc9
--- /dev/null
+++ b/bin/rndc/rndc.conf.rst
@@ -0,0 +1,158 @@
+.. 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.conf
+.. program:: rndc.conf
+.. _man_rndc.conf:
+
+rndc.conf - rndc configuration file
+-----------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`rndc.conf`
+
+Description
+~~~~~~~~~~~
+
+:program:`rndc.conf` is the configuration file for :iscman:`rndc`, the BIND 9 name
+server control utility. This file has a similar structure and syntax to
+:iscman:`named.conf`. Statements are enclosed in braces and terminated with a
+semi-colon. Clauses in the statements are also semi-colon terminated.
+The usual comment styles are supported:
+
+C style: /\* \*/
+
+C++ style: // to end of line
+
+Unix style: # to end of line
+
+:program:`rndc.conf` is much simpler than :iscman:`named.conf`. The file uses three
+statements: an options statement, a server statement, and a key
+statement.
+
+The ``options`` statement contains five clauses. The ``default-server``
+clause is followed by the name or address of a name server. This host
+is used when no name server is given as an argument to :iscman:`rndc`.
+The ``default-key`` clause is followed by the name of a key, which is
+identified by a ``key`` statement. If no ``keyid`` is provided on the
+rndc command line, and no ``key`` clause is found in a matching
+``server`` statement, this default key is used to authenticate the
+server's commands and responses. The ``default-port`` clause is followed
+by the port to connect to on the remote name server. If no ``port``
+option is provided on the rndc command line, and no ``port`` clause is
+found in a matching ``server`` statement, this default port is used
+to connect. The ``default-source-address`` and
+``default-source-address-v6`` clauses can be used to set the IPv4
+and IPv6 source addresses respectively.
+
+After the ``server`` keyword, the server statement includes a string
+which is the hostname or address for a name server. The statement has
+three possible clauses: ``key``, ``port``, and ``addresses``. The key
+name must match the name of a key statement in the file. The port number
+specifies the port to connect to. If an ``addresses`` clause is supplied,
+these addresses are used instead of the server name. Each address
+can take an optional port. If an ``source-address`` or
+``source-address-v6`` is supplied, it is used to specify the
+IPv4 and IPv6 source address, respectively.
+
+The ``key`` statement begins with an identifying string, the name of the
+key. The statement has two clauses. ``algorithm`` identifies the
+authentication algorithm for :iscman:`rndc` to use; currently only HMAC-MD5
+(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default),
+HMAC-SHA384, and HMAC-SHA512 are supported. This is followed by a secret
+clause which contains the base-64 encoding of the algorithm's
+authentication key. The base-64 string is enclosed in double quotes.
+
+There are two common ways to generate the base-64 string for the secret.
+The BIND 9 program :iscman:`rndc-confgen` can be used to generate a random
+key, or the ``mmencode`` program, also known as ``mimencode``, can be
+used to generate a base-64 string from known input. ``mmencode`` does
+not ship with BIND 9 but is available on many systems. See the Example
+section for sample command lines for each.
+
+Example
+~~~~~~~
+
+::
+
+         options {
+           default-server  localhost;
+           default-key     samplekey;
+         };
+
+::
+
+         server localhost {
+           key             samplekey;
+         };
+
+::
+
+         server testserver {
+           key     testkey;
+           addresses   { localhost port 5353; };
+         };
+
+::
+
+         key samplekey {
+           algorithm       hmac-sha256;
+           secret          "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
+         };
+
+::
+
+         key testkey {
+           algorithm   hmac-sha256;
+           secret      "R3HI8P6BKw9ZwXwN3VZKuQ==";
+         };
+
+
+In the above example, :iscman:`rndc` by default uses the server at
+localhost (127.0.0.1) and the key called "samplekey". Commands to the
+localhost server use the "samplekey" key, which must also be defined
+in the server's configuration file with the same name and secret. The
+key statement indicates that "samplekey" uses the HMAC-SHA256 algorithm
+and its secret clause contains the base-64 encoding of the HMAC-SHA256
+secret enclosed in double quotes.
+
+If :option:`rndc -s testserver <rndc -s>` is used, then :iscman:`rndc` connects to the server
+on localhost port 5353 using the key "testkey".
+
+To generate a random secret with :iscman:`rndc-confgen`:
+
+:iscman:`rndc-confgen`
+
+A complete :program:`rndc.conf` file, including the randomly generated key,
+is written to the standard output. Commented-out ``key`` and
+``controls`` statements for :iscman:`named.conf` are also printed.
+
+To generate a base-64 secret with ``mmencode``:
+
+``echo "known plaintext for a secret" | mmencode``
+
+Name Server Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The name server must be configured to accept rndc connections and to
+recognize the key specified in the :program:`rndc.conf` file, using the
+controls statement in :iscman:`named.conf`. See the sections on the
+``controls`` statement in the BIND 9 Administrator Reference Manual for
+details.
+
+See Also
+~~~~~~~~
+
+:iscman:`rndc(8) <rndc>`, :iscman:`rndc-confgen(8) <rndc-confgen>`, :manpage:`mmencode(1)`, BIND 9 Administrator Reference Manual.