From 52cf506b39ec774bba7e719390541e881296c3c4 Mon Sep 17 00:00:00 2001 From: nectar Date: Mon, 13 May 2002 19:33:58 +0000 Subject: Import of ISC BIND 8.3.2-T1B documentation. --- contrib/bind/doc/man/dig.1 | 29 +- contrib/bind/doc/man/dnskeygen.1 | 30 +- contrib/bind/doc/man/dnsquery.1 | 28 +- contrib/bind/doc/man/getaddrinfo.3 | 11 +- contrib/bind/doc/man/gethostbyname.3 | 22 +- contrib/bind/doc/man/getipnodebyname.3 | 14 +- contrib/bind/doc/man/getnameinfo.3 | 4 +- contrib/bind/doc/man/getnetent.3 | 11 +- contrib/bind/doc/man/host.1 | 14 +- contrib/bind/doc/man/hostname.7 | 9 +- contrib/bind/doc/man/inet_cidr.3 | 10 +- contrib/bind/doc/man/mailaddr.7 | 2 +- contrib/bind/doc/man/mkdep.1 | 6 +- contrib/bind/doc/man/named-bootconf.8 | 1 - contrib/bind/doc/man/named-xfer.8 | 6 +- contrib/bind/doc/man/named.8 | 29 +- contrib/bind/doc/man/named.conf.5 | 530 +++++++++------------------------ contrib/bind/doc/man/ndc.8 | 4 +- contrib/bind/doc/man/nslookup.8 | 99 +++--- contrib/bind/doc/man/nsupdate.8 | 36 +-- contrib/bind/doc/man/resolver.3 | 59 +++- contrib/bind/doc/man/resolver.5 | 22 +- contrib/bind/doc/man/tsig.3 | 4 +- 23 files changed, 381 insertions(+), 599 deletions(-) (limited to 'contrib/bind/doc/man') diff --git a/contrib/bind/doc/man/dig.1 b/contrib/bind/doc/man/dig.1 index 47284c2..ae4c3f2 100644 --- a/contrib/bind/doc/man/dig.1 +++ b/contrib/bind/doc/man/dig.1 @@ -1,4 +1,4 @@ -.\" $Id: dig.1,v 8.4 1999/10/15 21:29:58 vixie Exp $ +.\" $Id: dig.1,v 8.8 2001/09/24 15:21:29 marka Exp $ .\" .\" ++Copyright++ 1993 .\" - @@ -100,7 +100,7 @@ Internet address. If this optional field is omitted, .Ic dig will attempt to use the default name server for your machine. .sp 1 -.Em Note: +.Em Note : If a domain name is specified, this will be resolved using the domain name system resolver (i.e., BIND). If your system does not support DNS, you may @@ -116,7 +116,7 @@ itself can be resolved. See .Xr resolver @FORMAT_EXT@ for information on .Pa /etc/resolv.conf . -.Sy WARNING: +.Sy WARNING : Changing .Pa /etc/resolv.conf will affect both the standard resolver library and @@ -190,7 +190,7 @@ all/any class information .Pp (See RFC 1035 for the complete list.) .Pp -.Em Note: +.Em Note : .Dq Ar Any can be used to specify a .Em class @@ -323,7 +323,7 @@ environment is saved. If not, the file .Dq Pa DiG.env is created in the current working directory. .Pp -.Em Note: +.Em Note : .Ev LOCALDEF is specific to the .Ic dig @@ -521,6 +521,13 @@ print TTLs .Bq Cm tt .It Xo .Op Cm no +.Ns Cm trunc\ \ \ \ +.Pq Cm tr +.Xc +truncate origin from names +.Bq Cm tr +.It Xo +.Op Cm no .Ns Cm cl .Xc print class info @@ -566,6 +573,13 @@ print authoritative section .Xc print additional section .Bq Cm ad +.It Xo +.Op Cm no +.Ns Cm dnssec\ \ \ +.Pq Cm \ddn +.Xc +set the DNSSEC OK bit in the OPT pseudo record +.Bq Cm nodn .It Cm pfdef set to default print flags .It Cm pfmin @@ -641,7 +655,7 @@ and options, above. .Sh FILES .Bl -tag -width "/etc/resolv.conf " -compact -.It Pa /etc/resolv.conf +.It Pa /etc/resolv.conf initial domain name and name server addresses .It Pa \./DiG.env default save file for default options @@ -672,7 +686,8 @@ rather ad hoc genesis. .Ic Dig does not consistently exit nicely (with appropriate status) when a problem occurs somewhere in the resolver -.Po Sy NOTE: +.Po +.Sy NOTE : most of the common exit cases are handled .Pc . This is particularly annoying when running in diff --git a/contrib/bind/doc/man/dnskeygen.1 b/contrib/bind/doc/man/dnskeygen.1 index 4b3c406..7080f95 100644 --- a/contrib/bind/doc/man/dnskeygen.1 +++ b/contrib/bind/doc/man/dnskeygen.1 @@ -13,26 +13,26 @@ .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS .\" SOFTWARE. .\" -.\" $Id: dnskeygen.1,v 8.5 1999/02/23 05:20:18 vixie Exp $ +.\" $Id: dnskeygen.1,v 8.8 2002/04/22 04:27:19 marka Exp $ .\" .Dd December 2, 1998 .Dt DNSKEYGEN @CMD_EXT_U@ .Os BSD 4 .Sh NAME .Nm dnskeygen -.Nd generate public, private, and shared secret keys for DNS Security +.Nd "generate public, private, and shared secret keys for DNS Security" .Sh SYNOPSIS .Nm dnskeygen -.Oo Fl -.Op Cm DHR +.Oo +.Fl Op Cm DHR .Ar size .Oc .Op Fl F -.Fl Op Cm zhu -.Op Cm Fl a -.Op Cm Fl c -.Op Cm Fl p Ar num -.Op Cm Fl s Ar num +.Op Fl Cm zhu +.Op Fl Cm a +.Op Fl Cm c +.Op Fl Cm p Ar num +.Op Fl Cm s Ar num .Fl n Ar name .Sh DESCRIPTION .Ic Dnskeygen @@ -61,7 +61,7 @@ key. .Dq size must be between 512 and 4096. .It Fl F -.Ic (RSA only) +.Ic ( RSA only ) Use a large exponent for key generation. .It Fl z Fl h Fl u These flags define the type of key being generated: Zone (DNS validation) key, @@ -77,8 +77,8 @@ Indicates that the key be used for encryption. .It Fl p Ar num Sets the key's protocol field to -.Ar num -; the default is +.Ar num ; +the default is .Ic 3 (DNSSEC) if .Dq Fl z @@ -95,12 +95,12 @@ is specified and (ANY). .It Fl s Ar num Sets the key's strength field to -.Ar num; +.Ar num ; the default is -.Sy 0. +.Sy 0 . .It Fl n Ar name Sets the key's name to -.Ar name. +.Ar name . .El .Ss DETAILS .Ic Dnskeygen diff --git a/contrib/bind/doc/man/dnsquery.1 b/contrib/bind/doc/man/dnsquery.1 index 2662ab4..bc0307f 100644 --- a/contrib/bind/doc/man/dnsquery.1 +++ b/contrib/bind/doc/man/dnsquery.1 @@ -1,4 +1,4 @@ -.\" $Id: dnsquery.1,v 8.3 1999/01/08 18:54:21 vixie Exp $ +.\" $Id: dnsquery.1,v 8.4 2001/08/08 07:49:58 marka Exp $ .\" .\"Copyright (c) 1995,1996,1999 by Internet Software Consortium .\" @@ -63,25 +63,25 @@ address nameserver .It Ar CNAME canonical name -.It Ar PTR +.It Ar PTR domain name pointer -.It Ar SOA +.It Ar SOA start of authority -.It Ar WKS +.It Ar WKS well-known service .It Ar HINFO host information .It Ar MINFO mailbox information -.It Ar MX +.It Ar MX mail exchange -.It Ar RP +.It Ar RP responsible person -.It Ar MG +.It Ar MG mail group member -.It Ar AFSDB +.It Ar AFSDB DCE or AFS server -.It Ar ANY +.It Ar ANY wildcard .El .Pp @@ -91,13 +91,13 @@ Note that any case may be used. (Default: The class of resource records of interest. Classes include: .Bl -tag -width "CHAOS " -compact -offset indent -.It Ar IN +.It Ar IN Internet -.It Ar HS +.It Ar HS Hesiod .It Ar CHAOS Chaos -.It Ar ANY +.It Ar ANY wildcard .El .Pp @@ -135,9 +135,9 @@ The name of the host (or domain) of interest. .Bl -tag -width " " -compact .It Pa /etc/resolv.conf to get the default ns and search lists -.It Pa +.It Pa list of usable RR types and classes -.It Pa +.It Pa list of resolver flags .El .Sh DIAGNOSTICS diff --git a/contrib/bind/doc/man/getaddrinfo.3 b/contrib/bind/doc/man/getaddrinfo.3 index a906c5d..a18d3d0 100644 --- a/contrib/bind/doc/man/getaddrinfo.3 +++ b/contrib/bind/doc/man/getaddrinfo.3 @@ -30,7 +30,7 @@ .\" SUCH DAMAGE. .\" .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 -.\" $Id: getaddrinfo.3,v 8.1 1999/01/11 21:30:51 vixie Exp $ +.\" $Id: getaddrinfo.3,v 8.3 2001/12/28 04:24:15 marka Exp $ .\" .Dd May 25, 1995 .Dt GETADDRINFO @LIB_NETWORK_EXT@ @@ -97,9 +97,7 @@ A .Pf non Dv -NULL .Fa nodename string can be either a node name or a numeric host address string -.Po -i.e., a dotted-decimal IPv4 address or an IPv6 hex address -.Pc . +(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). A .Pf non Dv -NULL .Fa servname @@ -218,7 +216,8 @@ call to .Pq for a connection-oriented protocol or either .Fn connect , -.Fn sendto , or +.Fn sendto , +or .Fn sendmsg .Pq for a connectionless protocol . In this case, if the @@ -356,6 +355,6 @@ The .Fn getaddrinfo function is defined IEEE POSIX 1003.1g draft specification, and documented in ``Basic Socket Interface Extensions for IPv6'' -.Pq RFC2133 . +(RFC2133). .Sh BUGS The text was shamelessly copied from RFC2133. diff --git a/contrib/bind/doc/man/gethostbyname.3 b/contrib/bind/doc/man/gethostbyname.3 index 0498bd8..e23d51e 100644 --- a/contrib/bind/doc/man/gethostbyname.3 +++ b/contrib/bind/doc/man/gethostbyname.3 @@ -31,19 +31,19 @@ .Sh SYNOPSIS .Fd #include .Ft extern int -.Fa h_errno; +.Fa h_errno ; .Pp .Ft struct hostent * -.Fn gethostbyname "char *name"; +.Fn gethostbyname "char *name" .Ft struct hostent * -.Fn gethostbyname2 "char *name" "int af"; +.Fn gethostbyname2 "char *name" "int af" .Ft struct hostent * -.Fn gethostbyaddr "char *addr" "int len, type"; +.Fn gethostbyaddr "char *addr" "int len, type" .Ft struct hostent * .Fn gethostent -.Fn sethostent "int stayopen"; +.Fn sethostent "int stayopen" .Fn endhostent -.Fn herror "char *string"; +.Fn herror "char *string" .Sh DESCRIPTION .Fn Gethostbyname , .Fn gethostbyname2 , @@ -140,21 +140,17 @@ Otherwise, queries are performed using UDP datagrams. .Fn Endhostent closes the TCP connection. .Sh ENVIRONMENT -.Bl -tag -width "HOSTALIASES " -compress +.Bl -tag -width "HOSTALIASES " -compact .It Ev HOSTALIASES Name of file containing .Pq Ar host alias , full hostname pairs. .El .Sh FILES -.Bl -tag -width "HOSTALIASES " -compress +.Bl -tag -width "HOSTALIASES " -compact .It Pa /etc/hosts See .Xr hosts @FORMAT_EXT@ . -.It Ev HOSTALIASES -Name of file containing -.Pq Ar host alias , full hostname -pairs. .El .Sh DIAGNOSTICS .Pp @@ -222,7 +218,7 @@ when is built to use only the routines to lookup in .Pa /etc/hosts and not the name server: -.Bd -filled -offset indent +.Bd -ragged -offset indent .Pp .Fn Gethostent reads the next line of diff --git a/contrib/bind/doc/man/getipnodebyname.3 b/contrib/bind/doc/man/getipnodebyname.3 index 3396c3a..95ca428 100644 --- a/contrib/bind/doc/man/getipnodebyname.3 +++ b/contrib/bind/doc/man/getipnodebyname.3 @@ -43,11 +43,11 @@ .Fd #include .Pp .Ft struct hostent * -.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error"; +.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error" .Ft struct hostent * -.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error"; +.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error" .Ft void -.Fn freehostent "struct hostent *he"; +.Fn freehostent "struct hostent *he" .Sh DESCRIPTION .Fn Getipnodebyname , and @@ -166,21 +166,17 @@ should not be passed to .Fn freehostent as they are pointers to static areas. .Sh ENVIRONMENT -.Bl -tag -width "HOSTALIASES " -compress +.Bl -tag -width "HOSTALIASES " -compact .It Ev HOSTALIASES Name of file containing .Pq Ar host alias , full hostname pairs. .El .Sh FILES -.Bl -tag -width "HOSTALIASES " -compress +.Bl -tag -width "HOSTALIASES " -compact .It Pa /etc/hosts See .Xr hosts @FORMAT_EXT@ . -.It Ev HOSTALIASES -Name of file containing -.Pq Ar host alias , full hostname -pairs. .El .Sh DIAGNOSTICS .Pp diff --git a/contrib/bind/doc/man/getnameinfo.3 b/contrib/bind/doc/man/getnameinfo.3 index 02548c0..e80dc36 100644 --- a/contrib/bind/doc/man/getnameinfo.3 +++ b/contrib/bind/doc/man/getnameinfo.3 @@ -1,4 +1,4 @@ -.\" $Id: getnameinfo.3,v 8.1 1999/01/11 21:30:51 vixie Exp $ +.\" $Id: getnameinfo.3,v 8.2 2001/12/28 04:24:16 marka Exp $ .\" .\"Copyright (c) 1998,1999 by Internet Software Consortium .\" @@ -100,4 +100,4 @@ The .Fn getaddrinfo function is defined IEEE POSIX 1003.1g draft specification, and documented in ``Basic Socket Interface Extensions for IPv6'' -.Pq RFC2133 . +(RFC2133). diff --git a/contrib/bind/doc/man/getnetent.3 b/contrib/bind/doc/man/getnetent.3 index 4f600e0..0475256 100644 --- a/contrib/bind/doc/man/getnetent.3 +++ b/contrib/bind/doc/man/getnetent.3 @@ -1,4 +1,4 @@ -.\" $Id: getnetent.3,v 8.4 1999/01/08 18:54:23 vixie Exp $ +.\" $Id: getnetent.3,v 8.6 2001/12/28 04:24:17 marka Exp $ .\" .\"Copyright (c) 1995,1996,1999 by Internet Software Consortium .\" @@ -30,11 +30,11 @@ .Ft struct netent * .Fn getnetent .Ft struct netent * -.Fn getnetbyname "char name"; +.Fn getnetbyname "char name" .Ft struct netent * -.Fn getnetbyaddr "unsigned long net" "int type"; +.Fn getnetbyaddr "unsigned long net" "int type" .Ft void -.Fn setnetent "int stayopen"; +.Fn setnetent "int stayopen" .Ft void .Fn endnetent .Sh DESCRIPTION @@ -145,7 +145,8 @@ The .Fn "setnetent" , and .Fn "endnetent" -functions appeared in 4.2BSD. +functions appeared in +.Bx 4.2 . .Sh BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls to these functions diff --git a/contrib/bind/doc/man/host.1 b/contrib/bind/doc/man/host.1 index 12219e7..90b5e84 100644 --- a/contrib/bind/doc/man/host.1 +++ b/contrib/bind/doc/man/host.1 @@ -50,7 +50,7 @@ .\" SOFTWARE. .\" - .\" --Copyright-- -.\" $Id: host.1,v 8.4 2000/02/29 03:50:47 vixie Exp $ +.\" $Id: host.1,v 8.6 2001/08/10 00:14:47 cyarnell Exp $ .Dd December 15, 1994 .Dt HOST @CMD_EXT_U@ .Os BSD 4 @@ -72,7 +72,7 @@ .Ic Host looks for information about Internet hosts. It gets this information from a set of interconnected servers that are spread across the -country. By default, it simply converts between host names and +world. By default, it simply converts between host names and Internet addresses. However, with the .Dq Fl t or @@ -251,7 +251,7 @@ will give a complete download of the zone data for rutgers.edu, in the official master file format. (However the SOA record is listed twice, for arcane reasons.) .Pp -.Sy NOTE: +.Sy NOTE : .Dq Fl l is implemented by doing a complete zone transfer and then filtering out the information @@ -275,21 +275,17 @@ host name. The name file must be contained in the .Ev HOSTALIASES environment variable. .Sh ENVIRONMENT -.Bl -tag -width "/etc/resolv.conf " -compress +.Bl -tag -width "/etc/resolv.conf " -compact .It Ev HOSTALIASES Name of file containing .Pq Ar host alias , full hostname pairs. .El .Sh FILES -.Bl -tag -width "/etc/resolv.conf " -compress +.Bl -tag -width "/etc/resolv.conf " -compact .It Pa /etc/resolv.conf See .Xr resolver @FORMAT_EXT@ . -.It Ev HOSTALIASES -Name of file containing -.Pq Ar host alias , full hostname -pairs. .El .Sh SEE ALSO .Xr @INDOT@named @SYS_OPS_EXT@ , diff --git a/contrib/bind/doc/man/hostname.7 b/contrib/bind/doc/man/hostname.7 index 6a92d64..1c5a256 100644 --- a/contrib/bind/doc/man/hostname.7 +++ b/contrib/bind/doc/man/hostname.7 @@ -147,7 +147,7 @@ If the name was not previously tried threshold or did not contain a dot), then the name as originally provided is attempted. .Sh ENVIRONMENT -.Bl -tag -width "/etc/resolv.conf " -compress +.Bl -tag -width "/etc/resolv.conf " .It Ev LOCALDOMAIN Affects domains appended to partial hostnames. .It Ev HOSTALIASES @@ -156,14 +156,11 @@ Name of file containing pairs. .El .Sh FILES -.Bl -tag -width "/etc/resolv.conf " -compress +.Bl -tag -width "/etc/resolv.conf " -compact .It Pa /etc/resolv.conf See .Xr resolve @FORMAT_EXT@ . -.It Ev HOSTALIASES -Name of file containing -.Pq Ar host alias , full hostname -pairs. +.El .Sh SEE ALSO .Xr gethostbyname @LIB_NETWORK_EXT@ , .Xr resolver @FORMAT_EXT@ , diff --git a/contrib/bind/doc/man/inet_cidr.3 b/contrib/bind/doc/man/inet_cidr.3 index 9aeb102..0bed686 100644 --- a/contrib/bind/doc/man/inet_cidr.3 +++ b/contrib/bind/doc/man/inet_cidr.3 @@ -1,4 +1,4 @@ -.\" $Id: inet_cidr.3,v 8.2 1999/01/08 18:54:24 vixie Exp $ +.\" $Id: inet_cidr.3,v 8.3 2001/08/08 07:50:06 marka Exp $ .\" .\"Copyright (c) 1998,1999 by Internet Software Consortium .\" @@ -44,13 +44,13 @@ converts an address from network to presentation format. .Pp .Ft af describes the type of address that is being passed in -.Ft src. +.Ft src . .\"Currently defined types are AF_INET and AF_INET6. Currently only AF_INET is supported. .Pp .Ft src is an address in network byte order, its length is determined from -.Ft af. +.Ft af . .Pp .Ft bits specifies the number of bits in the netmask unless it is -1 in which case @@ -71,13 +71,13 @@ Check errno for reason. converts and address from presentation format, with optional CIDR reperesentation, to network format. The resulting address is zero filled if there were insufficint bits in -.Ft src. +.Ft src . .Pp .Ft af describes the type of address that is being passed in via .Ft src and determines the size of -.Ft dst. +.Ft dst . .Pp .Ft src is an address in presentation format. diff --git a/contrib/bind/doc/man/mailaddr.7 b/contrib/bind/doc/man/mailaddr.7 index 270fe9c..f194321 100644 --- a/contrib/bind/doc/man/mailaddr.7 +++ b/contrib/bind/doc/man/mailaddr.7 @@ -122,7 +122,7 @@ Under some circumstances it may be necessary to route a message through several hosts to get it to the final destination. Normally this routing is done automatically, but sometimes it is desirable to route the message manually. Addresses which show these relays are termed -.Dq route-addrs. +.Dq route-addrs . These use the syntax: .Bd -ragged -offset indent-two .Li <@hosta,@hostb:user@hostc> diff --git a/contrib/bind/doc/man/mkdep.1 b/contrib/bind/doc/man/mkdep.1 index 177ab1a..bf46eaf 100644 --- a/contrib/bind/doc/man/mkdep.1 +++ b/contrib/bind/doc/man/mkdep.1 @@ -26,7 +26,7 @@ .Op Fl ap .Op Fl f Ar depend_file .Op Ar flags -.Ar file ... +.Ar .Sh DESCRIPTION .Ic Mkdep takes a set of flags for the C compiler and a list @@ -73,9 +73,7 @@ C module. The .Dq Fl a option causes appending to the output file, so that multiple -.Xo Ic mkdep -.Ns 's -.Xc +.Ic mkdep Ns 's may be run from a single .Pa Makefile . .Sh SEE ALSO diff --git a/contrib/bind/doc/man/named-bootconf.8 b/contrib/bind/doc/man/named-bootconf.8 index 2a0d39d..2798637 100644 --- a/contrib/bind/doc/man/named-bootconf.8 +++ b/contrib/bind/doc/man/named-bootconf.8 @@ -48,7 +48,6 @@ .\" 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. - .Dd November 19, 1998 .Dt NAMED-BOOTCONF 8 .Os NetBSD diff --git a/contrib/bind/doc/man/named-xfer.8 b/contrib/bind/doc/man/named-xfer.8 index e7b2cf3..7d73b0f 100644 --- a/contrib/bind/doc/man/named-xfer.8 +++ b/contrib/bind/doc/man/named-xfer.8 @@ -89,9 +89,7 @@ .Op Fl p Ar port# .Op Fl S .Ar nameserver -.Op Ar [ Sy axfr -| -.Op Sy ixfr ] +.Op Sy axfr | ixfr .Sh DESCRIPTION .Ic Named-xfer is an ancillary program executed by @@ -161,7 +159,7 @@ for more information. Additional arguments are taken as name server addresses in so-called .Dq dotted-quad syntax -.Em only; +.Em only ; no host name are allowed here. At least one address must be specified. Any additional addresses will be tried, in order, if the first one fails to transfer to us successfully. diff --git a/contrib/bind/doc/man/named.8 b/contrib/bind/doc/man/named.8 index b978993..882cea1 100644 --- a/contrib/bind/doc/man/named.8 +++ b/contrib/bind/doc/man/named.8 @@ -92,7 +92,7 @@ or .Dq Fl c flags. .Pp -.Sy NOTE: +.Sy NOTE : Several of .Nm named Ns 's options, and much more of its behaviour, can be controlled in the configuration @@ -111,7 +111,7 @@ is a number determines the level of messages printed. If negative, is set to .Dq 1 . .Pp -.Sy NOTE: +.Sy NOTE : The new debugging framework is considerably more sophisticated than it was in older versions of .Nm @INDOT@named . @@ -131,7 +131,7 @@ the port number returned by for service .Dq Li domain . .Pp -.Sy NOTE: +.Sy NOTE : Previously, the syntax .Dq Fl p Ar port# Ns Op Ar \&/localport# was supported; the first port was that used when contacting @@ -169,7 +169,7 @@ has been compiled with .Li QRYLOG defined. .Pp -.Sy NOTE: +.Sy NOTE : This option is deprecated in favor of the .Dq Li queries .Em logging category @@ -183,7 +183,7 @@ Turns recursion off in the server. Answers can come only from local (primary or secondary) zones. This can be used on root servers. The default is to use recursion. .Pp -.Sy NOTE: +.Sy NOTE : This option can be overridden by and is deprecated in favor of the .Dq Li recursion clause of the configuration file's @@ -242,7 +242,7 @@ where: .Bl -tag -width "opt_domain " .It Ar domain is -.Dq Li \&. +.Dq Li .\& for root, .Dq Li @ for the current origin, or a standard domain name. If @@ -252,7 +252,7 @@ is a standard domain name that does end with .Dq Li \&. , the current origin is appended to the domain. Domain names ending with -.Dq Li \&. +.Dq Li .\& are unmodified. .It Ar opt_domain This field is used to define an origin for the data in an included file. @@ -270,7 +270,7 @@ an explicit ttl. .It Ar opt_ttl An optional integer number for the time-to-live field. If not set the ttl is taken from the last $TTL statement. -If no $TTL statement has occured then the SOA minimum value is used and a +If no $TTL statement has occurred then the SOA minimum value is used and a warning is generated. .It Ar opt_class The object address type; currently only one type is supported, @@ -310,7 +310,7 @@ Resource records normally end at the end of a line, but may be continued across lines between opening and closing parentheses. Comments are introduced by semicolons and continue to the end of the line. .Pp -.Sy NOTE: +.Sy NOTE : There are other resource record types not shown here. You should consult the .Sy BIND @@ -400,19 +400,21 @@ Saves any modified dynamic zones to the file system, and shuts down the server. Turns on debugging; each .Dv SIGUSR1 increments debug level. -.Po Dv SIGEMT +.Po +.Dv SIGEMT on older systems without .Dv SIGUSR1 . .Pc .It Dv SIGUSR2 Turns off debugging completely. -.Po Dv SIGFPE +.Po +.Dv SIGFPE on older systems without .Dv SIGUSR2 . .Pc .It Dv SIGWINCH Toggles logging of all incoming queries via -.Xr syslog @SYS_OPS_EXT@ +.Xr syslog @LIB_C_EXT@ (requires server to have been built with the .Li QRYLOG option). @@ -431,12 +433,13 @@ debug output nameserver statistics data .El .Sh SEE ALSO +.Xr named.conf @FORMAT_EXT@ , .Xr gethostbyname @LIB_NETWORK_EXT@ , .Xr hostname @DESC_EXT@ , .Xr kill @CMD_EXT@ , .Xr resolver @LIB_NETWORK_EXT@ , .Xr resolver @FORMAT_EXT@ , -.Xr signal @SYSCALL_EXT@ , +.Xr signal @LIB_C_EXT@ , RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123, RFC 2308 .Dq Name Server Operations Guide for Sy BIND diff --git a/contrib/bind/doc/man/named.conf.5 b/contrib/bind/doc/man/named.conf.5 index e2f4a0f..df07b1a 100644 --- a/contrib/bind/doc/man/named.conf.5 +++ b/contrib/bind/doc/man/named.conf.5 @@ -12,68 +12,52 @@ .\" 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. - .Dd January 7, 1999 .Dt NAMED.CONF 5 .Os BSD 4 - .Sh NAME .Nm named.conf .Nd configuration file for .Xr named 8 - .Sh OVERVIEW - BIND 8 is much more configurable than previous release of BIND. There are entirely new areas of configuration, such as access control lists and categorized logging. Many options that previously applied to all zones can now be used selectively. These features, plus a consideration of future configuration needs led to the creation of a new configuration file format. - .Ss General Syntax - A BIND 8 configuration consists of two general features, statements and comments. All statements end with a semicolon. Many statements can contain substatements, which are each also terminated with a semicolon. - .Pp The following statements are supported: -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic logging specifies what the server logs, and where the log messages are sent - .It Ic options controls global server configuration options and sets defaults for other statements - .It Ic zone defines a zone - .It Ic acl defines a named IP address matching list, for access control and other uses - .It Ic key specifies key information for use in authentication and authorization - .It Ic trusted-keys defines DNSSEC keys that are preconfigured into the server and implicitly trusted - .It Ic server sets certain configuration options for individual remote servers - .It Ic controls declares control channels to be used by the .Nm ndc utility - .It Ic include includes another file - .El - +.Pp The .Ic logging and @@ -81,11 +65,11 @@ and statements may only occur once per configuration, while the rest may appear numerous times. Further detail on each statement is provided in individual sections below. - +.Pp Comments may appear anywhere that whitespace may appear in a BIND configuration file. To appeal to programmers of all kinds, they can be written in C, C++, or shell/perl constructs. - +.Pp C-style comments start with the two characters .Li /* (slash, star) and end with @@ -94,18 +78,17 @@ C-style comments start with the two characters Because they are completely delimited with these characters, they can be used to comment only a portion of a line or to span multiple lines. - +.Pp C-style comments cannot be nested. For example, the following is not valid because the entire comment ends with the first .Li */ : - .Bd -literal -offset indent /* This is the start of a comment. This is still part of the comment. /* This is an incorrect attempt at nesting a comment. */ This is no longer in any comment. */ .Ed - +.Pp C++-style comments start with the two characters .Li // (slash, slash) and continue to the end of the physical line. @@ -113,55 +96,46 @@ They cannot be continued across multiple physical lines; to have one logical comment span multiple lines, each line must use the .Li // pair. For example: - .Bd -literal -offset indent // This is the start of a comment. The next line // is a new comment, even though it is logically // part of the previous comment. .Ed - +.Pp Shell-style (or perl-style, if you prefer) comments start with the character .Li # (hash or pound or number or octothorpe or whatever) and continue to the end of the physical line, like C++ comments. For example: - .Bd -literal -offset indent # This is the start of a comment. The next line # is a new comment, even though it is logically # part of the previous comment. .Ed - -.Em WARNING: +.Pp +.Em WARNING : you cannot use the .Li ; (semicolon) character to start a comment such as you would in a zone file. The semicolon indicates the end of a configuration statement, so whatever follows it will be interpreted as the start of the next statement. - .Ss Converting from BIND 4.9.x - -.Pp BIND 4.9.x configuration files can be converted to the new format by using .Pa src/bin/named/named-bootconf , a shell script that is part of the BIND 8.2.x source kit. - .Sh DOCUMENTATION DEFINITIONS - Described below are elements used throughout the BIND configuration file documentation. Elements which are only associated with one statement are described only in the section describing that statement. - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Va acl_name The name of an .Va address_match_list as defined by the .Ic acl statement. - .It Va address_match_list A list of one or more .Va ip_addr , @@ -172,7 +146,6 @@ or elements, as described in the .Sx ADDRESS MATCH LISTS section. - .It Va dotted-decimal One or more integers valued 0 through 255 separated only by dots (``.''), such as @@ -180,20 +153,16 @@ One or more integers valued 0 through 255 separated only by dots .Li 45.67 or .Li 89.123.45.67 . - .It Va domain_name A quoted string which will be used as a DNS name, for example .Qq Li my.test.domain . - .It Va path_name A quoted string which will be used as a pathname, such as .Qq Li zones/master/my.test.domain . - .It Va ip_addr -An IP address in with exactly four elements in +An IP address with exactly four elements in .Va dotted-decimal notation. - .It Va ip_port An IP port .Va number . @@ -204,7 +173,6 @@ through with values below 1024 typically restricted to root-owned processes. In some cases an asterisk (``*'') character can be used as a placeholder to select a random high-numbered port. - .It Va ip_prefix An IP network specified in .Va dotted-decimal @@ -221,17 +189,14 @@ is network .Li 1.2.3.0 with netmask .Li 255.255.255.240. - .It Va key_name A string representing the name of a shared key, to be used for transaction security. - .It Va number A non-negative integer with an entire range limited by the range of a C language signed integer (2,147,483,647 on a machine with 32 bit integers). Its acceptable value might further be limited by the context in which it is used. - .It Va size_spec A .Va number , @@ -239,7 +204,6 @@ the word .Li unlimited , or the word .Li default . - .Pp The maximum value of .Va size_spec @@ -248,7 +212,6 @@ is that of unsigned long integers on the machine. requests unlimited use, or the maximum available amount. .Li default uses the limit that was in force when the server was started. - .Pp A .Va number @@ -266,14 +229,12 @@ or .Li g for gigabytes, which scale by 1024, 1024*1024, and 1024*1024*1024 respectively. - .Pp Integer storage overflow is currently silently ignored during conversion of scaled values, resulting in values less than intended, possibly even negative. Using .Li unlimited is the best way to safely set a really large number. - .It Va yes_or_no Either .Li yes @@ -286,22 +247,17 @@ and are also accepted, as are the numbers .Li 1 and .Li 0 . - .El - .Sh ADDRESS MATCH LISTS .Ss Syntax - .Bd -literal \fIaddress_match_list\fR = 1\&*\fIaddress_match_element\fR - +.Pp \fIaddress_match_element\fR = [ \&"!\&" ] ( \fIaddress_match_list\fR / \fIip_address\fR / \fIip_prefix\fR / \fIacl_name\fR / \&"key \&" \fIkey_id\fR ) \&";\&" .Ed - .Ss Definition and Usage - Address match lists are primarily used to determine access control for various server operations. They are also used to define priorities for querying other nameservers and to set the addresses on which @@ -309,7 +265,6 @@ for querying other nameservers and to set the addresses on which will listen for queries. The elements which constitute an address match list can be any of the following: - .Bl -bullet .It an @@ -336,7 +291,6 @@ statement, or another .Va address_match_list . .El - .Pp Elements can be negated with a leading exclamation mark (``!''), and the match list names @@ -349,7 +303,6 @@ are predefined. More information on those names can be found in the description of the .Ic acl statement. - .Pp The addition of the .Ic key @@ -357,7 +310,6 @@ clause made the name of this syntactic element something of a misnomer, since security keys can be used to validate access without regard to a host or network address. Nonetheless, the term ``address match list'' is still used throughout the documentation. - .Pp When a given IP address or prefix is compared to an address match list, the list is traversed in order until an element matches. The @@ -366,7 +318,6 @@ for access control, defining .Ic listen-on ports, or as a topology, and whether the element was negated. - .Pp When used as an access control list, a non-negated match allows access and a negated match denies access. If there is no match at all in the @@ -381,7 +332,6 @@ all use address match lists like this. Similarly, the .Ic listen-on option will cause the server to not accept queries on any of the machine's addresses which do not match the list. - .Pp When used with the .Ic topology @@ -391,7 +341,6 @@ shorter the distance is between it and the server). A negated match will be assigned the maximum distance from the server. If there is no match, the address will get a distance which is further than any non-negated list element, and closer than any negated element. - .Pp Because of the first-match aspect of the algorithm, an element that defines a subset of another element in the list should come before the @@ -403,10 +352,8 @@ match any lookup for 1.2.3.13 to the 1.2.3/24 element. Using .Dl !1.2.3.13; 1.2.3/24 fixes that problem by having 1.2.3.13 blocked by the negation but all other 1.2.3.* hosts fall through. - .Sh THE LOGGING STATEMENT .Ss Syntax - .Bd -literal logging { [ channel \fIchannel_name\fR { @@ -418,23 +365,21 @@ logging { local0 | local1 | local2 | local3 | local4 | local5 | local6 | local7 ) | null ); - +.Pp [ severity ( critical | error | warning | notice | info | debug [ \fIlevel\fR ] | dynamic ); ] [ print-category \fIyes_or_no\fR; ] [ print-severity \fIyes_or_no\fR; ] [ print-time \fIyes_or_no\fR; ] }; ] - +.Pp [ category \fIcategory_name\fR { \fIchannel_name\fR; [ \fIchannel_name\fR; ... ] }; ] ... }; .Ed - .Ss Definition and Usage - The .Ic logging statement configures a wide variety of logging options for the nameserver. @@ -444,7 +389,6 @@ phrase associates output methods, format options and severity levels with a name that can then be used with the .Ic category phrase to select how various classes of messages are logged. - .Pp Only one .Ic logging @@ -453,7 +397,6 @@ If there are multiple logging statements in a configuration, the first defined determines the logging, and warnings are issued for the others. If there is no logging statement, the logging configuration will be: - .Bd -literal logging { category default { default_syslog; default_debug; }; @@ -462,7 +405,7 @@ will be: category eventlib { default_debug; }; }; .Ed - +.Pp The logging configuration is established as soon as the .Ic logging statement is parsed. If you want to redirect @@ -473,13 +416,10 @@ redirect configuration file parsing messages, we recommend always putting the .Ic logging statement first so that this rule need not be consciously recalled if -you ever do need want the parser's messages relocated. - +you ever do want the parser's messages relocated. .Ss The channel phrase - All log output goes to one or more ``channels''; you can make as many of them as you want. - .Pp Every channel definition must include a clause that says whether messages selected for the channel go to a file, to a particular syslog @@ -490,21 +430,18 @@ and whether to include a time stamp generated by .Nm named , the category name, or severity level. The default is not to include any of those three. - .Pp The word .Li null as the destination option for the channel will cause all messages sent to it to be discarded; other options for the channel are meaningless. - .Pp The .Ic file clause can include limitations both on how large the file is allowed to become, and how many versions of the file will be saved each time the file is opened. - .Pp The .Ic size @@ -514,7 +451,6 @@ log growth. If the file ever exceeds the size, then will just not write anything more to it until the file is reopened; exceeding the size does not automatically trigger a reopen. The default behavior is to not limit the size of the file. - .Pp If you use the .Ic version @@ -531,7 +467,6 @@ The keyword is synonymous with .Li 99 in current BIND releases. Example usage of size and versions options: - .Bd -literal channel an_example_level { file "lamers.log" versions 3 size 20m; @@ -539,7 +474,6 @@ in current BIND releases. Example usage of size and versions options: print-category yes; }; .Ed - .Pp The argument for the .Ic syslog @@ -551,9 +485,8 @@ will handle messages sent to this facility is described in the .Xr syslog.conf 5 manual page. If you have a system which uses a very old version of syslog that only uses two arguments to the -.Fn openlog() +.Fn openlog function, then this clause is silently ignored. - .Pp The .Ic severity @@ -562,7 +495,6 @@ used if you are writing straight to a file rather than using syslog. Messages which are not at least of the severity level given will not be selected for the channel; messages of higher severity levels will be accepted. - .Pp If you are using syslog, then the .Pa syslog.conf @@ -586,7 +518,6 @@ writing messages of only or higher, then .Nm syslogd would print all messages it received from the channel. - .Pp The server can supply extensive debugging information when it is in debugging mode. If the server's global debug level is greater than @@ -607,21 +538,19 @@ signal (as with All debugging messages in the server have a debug level, and higher debug levels give more more detailed output. Channels that specify a specific debug severity, e.g. - .Bd -literal channel specific_debug_level { file \&"foo\&"; severity debug 3; }; .Ed - +.Pp will get debugging output of level 3 or less any time the server is in debugging mode, regardless of the global debugging level. Channels with .Li dynamic severity use the server's global level to determine what messages to print. - .Pp If .Ic print-time @@ -641,49 +570,43 @@ in any combination, and will always be printed in the following order: time, category, severity. Here is an example where all three .Ic print- options are on: - .Bd -literal 28-Apr-1997 15:05:32.863 default: notice: Ready to answer queries. .Ed - .Pp There are four predefined channels that are used for -.Nm named 's default logging as follows. How they are used used is described in the next section, -.Sx The category phrase. - +.Sx The category phrase . .Bd -literal channel default_syslog { syslog daemon; # send to syslog's daemon facility severity info; # only send priority info and higher }; - +.Pp channel default_debug { file \&"named.run\&"; # write to named.run in the working directory # Note: stderr is used instead of \&"named.run\&" # if the server is started with the -f option. severity dynamic; # log at the server's current debug level }; - +.Pp channel default_stderr { # writes to stderr file \&"\&"; # this is illustrative only; there's currently # no way of specifying an internal file # descriptor in the configuration language. severity info; # only send priority info and higher }; - +.Pp channel null { null; # toss anything sent to this channel }; .Ed - +.Pp Once a channel is defined, it cannot be redefined. Thus you cannot alter the built-in channels directly, but you can modify the default logging by pointing categories at channels you have defined. - .Ss The category phrase - There are many categories, so you can send the logs you want to see wherever you want, without seeing logs you don't want. If you don't specify a list of channels for a category, then log messages in that @@ -692,15 +615,13 @@ category will be sent to the category instead. If you don't specify a default category, the following ``default default'' is used: - .Bd -literal category default { default_syslog; default_debug; }; .Ed - +.Pp As an example, let's say you want to log security events to a file, but you also want keep the default logging behavior. You'd specify the following: - .Bd -literal channel my_security_channel { file \&"my_security_file\&"; @@ -709,109 +630,84 @@ the following: category security { my_security_channel; default_syslog; default_debug; }; .Ed - +.Pp To discard all messages in a category, specify the .Li null channel: - .Bd -literal category lame-servers { null; }; category cname { null; }; .Ed - +.Pp The following categories are available: - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic default The catch-all. Many things still aren't classified into categories, and they all end up here. Also, if you don't specify any channels for a category, the default category is used instead. If you do not define the default category, the following definition is used: .Dl category default { default_syslog; default_debug; }; - .It Ic config High-level configuration file processing. - .It Ic parser Low-level configuration file processing. - .It Ic queries A short log message is generated for every query the server receives. - .It Ic lame-servers Messages like ``Lame server on ...'' - .It Ic statistics Statistics. - .It Ic panic If the server has to shut itself down due to an internal problem, it will log the problem in this category as well as in the problem's native category. If you do not define the panic category, the following definition is used: .Dl category panic { default_syslog; default_stderr; }; - .It Ic update Dynamic updates. - .It Ic ncache Negative caching. - .It Ic xfer-in Zone transfers the server is receiving. - .It Ic xfer-out Zone transfers the server is sending. - .It Ic db All database operations. - .It Ic eventlib Debugging info from the event system. Only one channel may be specified for this category, and it must be a file channel. If you do not define the eventlib category, the following definition is used: .Dl category eventlib { default_debug; }; - .It Ic packet Dumps of packets received and sent. Only one channel may be specified for this category, and it must be a file channel. If you do not define the packet category, the following definition is used: .Dl category packet { default_debug; }; - .It Ic notify The NOTIFY protocol. - .It Ic cname Messages like ``... points to a CNAME''. - .It Ic security Approved/unapproved requests. - .It Ic os Operating system problems. - .It Ic insist Internal consistency check failures. - .It Ic maintenance Periodic maintenance events. - .It Ic load Zone loading messages. - .It Ic response-checks Messages arising from response checking, such as ``Malformed response ...'', ``wrong ans. name ...'', ``unrelated additional info ...'', ``invalid RR type ...'', and ``bad referral ...''. - .El - .Sh THE OPTIONS STATEMENT .Ss Syntax - .Bd -literal options { + [ hostname \fIhostname_string\fR; ] [ version \fIversion_string\fR; ] [ directory \fIpath_name\fR; ] [ named-xfer \fIpath_name\fR; ] @@ -828,7 +724,8 @@ options { [ host-statistics \fIyes_or_no\fR; ] [ host-statistics-max \fInumber\fR; ] [ multiple-cnames \fIyes_or_no\fR; ] - [ notify \fIyes_or_no\fR; ] + [ notify ( \fIyes_or_no\fR | explicit ); ] + [ suppress-initial-notify \fIyes_or_no\fR; ] [ recursion \fIyes_or_no\fR; ] [ rfc2308-type1 \fIyes_or_no\fR; ] [ use-id-pool \fIyes_or_no\fR; ] @@ -836,7 +733,7 @@ options { [ also-notify \fIyes_or_no\fR; ] [ forward ( only | first ); ] [ forwarders { [ \fIin_addr\fR ; [ \fIin_addr\fR ; ... ] ] }; ] - [ check-names ( master | slave | response ) ( warn | fail | ignore); ] + [ check-names ( master | slave | response ) ( warn | fail | ignore ); ] [ allow-query { \fIaddress_match_list\fR }; ] [ allow-recursion { \fIaddress_match_list\fR }; ] [ allow-transfer { \fIaddress_match_list\fR }; ] @@ -865,33 +762,40 @@ options { [ interface-interval \fInumber\fR; ] [ statistics-interval \fInumber\fR; ] [ topology { \fIaddress_match_list\fR }; ] - [ sortlist { \fIaddress_match_list|fR }; ] - [ rrset-order { \fIorder_spec\fR ; [ \fIorder_spec\fR ; ... [ [ }; + [ sortlist { \fIaddress_match_list\fR }; ] + [ rrset-order { \fIorder_spec\fR ; [ \fIorder_spec\fR ; ... ] }; ] + [ preferred-glue ( A | AAAA ); ] }; .Ed - .Ss Definition and Usage - The options statement sets up global options to be used by BIND. This statement may appear at only once in a configuration file; if more than one occurrence is found, the first occurrence determines the actual options used, and a warning will be generated. If there is no options statement, an options block with each option set to its default will be used. - -.Ss Pathnames - -.Bl -tag -width 1 - +.Ss Server Information +.Bl -tag -width 0n +.It Ic hostname +This defaults to the hostname of the machine hosting the nameserver as found by gethostname(). +Its prime purpose is to be able to identify which of a number of anycast +servers is actually answering your queries by sending a txt query for +.Pa hostname.bind +in class chaos to the anycast server and geting back a unique name. +Setting +the hostname to a empty string ("") will disable processing of the queries. .It Ic version The version the server should report via the ndc command or via a query of name .Pa version.bind -in class chaos. The default is the real version number of ths server, +in class chaos. +The default is the real version number of the server, but some server operators prefer the string ( .Ic surely you must be joking ). - +.El +.Ss Pathnames +.Bl -tag -width 0n .It Ic directory The working directory of the server. Any non-absolute pathnames in the configuration file will be taken as relative to this @@ -900,17 +804,15 @@ directory. The default location for most server output files .Pa named.run ) is this directory. If a directory is not specified, the working directory defaults to -.Pa . , +.Pa \&. , the directory from which the server was started. The directory specified should be an absolute path. - .It Ic named-xfer The pathname to the named-xfer program that the server uses for inbound zone transfers. If not specified, the default is system dependent (e.g. .Pa /usr/sbin/named-xfer ). - .It Ic dump-file The pathname of the file the server dumps the database to when it receives @@ -919,7 +821,6 @@ signal (as sent by .Ic ndc dumpdb ). If not specified, the default is .Pa named_dump.db . - .It Ic memstatistics-file The pathname of the file the server writes memory usage statistics to on exit, if @@ -928,7 +829,6 @@ is .Li yes . If not specified, the default is .Pa named.memstats . - .It Ic pid-file The pathname of the file the server writes its process ID in. If not specified, the default is operating system dependent, but is usually @@ -938,7 +838,6 @@ or The pid-file is used by programs like .Nm ndc that want to send signals to the running nameserver. - .It Ic statistics-file The pathname of the file the server appends statistics to when it receives @@ -948,10 +847,8 @@ signal (from If not specified, the default is .Pa named.stats . .El - .Ss Boolean Options - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic auth-nxdomain If .Li yes , @@ -966,7 +863,6 @@ Do not turn off .Ic auth-nxdomain unless you are sure you know what you are doing, as some older software won't like it. - .It Ic deallocate-on-exit If .Li yes , @@ -978,7 +874,6 @@ The default is because it is faster to let the operating system clean up. .Ic deallocate-on-exit is handy for detecting memory leaks. - .It Ic dialup If .Li yes , @@ -1000,7 +895,6 @@ statement, in which case it overrides the .Ic options dialup statement. - .Pp If the zone is a .Ic master @@ -1012,7 +906,6 @@ it supports .Dv NOTIFY ) allowing the slave to verify the zone while the call us up. - .Pp If the zone is a .Ic slave @@ -1022,7 +915,6 @@ then the server will suppress the zone regular zone up to date queries and only perform the when the .Ic heartbeat-interval expires. - .It Ic fake-iquery If .Li yes , @@ -1030,7 +922,6 @@ the server will simulate the obsolete DNS query type .Dv IQUERY . The default is .Li no . - .It Ic fetch-glue If .Li yes @@ -1042,16 +933,16 @@ can be used in conjunction with .Ic recursion no to prevent the server's cache from growing or becoming corrupted (at the cost of requiring more work from the client). - .It Ic has-old-clients Setting the option to .Li yes , is equivalent to setting the following three options: -.Ic auth-nxdomain yes ;, -.Ic maintain-ixfr-base yes ;, +.Ic auth-nxdomain yes ; , +.Ic maintain-ixfr-base yes ; , and .Ic rfc2308-type1 no ; -. The use of +.Pp +The use of .Ic has-old-clients with .Ic auth-nxdomain , @@ -1059,24 +950,16 @@ with and .Ic rfc2308-type1 is order dependant. - .It Ic host-statistics If .Li yes , then statistics are kept for every host that the the nameserver interacts with. The default is .Li no . -.Em Note: +.Em Note : turning on .Ic host-statistics can consume huge amounts of memory. - -.It IC host-statistics-max -The maximum number of host records that will be kept. -When this limit is reached no new hosts will be added to the host statistics. -If the set to zero then there is no limit set. -The default value is zero. - .It Ic maintain-ixfr-base If .Li yes , @@ -1085,7 +968,6 @@ This enables the server to answer IXFR queries which can speed up zone transfers enormously. The default is .Li no . - .It Ic multiple-cnames If .Li yes , @@ -1096,7 +978,6 @@ Allowing multiple CNAME records is against standards and is not recommended. Multiple CNAME support is available because previous versions of BIND allowed multiple CNAME records, and these records have been used for load balancing by a number of sites. - .It Ic notify If .Li yes @@ -1105,14 +986,25 @@ zone the server is authoritative for changes. The use of NOTIFY speeds convergence between the master and its slaves. Slave servers that receive a NOTIFY message and understand it will contact the master server for the zone and see if they need to do a zone transfer, and -if they do, they will initiate it immediately. The +if they do, they will initiate it immediately. +If +.Li explicit , +the DNS NOTIFY messages will only be sent to the addresses in the +.Ic also-notify +list. +The .Ic notify option may also be specified in the .Ic zone statement, in which case it overrides the .Ic options notify statement. - +.It Ic suppress-initial-notify +If +.Li yes , +suppress the initial notify messages when the server first loads. +The default is +.Li no . .It Ic recursion If .Li yes , @@ -1124,7 +1016,6 @@ client if it doesn't know the answer. The default is See also .Ic fetch-glue above. - .It Ic rfc2308-type1 If .Li yes, @@ -1134,7 +1025,6 @@ you as a forwarder that does not understand negative answers which contain both SOA and NS records or you have an old version of sendmail. The correct fix is to upgrade the broken server or sendmail. The default is .Li no . - .It Ic use-id-pool If .Li yes, @@ -1142,7 +1032,6 @@ the server will keep track of its own outstanding query ID's to avoid duplicatio and increase randomness. This will result in 128KB more memory being consumed by the server. The default is .Li no . - .It Ic treat-cr-as-space If .Li yes, @@ -1150,14 +1039,10 @@ the server will treat CR characters the same way it treats a space or tab. This may be necessary when loading zone files on a UNIX system that were generated on an NT or DOS machine. The default is .Li no . - - .El - .Ss Also-Notify - .Ic also-notify - +.Pp Defines a global list of IP addresses that also get sent NOTIFY messages whenever a fresh copy of the zone is loaded. This helps to ensure that copies of the zones will quickly converge on ``stealth'' servers. If an @@ -1175,18 +1060,14 @@ the global .Ic also-notify list will not get sent NOTIFY messages for that zone. The default is the empty list (no global notification list). - .Ss Forwarding - -.Pp The forwarding facility can be used to create a large site-wide cache on a few servers, reducing traffic over links to external nameservers. It can also be used to allow queries by servers that do not have direct access to the Internet, but wish to look up exterior names anyway. Forwarding occurs only on those queries for which the server is not authoritative and does not have the answer in its cache. - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic forward This option is only meaningful if the .Ic forwarders @@ -1198,12 +1079,10 @@ server to query the forwarders first, and if that doesn't answer the question the server will then look for the answer itself. If .Li only is specified, the server will only query the forwarders. - .It Ic forwarders Specifies the IP addresses to be used for forwarding. The default is the empty list (no forwarding). .El - .Pp Forwarding can also be configured on a per-zone basis, allowing for the global forwarding options to be overridden in a variety of ways. @@ -1214,33 +1093,25 @@ behavior, or to not forward at all. See .Sx THE ZONE STATEMENT section for more information. - .Pp Future versions of BIND 8 will provide a more powerful forwarding system. The syntax described above will continue to be supported. - .Ss Name Checking - The server can check domain names based upon their expected client contexts. For example, a domain name used as a hostname can be checked for compliance with the RFCs defining valid hostnames. - .Pp Three checking methods are available: - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic ignore No checking is done. - .It Ic warn Names are checked against their expected client contexts. Invalid names are logged, but processing continues normally. - .It Ic fail Names are checked against their expected client contexts. Invalid names are logged, and the offending data is rejected. .El - .Pp The server can check names three areas: master zone files, slave zone files, and in responses to queries the server has initiated. If @@ -1250,16 +1121,13 @@ answering the client's question would require sending an invalid name to the client, the server will send a .Dv REFUSED response code to the client. - .Pp The defaults are: - .Bd -literal check-names master fail; check-names slave warn; check-names response ignore; .Ed - .Pp .Ic check-names may also be specified in the @@ -1270,16 +1138,12 @@ statement. When used in a .Ic zone statement, the area is not specified (because it can be deduced from the zone type). - .Ss Access Control - -.Pp Access to the server can be restricted based on the IP address of the requesting system or via shared secret keys. See .Sx ADDRESS MATCH LISTS for details on how to specify access criteria. - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic allow-query Specifies which hosts are allowed to ask ordinary questions. .Ic allow-query @@ -1289,13 +1153,11 @@ statement, in which case it overrides the .Ic options allow-query statement. If not specified, the default is to allow queries from all hosts. - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic allow-recursion Specifies which hosts are allowed to ask recursive questions. If not specified, the default is to allow recursive queries from all hosts. - .It Ic allow-transfer Specifies which hosts are allowed to receive zone transfers from the server. @@ -1306,17 +1168,13 @@ statement, in which case it overrides the .Ic options allow-transfer statement. If not specified, the default is to allow transfers from all hosts. - .It Ic blackhole Specifies a list of addresses that the server will not accept queries from or use to resolve a query. Queries from these addresses will not be responded to. .El .El - .Ss Interfaces - -.Pp The interfaces and ports that the server will answer queries from may be specified using the .Ic listen-on @@ -1325,30 +1183,24 @@ option. takes an optional port, and an address match list. The server will listen on all interfaces allowed by the address match list. If a port is not specified, port 53 will be used. - .Pp Multiple .Ic listen-on statements are allowed. For example, - .Bd -literal listen-on { 5.6.7.8; }; listen-on port 1234 { !1.2.3.4; 1.2/16; }; .Ed - +.Pp will enable the nameserver on port 53 for the IP address 5.6.7.8, and on port 1234 of an address on the machine in net 1.2 that is not 1.2.3.4. - .Pp If no .Ic listen-on is specified, the server will listen on port 53 on all interfaces. - .Ss Query Address - -.Pp If the server doesn't know the answer to a question, it will query other nameservers. .Ic query-source @@ -1366,24 +1218,20 @@ is or is omitted, a random unprivileged port will be used. The default is .Dl query-source address * port *; - .Pp Note: .Ic query-source currently applies only to UDP queries; TCP queries always use a wildcard IP address and a random unprivileged port. - .Ss Zone Transfers - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic max-transfer-time-in Inbound zone transfers ( .Nm named-xfer processes) running longer than this many minutes will be terminated. The default is 120 minutes (2 hours). - .It Ic transfer-format The server supports two zone transfer methods. .Li one-answer @@ -1400,19 +1248,16 @@ patched versions of BIND 4.9.5. The default is may be overridden on a per-server basis by using the .Ic server statement. - .It Ic transfers-in The maximum number of inbound zone transfers that can be running concurrently. The default value is 10. Increasing .Ic transfers-in may speed up the convergence of slave zones, but it also may increase the load on the local system. - .It Ic transfers-out This option will be used in the future to limit the number of concurrent outbound zone transfers. It is checked for syntax, but is otherwise ignored. - .It Ic transfers-per-ns The maximum number of inbound zone transfers ( .Nm named-xfer @@ -1427,7 +1272,6 @@ may be overridden on a per-server basis by using the phrase of the .Ic server statement. - .It Ic transfer-source .Nm transfer-source determines which local address will be bound to the TCP connection used to fetch all zones @@ -1440,10 +1284,7 @@ for all zones, but can be overriden on a per-zone basis by includinga .Nm transfer-source statement within the zone block in the configuration file. .El - .Ss Resource Limits - -.Pp The server's usage of many system resources can be limited. Some operating systems don't support some of the limits. On such systems, a warning will be issued if the unsupported limit is used. Some @@ -1452,7 +1293,6 @@ a .D1 cannot set resource limits on this system message will be logged. - .Pp Scaled values are allowed when specifying resource limits. For example, @@ -1471,17 +1311,14 @@ See the definition of in the .Sx DOCUMENTATION DEFINITIONS section for more details. - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic coresize The maximum size of a core dump. The default value is .Li default . - .It Ic datasize The maximum amount of data memory the server may use. The default value is .Li default . - .It Ic files The maximum number of files the server may have open concurrently. The default value is @@ -1501,35 +1338,28 @@ If the actual kernel limit is larger than this value, use .Ic limit files to specify the limit explicitly. - .It Ic max-ixfr-log-size The .Li max-ixfr-log-size will be used in a future release of the server to limit the size of the transaction log kept for Incremental Zone Transfer. - .It Ic stacksize The maximum amount of stack memory the server may use. The default value is .Li default . .El - .Ss Periodic Task Intervals - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic cleaning-interval The server will remove expired resource records from the cache every - .Ic cleaning-interval minutes. The default is 60 minutes. If set to 0, no periodic cleaning will occur. - .It Ic heartbeat-interval The server will perform zone maintenance tasks for all zones marked .Ic dialup yes whenever this interval expires. The default is 60 minutes. Reasonable values are up to 1 day (1440 minutes). If set to 0, no zone maintenance for these zones will occur. - .It Ic interface-interval The server will scan the network interface list every .Ic interface-interval @@ -1540,16 +1370,12 @@ interfaces (provided they are allowed by the .Ic listen-on configuration). Listeners on interfaces that have gone away will be cleaned up. - .It Ic statistics-interval Nameserver statistics will be logged every .Ic statistics-interval minutes. The default is 60. If set to 0, no statistics will be logged. .El - .Ss Topology - -.Pp All other things being equal, when the server chooses a nameserver to query from a list of nameservers, it prefers the one that is topologically closest to itself. The @@ -1563,7 +1389,6 @@ negated match will be assigned the maximum distance from the server. If there is no match, the address will get a distance which is further than any non-negated list element, and closer than any negated element. For example, - .Bd -literal topology { 10/8; @@ -1571,44 +1396,40 @@ element. For example, { 1.2/16; 3/8; }; }; .Ed - +.Pp will prefer servers on network 10 the most, followed by hosts on network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the exception of hosts on network 1.2.3 (netmask 255.255.255.0), which is preferred least of all. - .Pp The default topology is .Dl topology { localhost; localnets; }; - .Ss Resource Record sorting - -.Pp When returning multiple RRs, the nameserver will normally return them in .Ic Round Robin , i.e. after each request, the first RR is put to the end of the list. As the order of RRs is not defined, this should not cause any problems. - +.Pp The client resolver code should re-arrange the RRs as appropriate, i.e. using any addresses on the local net in preference to other addresses. However, not all resolvers can do this, or are not correctly configured. - +.Pp When a client is using a local server, the sorting can be performed in the server, based on the client's address. This only requires configuring the nameservers, not all the clients. - +.Pp The .Ic sortlist statement takes an address match list and interprets it even more specially than the -.Ictopology +.Ic topology statement does. - +.Pp Each top level statement in the sortlist must itself be an explicit address match list with one or two elements. The first element (which may be an IP address, an IP prefix, an ACL name or nested address match list) of each top level list is checked against the source address of the query until a match is found. - +.Pp Once the source address of the query has been matched, if the top level statement contains only one element, the actual primitive element that matched the source address is used to select the address in the response to @@ -1616,7 +1437,7 @@ move to the beginning of the response. If the statement is a list of two element the second element is treated like the address match list in a topology statement. Each top level element is assigned a distance and the address in the response with the minimum distance is moved to the beginning of the response. - +.Pp In the following example, any queries received from any of the addresses of the host itself will get responses preferring addresses on any of the locally connected networks. Next most preferred are addresses on the 192.168.1/24 @@ -1626,7 +1447,6 @@ the 192.168.1/24 network will prefer other addresses on that network to the 192.168.2/24 and 192.168.3/24 networks. Queries received from a host on the 192.168.4/24 or the 192.168.5/24 network will only prefer other addresses on their directly connected networks. - .Bd -literal sortlist { { localhost; // IF the local host @@ -1646,24 +1466,20 @@ sortlist { }; }; .Ed - +.Pp The following example will give reasonable behaviour for the local host and hosts on directly connected networks. It is similar to the behavior of the address sort in BIND 4.9.x. Responses sent to queries from the local host will favor any of the directly connected networks. Responses sent to queries from any other hosts on a directly connected network will prefer addresses on that same network. Responses to other queries will not be sorted. - .Bd -literal sortlist { { localhost; localnets; }; { localnets; }; }; .Ed - .Ss RRset Ordering - -.Pp When multiple records are returned in an answer it may be useful to configure the order the records are placed into the response. For example the records for a zone might be configured to always be returned in the order they are defined @@ -1671,15 +1487,14 @@ in the zone file. Or perhaps a random shuffle of the records as they are returned is wanted. The rrset-order statement permits configuration of the ordering made of the records in a multiple record response. The default, if no ordering is defined, is a cyclic ordering (round robin). - +.Pp An .Ic order_spec is defined as follows: - .Bd -literal [ \fIclass class_name\fR ][ \fItype type_name\fR ][ \fIname\fR "FQDN" ] \fIorder\fR ordering .Ed - +.Pp If no class is specified, the default is .Ic ANY . If no @@ -1687,48 +1502,53 @@ If no is specified, the default is .Ic ANY . If no name is specified, the default is "*". - +.Pp The legal values for .Ic ordering are: - -.Bd -literal -.Ic fixed - Records are returned in the order they are defined in the zone file. -.Ic random - Records are returned in some random order. -.Ic cyclic - Records are returned in a round-robin order. - +.Bl -tag -width indent +.It Ic fixed +Records are returned in the order they are defined in the zone file. +.It Ic random +Records are returned in some random order. +.It Ic cyclic +Records are returned in a round-robin order. +.El +.Pp For example: - +.Bd -literal rrset-order { class IN type A name "rc.vix.com" order random; order cyclic; }; .Ed - +.Pp will cause any responses for type A records in class IN that have "rc.vix.com" as a suffix, to always be returned in random order. All other records are returned in cyclic order. - +.Pp If multiple .Ic rrset-order statements appear, they are not combined--the last one applies. - +.Pp If no .Ic rrset-order statement is specified, a default one of: - .Bd -literal rrset-order { class ANY type ANY name "*" order cyclic ; }; .Ed - +.Pp is used. - +.Ss Glue Ordering +When running a root nameserver it is sometimes necessary to ensure that other +nameservers that are priming are successful. +This requires that glue A records for at least of the nameservers are returned +in the answer to a priming query. +This can be achieved by setting +.Ic preferred-glue A; +which will add A records before other types in the additional section. .Ss Tuning - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic lame-ttl Sets the number of seconds to cache a lame server indication. 0 disables caching. Default is 600 (10 minutes). Maximum value is 1800 (30 minutes) @@ -1748,10 +1568,8 @@ value which is greater that 7 days. The minimum number of root servers that is required for a request for the root servers to be accepted. Default is 2. .El - .Sh THE ZONE STATEMENT .Ss Syntax - .Bd -literal zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { type master; @@ -1763,15 +1581,15 @@ zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { [ forward ( only | first ); ] [ forwarders { [ \fIip_addr\fR ; [ \fIip_addr\fR ; ... ] ] }; ] [ dialup \fIyes_or_no\fR; ] - [ notify \fIyes_or_no\fR; ] + [ notify ( \fIyes_or_no\fR | explicit ); ] [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ] }; - +.Pp zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { type ( slave | stub ); [ file \fIpath_name\fR; ] - masters [ port \fIip_port\fR ] { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; + masters [ port \fIip_port\fR ] { \fIip_addr\fR [ key \fIkey_id\fR ]; [ ... ] }; [ check-names ( warn | fail | ignore ); ] [ allow-update { \fIaddress_match_list\fR }; ] [ allow-query { \fIaddress_match_list\fR }; ] @@ -1784,33 +1602,29 @@ zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ] }; - +.Pp zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { type forward; [ forward ( only | first ); ] [ forwarders { [ \fIip_addr\fR ; [ \fIip_addr\fR ; ... ] ] }; ] [ check-names ( warn | fail | ignore ); ] }; - +.Pp zone \&".\&" [ ( in | hs | hesiod | chaos ) ] { type hint; file \fIpath_name\fR; [ check-names ( warn | fail | ignore ); ] }; .Ed - .Ss Definition and Usage - The .Ic zone statement is used to define how information about particular DNS zones is managed by the server. There are five different zone types. - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic master The server has a master copy of the data for the zone and will be able to provide authoritative answers for it. - .It Ic slave A .Ic slave @@ -1827,13 +1641,11 @@ Use of the .Ic file clause is highly recommended, since it often speeds server startup and eliminates a needless waste of bandwidth. - .It Ic stub A .Ic stub zone is like a slave zone, except that it replicates only the NS records of a master zone instead of the entire zone. - .It Ic forward A .Ic forward @@ -1843,7 +1655,6 @@ section. The specification of options in such a zone will override any global options declared in the .Ic options statement. - .Pp If either no .Ic forwarders @@ -1860,14 +1671,12 @@ the global .Ic forward option, and not the servers used, then you also need to respecify the global forwarders. - .It Ic hint The initial set of root nameservers is specified using a .Ic hint zone. When the server starts up, it uses the root hints to find a root nameserver and get the most recent list of root nameservers. .El - .Pp Note: previous releases of BIND used the term .Ic primary @@ -1876,15 +1685,12 @@ for a master zone, for a slave zone, and .Ic cache for a hint zone. - .Ss Classes - The zone's name may optionally be followed by a class. If a class is not specified, class .Ic in (for "internet"), is assumed. This is correct for the vast majority of cases. - .Pp The .Ic hesiod @@ -1896,7 +1702,6 @@ The keyword .Ic hs is a synonym for .Ic hesiod . - .Pp Another MIT development was CHAOSnet, a LAN protocol created in the mid-1970s. It is still sometimes seen on LISP stations and other @@ -1904,16 +1709,13 @@ hardware in the AI community, and zone data for it can be specified with the .Ic chaos class. - .Ss Options - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic check-names See the subsection on .Sx Name Checking in .Sx THE OPTIONS STATEMENT . - .It Ic allow-query See the description of .Ic allow-query @@ -1921,11 +1723,9 @@ in the .Sx Access Control subsection of .Sx THE OPTIONS STATEMENT . - .It Ic allow-update Specifies which hosts are allowed to submit Dynamic DNS updates to the server. The default is to deny updates from all hosts. - .It Ic allow-transfer See the description of .Ic allow-transfer @@ -1933,7 +1733,6 @@ in the .Sx Access Control subsection of .Sx THE OPTIONS STATEMENT . - .It Ic transfer-source .Ic transfer-source determines which local address will be bound to the TCP connection @@ -1942,7 +1741,6 @@ controlled value which will usually be the address of the interface ``closest to'' the remote end. This address must appear in the remote end's .Ic allow-transfer option for this zone if one is specified. - .It Ic max-transfer-time-in See the description of .Ic max-transfer-time-in @@ -1950,7 +1748,6 @@ in the .Sx Zone Transfers subsection of .Sx THE OPTIONS STATEMENT . - .It Ic dialup See the description of .Ic dialup @@ -1958,7 +1755,6 @@ in the .Sx Boolean Options subsection of .Sx THE OPTIONS STATEMENT . - .It Ic notify See the description of .Sx notify @@ -1966,7 +1762,6 @@ in the .Sx Boolean Options subsection of the .Sx THE OPTIONS STATEMENT . - .It Ic also-notify .Ic also-notify is only meaningful if @@ -1980,7 +1775,6 @@ the primary master) plus any IP addresses specified with is not meaningful for .Ic stub zones. The default is the empty list. - .It Ic forward .Ic forward is only meaningful if the zone has a @@ -1992,7 +1786,6 @@ value causes the lookup to fail after trying the and getting no answer, while .Ic first would allow a normal lookup to be tried. - .It Ic forwarders The .Ic forwarders @@ -2001,39 +1794,31 @@ If it is not specified in a zone of type .Ic forward , .Em no forwarding is done for the zone; the global options are not used. - .It Ic pubkey The DNSSEC flags, protocol, and algorithm are specified, as well as a base-64 encoded string representing the key. .El - .Sh THE ACL STATEMENT .Ss Syntax - .Bd -literal acl \fIname\fR { \fIaddress_match_list\fR }; .Ed - .Ss Definition and Usage - The .Ic acl statement creates a named address match list. It gets its name from a primary use of address match lists: Access Control Lists (ACLs). - .Pp Note that an address match list's name must be defined with .Ic acl before it can be used elsewhere; no forward references are allowed. - .Pp The following ACLs are built-in: - -.Bl -tag -width 1 +.Bl -tag -width 0n .It Ic any Allows all hosts. .It Ic none @@ -2043,19 +1828,15 @@ Allows the IP addresses of all interfaces on the system. .It Ic localnets Allows any host on a network for which the system has an interface. .El - .Sh THE KEY STATEMENT .Ss Syntax - .Bd -literal key \fIkey_id\fR { algorithm \fIalgorithm_id\fR; secret \fIsecret_string\fR; }; .Ed - .Ss Definition and Usage - The .Ic key statement defines a key ID which can be used in a @@ -2067,7 +1848,6 @@ A key ID must be created with the statement before it can be used in a .Ic server definition or an address match list. - .Pp The .Va algorithm_id @@ -2082,18 +1862,14 @@ that if you have in your .Pa named.conf , then it should not be readable by anyone but the superuser. - .Sh THE TRUSTED-KEYS STATEMENT .Ss Syntax - .Bd -literal trusted-keys { [ \fIdomain_name\fR \fIflags\fR \fIprotocol\fR \fIalgorithm\fR \fIkey\fR; ] }; .Ed - .Ss Definition and Usage - The .Ic trusted-keys statement is for use with DNSSEC-style security, originally specified @@ -2104,7 +1880,6 @@ complete description of DNSSEC and its use is beyond the scope of this document, and readers interested in more information should start with RFC 2065 and then continue with the Internet Drafts available at http://www.ietf.org/ids.by.wg/dnssec.html. - .Pp Each trusted key is associated with a domain name. Its attributes are the non-negative integral @@ -2114,27 +1889,22 @@ and .Va algorithm , as well as a base-64 encoded string representing the .Va key . - .Pp Any number of trusted keys can be specified. - .Sh THE SERVER STATEMENT .Ss Syntax - .Bd -literal server \fIip_addr\fR { [ bogus \fIyes_or_no\fR; ] + [ support-ixfr \fIyes_or_no\fR; ] [ transfers \fInumber\fR; ] [ transfer-format ( one-answer | many-answers ); ] [ keys { \fIkey_id\fR [ \fIkey_id\fR ... ] }; ] }; .Ed - .Ss Definition and Usage - The server statement defines the characteristics to be associated with a remote name server. - .Pp If you discover that a server is giving out bad data, marking it as .Ic bogus @@ -2142,12 +1912,15 @@ will prevent further queries to it. The default value of .Ic bogus is .Li no . -Marking a server as -.Ic bogus -will mark all other addresses for that server as -.Ic bogus -when a match is made when looking up a server's address by name. - +.Pp +If the server supports IXFR you can tell named to attempt to +perform a IXFR style zone transfer by specifing +.Ic support-ixfr +.Li yes . +The default value of +.Ic support-ixfr +is +.Li no . .Pp The server supports two zone transfer methods. The first, .Ic one-answer , @@ -2166,14 +1939,12 @@ is not specified, the specified by the .Ic options statement will be used. - .Pp The .Ic transfers will be used in a future release of the server to limit the number of concurrent in-bound zone transfers from the specified server. It is checked for syntax but is otherwise ignored. - .Pp The .Ic keys @@ -2188,16 +1959,13 @@ The statememnt must come before the .Ic server statement that references it. - .Pp The .Ic keys statement is intended for future use by the server. It is checked for syntax but is otherwise ignored. - .Sh THE CONTROLS STATEMENT .Ss Syntax - .Bd -literal controls { [ inet \fIip_addr\fR @@ -2209,9 +1977,7 @@ controls { group \fInumber\fR; ] }; .Ed - .Ss Definition and Usage - The .Ic controls statement declares control channels to be used by system @@ -2220,7 +1986,6 @@ These control channels are used by the .Nm ndc utility to send commands to and retrieve non-DNS results from a name server. - .Pp A .Ic unix @@ -2244,7 +2009,6 @@ must be given as numbers, not names. It is recommended that the permissions be restricted to administrative personnel only, or else any user on the system might be able to manage the local name server. - .Pp An .Ic inet @@ -2261,16 +2025,12 @@ It is recommended that 127.0.0.1 be the only .Va ip_addr used, and this only if you trust all non-privileged users on the local host to manage your name server. - .Sh THE INCLUDE STATEMENT .Ss Syntax - .Bd -literal include \fIpath_name\fR; .Ed - .Ss Definition and Usage - The .Ic include statement inserts the specified file at the point that the @@ -2279,28 +2039,23 @@ statement is encountered. It cannot be used within another statement, though, so a line such as .Dl acl internal_hosts { include "internal_hosts.acl"; }; is not allowed. - .Pp Use .Ic include to break the configuration up into easily-managed chunks. For example: - .Bd -literal include "/etc/security/keys.bind"; include "/etc/acls.bind"; .Ed - +.Pp could be used at the top of a BIND configuration file in order to include any ACL or key information. - .Pp Be careful not to type ``#include'', like you would in a C program, because ``#'' is used to start a comment. - .Sh EXAMPLES - The simplest configuration file that is still realistically useful is one which simply defines a hint zone that has a full path to the root servers file. @@ -2310,58 +2065,55 @@ zone \&".\&" in { file \&"/var/named/root.cache\&"; }; .Ed - +.Pp Here's a more typical real-world example. - .Bd -literal /* * A simple BIND 8 configuration */ - +.Pp logging { category lame-servers { null; }; category cname { null; }; }; - +.Pp options { directory \&"/var/named\&"; }; - +.Pp controls { inet * port 52 allow { any; }; // a bad idea unix \&"/var/run/ndc\&" perm 0600 owner 0 group 0; // the default }; - +.Pp zone \&"isc.org\&" in { type master; file \&"master/isc.org\&"; }; - +.Pp zone \&"vix.com\&" in { type slave; file \&"slave/vix.com\&"; masters { 10.0.0.53; }; }; - +.Pp zone \&"0.0.127.in-addr.arpa\&" in { type master; file \&"master/127.0.0\&"; }; - +.Pp zone \&".\&" in { type hint; file \&"root.cache\&"; }; .Ed - .Sh FILES -.Bl -tag -width 1 -compact +.Bl -tag -width 0n -compact .It Pa /etc/named.conf The BIND 8 .Nm named configuration file. .El - .Sh SEE ALSO .Xr named 8 , .Xr ndc 8 diff --git a/contrib/bind/doc/man/ndc.8 b/contrib/bind/doc/man/ndc.8 index a4645e6..33a7076 100644 --- a/contrib/bind/doc/man/ndc.8 +++ b/contrib/bind/doc/man/ndc.8 @@ -94,7 +94,7 @@ Exit from command interpreter. .It Ar /trace Toggle tracing (see -.Fl -t +.Fl t description above). .It Ar /debug Toggle debugging (see @@ -125,7 +125,7 @@ mode, there is no command and the .Ar restart command just tells the name server to -.Xr execvp 2 +.Xr execvp @LIB_C_EXT@ itself. .Sh AUTHOR Paul Vixie (Internet Software Consortium) diff --git a/contrib/bind/doc/man/nslookup.8 b/contrib/bind/doc/man/nslookup.8 index d74d84f..54c45b6 100644 --- a/contrib/bind/doc/man/nslookup.8 +++ b/contrib/bind/doc/man/nslookup.8 @@ -170,7 +170,7 @@ command. Connects with the finger server on the current host. The current host is defined when a previous lookup for a host was successful and returned address information (see the -.Dq Ic set querytype=A +.Dq Ic set querytype Ns = Ns Dv A command). The .Ar name @@ -223,12 +223,13 @@ Sorts and lists the output of previous command(s) with .Xr more @CMD_EXT@ . .It Ic help -.It Ic ? +.It Ic ?\& Prints a brief summary of commands. .It Ic exit Exits the program. -.It Xo Ic set Ar keyword -.Ns Op = Ns Ar value +.It Xo +.Ic set +.Ar keyword Ns Op = Ns Ar value .Xc This command is used to change state information that affects the lookups. Valid keywords are: @@ -237,7 +238,7 @@ Valid keywords are: Prints the current values of the frequently-used options to .Ic set . Information about the current default server and host is also printed. -.It Ic class= Ns Ar value +.It Ic class Ns = Ns Ar value Change the query class to one of: .Bl -tag -width "HESIOD " .It Dv IN @@ -256,8 +257,8 @@ The class specifies the protocol group of the information. .Dv IN ; abbreviation = .Ic cl ) -.It Xo Op Ic no -.Ns Ic debug +.It Xo +.Oo Ic no Oc Ns Ic debug .Xc Turn debugging mode on. A lot more information is printed about the packet sent to the server and the resulting answer. @@ -265,18 +266,16 @@ packet sent to the server and the resulting answer. (Default = .Ic nodebug ; abbreviation = -.Xo Op Ic no -.Ns Ic deb ) -.Xc -.It Xo Op Ic no -.Ns Ic d2 +.Oo Ic no Oc Ns Ic deb ) +.It Xo +.Oo Ic no Oc Ns Ic d2 .Xc Turn exhaustive debugging mode on. Essentially all fields of every packet are printed. .Pp (Default = .Ic nod2 ) -.It Ic domain= Ns Ar name +.It Ic domain Ns = Ns Ar name Change the default domain name to .Ar name . The default domain name is appended to a lookup request depending on the @@ -300,10 +299,17 @@ command to display the list. .Xr hostname @CMD_EXT@ , .Pa /etc/resolv.conf , or -.Ev LOCALDOMAIN; +.Ev LOCALDOMAIN ; abbreviation = .Ic do ) -.It Ic srchlist= Ns Ar name1/name2/... +.It Xo +.Sm off +.Ic srchlist No = +.Ar name1 No / +.Ar name2 No / +.Ar ... +.Sm on +.Xc Change the default domain name to .Ar name1 and the domain search list @@ -329,11 +335,11 @@ command to display the list. .Xr hostname @CMD_EXT@ , .Pa /etc/resolv.conf , or -.Ev LOCALDOMAIN; +.Ev LOCALDOMAIN ; abbreviation = .Ic srchl ) -.It Xo Op Ic no -.Ns Ic defname +.It Xo +.Oo Ic no Oc Ns Ic defname .Xc If set, append the default domain name to a single-component lookup request (i.e., one that does not contain a period). @@ -341,11 +347,9 @@ If set, append the default domain name to a single-component lookup request (Default = .Ic defname ; abbreviation = -.Xo Op Ic no -.Ns Ic defname ) -.Xc -.It Xo Op Ic no -.Ns Ic search +.Oo Ic no Oc Ns Ic defname ) +.It Xo +.Oo Ic no Oc Ns Ic search .Xc If the lookup request contains at least one period but .Em doesn't @@ -355,18 +359,16 @@ to the request until an answer is received. (Default = .Ic search ; abbreviation = -.Xo Op Ic no -.Ns Ic sea ) -.Xc -.It Ic port= Ns Ar value +.Oo Ic no Oc Ns Ic sea ) +.It Ic port Ns = Ns Ar value Change the default TCP/UDP name server port to .Ar value . .Pp (Default = 53; abbreviation = .Ic \&po ) -.It Ic querytype= Ns Ar value -.It Ic type= Ns Ar value +.It Ic querytype Ns = Ns Ar value +.It Ic type Ns = Ns Ar value Change the type of information query to one of: .Bl -tag -width "HINFO " .It Dv A @@ -397,15 +399,16 @@ the supported well-known services. .El .Pp Other types -.Pq Dv ANY, AXFR, MB, MD, MF, NULL +.Dv ( ANY , AXFR , MB , +.Dv MD , MF , NULL ) are described in the RFC-1035 document. .Pp (Default = .Dv A ; abbreviations = .Ic q , ty ) -.It Xo Op Ic no -.Ns Ic recurse +.It Xo +.Oo Ic no Oc Ns Ic recurse .Xc Tell the name server to query other servers if it does not have the information. @@ -413,10 +416,8 @@ information. (Default = .Ic recurse ; abbreviation = -.Xo Op Ic no -.Ns Ic rec ) -.Xc -.It Ic retry= Ns Ar number +.Oo Ic no Oc Ns Ic rec ) +.It Ic retry Ns = Ns Ar number Set the number of retries to .Ar number . When a reply to a request is not received within a certain @@ -427,7 +428,7 @@ The retry value controls how many times a request is resent before giving up. .Pp (Default = 4, abbreviation = .Ic ret ) -.It Ic root= Ns Ar host +.It Ic root Ns = Ns Ar host Change the name of the root server to .Ar host . This affects the @@ -438,35 +439,31 @@ command. .Ic ns.internic.net. ; abbreviation = .Ic ro ) -.It Ic timeout= Ns Ar number +.It Ic timeout Ns = Ns Ar number Change the initial timeout interval for waiting for a reply to .Ar number seconds. Each retry doubles the timeout period. .Pp (Default = 5 seconds; abbreviation = .Ic ti ) -.It Xo Op Ic no -.Ns Ic vc +.It Xo +.Oo Ic no Oc Ns Ic vc .Xc Always use a virtual circuit when sending requests to the server. .Pp (Default = .Ic novc ; abbreviation = -.Xo Op Ic no -.Ns Ic v ) +.Oo Ic no Oc Ns Ic v ) +.It Xo +.Oo Ic no Oc Ns Ic ignoretc .Xc -.It Xo Op Ic no -.Ns Ic ignoretc -.Xc Ignore packet truncation errors. .Pp (Default = .Ic noignoretc ; abbreviation = -.Xo Op Ic no -.Ns Ic ig ) -.Xc +.Oo Ic no Oc Ns Ic ig ) .El .El .Sh DIAGNOSTICS @@ -476,9 +473,11 @@ Possible errors are: .It Li Timed out The server did not respond to a request after a certain amount of time (changed with -.Dq Ic set timeout= Ns Ar value ) +.Dq Ic set timeout Ns = Ns Ar value ) and a certain number of retries (changed with -.Dq Ic set retry= Ns Ar value ) . +.Do +.Ic set retry Ns = Ns Ar value +.Dc ) . .It Li \&No response from server No name server is running on the server machine. .It Li \&No records diff --git a/contrib/bind/doc/man/nsupdate.8 b/contrib/bind/doc/man/nsupdate.8 index 88dc327..6045984 100644 --- a/contrib/bind/doc/man/nsupdate.8 +++ b/contrib/bind/doc/man/nsupdate.8 @@ -1,4 +1,4 @@ -.\" $Id: nsupdate.8,v 8.6 2000/10/30 23:06:57 cyarnell Exp $ +.\" $Id: nsupdate.8,v 8.8 2002/04/22 04:38:04 marka Exp $ .\" .\"Copyright (c) 1999 by Internet Software Consortium .\" @@ -22,9 +22,9 @@ .Nd update Internet name servers interactively .Sh SYNOPSIS .Nm nsupdate -.Op Fl Ar k keydir:keyname -.Op Fl Ar d -.Op Fl Ar v +.Op Fl k Ar keydir:keyname +.Op Fl d +.Op Fl v .Op Ar filename .Sh DESCRIPTION .Ic Nsupdate @@ -81,18 +81,14 @@ will be performed. .Ic Nsupdate understands the following input record formats: .Pp - .Bl -hang - .It Ic prereq nxdomain Va domain-name Requires that no RR of any type exists with name .Va domain-name . - .It Ic prereq yxdomain Va domain-name Requires that at least one RR named .Va domain-name must exist. - .It Xo .Ic prereq nxrrset Va domain-name Op class .Va type @@ -101,11 +97,10 @@ Requires that no RR exists of the specified .Va type and .Va domain-name . - .It Xo .Ic prereq yxrrset -.Va domain-name Op class -.Va type Op data... +.Va domain-name Op Va class +.Va type Op Va data... .Xc Requires that a RR exists of the specified .Va type @@ -114,11 +109,10 @@ and If .Va data is specified, it must match exactly. - .It Xo .Ic update delete -.Va domain-name Op class -.Va Op type Op data... +.Va domain-name Op Va class +.Op Va type Op Va data... .Xc Deletes RRs named .Va domain-name . @@ -128,19 +122,16 @@ If .Va data ) is specified, only matching records will be deleted. - .It Xo .Ic update add -.Va domain-name ttl Op class +.Va domain-name ttl Op Va class .Va type data... .Xc Adds a new RR with specified .Va ttl , type , and .Va data . - .El - .Sh EXAMPLES The following example illustrates the interactive use of .Ic nsupdate @@ -156,7 +147,6 @@ $ nsupdate > update delete test.example.com A > update add test.example.com 3600 A 10.1.1.1 > - .Ed .Pp In this example, a CNAME alias is added to the database @@ -168,7 +158,6 @@ $ nsupdate > prereq nxrrset www.example.com CNAME > update add www.example.com 3600 CNAME test.example.com > - .Ed .Pp In this example, the nsupdate will be signed with the key "mykey", which @@ -177,20 +166,15 @@ is in the directory "/var/named/keys". $ nsupdate -k /var/named/keys:mykey > update add ftp.example.com 60 A 192.168.5.1 > - .Ed - .Sh DIAGNOSTICS .Bl -hang - .It Qq send error Typically indicates that the authoritative nameservers could not be reached - .It Qq failed update packet Typically indicates that the nameserver has rejected the update, either because the nameserver doesn't support dynamic update, or due to an authentication failure - .It Qq res_mkupdate: packet size = Va size (and no other messages) The update was successfully received and authenticated by the nameserver. @@ -203,8 +187,8 @@ and examine the status field in the nameserver's reply. .Sh FILES .Bl -hang .It Pa /etc/resolv.conf -.El initial domain name and name server addresses +.El .Sh SEE ALSO .Xr @INDOT@named @SYS_OPS_EXT@ , .Xr resolver @LIB_NETWORK_EXT@ , diff --git a/contrib/bind/doc/man/resolver.3 b/contrib/bind/doc/man/resolver.3 index b858d28..9e2ef6f 100644 --- a/contrib/bind/doc/man/resolver.3 +++ b/contrib/bind/doc/man/resolver.3 @@ -16,7 +16,7 @@ .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" @(#)resolver.3 6.5 (Berkeley) 6/23/90 -.\" $Id: resolver.3,v 8.13 2000/12/05 02:37:33 vixie Exp $ +.\" $Id: resolver.3,v 8.16 2001/12/28 04:24:20 marka Exp $ .\" .Dd July 4, 2000 .Dt RESOLVER @LIB_NETWORK_EXT_U@ @@ -59,7 +59,7 @@ .Fd #include .Fd #include .Fd #include -.Ft typedef struct __res_state *res_state; +.Vt typedef struct __res_state *res_state ; .Pp .Fn res_ninit "res_state statp" .Fn res_ourserver_p "const res_state statp" "const struct sockaddr_in *addr" @@ -69,18 +69,28 @@ .Fn res_nquery "res_state statp" "const char *dname" "int class" "int type" "u_char *answer" "int anslen" .Fn res_nsearch "res_state statp" "const char *dname" "int class" "int type" "u_char * answer" "int anslen" .Fn res_nquerydomain "res_state statp" "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen" -.Fn res_nmkquery "res_state statp, int op, const char *dname" "int class" "int type" "const u_char *data" "int datalen" "const u_char *newrr" "u_char *buf" "int buflen" +.Fo res_nmkquery +.Fa "res_state statp" +.Fa "int op" +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "const u_char *data" +.Fa "int datalen" +.Fa "const u_char *newrr" +.Fa "u_char *buf" +.Fa "int buflen" +.Fc .Fn res_nsend "res_state statp" "const u_char *msg" "int msglen" "u_char *answer" "int anslen" .Fn res_nupdate "res_state statp" "ns_updrec *rrecp_in" .Fn res_nmkupdate "res_state statp" "ns_updrec *rrecp_in" "u_char *buf" "int buflen" .Fn res_nclose "res_state statp" .Fn res_nsendsigned "res_state statp" "const u_char *msg" "int msglen" "ns_tsig_key *key" "u_char *answer" "int anslen" .Fn res_findzonecut "res_state statp" "const char *dname" "ns_class class" "int options" "char *zname" "size_t zsize" "struct in_addr *addrs" "int naddrs" -.Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs, **lastdnptr" -.Fn dn_expand "const u_char *msg, *eomorig, *comp_dn" "char *exp_dn" "int length" +.Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs" "u_char **lastdnptr" +.Fn dn_expand "const u_char *msg" "const u_char *eomorig" "const u_char *comp_dn" "char *exp_dn" "int length" .Fn hstrerror "int err" -.Sh DEPRECATED -.nr nS 1 +.Ss DEPRECATED .Fd #include .Fd #include .Fd #include @@ -90,10 +100,20 @@ .Fn fp_nquery "const u_char *msg" "int msglen" "FILE *fp" .Fn p_query "const u_char *msg" "FILE *fp" .Fn hostalias "const char *name" -.Fn res_query "const char *dname" "int class, type" "u_char *answer" "int anslen" -.Fn res_search "const char *dname" "int class, type" "u_char *answer" "int anslen" +.Fn res_query "const char *dname" "int class" "int type" "u_char *answer" "int anslen" +.Fn res_search "const char *dname" "int class" "int type" "u_char *answer" "int anslen" .Fn res_querydomain "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen" -.Fn res_mkquery "int op" "const char *dname, int class, type" "const char *data" "int datalen" "struct rrec *newrr" "u_char *buf" "int buflen" +.Fo res_mkquery +.Fa "int op" +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "const char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "u_char *buf" +.Fa "int buflen" +.Fc .Fn res_send "const u_char *msg" "int msglen" "u_char *answer" "int anslen" .Fn res_update "ns_updrec *rrecp_in" .Fn res_close "void" @@ -163,7 +183,7 @@ has been called). Print debugging messages. .It Dv RES_AAONLY Accept authoritative answers only. -should continue until it finds an authoritative answer or finds an error. +Should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .It Dv RES_USEVC Use TCP connections for queries instead of UDP datagrams. @@ -226,6 +246,18 @@ This option causes .Fn res_nsendsigned to leave the message unchanged after TSIG verification; otherwise the TSIG record would be removed and the header updated. +.It Dv RES_NOTLDQUERY +This option causes +.Fn res_nsearch +to not attempt to resolve a unqualified name as if it were a top level +domain (TLD). +This option can cause problems if the site has "localhost" as a TLD rather +than having localhost on one or more elements of the search list. +This option has no effect if neither +.Dv RES_DEFNAMES +or +.Dv RES_DNSRCH +is set. .El .Pp The @@ -409,7 +441,8 @@ The functions / .Fn hostalias lookup up name in the file referred to by the -.Ev HOSTALIASES files return a fully qualified hostname if found or NULL if +.Ev HOSTALIASES +files return a fully qualified hostname if found or NULL if not found or an error occurred. .Fn res_hostalias uses @@ -559,7 +592,7 @@ value of the parameter. .Sh FILES .Bl -tag -width "/etc/resolv.conf " -.It Pa /etc/resolv.conf +.It Pa /etc/resolv.conf See .Xr resolver @FORMAT_EXT@ . .El diff --git a/contrib/bind/doc/man/resolver.5 b/contrib/bind/doc/man/resolver.5 index 2129893..84ada33 100644 --- a/contrib/bind/doc/man/resolver.5 +++ b/contrib/bind/doc/man/resolver.5 @@ -14,7 +14,7 @@ .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 -.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ +.\" $Id: resolver.5,v 8.9 2001/12/28 04:24:21 marka Exp $ .\" .Dd November 11, 1993 .Dt RESOLVER @FORMAT_EXT_U@ @@ -146,14 +146,14 @@ name server before retrying the query via a different name server. Measured in seconds, the default is .Dv RES_TIMEOUT (see -.Pa ). +.Pa ) . .It Li attempts: Ns Ar n sets the number of times the resolver will send a query to its name servers before giving up and returning an error to the calling application. The default is .Dv RES_DFLRETRY (see -.Pa ). +.Pa ) . .It Li rotate sets .Dv RES_ROTATE @@ -178,6 +178,22 @@ This has the effect of trying a AAAA query before an A query inside the .Ft gethostbyname function, and of mapping IPv4 responses in IPv6 ``tunnelled form'' if no AAAA records are found but an A record set exists. +.It Li no-tld-query +sets +.Dv RES_NOTLDQUERY +in +.Ft _res.options . +This option causes +.Fn res_nsearch +to not attempt to resolve a unqualified name as if it were a top level +domain (TLD). +This option can cause problems if the site has "localhost" as a TLD rather +than having localhost on one or more elements of the search list. +This option has no effect if neither +.Dv RES_DEFNAMES +or +.Dv RES_DNSRCH +is set. .El .El .Pp diff --git a/contrib/bind/doc/man/tsig.3 b/contrib/bind/doc/man/tsig.3 index fa852ee..300527a 100644 --- a/contrib/bind/doc/man/tsig.3 +++ b/contrib/bind/doc/man/tsig.3 @@ -1,4 +1,4 @@ -.\" $Id: tsig.3,v 8.2 1999/01/08 18:54:28 vixie Exp $ +.\" $Id: tsig.3,v 8.3 2001/08/08 07:50:19 marka Exp $ .\" .\"Copyright (c) 1995-1999 by Internet Software Consortium .\" @@ -80,7 +80,7 @@ and .Fn ns_verify_tcp are used to sign/verify TCP messages that may be split into multiple packets, such as zone transfers, and -.Fn ns_sign_tcp_init, +.Fn ns_sign_tcp_init , .Fn ns_verify_tcp_init initialize the state structure necessary for TCP operations. .Fn ns_find_tsig -- cgit v1.1