Adding upstream version 1:9.16.44.upstream/1%9.16.44

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 196 insertions, 0 deletions

diff --git a/doc/man/rndc.conf.5in b/doc/man/rndc.conf.5in
new file mode 100644
index 0000000..54a0847
--- /dev/null
+++ b/doc/man/rndc.conf.5in
@@ -0,0 +1,196 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "RNDC.CONF" "5" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9"
+.SH NAME
+rndc.conf \- rndc configuration file
+.SH SYNOPSIS
+.sp
+\fBrndc.conf\fP
+.SH DESCRIPTION
+.sp
+\fBrndc.conf\fP is the configuration file for \fBrndc\fP, the BIND 9 name
+server control utility. This file has a similar structure and syntax to
+\fBnamed.conf\fP\&. 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:
+.sp
+C style: /* */
+.sp
+C++ style: // to end of line
+.sp
+Unix style: # to end of line
+.sp
+\fBrndc.conf\fP is much simpler than \fBnamed.conf\fP\&. The file uses three
+statements: an options statement, a server statement, and a key
+statement.
+.sp
+The \fBoptions\fP statement contains five clauses. The \fBdefault\-server\fP
+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 \fBrndc\fP\&.
+The \fBdefault\-key\fP clause is followed by the name of a key, which is
+identified by a \fBkey\fP statement. If no \fBkeyid\fP is provided on the
+rndc command line, and no \fBkey\fP clause is found in a matching
+\fBserver\fP statement, this default key is used to authenticate the
+server\(aqs commands and responses. The \fBdefault\-port\fP clause is followed
+by the port to connect to on the remote name server. If no \fBport\fP
+option is provided on the rndc command line, and no \fBport\fP clause is
+found in a matching \fBserver\fP statement, this default port is used
+to connect. The \fBdefault\-source\-address\fP and
+\fBdefault\-source\-address\-v6\fP clauses can be used to set the IPv4
+and IPv6 source addresses respectively.
+.sp
+After the \fBserver\fP keyword, the server statement includes a string
+which is the hostname or address for a name server. The statement has
+three possible clauses: \fBkey\fP, \fBport\fP, and \fBaddresses\fP\&. 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 \fBaddresses\fP clause is supplied,
+these addresses are used instead of the server name. Each address
+can take an optional port. If an \fBsource\-address\fP or
+\fBsource\-address\-v6\fP is supplied, it is used to specify the
+IPv4 and IPv6 source address, respectively.
+.sp
+The \fBkey\fP statement begins with an identifying string, the name of the
+key. The statement has two clauses. \fBalgorithm\fP identifies the
+authentication algorithm for \fBrndc\fP 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\(aqs
+authentication key. The base\-64 string is enclosed in double quotes.
+.sp
+There are two common ways to generate the base\-64 string for the secret.
+The BIND 9 program \fBrndc\-confgen\fP can be used to generate a random
+key, or the \fBmmencode\fP program, also known as \fBmimencode\fP, can be
+used to generate a base\-64 string from known input. \fBmmencode\fP does
+not ship with BIND 9 but is available on many systems. See the Example
+section for sample command lines for each.
+.SH EXAMPLE
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+options {
+  default\-server  localhost;
+  default\-key     samplekey;
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+server localhost {
+  key             samplekey;
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+server testserver {
+  key     testkey;
+  addresses   { localhost port 5353; };
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+key samplekey {
+  algorithm       hmac\-sha256;
+  secret          \(dq6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz\(dq;
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+key testkey {
+  algorithm   hmac\-sha256;
+  secret      \(dqR3HI8P6BKw9ZwXwN3VZKuQ==\(dq;
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the above example, \fBrndc\fP by default uses the server at
+localhost (127.0.0.1) and the key called \(dqsamplekey\(dq. Commands to the
+localhost server use the \(dqsamplekey\(dq key, which must also be defined
+in the server\(aqs configuration file with the same name and secret. The
+key statement indicates that \(dqsamplekey\(dq uses the HMAC\-SHA256 algorithm
+and its secret clause contains the base\-64 encoding of the HMAC\-SHA256
+secret enclosed in double quotes.
+.sp
+If \fBrndc \-s testserver\fP is used, then \fBrndc\fP connects to the server
+on localhost port 5353 using the key \(dqtestkey\(dq.
+.sp
+To generate a random secret with \fBrndc\-confgen\fP:
+.sp
+\fBrndc\-confgen\fP
+.sp
+A complete \fBrndc.conf\fP file, including the randomly generated key,
+is written to the standard output. Commented\-out \fBkey\fP and
+\fBcontrols\fP statements for \fBnamed.conf\fP are also printed.
+.sp
+To generate a base\-64 secret with \fBmmencode\fP:
+.sp
+\fBecho \(dqknown plaintext for a secret\(dq | mmencode\fP
+.SH NAME SERVER CONFIGURATION
+.sp
+The name server must be configured to accept rndc connections and to
+recognize the key specified in the \fBrndc.conf\fP file, using the
+controls statement in \fBnamed.conf\fP\&. See the sections on the
+\fBcontrols\fP statement in the BIND 9 Administrator Reference Manual for
+details.
+.SH SEE ALSO
+.sp
+\fBrndc(8)\fP, \fBrndc\-confgen(8)\fP, \fBmmencode(1)\fP, BIND 9 Administrator Reference Manual.
+.SH AUTHOR
+Internet Systems Consortium
+.SH COPYRIGHT
+2023, Internet Systems Consortium
+.\" Generated by docutils manpage writer.
+.