upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-04-29 09:59:08 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

binary man pages have been moved to the source directories of

Browse source 
their respective binaries, and resolver.5 has been moved to ../lwres
(note that resolver.5 is still not included in releases)
This commit is contained in:
Andreas Gustafsson 2001-01-18 01:04:10 +00:00
parent 9fc2037ffe
commit d4134b2fc3
10 changed files with 0 additions and 2068 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

462
doc/man/bin/dig.1
View file

@ -1,462 +0,0 @@
.\" 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 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: dig.1,v 1.7 2001/01/09 21:47:10 bwelling Exp $
.Dd Jun 30, 2000
.Dt DIG 1
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm dig
.Nd DNS lookup utility
.Sh SYNOPSIS
.Nm dig
.Op @server
.Op Fl b Ar address
.Op Fl c Ar class
.Op Fl f Ar filename
.Op Fl k Ar filename
.Op Fl p Ar port#
.Op Fl t Ar type
.Op Fl x Ar addr
.Op Fl y Ar name:key
.Op name
.Op type
.Op class
.Op queryopt ...
.Nm dig
.Fl h
.Nm dig
.Op global-queryopt ...
.Op query1
.Op query2 ...
.Sh DESCRIPTION
.Pp
.Nm dig
(domain information groper) is a flexible tool for interrogating DNS
name servers.
It performs DNS lookups and displays the answers that are returned from
the name server(s) that were queried.
Most DNS administrators use
.Nm dig
to troubleshoot DNS problems because of its flexibility, ease of use and
clarity of output.
Other lookup tools tend to have less functionality than
.Nm dig .
.Pp
Although
.Nm dig
is normally used with command-line arguments, it also has a batch
mode of operation for reading lookup requests from a file.
A brief summary of its command-line arguments and options is printed
when the
.Fl h
option is given.
Unlike earlier versions, the BIND9 implementation of
.Nm dig
allows multiple lookups to be issued from the command line.
.Pp
Unless it is told to query a specific name server,
.Nm dig
will try each of the servers listed in
.Pa /etc/resolv.conf .
.Pp
When no command line arguments or options are given,
will perform an NS query for "." (the root).
.Sh SIMPLE USAGE
.Pp
A typical invocation of
.Nm dig
looks like:
.Bd -ragged | -offset indent
.Ic dig Ar @server name type
.Ed
.Pp
where:
.Bl -tag -width server
.It Ar server
is the name or IP address of the name server to query.
An IPv4 address can be provided in dotted-decimal notation.
When the supplied
.Ar server
argument is a hostname,
.Nm dig
resolves that name before querying that name server.
If no
.Ar server
argument is provided,
.Nm dig
consults
.Pa /etc/resolv.conf
and queries the name servers listed there.
The reply from the name server that responds is displayed.
.It Ar name
is the name of the resource record that is to be looked up.
.It Ar type
indicates what type of query is required - ANY, A, MX, SIG, etc.
.Ar type
can be any valid query type.
If no
.Ar type
argument is supplied,
.Nm dig
will perform a lookup for an A record.
.El
.Pp
.Sh OPTIONS
The
.Fl b
option sets the source IP address of the query to
.Ar address .
This must be a valid
address on one of the host's network interfaces.
.Pp
The default query class (IN for internet) is overridden by the
.Fl c
option.
.Ar class
is any valid class, such as HS for Hesiod records or CH for
CHAOSNET records.
.Pp
The
.Fl f
option makes
.Nm dig
operate in batch mode by reading a list of lookup requests to process
from the file
.Ar filename .
The file contains a number of queries, one per line.
Each entry in the file should be organised in the same way they would be
presented as queries to
.Nm dig
using the command-line interface.
.Pp
If a non-standard port number is to be queried, the
.Fl p
option is used.
.Ar port#
is the port number that
.Nm dig
will send its queries instead of the standard DNS port number 53.
This option would be used to test a name server that has been configured
to listen for queries on a non-standard port number.
.Pp
The
.Fl t
option sets the query type to
.Ar type .
It can be any valid query type which is supported in BIND9.
The default query type "A", unless the
.Fl x
option is supplied to indicate a reverse lookup.
A zone transfer can be requested by specifying a type of AXFR.
When an incremental zone transfer (IXFR) is required,
.Ar type
is set to
.Dv ixfr=N .
The incremental zone transfer will contain the changes made to the zone
since the serial number in the zone's SOA record was
.Ar N .
.Pp
Reverse lookups - mapping addresses to names - are simplified
by the
.Fl x
option.
.Ar addr
is an IPv4 address in dotted-decimal notation, or a colon-delimited
IPv6 address.
When this option is used, there is no need to provide the
.Ar name ,
.Ar class
and
.Ar type
arguments.
.Nm dig
automatically performs a lookup for a name like
.Dv 11.12.13.10.in-addr.arpa
and sets the query type and class to PTR and IN respectively.
By default, IPv6 addresses are looked up using the
IP6.ARPA domain and binary labels as defined in RFC2874.
To use the older RFC1886 method using the IP6.INT domain and "nibble" labels,
specify the
.Fl n
(nibble) option.
.Pp
To sign the DNS queries sent by
.Nm dig
and their responses using transaction signatures (TSIG),
specify a TSIG key file using the
.Fl k
option. You can also specify the TSIG key itself on the command
line using the
.Fl y
option;
.Ar name
is the name of the TSIG key and
.Ar key
is the actual key. The key is a base-64 encoded string,
typically generated by
.Xr dnssec-keygen 8 .
Caution should be taken when using the
.Fl y
option on multi-user systems as the key can be visible
in the output from
.Xr ps 1
or in the shell's history file.
When using TSIG authentication with
.Nm dig ,
the name server that is queried needs to know the key and algorithm
that is being used.
In BIND, this is done by providing appropriate
.Dv key
and
.Dv server
statements in
.Pa named.conf .
.Sh QUERY OPTIONS
.Nm dig
provides a number of query options which affect the way in which
lookups are made and the results displayed.
Some of these set or reset flag bits in the query header,
some determine which sections of the answer get printed,
and others determine the timeout and retry strategies.
.Pp
Each query option is identified by a keyword preceded by a
plus sign: \*q+\*q.
Some keywords set or reset an option.
These may be preceded by the string \*qno\*q to negate the meaning of
that keyword.
Other keywords assign values to options like the timeout interval.
They have the form
.Dv +keyword=value .
The query options are:
.Bl -tag -width +[no]additional
.It +[no]tcp
Use [do not use] TCP when querying name servers.
The default behaviour is to use UDP unless an AXFR or IXFR query is
requested, in which case a TCP connection is used.
.It +[no]vc
Use [do not use] TCP when querying name servers.
This alternate syntax to
.Ar +[no]tcp
is provided for backwards compatibility.
The "vc" stands for "virtual circuit".
.It +[no]ignore
Ignore truncation in UDP responses instead of
retrying with TCP. By default, TCP retries are
performed.
.It +domain=somename
Set the default domain to
.Ar somename ,
as if specified in a
.Dv domain
directive in
.Pa /etc/resolv.conf .
.It +[no]search
Use [do not use] the search list in
.Pa resolv.conf
(if any).
The search list is not used by default.
.It +[no]defname
Use [do not use] the default domain name, if any, in
.Pa resolv.conf
The default is not to append that name to
.Ar name
when making queries.
.It +[no]aaonly
This option does nothing.
It is provided for compatibilty with old versions of
.Nm dig
where it set an unimplemented resolver flag.
.It +[no]adflag
Set [do not set] the AD (authentic data) bit in the query.
The AD bit currently has a standard meaning only in responses,
not in queries, but the ability to set the bit in the query
is provided for completeness.
.It +[no]cdflag
Set [do not set] the CD (checking disabled) bit in the query.
This requests the server to not perform DNSSEC validation
of responses.
.It +[no]recursive
Toggle the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means
.Nm dig .
normally sends recursive queries.
Recursion is automatically disabled when the
.Ar +nssearch
or
.Ar +trace
query options are used.
.It +[no]nssearch
When this option is set,
.Nm dig
attempts to find the authoritative name servers for the zone containing
the name being looked up and
display the SOA record that each name server has for the zone.
.It +[no]trace
Toggle tracing of the delegation path from the root name servers for
the name being looked up.
Tracing is disabled by default.
When tracing is enabled,
.Nm dig
makes iterative queries to resolve the name being looked up.
It will follow referrals from the root servers, showing
the answer from each server that was used to resolve the lookup.
.It +[no]cmd
toggles the printing of the initial comment in the output identifying
the version of
.Nm dig
and the query options that have been applied.
This comment is printed by default.
.It +[no]short
Provide a terse answer.
The default is to print the answer in a verbose form.
.It +[no]identify
Show [or do not show] the IP address and port number that supplied the
answer when the
.Ar +short
option is enabled.
If short form answers are requested, the default is not to show
the source address and port number of the server that provided the
answer.
.It +[no]comments
Toggle the display of comment lines in the output.
The default is to print comments.
.It +[no]stats
This query option toggles the printing of statistics: when the query was
made, the size of the reply and so on.
The default behaviour is to print the query statistics.
.It +[no]qr
Print [do not print] the query as it is sent.
before sending the query. By default, the query is not printed.
.It +[no]question
Print [do not print] the question section of a query when an answer is
returned.
The default is to print the question section as a comment.
.It +[no]answer
Display [do not display] the answer section of a reply.
The default is to display it.
.It +[no]authority
Display [do not display] the authority section of a reply.
The default is to display it.
.It +[no]additional
Display [do not display] the additional section of a reply.
The default is to display it.
.It +[no]all
Set or clear all display flags
.It +time=T
Sets the timeout for a query to
.Dv T
seconds.
The default time out is 5 seconds.
An attempt to set
.Dv T
to less than 1 will result in a query timeout of 1 second being applied.
.It +tries=A
Sets the number of times to retry UDP queries to server to
.Dv T
instead of the default, 3.
If
.Dv T
is less than or equal to zero, the number of retries is silently rounded
up to 1.
.It +ndots=D
Set the number of dots that have to appear in
.Ar name
to
.Dv D
for it to be considered absolute. The default value is that
defined using the ndots statement in
.Pa /etc/resolv.conf ,
or 1 if no ndots statement is present. Names with fewer
dots are interpreted as relative names and will be searched
for in the domains listed in the
.Dv search
or
.Dv domain
directive in
.Pa /etc/resolv.conf .
.It +bufsize=B
Set the UDP message buffer size advertised using EDNS0 to
.Dv B
bytes.
The maximum and minimum sizes of this buffer are 65535 and 0
respectively.
Values outside this range are rounded up or down appropriately.
.El
.Sh MULTIPLE QUERIES
.Pp
The BIND 9
implementation of
.Nm dig
supports specifying multiple queries on the command line
(in addition to supporting the
.Fl f
batch file option).
Each of those queries can be supplied with its own set of flags,
options and query options.
.Pp
In this case,
.Ar query1 ,
.Ar query2
and so on represent an individual query in the command-line syntax described
above.
Each consists of any of the standard options and flags, the name to be looked
up, an optional query type and class and any query options that should
be applied to that query.
.Pp
A global set of query options, which should be applied to all queries, can
also be supplied.
These global query options must precede the first tuple of name, class, type,
options, flags, and query options supplied on the command line.
Any global query options can be overridden by a
query-specific set of query options.
For example:
.Bd -literal
dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr
.Ed
.Pp
shows how
.Nm dig
could be used from the command line to make three lookups: an ANY query
for
.Dv www.isc.org ,
a reverse lookup of 127.0.0.1
and
a query for the NS records of
.Dv isc.org .
A global query option of
.Ar +qr
is applied, so that
.Nm dig
shows the initial query it made for each lookup.
The final query has a local query option of
.Ar +noqr
which means that
.Nm dig
will not print the initial query when it looks up the
NS records for
.Dv isc.org .
.Sh FILES
.Pa /etc/resolv.conf
.Sh SEE ALSO
.Xr host 1 ,
.Xr resolver 5 ,
.Xr named 8 ,
.Xr dnssec-keygen 8 ,
.Xr RFC1035 .
.Sh BUGS
There are probably too many query options.

