X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=chiark-utils.git;a=blobdiff_plain;f=scripts%2Fnamed-conf.8;h=ef7dcb60dd2978dd75317ef688ce139ba29614a3;hp=d4639f202ef76c35fb79fccec9a29128d10d1ef7;hb=7b2bcecc03b61eb95d5ab7820dd970ec3afdbfc9;hpb=080e68c9adee644e6923e3d6f4ad3cd4102efea7

diff --git a/scripts/named-conf.8 b/scripts/named-conf.8
index d4639f2..ef7dcb6 100644
--- a/scripts/named-conf.8
+++ b/scripts/named-conf.8
@@ -14,6 +14,13 @@ delegations are appropriate and working, 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
@@ -64,15 +71,11 @@ increase the debugging level.  (Maximum is
 .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
+Do not warn about glueless referrals.  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
@@ -97,10 +100,17 @@ with foreign zones (zones supplied explictly on the command line but
 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
@@ -110,40 +120,15 @@ option) contains a sequence of directives, one per line.  Blank lines
 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\-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.
-.TP
 \fBdefault\-dir\fP \fIdirectory\fP
 Makes
 .I directory
@@ -155,6 +140,24 @@ if no
 .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.
+.TP
 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 Arranges that each
 .I filename
@@ -176,6 +179,35 @@ otherwise it is an error for there to be any zones in the
 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
@@ -186,20 +218,34 @@ for
 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