From 3b9b6d0b8e7f798023c9d109c490449d528fde80 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:59:48 +0200 Subject: Adding upstream version 1:9.18.19. Signed-off-by: Daniel Baumann --- doc/man/rndc.conf.5in | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 doc/man/rndc.conf.5in (limited to 'doc/man/rndc.conf.5in') diff --git a/doc/man/rndc.conf.5in b/doc/man/rndc.conf.5in new file mode 100644 index 0000000..33fd93c --- /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@" "@PACKAGE_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 \fI\%rndc\fP, the BIND 9 name +server control utility. This file has a similar structure and syntax to +\fI\%named.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 \fI\%named.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 \fI\%rndc\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 \fI\%rndc\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 \fI\%rndc\-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, \fI\%rndc\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 \fI\%rndc \-s testserver\fP is used, then \fI\%rndc\fP connects to the server +on localhost port 5353 using the key \(dqtestkey\(dq. +.sp +To generate a random secret with \fI\%rndc\-confgen\fP: +.sp +\fI\%rndc\-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 \fI\%named.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 \fI\%named.conf\fP\&. See the sections on the +\fBcontrols\fP statement in the BIND 9 Administrator Reference Manual for +details. +.SH SEE ALSO +.sp +\fI\%rndc(8)\fP, \fI\%rndc\-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. +. -- cgit v1.2.3