214
doc/man/bin/host.1
View file

@ -1,214 +0,0 @@
.\" 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 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: host.1,v 1.7 2001/01/09 21:47:11 bwelling Exp $
.Dd Jun 30, 2000
.Dt HOST 1
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm host
.Nd DNS lookup utility
.Sh SYNOPSIS
.Nm host
.Op Fl aCdlnrTwv
.Op Fl c Ar class
.Op Fl N Ar ndots
.Op Fl R Ar number
.Op Fl t Ar type
.Op Fl W Ar wait
.Ar name
.Op Ar server
.Sh DESCRIPTION
.Nm host
is a simple utility for performing DNS lookups.
It is normally used to convert names to IP addresses and vice versa.
When no arguments or options are given,
.Nm host
prints a short summary of its command line arguments and options.
.Pp
.Ar name
is the domain name that is to be looked up.
It can also be a dotted-decimal IPv4 address
or a colon-delimited IPv6 address,
in which case
.Nm host
will by default perform a reverse lookup for that address.
.Ar server
is an optional argument which is either the name or IP address of the
name server that
.Nm host
should query instead of the server or servers listed in
.Pa /etc/resolv.conf .
.Pp
The
.Fl a
(all) option is equivalent to setting the
.Fl v
option and asking
.Nm host
to make a query of type ANY.
.Pp
When the
.Fl C
option is used,
.Nm host
will attempt to display the SOA records for zone
.Ar name
from all the listed authoritative name servers for that zone.
The list of name servers is defined by the NS records that are found for
the zone.
.Pp
The
.Fl c
option instructs to make a DNS query of class
.Ar class .
This can be used to lookup Hesiod or Chaosnet class resource records.
The default class is IN: Internet.
.Pp
Verbose output is generated by
.Nm host
when the
.Fl d
or
.Fl v
option is used.
The two options are equivalent.
They have been provided for backwards compatibility.
In previous versions, the
.Fl d
option switched on debugging traces and
.Fl v
enabled verbose output.
.Pp
List mode is selected by the
.Fl l
option.
This makes
.Nm host
perform a zone transfer for zone
.Ar name .
The argument is provided for compatibility with older implemementations.
This option is equivalent to making a query of type AXFR.
.Pp
The
.Fl n
option specifies that reverse lookups of IPv6 addresses should
use the IP6.INT domain and "nibble" labels as defined in RFC1886.
The default is to use IP6.ARPA and binary labels as defined in RFC2874.
.Pp
The
.Fl N
option sets the number of dots that have to be in
.Ar name
for it to be considered absolute. The default value is that
defined using the ndots statement in
.Pa /etc/resolv.conf ,
or 1 if no ndots statement is present. Names with fewer
dots are interpreted as relative names and will be searched
for in the domains listed in the
.Dv search
or
.Dv domain
directive in
.Pa /etc/resolv.conf .
.Pp
The number of UDP retries for a lookup can be changed with the
.Fl R
option.
.Ar number
indicates how many times
.Nm host
will repeat a query that does not get answered.
The default number of retries is 1.
If
.Ar number
is negative or zero, the number of retries will default to 1.
.Pp
Non-recursive queries can be made via the
.Fl r
option.
Setting this option clears the
.Dv RD
- recursion desired - bit in the query which
.Nm host
makes.
This should mean that the name server receiving the query will not attempt
to resolve
.Ar name .
The
.Fl r
option enables
.Nm host
to mimic the behaviour of a name server by making non-recursive queries
and expecting to receive answers to those queries that are usually
referrals to other name servers.
.Pp
By default
.Nm host
uses UDP when making queries.
The
.Fl T
option makes it use a TCP connection when querying the name server.
TCP will be automatically selected for queries that require it,
such as zone transfer (AXFR) requests.
.Pp
The
.Fl t
option is used to select the query type.
.Ar type
can be any recognised query type: CNAME, NS, SOA, SIG, KEY, AXFR, etc.
When no query type is specified,
.Nm host
automatically selects an appropriate query type.
By default it looks for A records, but if the
.Fl C
option was given, queries will be made for SOA records,
and if
.Ar name
is a dotted-decimal IPv4 address or colon-delimited IPv6 address,
.Nm host
will query for PTR records.
.Pp
The time to wait for a reply can be controlled through the
.Fl W
and
.Fl w
options.
The
.Fl W
option makes
.Nm host
wait for
.Ar wait
seconds.
If
.Ar wait
is less than one,
the wait interval is set to one second.
When the
.Fl w
option is used,
.Nm host
will effectively wait forever for a reply.
The time to wait for a response will be set to the number of seconds
given by the hardware's maximum value for an integer quantity.
.Sh FILES
.Pa /etc/resolv.conf
.Sh SEE ALSO
.Xr dig 1 ,
.Xr resolver 5
.Xr named 8 .

