143 lines
5.1 KiB
Groff
143 lines
5.1 KiB
Groff
.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
|
|
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
|
|
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
|
|
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
.\" PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" $Id: rndc.conf.5,v 1.21.206.2 2004/06/03 05:35:50 marka Exp $
|
|
.\"
|
|
.TH "RNDC.CONF" "5" "June 30, 2000" "BIND9" ""
|
|
.SH NAME
|
|
rndc.conf \- rndc configuration file
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fBrndc.conf\fR
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fIrndc.conf\fR is the configuration file
|
|
for \fBrndc\fR, the BIND 9 name server control
|
|
utility. This file has a similar structure and syntax to
|
|
\fInamed.conf\fR. 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:
|
|
.PP
|
|
C style: /* */
|
|
.PP
|
|
C++ style: // to end of line
|
|
.PP
|
|
Unix style: # to end of line
|
|
.PP
|
|
\fIrndc.conf\fR is much simpler than
|
|
\fInamed.conf\fR. The file uses three
|
|
statements: an options statement, a server statement
|
|
and a key statement.
|
|
.PP
|
|
The \fBoptions\fR statement contains three clauses.
|
|
The \fBdefault-server\fR clause is followed by the
|
|
name or address of a name server. This host will be used when
|
|
no name server is given as an argument to
|
|
\fBrndc\fR. The \fBdefault-key\fR
|
|
clause is followed by the name of a key which is identified by
|
|
a \fBkey\fR statement. If no
|
|
\fBkeyid\fR is provided on the rndc command line,
|
|
and no \fBkey\fR clause is found in a matching
|
|
\fBserver\fR statement, this default key will be
|
|
used to authenticate the server's commands and responses. The
|
|
\fBdefault-port\fR clause is followed by the port
|
|
to connect to on the remote name server. If no
|
|
\fBport\fR option is provided on the rndc command
|
|
line, and no \fBport\fR clause is found in a
|
|
matching \fBserver\fR statement, this default port
|
|
will be used to connect.
|
|
.PP
|
|
After the \fBserver\fR keyword, the server statement
|
|
includes a string which is the hostname or address for a name
|
|
server. The statement has two possible clauses:
|
|
\fBkey\fR and \fBport\fR. The key name must
|
|
match the name of a key statement in the file. The port number
|
|
specifies the port to connect to.
|
|
.PP
|
|
The \fBkey\fR statement begins with an identifying
|
|
string, the name of the key. The statement has two clauses.
|
|
\fBalgorithm\fR identifies the encryption algorithm
|
|
for \fBrndc\fR to use; currently only HMAC-MD5 is
|
|
supported. This is followed by a secret clause which contains
|
|
the base-64 encoding of the algorithm's encryption key. The
|
|
base-64 string is enclosed in double quotes.
|
|
.PP
|
|
There are two common ways to generate the base-64 string for the
|
|
secret. The BIND 9 program \fBrndc-confgen\fR can
|
|
be used to generate a random key, or the
|
|
\fBmmencode\fR program, also known as
|
|
\fBmimencode\fR, can be used to generate a base-64
|
|
string from known input. \fBmmencode\fR does not
|
|
ship with BIND 9 but is available on many systems. See the
|
|
EXAMPLE section for sample command lines for each.
|
|
.SH "EXAMPLE"
|
|
.sp
|
|
.nf
|
|
options {
|
|
default-server localhost;
|
|
default-key samplekey;
|
|
};
|
|
|
|
server localhost {
|
|
key samplekey;
|
|
};
|
|
|
|
key samplekey {
|
|
algorithm hmac-md5;
|
|
secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
|
|
};
|
|
|
|
.sp
|
|
.fi
|
|
.PP
|
|
In the above example, \fBrndc\fR will by default use
|
|
the server at localhost (127.0.0.1) and the key called samplekey.
|
|
Commands to the localhost server will 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-MD5 algorithm and its secret clause contains the
|
|
base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
|
|
.PP
|
|
To generate a random secret with \fBrndc-confgen\fR:
|
|
.PP
|
|
\fBrndc-confgen\fR
|
|
.PP
|
|
A complete \fIrndc.conf\fR file, including the
|
|
randomly generated key, will be written to the standard
|
|
output. Commented out \fBkey\fR and
|
|
\fBcontrols\fR statements for
|
|
\fInamed.conf\fR are also printed.
|
|
.PP
|
|
To generate a base-64 secret with \fBmmencode\fR:
|
|
.PP
|
|
\fBecho "known plaintext for a secret" | mmencode\fR
|
|
.SH "NAME SERVER CONFIGURATION"
|
|
.PP
|
|
The name server must be configured to accept rndc connections and
|
|
to recognize the key specified in the \fIrndc.conf\fR
|
|
file, using the controls statement in \fInamed.conf\fR.
|
|
See the sections on the \fBcontrols\fR statement in the
|
|
BIND 9 Administrator Reference Manual for details.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBrndc\fR(8),
|
|
\fBrndc-confgen\fR(8),
|
|
\fBmmencode\fR(1),
|
|
\fIBIND 9 Administrator Reference Manual\fR.
|
|
.SH "AUTHOR"
|
|
.PP
|
|
Internet Systems Consortium
|