.\" Hey, Emacs! This is an -*- nroff -*- source file.
-.TH CHIARK\-NAMED\-CONF 8 "30th December 2001" "Greenend" "chiark utilities"
+.TH CHIARK\-NAMED\-CONF 8 "12th January 2002" "Greenend" "chiark utilities"
.SH NAME
chiark\-named\-conf \- check and generate nameserver configuration
.SH SYNOPSIS
.B chiark\-named\-conf
is a tool for managing nameserver configurations and checking for
suspected DNS problems. Its main functions are to check that
-delegations are appropriate and working, and to generate a
-configuration for
+delegations are appropriate and working, that secondary zones are
+slaved from the right places, and to generate a configuration for
.BR BIND ,
from its own input file.
+
+By default, for each zone, in addition to any warnings, the output
+lists the zone's configuration type. If the zone is checked, the
+serial number at each of the nameservers is shown, with any
+unpublished primary having
+.B *
+after the serial number.
.SH OPTIONS
.SS MODE OPTIONS
.B ?
zone style modifier in the configuration.
.TP
-\fB\-C\fP|\-\-config \fIconfig\-file\fP
+.BR \-C | \-\-config " \fIconfig\-file\fP"
Use
.I config\-file
instead of
.BR -DD .)
.TP
.BR \-g | \-\-glueless
-Warn only once about a glueless referral for each zone and server,
-rather than once for each parent which gave out a referral without
-glue.
-
-When repeated, do not warn about glueless referrals at all. Not
-recommended. Note that glueless referrals usually cause extra delays
-looking up names, and can make lookups fail even if in theory they
-could succeed. There is no generally agreed convention or standard
-for avoiding circular glueless situations such as
-.br
-.B example.com NS ns0.example.net.uk
-.br
-.B example.com NS ns1.example.net.uk
-.br
-.B example.net.uk NS ns0.example.com
-.br
-.B example.net.uk NS ns1.example.com
-.br
-where gluelessness would completely prevent lookups inside
-example.net.uk and example.com. The best way to be sure to avoid this
-is to avoid gluelessness.
+Do not warn about glueless referrals. Not recommended - see
+the section GLUELESSNESS, below.
.TP
.BR \-l | \-\-local
Only checks for mistakes which are the responsibility of the local
not relevant to the local server); doing so produces a warning.
.TP
.BR \-q | \-\-quiet
-Do not print any information about zone(s) which do not have warnings.
+Suppress the usual report of the list of nameservers for each zone and
+the serial number from each. When specified twice, do not print any
+information except warnings.
+.TP
+.BR \-r | \-\-repeat
+When a problem is detected, warn for all sources of the same imperfect
+data, rather than only the first we come across
.TP
.BR \-v | \-\-verbose
-Print additional information about each zone.
+Print additional information about what is being checked, as we go
+along.
.SH USAGE
The file
.B /etc/bind/chiark-conf-gen.zones
are permitted. Leading and trailing whitespace on each line is
ignored. Comments are lines starting with
.BR # .
+Ending a line with a
+.BR \\
+joins it to the next line, so that long directives can be split across
+several physical lines.
.SS GENERAL DIRECTIVES
These directives specify general configuration details. They should
appear before directives specifying zones, as each will affect only
later zone directives.
.TP
-\fBself\-ns\fP \fIfqdn ...\fP
-Specifies the list of names that this server may be known by in NS
-records. There is no default.
-.TP
-\fBself\-soa\fP \fIfqdn ...\fP
-Specifies the list of names that this server may be known by in
-the ORIGIN field of SOA records. There is no default.
-.TP
-.BI self " fqdn ..."
-Equivalent to both
-.B self\-ns " and " self\-soa
-with the same set of names.
-.TP
-\fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
-Specifies the directory in which slave (published and stealth)
-zonefiles should be placed. The default
-.I directory
-is
-.BR /var/cache/bind/chiark-slave .
-The default
-.IR suffix " and " prefix
-are empty; they also will be reset to these defaults by a
-.B slave\-dir
-directive which does not specify them.
-.TP
\fBdefault\-dir\fP \fIdirectory\fP
Makes
.I directory
.B -C
option is specified.
.TP
+\fBforbid\-addr\fP [\fIip-address ...\fP]
+Specifies the list of addresses that are forbidden as any nameserver
+for any zone. The default is no such addresses.
+.TP
+\fBserverless\-glueless\fP \fIdomain ...\fP
+Specifies a list of domains under which we do not expect to find any
+nameservers; for these zones it is OK to find glueless referrals.
+Each domain listed names a complete subtree of the DNS, starting at
+the named point. The default is
+.BR "in\-addr.arpa ip6.arpa ip6.int" .
+
+To avoid indefinitely long or even circularly glueless referrals
+(which delay or prevent lookups) it is necessary for all sites to
+effectively implement similar conventions; currently the author
+believes that only the reverse lookup namespaces are conventionally
+devoid of nameservers, and therefore fine to provide glueless
+referrals for. See GLUELESSNESS below.
+.TP
\fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
Arranges that each
.I filename
configuration before the first
.B output
directive.
+.TP
+\fBself\-addr\fP \fIip-address ...\fP
+Specifies the list of addresses that this server may be known by in
+A records. There is no default.
+.TP
+\fBself\-ns\fP \fIfqdn ...\fP
+Specifies the list of names that this server may be known by in NS
+records. There is no default.
+.TP
+\fBself\-soa\fP \fIfqdn ...\fP
+Specifies the list of names that this server may be known by in
+the ORIGIN field of SOA records. There is no default.
+.TP
+.BI self " fqdn ..."
+Equivalent to both
+.B self\-ns " and " self\-soa
+with the same set of names.
+.TP
+\fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
+Specifies the directory in which slave (published and stealth)
+zonefiles should be placed. The default
+.I directory
+is
+.BR /var/cache/bind/chiark-slave .
+The default
+.IR suffix " and " prefix
+are empty; they also will be reset to these defaults by a
+.B slave\-dir
+directive which does not specify them.
.SS ZONE DIRECTIVES
These directives specify one or more zones.
.TP
and that the zone data is to be found in
.IR filename .
.TP
-.BR primary\-dir [ * | ? "] \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]"
+.BR primary\-dir [ * | ? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
Search
.I directory
-for files whose names match the glob pattern
-.IR suffix * prefix .
-Each such file is taken to represent a zone file for which this server
-is supposed to be the primary. * is the name of the zone. The
-default for
-.I suffix
-is
-.BR _db ;
-the default for
+for files whose names start with
.I prefix
-is empty.
+and end with
+.IR suffix .
+Each such file is taken to represent a zone file for which this server
+is supposed to be the primary; the part of the filename between
+.IR prefix " and " suffix
+is the name of the zone.
+
+If
+.BI / subfile
+is specified, then instead of looking for files, we search for
+directories containing
+.IR subfile ;
+directories which do not contain the subfile are simply skipped.
+
+If
+.IR directory [\fB/\fP prefix ]
+exists as specified and is a directory then it is interpreted as
+.I directory
+with an empty prefix; otherwise the final path component is assumed to
+be the prefix. If no
+.IB suffix / subfile
+is specified then the default is
+.BR _db .
.TP
.BR published [ * | ? "] \fIzone origin\-addr\fP"
Specifies that this server is supposed to be a published slave
Origin server's data: The set of nameservers in the origin server's
version of the zone should be a superset of those in the delegations.
-Our zone configuration: For
-.B primary
-zones, the SOA origin should be one of the names specified with
-.BR self\-soa " (or " self ). For
-.B published
-zones, the address should be that of the SOA origin. For
-.B stealth
-zones, the address should be that of the SOA origin or one of the
-published nameservers.
+Our zone configuration: For primary zones, the SOA origin should be
+one of the names specified with
+.BR self\-soa " (or " self ).
+For published zones, the address should be that of the SOA origin.
+For stealth zones, the address should be that of the SOA origin or one
+of the published nameservers.
+.SH GLUELESSNESS
+Glue is the name given for the addresses of nameservers which are
+often supplied in a referral. In fact, it turns out that it is
+important for the reliability and performance of the DNS that
+referrals, in general, always come with glue.
+
+Firstly, glueless referrals usually cause extra delays looking up
+names. BIND 8, when it receives a completely glueless referral and
+does not have the nameservers' addresses in its cache, will start
+queries for the nameserver addresses; but it will throw the original
+client's question away, so that when these queries arrive, it won't
+restart the query from where it left off. This means that the client
+won't get its answer until it retries, typically at least 1 second
+later - longer if you have more than one nameserver listed. Worse, if
+the nameserver to which the glueless referral points is itself under
+another glueless referral, another retry will be required.
+
+Even for better resolvers than BIND 8, long chains of glueless
+referrals can cause performance and reliability problems, turning a
+simple two or three query exchange into something needing more than a
+dozen queries.
+
+Even worse, one might accidentally create a set of circularly glueless
+referrals such as
+.br
+.B example.com NS ns0.example.net.uk
+.br
+.B example.com NS ns1.example.net.uk
+.br
+.B example.net.uk NS ns0.example.com
+.br
+.B example.net.uk NS ns1.example.com
+.br
+Here it is impossible to look up anything in either example.com or
+example.net.uk.
+
+There are, as far as the author is aware, no generally agreed
+conventions or standards for avoiding unreasonably long glueless
+chains, or even circular glueless situations. The only way to
+guarantee that things will work properly is therefore to always supply
+glue.
+
+However, the situation is further complicated by the fact that many
+implementations (including BIND 8.2.3, and many registry systems),
+will refuse to accept glue RRs for delegations in a parent zonefile
+unless they are under the parent's zone apex. In these cases it can
+be necessary to create names for the child's nameservers which are
+underneath the child's apex, so that the glue records are both in the
+parent's bailiwick and obviously necessary.
+
+Even worse, the horrid `shared registry system' managing .com, .net
+and .org does not allow a single IPv4 address to be used for more than
+one nameserver name! It does, however, give out glue for any
+nameserver properly registered in the system. I therefore recommend
+that you create a single name for your nameserver somewhere
+in .com, .net or .org, and use that for all the delegations
+from .com, .net and .org. At the time of writing (January 2002) this
+seems to produce correct and glueful referrals.
+
+Finally, a note about `reverse' zones, such as those in in-addr.arpa:
+It does not seem at all common practice to create nameservers in
+in-addr.arpa zones (ie, no NS RRs seem to point into in-addr.arpa,
+even those for in-addr.arpa zones). Current practice seems to be to
+always use nameservers for in-addr.arpa which are in the normal,
+forward, address space. If everyone sticks to the rule of always
+publishing nameservers names in the `main' part of the namespace, and
+publishing glue for them, there is no chance of anything longer than a
+1-step glueless chain might occur for a in-addr.arpa zone. It is
+probably best to maintain this as the status quo, despite the
+performance problem this implies for BIND 8 caches. This is what the
+serverless\-glueless directive is for.
+
+Dan Bernstein has some information and examples about this at
+.UR http://cr.yp.to/djbdns/notes.html#gluelessness
+http://cr.yp.to/djbdns/notes.html#gluelessness
+.UE
+but be warned that it is rather opinionated.
.SH SECURITY
chiark\-named\-conf is supposed to be resistant to malicious data in
the DNS. It is not resistant to malicious data in its own options,
Avoid messing with these if possible.
.LP
.B PATH
-Used to find subprograms such as
+is used to find subprograms such as
.BR dig " and " adnshost .
.SH BUGS
The determination of the parent zone for each zone to be checked, and
failures.
.SH AUTHOR
.B chiark\-named\-conf
-and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.
+and this manpage were written by Ian Jackson
+<ian@chiark.greenend.org.uk>. They are Copyright 2002 Ian Jackson.
+
+chiark\-named\-conf and this manpage are free software; you can
+redistribute it and/or modify it under the terms of the GNU General
+Public License as published by the Free Software Foundation; either
+version 2, or (at your option) any later version.
+
+This is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
~ian / chiark-utils.git / blobdiff