168
doc/man/bin/lwresd.8
View file

@ -1,168 +0,0 @@
.\" 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 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: lwresd.8,v 1.10 2001/01/09 21:47:12 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRESD 8
.Os BIND9 9
.ds vT BIND 9 Programmer's Manual
.Sh NAME
.Nm lwresd
.Nd lightweight resolver daemon
.Sh SYNOPSIS
.Nm lwresd
.Op Fl C Ar config-file
.Op Fl d Ar debuglevel
.Op Fl f g s
.Op Fl i Ar pid-file
.Op Fl n Ar #cpus
.Op Fl P Ar listen-port#
.Op Fl p Ar port#
.Op Fl t Ar directory
.Op Fl u Ar user-id
.Op Fl v
.Sh DESCRIPTION
.Nm lwresd
is the daemon providing name lookup services to clients that use
the BIND 9 lightweight resolver library.
It is essentially a stripped-down, caching-only name server that
answers queries using the BIND 9 lightweight resolver protocol
rather than the DNS protocol.
.Pp
.Nm lwresd
listens for resolver queries on a UDP port on the IPv4 loopback
interface, 127.0.0.1.
This means that
.Nm lwresd
can only be used by processes running on the local machine.
By default UDP port number 921 is used for lightweight resolver
requests and responses.
.Pp
Incoming lightweight resolver requests are decoded by
.Nm lwresd
which then resolves them using the DNS protocol.
When the DNS lookup completes,
.Nm lwresd
encodes the answers from the name servers in the lightweight
resolver format and returns them to the client that made the original
request.
.Pp
If
.Pa /etc/resolv.conf
contains any
.Sy nameserver
entries,
.Nm lwresd
sends recursive DNS queries to those servers. This
is similar to the use of forwarders in a chaching name
server. If no
.Sy nameserver
entries are present, or if forwarding fails,
.Nm lwresd
resolves the queries autonomously starting at the
root name servers, using a compiled-in list of root
servers hints.
.Pp
The options to
.Nm lwresd
are as follows:
.Bl -tag -width Ds
.It Fl C
use
.Ar config-file
as the configuration file instead of the default,
.Pa /etc/resolv.conf .
.It Fl d
set the daemon's debug level to
.Ar debuglevel .
Debugging traces from
.Nm lwresd
become more verbose as the debug level increases.
.It Fl f
run
.Nm lwresd
in the foreground.
.It Fl g
run
.Nm lwresd
in the foreground and force all logging to
.Dv stderr .
.It Fl i
write the daemon's process id to
.Ar pid-file
instead of the default pathname.
.It Fl n
create
.Ar #cpus
worker threads to take advantage of multiple CPUs.
If no option is given,
.Nm lwresd
will try to determine the number of CPUs present and create
one thread per CPU. If
.Nm lwresd
is unable to determine the number of CPUs, a single worker thread
is created.
.It Fl P
listen for lightweight resolver queries on the loopback interface
using UDP port
.Ar port#
instead of the default port number, 921.
.It Fl p
send DNS lookups to port number
.Ar listen-port#
when querying name servers.
This provides a way of testing the lightweight resolver daemon with a
name server that listens for queries on a non-standard port number.
.It Fl s
write memory usage statistics to
.Dv stdout
on exit.
This option is only of interest to BIND 9 developers and may be
removed or changed in a future release.
.It Fl t
tells
.Nm lwresd
to chroot() to
.Ar directory
immediately after reading its configuration file.
.It Fl u
run
.Nm lwresd
as
.Ar user-id ,
which is a user name or numeric id that must be present in the
password file.
The lightweight resolver daemon will change its user-id after it has
carried out any privileged operations, such as writing the process-id
file or binding a socket to a privileged port (typically any port
less than 1024).
.It Fl v
report the version number and exit.
.El
.Sh FILES
.Bl -tag -width /var/run/lwresd.pid -compact
.It Pa /etc/resolv.conf
default configuration file
.It Pa /var/run/lwresd.pid
default process-id file
.El
.Sh SEE ALSO
.Xr named 8 ,
.Xr lwres 3 .
.Sh NOTES
.Nm lwresd
is a daemon for lightweight resolvers, not a lightweight daemon
for resolvers.

48
doc/man/bin/named-checkconf.1
View file

@ -1,48 +0,0 @@
.\" 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 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-checkconf.1,v 1.3 2001/01/09 21:47:14 bwelling Exp $
.Dd Jun 14, 2000
.Dt NAMED-CHECKCONF 1
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm named-checkconf
.Nd Configuration file syntax checking tool.
.Sh SYNOPSIS
.Nm named-checkconf
.Op filename
.Sh DESCRIPTION
.Pp
.Nm named-checkconf
is a tool to check the syntax, but not sematics, of the configuration file
for named.
.Pp
The options to
.Nm named-checkconf
are as follows:
.Bl -tag -width Ds
.It Ar filename
the name of the configuration file to be checked.
If not specified it defaults /etc/named.conf.
.Sh RETURN VALUES
.Pp
.Nm named-checkconf
return a an exit status of 1 if errors were detected,
0 otherwise.
.Sh SEE ALSO
.Xr named 8 ,
.Xr RFC1035 .

61
doc/man/bin/named-checkzone.1
View file

@ -1,61 +0,0 @@
.\" 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 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-checkzone.1,v 1.3 2001/01/09 21:47:15 bwelling Exp $
.Dd Jun 13, 2000
.Dt NAMED-CHECKZONE 1
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm named-checkzone
.Nd Zone validity checking tool.
.Sh SYNOPSIS
.Nm named-checkzone
.Op Fl dq
.Op Fl c Ar class
.Ar zone
.Op filename
.Sh DESCRIPTION
.Pp
.Nm named-checkzone
is a tool for performing integrity checks on a zones contents.
It uses the same integrity checks as
.Nm named .
.Pp
The options to
.Nm named-checkzone
are as follows:
.Bl -tag -width Ds
.It Fl d
enable debugging.
.It Fl q
quiet mode - exit code only.
.It Fl c Ar class
specify the class of the zone.
If not specified "IN" is assumed.
.It Ar zone
the name of the zone being loaded.
.It Op filename
the name of the file containing the zone.
If not specified it defaults to the zone name.
.Sh RETURN VALUES
.Pp
.Nm named-checkzone
return a an exit status of 1 if errors were detected,
0 otherwise.
.Sh SEE ALSO
.Xr named 8 ,
.Xr RFC1035 .

