216 lines
5.2 KiB
Groff
216 lines
5.2 KiB
Groff
.\" Copyright (C) 2000 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 INTERNET SOFTWARE CONSORTIUM
|
|
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
|
.\" INTERNET SOFTWARE CONSORTIUM 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.9 2000/12/15 00:24:10 gson Exp $
|
|
|
|
.Dd Jun 30, 2000
|
|
.Dt RDNC.CONF 5
|
|
.Os BIND9 9
|
|
.ds vT BIND9 Programmer's Manual
|
|
.Sh NAME
|
|
.Nm rdnc.conf
|
|
.Nd rdnc configuration file
|
|
.Sh SYNOPSIS
|
|
.Nm rdnc.conf
|
|
.Sh DESCRIPTION
|
|
The BIND9 utility for controlling the name server,
|
|
.Nm rndc ,
|
|
has its own configuration file
|
|
.Pa /etc/rndc.conf .
|
|
This file has a similar structure and syntax to
|
|
.Pa named.conf ,
|
|
the file used to configure the name server.
|
|
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:
|
|
.Bl -tag -width UNIX-style:
|
|
.It C style: /* */
|
|
.It C++ style: // to end of line
|
|
.It Unix style: # to end of line
|
|
.El
|
|
.Pp
|
|
.Pa rndc.conf
|
|
is much simpler than
|
|
.Pa named.conf .
|
|
The file uses three statements: an
|
|
.Dv options
|
|
statement, a
|
|
.Dv server
|
|
statement and a
|
|
.Dv key
|
|
statement.
|
|
.Pp
|
|
The
|
|
.Dv options
|
|
statement contains two clauses.
|
|
The
|
|
.Dv default-server
|
|
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
|
|
.Nm rndc .
|
|
The
|
|
.Dv default-key
|
|
clause
|
|
is followed by the name of a key which is identified by a
|
|
.Dv key
|
|
statement.
|
|
If no
|
|
.Fl y
|
|
option is provided on the
|
|
.Xr rndc
|
|
command line, and no
|
|
.Dv key
|
|
clause is found in a a matching
|
|
.Dv server
|
|
statement, this default key will be used to authenticate the server's
|
|
commands and responses.
|
|
.Pp
|
|
After the keyword
|
|
.Dv server ,
|
|
the
|
|
.Dv server
|
|
statement is followed by a string which is the hostname or address for a
|
|
name server.
|
|
The statement has a single clause,
|
|
.Dv key .
|
|
The key name must match the name of a
|
|
.Dv key
|
|
statement in the file.
|
|
.Pp
|
|
The
|
|
.Dv key
|
|
statement begins with an identifying string, the name of the key.
|
|
The statement has two clauses.
|
|
.Dv algorithm
|
|
identifies the encryption algorithm for
|
|
.Nm rndc
|
|
to use; currently only HMAC-MD5 is supported.
|
|
This is followed by a
|
|
.Dv 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
|
|
.Dv secret .
|
|
The BIND 9 program
|
|
.Xr dnssec-keygen 8
|
|
can be used to generate a random key, or the
|
|
.Xr mmencode 1
|
|
program, also known as
|
|
.Xr mimencode 1 ,
|
|
can be used to generate a base-64 string from known input.
|
|
.Xr mmencode
|
|
does not ship with BIND 9 but is available on many systems.
|
|
See the
|
|
.Sx EXAMPLES
|
|
section for sample command lines for each.
|
|
.Pp
|
|
Host and key names must be quoted using double quotes if they
|
|
match a keyword, such as having a key named "key".
|
|
.Sh EXAMPLE
|
|
.Bd -literal indent
|
|
options {
|
|
default-server localhost;
|
|
default-key samplekey;
|
|
};
|
|
|
|
server localhost {
|
|
key samplekey;
|
|
};
|
|
|
|
key samplekey {
|
|
algorithm hmac-md5;
|
|
secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
|
|
};
|
|
.Ed
|
|
.Pp
|
|
In the above example,
|
|
.Nm rndc
|
|
will by default use the server at localhost (127.0.0.1) and the key called
|
|
.Dv samplekey .
|
|
Commands to the localhost server will use the
|
|
.Dv samplekey
|
|
key.
|
|
The
|
|
.Dv key
|
|
statement indicates that
|
|
.Dv samplekey
|
|
uses the HMAC-MD5 algorithm and its
|
|
.Dv secret
|
|
clause contains the base-64 encoding of the HMAC-MD5 secret enclosed
|
|
in double quotes.
|
|
.Pp
|
|
To generate a random secret with
|
|
.Xr dnssec-keygen :
|
|
.Bd -literal indent
|
|
$ dnssec-keygen -a hmac-md5 -b 128 -n user rndc
|
|
.Ed
|
|
.Pp
|
|
The base-64 string will appear in two files,
|
|
.Pa Krndc.+157.+{random}.key
|
|
and
|
|
.Pa Krndc.+157.+{random}.private .
|
|
After extracting the key to be
|
|
placed in the
|
|
.Nm rndc.conf
|
|
and
|
|
.Xr named.conf
|
|
.Dv key
|
|
statements, the
|
|
.Pa .key
|
|
and
|
|
.Pa .private
|
|
files can be removed.
|
|
.Pp
|
|
To generate a secret from known input with
|
|
.Xr mmenode :
|
|
.Bd -literal indent
|
|
$ echo "known plaintext for a secret" | mmencode
|
|
.Ed
|
|
.Sh NAME SERVER CONFIGURATION
|
|
The name server must be configured to accept
|
|
.Xr rndc
|
|
connections and to recognize the key specified in
|
|
the
|
|
.Nm rndc.conf
|
|
file, using the
|
|
.Dv controls
|
|
statement in
|
|
.Nm named.conf .
|
|
See the sections on the
|
|
.Dv controls
|
|
statement in the BIND 9 Administrator Reference Manual for
|
|
details.
|
|
.Sh LIMITATIONS
|
|
There is currently no way to specify the port for
|
|
.Xr rndc
|
|
to use. This will be remedied in future releases by allowing a
|
|
.Dv port
|
|
clause to the
|
|
.Dv server
|
|
statement and a
|
|
.Dv default-port
|
|
clause to the
|
|
.Dv options
|
|
statement.
|
|
.Sh SEE ALSO
|
|
.Xr rndc 8 ,
|
|
.Xr dnssec-keygen 8 ,
|
|
.Xr mmencode 1 ,
|
|
"BIND 9 Administrator Reference Manual".
|