Suppress repetition.

[chiark-utils.git] / scripts / named-conf.8

diff --git a/scripts/named-conf.8 b/scripts/named-conf.8
index 864324e1dd4c363a7adb28919acf911a74d1ab54..d7887085775bd7f63a04bdc4b8c7e5ef5575404a 100644 (file)
--- a/scripts/named-conf.8
+++ b/scripts/named-conf.8
@@ -45,7 +45,12 @@ no new configuration file for the nameserver will be made.
 
 .SS ADDITIONAL OPTIONS
 .TP
 
 .SS ADDITIONAL OPTIONS
 .TP

-\fB\-C\fP|\-\-config \fIconfig\-file\fP
+.BR \-A | \-\-all
+Checks even zones known to be broken.  Ie, ignores the
+.B ?
+zone style modifier in the configuration.
+.TP
+.BR \-C | \-\-config " \fIconfig\-file\fP"

 Use
 .I config\-file
 instead of
 Use
 .I config\-file
 instead of


@@ -79,9 +84,10 @@ is to avoid gluelessness.
 .TP
 .BR \-l | \-\-local
 Only checks for mistakes which are the responsibility of the local
 .TP
 .BR \-l | \-\-local
 Only checks for mistakes which are the responsibility of the local

-administrator.  This means that for secondary and stealth zones we
-only check that we're slaving from the right place.  For primary zones
-all checks are still done.  It is a mistake to specify
+administrator (to fix or get fixed).  This means that for published
+and stealth zones we only check that we're slaving from the right
+place and that any names and addresses for ourself are right.  For
+primary zones all checks are still done.  It is a mistake to specify

 .B \-l
 with foreign zones (zones supplied explictly on the command line but
 not relevant to the local server); doing so produces a warning.
 .B \-l
 with foreign zones (zones supplied explictly on the command line but
 not relevant to the local server); doing so produces a warning.


@@ -89,6 +95,10 @@ not relevant to the local server); doing so produces a warning.
 .BR \-q | \-\-quiet
 Do not print any information about zone(s) which do not have warnings.
 .TP
 .BR \-q | \-\-quiet
 Do not print any information about zone(s) which do not have 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.
 .SH USAGE
 .BR \-v | \-\-verbose
 Print additional information about each zone.
 .SH USAGE


@@ -100,36 +110,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 (secondary 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


@@ -141,6 +130,10 @@ 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

 \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


@@ -162,38 +155,98 @@ 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

-\fBprimary\fP \fIzone\fP \fIfilename\fP
+.BR primary [ * | ? "] \fIzone filename\fP"

 Specifies that this server is supposed to be the primary nameserver
 for
 .I zone
 and that the zone data is to be found in
 .IR filename .
 .TP
 Specifies that this server is supposed to be the primary nameserver
 for
 .I zone
 and that the zone data is to be found in
 .IR filename .
 .TP

-\fBprimary-dir\fP \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
 .TP

-\fBsecondary\fP \fIzone\fP \fIorigin\-addr\fP
-Specifies that this server is supposed to be a published secondary for
-the zone in question.
+.BR published [ * | ? "] \fIzone origin\-addr\fP"
+Specifies that this server is supposed to be a published slave
+nameserver for the zone in question.

 .TP
 .TP

-\fBstealth\fP \fIzone\fP \fIserver\-addr ...\fP
+.BR stealth [ * | ? "] \fIzone server\-addr ...\fP"

 Specifies that this server is supposed to be an unpublished secondary
 (aka stealth secondary) for the zone in question.
 Specifies that this server is supposed to be an unpublished secondary
 (aka stealth secondary) for the zone in question.

+.SS ZONE DIRECTIVE STYLE MODIFIERS
+Each of the zone directives may optionally be followed by one of the
+following characters:
+.TP
+.B *
+Indicates that the zone is unofficial, ie that it is not delegated as
+part of the global Internet DNS and that no attempt should be made to
+find the superzone and check delegations.  Note that unofficial, local
+zones should be created with caution.  They should be in parts of the
+namespace which are reserved for private use, or belong to the actual
+zone maintainer.
+.TP
+.B ?
+Indicates that the zone is known to be broken and no checks should be
+carried out on it, unless the
+.B \-A
+option is specified.

 .SS OTHER DIRECTIVES
 .TP
 \fBinclude\fP \fIfile\fP
 .SS OTHER DIRECTIVES
 .TP
 \fBinclude\fP \fIfile\fP


@@ -223,15 +276,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 secondary
-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,


@@ -277,7 +327,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