172
doc/man/bin/named.8
View file

@ -1,172 +0,0 @@
.\" 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 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.12 2001/01/09 21:47:16 bwelling 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
.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 v
.Op Fl x Ar cache-file
.Sh DESCRIPTION
.Nm named
is a Domain Name System (DNS) server, part of the BIND 9 distribution
from ISC. For more information on the DNS, see RFCs 1033, 1034, and 1035.
.Pp
When invoked without arguments,
.Nm named
will read the default configuration file
.Pa /etc/named.conf ,
read any initial data, and listen for queries.
.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 .
To ensure that reloading the configuration file continues to
work after the server has changed its working directory
due to to a possible
.Dv directory
option in the configuration file,
.Ar config-file
should be an absolute pathname.
.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.
This should be used in conjunction with the
.Fl u
option, as chrooting a process running as root doesn't
enhance security on most systems - the way chroot() is defined
allows a process with root privileges to escape the chroot jail.
.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.
.Pp
On Linux,
.Nm named
uses the kernel's capability mechanism to drop
all root privileges except the ability to bind() to a privileged
port. Unfortunately, this means that the "-u" option only works
when
.Nm named
is run on 2.3.99-pre3 or later kernel, since previous
kernels did not allow privileges to be retained after setuid().
.It Fl v
report the version number and exit.
.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 rndc 8 ,
.Xr lwresd 8 ,
BIND9 Administrator Reference Manual, June 2000.

355
doc/man/bin/nsupdate.8
View file

@ -1,355 +0,0 @@
.\" 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 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: nsupdate.8,v 1.12 2001/01/09 21:47:17 bwelling Exp $
.Dd Jun 30, 2000
.Dt NSUPDATE 8
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm nsupdate
.Nd Dynamic DNS update utility
.Sh SYNOPSIS
.Nm nsupdate
.Op Fl d
.Oo
.Fl y Ar keyname:secret |
.Fl k Ar keyfile
.Oc
.Op Fl v
.Op filename
.Sh DESCRIPTION
.Nm nsupdate
is used to submit Dynamic DNS Update requests as defined in RFC2136
to a name server.
This allows resource records to be added or removed from a zone
without manually editing the zone file.
A single update request can contain requests to add or remove more than one
resource record.
.Pp
Zones that are under dynamic control via
.Nm nsupdate
or a DHCP server should not be edited by hand.
Manual edits could
conflict with dynamic updates and cause data to be lost.
.Pp
The resource records that are dynamically added or removed with
.Nm nsupdate
have to be in the same zone.
Requests are sent to the zone's master server.
This is identified by the MNAME field of the zone's SOA record.
.Pp
The
.Fl d
option makes
.Nm nsupdate
operate in debug mode.
This provides tracing information about the update requests that are
made and the replies received from the name server.
.Pp
Transaction signatures can be used to authenticate the Dynamic DNS
updates.
These use the TSIG resource record type described in RFC2845.
The signatures rely on a shared secret that should only be known to
.Nm nsupdate
and the name server.
Currently, the only supported encryption algorithm for TSIG is
HMAC-MD5, which is defined in RFC 2104.
Once other algorithms are defined for TSIG, applications will need to
ensure they select the appropriate algorithm as well as the key when
authenticating each other.
For instance suitable
.Dv key
and
.Dv server
statements would be added to
.Pa /etc/named.conf
so that the name server can associate the appropriate secret key
and algorithm with the IP address of the
client application that will be using TSIG authentication.
.Nm nsupdate
does not read
.Pa /etc/named.conf .
.Pp
.Nm nsupdate
uses the
.Fl y
or
.Fl k
option to provide the shared secret needed to generate a TSIG record
for authenticating Dynamic DNS update requests.
These options are mutually exclusive.
With the
.Fl k
option,
.Nm nsupdate
reads the shared secret from the file
.Ar keyfile ,
whose name is of the form
.Pa K{name}.+157.+{random}.private .
For historical
reasons, the file
.Pa K{name}.+157.+{random}.key
must also be present. When the
.Fl y
option is used, a signature is generated from
.Ar keyname:secret.
.Ar keyname
is the name of the key,
and
.Ar secret
is the base64 encoded shared secret.
Use of the
.Fl y
option is discouraged because the shared secret is supplied as a command
line argument in clear text.
This may be visible in the output from
.Xr ps 1
or in a history file maintained by the user's shell.
.Pp
By default
.Nm nsupdate
uses UDP to send update requests to the name server.
The
.Fl v
option makes
.Nm nsupdate
use a TCP connection.
This may be preferable when a batch of update requests is made.
.Sh INPUT FORMAT
.Nm nsupdate
reads input from
.Ar filename
or standard input.
Each command is supplied on exactly one line of input.
Some commands are for administrative purposes.
The others are either update instructions or prerequisite checks on the
contents of the zone.
These checks set conditions that some name or set of
resource records (RRset) either exists or is absent from the zone.
These conditions must be met if the entire update request is to succeed.
Updates will be rejected if the tests for the prerequisite conditions fail.
.Pp
Every update request consists of zero or more prerequisites
and zero or more updates.
This allows a suitably authenticated update request to proceed if some
specified resource records are present or missing from the zone.
A blank input line causes the accumulated commands to be sent as one Dynamic
DNS update request to the name server.
.Pp
The command formats and their meaning are as follows:
.Bl -ohang indent
.It Xo
.Ic server Va servername Op port
.Xc
.sp 1
Sends all dynamic update requests to the name server
.Va servername .
When no server statement is provided,
.Nm nsupdate
will send updates to the master server of the correct zone.
The MNAME field of that zone's SOA record will identify the master
server for that zone.
.Va port
is the port number on
.Va servername
where the dynamic update requests get sent.
If no port number is specified, the default DNS port number of 53 is
used.
.It Xo
.Ic local Va address Op port
.Xc
.sp 1
Sends all dynamic update requests using the local
.Va address .
When no local statement is provided,
.Nm nsupdate
will send updates using an address and port choosen by the system.
.Va port
can additionally be used to make requests come from a specific port.
If no port number is specified, the system will assign one.
.It Xo
.Ic zone Va zonename
.Xc
.sp 1
Specifies that all updates are to be made to the zone
.Va zonename .
If no
.Va zone
statement is provided,
.Nm nsupdate
will attempt determine the correct zone to update based on the rest of the input.
.It Xo
.Ic prereq nxdomain Va domain-name
.Xc
.sp 1
Requires that no resource record of any type exists with name
.Va domain-name .
.It Xo
.Ic prereq yxdomain Va domain-name
.Xc
.sp 1
Requires that
.Va domain-name
exists (has as at least one resource record, of any type).
.It Xo
.Ic prereq nxrrset Va domain-name Op class
.Va type
.Xc
.sp 1
Requires that no resource record exists of the specified
.Va type ,
.Va class
and
.Va domain-name .
If
.Va class
is omitted, IN (internet) is assumed.
.It Xo
.Ic prereq yxrrset
.Va domain-name Op class
.Va type
.Xc
.sp 1
This requires that a resource record of the specified
.Va type ,
.Va class
and
.Va domain-name
must exist.
If
.Va class
is omitted, IN (internet) is assumed.
.It Xo
.Ic prereq yxrrset
.Va domain-name Op class
.Va type data...
.Xc
.sp 1
The
.Va data
from each set of prerequisites of this form
sharing a common
.Va type ,
.Va class ,
and
.Va domain-name
are combined to form a set of RRs. This set of RRs must
exactly match the set of RRs existing in the zone at the
given
.Va type ,
.Va class ,
and
.Va domain-name .
The
.Va data
are written in the standard text representation of the resource record's
RDATA.
.It Xo
.Ic update delete
.Va domain-name Op class
.Va Op type Op data...
.Xc
.sp 1
Deletes any resource records named
.Va domain-name .
If
.Va type
and
.Va data
is provided, only matching resource records will be removed.
The internet class is assumed if
.Va class
is not supplied.
.It Xo
.Ic update add
.Va domain-name ttl Op class
.Va type data..
.Xc
.sp 1
Adds a new resource record with the specified
.Va ttl ,
.Va class
and
.Va data .
.El
.Sh EXAMPLES
The examples below show how
.Nm nsupdate
could be used to insert and delete resource records from the
.Dv example.com
zone.
Notice that the input in each example contains a trailing blank line so that
a group of commands are sent as one dynamic update request to the
master name server for
.Dv example.com .
.Bd -literal -offset indent
# nsupdate
> update delete oldhost.example.com A
> update add newhost.example.com 86400 A 172.16.1.1
>
.Ed
.Pp
Any A records for
.Dv oldhost.example.com
are deleted.
and an A record for
.Dv newhost.example.com
it IP address 172.16.1.1 is added.
The newly-added record has a 1 day TTL (86400 seconds)
.Bd -literal -offset indent
# nsupdate
> prereq nxdomain nickname.example.com
> update add nickname.example.com CNAME somehost.example.com
>
.Ed
.Pp
The prerequisite condition gets the name server to check that there
are no resource records of any type for
.Dv nickname.example.com .
If there are, the update request fails.
If this name does not exist, a CNAME for it is added.
This ensures that when the CNAME is added, it cannot conflict with the
long-standing rule in RFC1034 that a name must not exist as any other
record type if it exists as a CNAME.
(The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
SIG, KEY and NXT records.)
.Pp
.Sh FILES
.Bl -tag -width K{name}.+157.+{random}.private -compact
.It Pa /etc/resolv.conf
used to identify default name server
.It Pa K{name}.+157.+{random}.key
base-64 encoding of HMAC-MD5 key created by
.Xr dnssec-keygen 8 .
.It Pa K{name}.+157.+{random}.private
base-64 encoding of HMAC-MD5 key created by
.Xr dnssec-keygen 8 .
.El
.Sh SEE ALSO
.Xr RFC2136 ,
.Xr RFC2137 ,
.Xr RFC2104 ,
.Xr RFC2845 ,
.Xr RFC1034 ,
.Xr RFC2535 ,
.Xr named 8 ,
.Xr dnssec-keygen 8 .
.Sh BUGS
The TSIG key is redundantly stored in two separate files.
This is a consequence of nsupdate using the DST library
for its cryptographic operations, and may change in future
releases.

215
doc/man/bin/resolver.5
View file

@ -1,215 +0,0 @@
.\" 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 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: resolver.5,v 1.3 2001/01/09 21:47:18 bwelling Exp $
.Dd Jun 30, 2000
.Dt RESOLVER 5
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm resolver
.Nd resolver configuration file
.Sh SYNOPSIS
.Pa /etc/resolv.conf
.Sh DESCRIPTION
The
.Nm resolver
and
.Nm "BIND9 lightwreight resolver"
are sets of routines in the C library and BIND9 library respectively
that provide access to the Internet Domain Name System.
The resolver configuration file,
.Pa /etc/resolv.conf ,
is normally gets read
by the resolver and lightweight resolver
routines to initialise low-level resolver data structures the first time
that a process invokes those routines.
The file contains a list of
keywords with values that provide various types of
information, such as the IP addresses of the servers that should be
used when making lookup requests.
.Pp
Each keyword and value must appear on a single line.
The value follows the keyword, separated by white space.
The hash character '#' or semi-colon ';' introduce comments.
Anything from either of these characters to the end of the line
is treated as a comment and ignored.
.\" XXXJR - Don't think the next para is relevant. Not every host will run
.\" a name server or lightweight resolver. Those that don't will need
.\" a resolv.conf so they can send their lookups somewhere sensible.
.\".Pp
.\"On a normally configured system, this file should not be necessary.
.\"The only name server to be queried will be on the local machine,
.\"the domain name is determined from the host name,
.\"and the domain search path is constructed from the domain name.
.Pp
The available configuration directives are:
.Bl -tag -width "nameserver"
.It Li nameserver
Internet address of a name server that the resolver should query.
The IP address of the server can be supplied in the usual notation:
either in dotted-decimal form for an IPv4 addess or in double colon
form described in RFC1884 for an IPv6 address.
Up to three nameserver directives can be listed.
See
.Dv LWRES_CONFMAXNAMESERVERS
in
.Pa <lwres/lwres.h> .
If more than
.Dv LWRES_CONFMAXNAMESERVERS
nameserver directives are present in the file,
only the first three are used.
Any others are ignored.
.Pp
When there are multiple servers, the resolver
library queries them in the order listed.
If no
.Li nameserver
entries are present, the default is to attempt to use the name server or
lightweight resolver daemon on the local machine.
The algorithm used is to try a server, and if the query times out,
try the next, until out of name servers,
then repeat trying all the name servers
until a maximum number of retries are made.
.It Li domain
Local domain name.
Most queries for names within this domain can use short names
relative to the local domain.
When no
.Li domain
entry is present, the domain is determined from the local host name returned by
.Xr gethostname 2 ;
the domain part is taken to be everything after the first
.Sq \&. .
Finally, if the host name does not contain a domain part, the root
domain is assumed.
.It Li search
Search list for host-name lookup.
The search list is normally determined from the local domain name;
by default, it contains only the local domain name.
This may be changed by listing the desired domain search path
following the
.Li search
keyword with spaces or tabs separating the names.
Most resolver
queries will be attempted using each component
of the search path in turn until a match is found.
Note that this process may be slow and will generate a lot of network
traffic if the servers for the listed domains are not local,
and that queries will time out if no server is available
for one of the domains.
.Pp
The search list is currently limited to eight domains
with a total of 256 characters.
See
.Dv LWRES_CONFMAXSEARCH
and
.Dv LWRES_CONFMAXLINELEN
in
.Pa lwres/lwres.h .
.It Li sortlist
Allows addresses returned by gethostbyname to be sorted.
A
.Li sortlist
is specified by IP address netmask pairs.
The netmask is optional and defaults to the natural netmask of the net.
The IP address and optional network pairs are separated by slashes.
Up to 10 pairs may be specified.
For example:
.Bd -literal -offset indent
sortlist 130.155.160.0/255.255.240.0 130.155.0.0
.Ed
.It Li options
Allows certain internal
.Nm resolver
variables to be modified.
The syntax is
.D1 Li options Ar option ...
where
.Ar option
is one of the following:
.Bl -tag -width "no_tld_query"
.It Li ndots: Ns Ar n
sets a threshold for the number of dots which
must appear in a name given to
.Fn res_query
(see
.Xr resolver 3 )
before an
.Em initial absolute query
will be made.
The default for
.Ar n
is
.Dq 1 ,
meaning that if there are
.Em any
dots in a name, the name will be tried first as an absolute name before any
.Em search list
elements are appended to it.
Acceptable values of
.Ar n
are between 0 and 255 inclusive.
.It debug
enables debugging traces for the resolver
XXXJR if anything actually looked at
.Dv confdata->resdebug .
At present the option is just recognised but not used by
the BIND9 implementation.
.It no_tld_query
tells the resolver not to attempt to resolve a
top level domain name, i.e. a name containing no dots.
Use of this option does not prevent the resolver from obeying the
standard
.Ar domain
and
.Ar search
rules with the given name.
XXXJR At present this option is recognised but is otherwise unused
in BIND9.
.It missing
XXXJR what about the other BIND8 resolver options like rotate and
timeout? Shouldn't these be provided for backwards compatibility?
.El
.El
.Pp
The
.Li domain
and
.Li search
keywords are mutually exclusive.
If more than one instance of these keywords is present,
the last instance wins.
.Sh FILES
.Pa /etc/resolv.conf
.Pa <lwres/lwres.h>
.Sh SEE ALSO
.Xr gethostbyname 3 ,
.Xr lwres_config 3 ,
.Xr lwres 3 ,
.Xr resolver 3 ,
.Xr hostname 7 ,
.Xr lwresd 8 ,
.Xr named 8 ,
"BIND9 Administrators Manual".
.Sh BUGS
Unrecognised directives and syntax errors in
.Pa /etc/resolv.conf
are usually silently ignored, though
.Er LWRES_R_FAILURE
can be returned by the lightweight resolver functions described in
.Xr lwres_config 3
which parse this file.

158
doc/man/bin/rndc.8
View file

@ -1,158 +0,0 @@
.\" 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 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.12 2001/01/09 21:47:19 bwelling 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 option
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
For the complete set of commands supported by rndc, see the
BIND 9 Administrator Reference Manual or run
.Nm rndc
without arguments to see its help message.
.Pp
.Sh LIMITATIONS
.Nm rndc
does not yet support all the commands of the BIND 8
.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 .

215
doc/man/bin/rndc.conf.5
View file

@ -1,215 +0,0 @@
.\" 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 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.10 2001/01/09 21:47:20 bwelling 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".