186 lines
6.1 KiB
Text
186 lines
6.1 KiB
Text
.\" 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
|
|
.EX
|
|
options {
|
|
default\-server localhost;
|
|
default\-key samplekey;
|
|
};
|
|
.EE
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.EX
|
|
server localhost {
|
|
key samplekey;
|
|
};
|
|
.EE
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.EX
|
|
server testserver {
|
|
key testkey;
|
|
addresses { localhost port 5353; };
|
|
};
|
|
.EE
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.EX
|
|
key samplekey {
|
|
algorithm hmac\-sha256;
|
|
secret \(dq6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz\(dq;
|
|
};
|
|
.EE
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.EX
|
|
key testkey {
|
|
algorithm hmac\-sha256;
|
|
secret \(dqR3HI8P6BKw9ZwXwN3VZKuQ==\(dq;
|
|
};
|
|
.EE
|
|
.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
|
|
2025, Internet Systems Consortium
|
|
.\" Generated by docutils manpage writer.
|
|
.
|