chiark / gitweb /
Show IP addr in report.
[chiark-utils.git] / scripts / named-conf.8
index 450c4c4..ef7dcb6 100644 (file)
@@ -14,6 +14,13 @@ delegations are appropriate and working, and to generate a
 configuration for
 .BR BIND ,
 from its own input file.
 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
 .SH OPTIONS
 
 .SS MODE OPTIONS
@@ -50,7 +57,7 @@ Checks even zones known to be broken.  Ie, ignores the
 .B ?
 zone style modifier in the configuration.
 .TP
 .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
 Use
 .I config\-file
 instead of
@@ -64,15 +71,11 @@ increase the debugging level.  (Maximum is
 .BR -DD .)
 .TP
 .BR \-g | \-\-glueless
 .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
 .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
 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
 .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
 .SH USAGE
 The file
 .B /etc/bind/chiark-conf-gen.zones
@@ -110,36 +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 # .
 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
 .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
 \fBdefault\-dir\fP \fIdirectory\fP
 Makes
 .I directory
@@ -151,6 +140,24 @@ if no
 .B -C
 option is specified.
 .TP
 .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
 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 Arranges that each
 .I filename
@@ -172,6 +179,35 @@ otherwise it is an error for there to be any zones in the
 configuration before the first
 .B output
 directive.
 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
 .SS ZONE DIRECTIVES
 These directives specify one or more zones.
 .TP
@@ -182,20 +218,34 @@ for
 and that the zone data is to be found in
 .IR filename .
 .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
 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
 .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
 .TP
 .BR published [ * | ? "] \fIzone origin\-addr\fP"
 Specifies that this server is supposed to be a published slave
@@ -250,15 +300,12 @@ always give the same addresses.
 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.
 
 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 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,
 .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,
@@ -304,7 +351,7 @@ will affect the operation of chiark\-named\-conf.
 Avoid messing with these if possible.
 .LP
 .B PATH
 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
 .BR dig " and " adnshost .
 .SH BUGS
 The determination of the parent zone for each zone to be checked, and