Skip to content

GitLab

Commit 5704b77b authored by cvs2git's avatar cvs2git
Browse files
Options

This commit was manufactured by cvs2git to create tag 'v9_0_0rc1'.

parents 4d631bac 5fd4b1c6
Hide whitespace changes
Inline Side-by-side
Showing with 539 additions and 0 deletions
doc/man/bin/named.8 0 → 100644
View file @ 5704b77b
.\"
.\" Copyright (C) 2000 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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: named.8,v 1.3 2000/07/12 02:07:32 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt NAMED 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm named
.Nd Internet domain name server (DNS)
.Sh SYNOPSIS
.Nm named
.Op Fl c Ar config-file
.Op Fl d Ar debuglevel
.Op Fl f g s
.Op Fl n Ar #cpus
.Op Fl p Ar port#
.Op Fl t Ar directory
.Op Fl u Ar user-id
.Op Fl x Ar cache-file
.Sh DESCRIPTION
.Nm named
is the ISC implementation of an Internet domain name server.
See RFCs 1033, 1034, and 1035 for more information on the Internet
domain name system.
For historical reasons, the ISC's DNS software is known as BIND -
Berkeley Internet Name Daemon - because it was originally
supplied with BSD
.Ux
releases.
.Pp
Without any arguments,
.Nm named
will read the default configuration file
.Pa /etc/named.conf ,
read any initial data, and listen for queries.
It is also possible to use the BIND9 name server
as a lightweight resolver server
.Nm lwresd .
However when operating as a lightweight resolver server,
.Nm named
is functionally and logically distinct from a
conventional name server.
More information can be found in
.Xr lwresd 8 .
.Pp
Although some command-line options can be used with
.Nm named ,
the name server's behaviour is mainly controlled by its configuration file,
.Pa /etc/named.conf .
Refer to the BIND9 Administrator Reference Manual for further details.
.Pp
The options to
.Nm named
are as follows:
.Bl -tag -width Ds
.It Fl c
use
.Ar config-file
as the configuration file instead of the default,
.Pa /etc/named.conf .
.It Fl d
set the daemon's debug level to
.Ar debuglevel .
Debugging traces from
.Nm named
become more verbose as the debug level increases.
.It Fl f
run
.Nm named
in the foreground.
.It Fl g
run
.Nm named
in the foreground and force all logging to
.Dv stderr .
.It Fl n
create
.Ar #cpus
worker threads to take advantage of multiple CPUs.
If no option is given,
.Nm named
will try to determine the number of CPUs present and create
one thread per CPU. If
.Nm named
is unable to determine the number of CPUs, a single worker thread
is created.
.It Fl p
listen for queries on port
.Ar port#
instead of the default port number, 53.
.It Fl s
write memory usage statistics to
.Dv stdout
on exit.
This option is mainly of interest
to BIND9 developers and may be removed or changed in a future release.
.It Fl t
tells
.Nm named
to chroot() to
.Ar directory
immediately after reading its config file.
.It Fl u
run
.Nm named
as UID
.Ar user-id .
.Nm named
will change its UID after it has
carried out any privileged operations, such as
creating sockets that listen on privileged ports.
.It Fl x
load data from
.Ar cache-file .
into the cache of the default view.
This option must not be used.
It is only of interest
to BIND9 developers and may be removed or changed in a future release.
.El
.Sh SIGNALS
In routine operation, signals should not be used to \*qcontrol\*q the
name server.
.Nm rndc
should be used instead.
Sending the name server a
.Dv SIGHUP
signal forces a reload of the server.
A
.Dv SIGINT
or
.Dv SIGTERM
signal can be used to gracefully shut down the server.
Sending any other signals to the name server
will have an undefined outcome.
.\".Sh CONFIGURATION FILE FORMAT
.\".Nm named 's
.\"configuration file is too complex to describe in detail here.
.\"A complete description is provided in the BIND9 Administrator
.\"Reference Manual.
.Sh FILES
.Bl -tag -width /var/run/named.pid -compact
.It Pa /etc/named.conf
default configuration file
.It Pa /var/run/named.pid
default process-id file
.El
.Sh SEE ALSO
.Xr RFC1033 ,
.Xr RFC1034 ,
.Xr RFC1035 ,
.Xr named.conf 5 ,
.Xr zonefile 5 ,
.Xr rndc 8 ,
.Xr lwresd 8 ,
BIND9 Administrator Reference Manual, June 2000.
doc/man/bin/rndc.8 0 → 100644
View file @ 5704b77b
.\" Copyright (C) @YEARS@ 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.8,v 1.6 2000/07/12 16:48:19 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt RDNC 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm rdnc
.Nd name server control utility
.Sh SYNOPSIS
.Nm rndc
.Op Fl c Ar config-file
.Op Fl M
.Op Fl m
.Op Fl p Ar port#
.Op Fl s Ar server
.Op Fl v
.Op Fl y Ar key_id
.Ar command ....
.Sh DESCRIPTION
This command allows the system administrator to control the operation
of a name server.
It supersedes the
.Xr ndc 8
utility that was provided in old BIND releases.
If
.Nm rndc
is invoked with no command line options or arguments, it
prints a short summary of the supported commands and the available
options and their arguments.
.Pp
.Nm rndc
communicates with the name server over a TCP connection,
sending commands authenticated with digital signatures.
In the current versions of
.Nm rndc
and
.Xr named 8
the only supported encryption algorithm is HMAC-MD5, which uses a
shared secret on each end of the connection.
This provides TSIG-style authentication for the command request
and the name server's response.
All commands sent over the channel
must be signed by a key_id known to the server.
.Pp
.Nm rndc
reads its default configuration file,
.Pa /etc/rndc.conf
to determine how to contact the name server and decide what algorithm
and keys is should use.
The
.Fl c
option can be used to specify an alternate configuration file.
.Pp
.Ar server
is the name or address of the server which matches a
.Dv server{}
statement in the configuration file for
.Nm rndc .
If no
.Ar server
is supplied on the command line, the host named by the
.Dv default-server
clause in the
.Dv options{}
statement of the configuration file will be used.
.Pp
The
.Fl p
option can be used to make
.Nm rndc
send commands to TCP port number
.Ar port#
on the system running the name server instead of BIND 9's
default control channel port of 953.
.Pp
The
.Fl y
option identifies the
.Ar key_id
to use from the configuration file.
.Ar key_id
must be known by
.Xr named
with the same algorithm and secret string in order for
control message validation to succeed.
If no
.Fl y
option is provided,
.Nm rndc
will first look for a
.Dv key
clause in the
.Dv server{}
statement of the server being used, or if no
.Dv server{}
statement is present for that host, then the
.Dv default-key
clause of the
.Dv options{}
statement.
Note that the configuration file for
.Nm rdnc
contains shared secrets which are used to send authenticated
control commands to name servers.
It should therefore not have general read or write access.
.Pp
The
.Fl M ,
.Fl m ,
and
.Fl v
options provided debugging information and are primarily of interest
only to the BIND 9 developers.
They might be changed or removed in future releases.
.Pp
The only valid value for
.Ar command
is \*qreload\*q, which forces the name server to reload its configuation
file and zones.
Further commands will be provided in future releases as the management
capabilities of
.Nm rndc
are extended.
.Sh LIMITATIONS
.Nm rndc
currently only supports the
.Dv reload
command.
Future releases will provide more commands so that
.Nm rndc
offers at least as many management capabilities as the old
.Xr ndc
utility.
.Pp
There is currently no way to provide the shared secret for a key_id
without using the configuration file.
.Pp
Several error messages could be clearer.
For example, trying to connect
from an address that is not in the list of acceptable addresses
configured into
.Xr named
will result in the error message "end of file" when the server
unceremoniously closes the connection.
.Sh SEE ALSO
.Xr rndc.conf 5 ,
.Xr named 8 ,
.Xr named.conf 5 ,
.Xr RFC2845 ,
.Xr ndc 8 .
doc/man/bin/rndc.conf.5 0 → 100644
View file @ 5704b77b
.\" Copyright (C) @YEARS@ 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.4 2000/07/12 17:37:57 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 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 named.conf 8 ,
.Xr dnssec-keygen 8 ,
.Xr mmencode 1 ,
"BIND9 Administrators Manual".
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment