Halfway through new features.

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

diff --git a/scripts/named-conf.8 b/scripts/named-conf.8
index a75dd7fb440cf445763c94d915ef92946330579f..85d93982daaf29494fe48a41b45fe9e02c9d5b30 100644 (file)
--- a/scripts/named-conf.8
+++ b/scripts/named-conf.8
@@ -1,5 +1,5 @@
 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
 .\" 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
 .SH NAME
 chiark\-named\-conf \- check and generate nameserver configuration
 .SH SYNOPSIS


@@ -10,8 +10,8 @@ chiark\-named\-conf \- check and generate nameserver configuration
 .B chiark\-named\-conf
 is a tool for managing nameserver configurations and checking for
 suspected DNS problems.  Its main functions are to check that
 .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.
 
 .BR BIND ,
 from its own input file.
 


@@ -44,6 +44,20 @@ do not generate new nameserver config.
 Generate and install new nameserver config, without doing any
 configuration cross-checking.  (Syntax errors in our input
 configuration will still abort this operation.)
 Generate and install new nameserver config, without doing any
 configuration cross-checking.  (Syntax errors in our input
 configuration will still abort this operation.)

+.TP
+.BR \-\-nothing
+Do nothing: do no checks, and don't write a new config.  This can be
+used to get a list of the zones being processed.
+.TP
+.BR \-\-mail\-first " | " \-\-mail\-middle " | " \-\-mail\-final
+Send mails to zone SOA MNAMEs reporting zones with problems.  You must
+call chiark\-named\-conf at least twice, once with \-\-mail\-first,
+and later with \-\-mail\-final, and preferably with one or more calls
+to \-\-mail\-middle in between.  All three options carry out a check
+and store the results; \-\-mail\-final also sends a mail to the zone
+SOA MNAME or local administrator, if too many of the calls had errors
+or warnings (calls before the most recent \-\-mail\-first being
+ignored).

 .LP
 Alternatively, one or more zone names may be supplied as arguments, in
 which case their delegations will be checked, and compared with the
 .LP
 Alternatively, one or more zone names may be supplied as arguments, in
 which case their delegations will be checked, and compared with the


@@ -114,6 +128,11 @@ These directives specify general configuration details.  They should
 appear before directives specifying zones, as each will affect only
 later zone directives.
 .TP
 appear before directives specifying zones, as each will affect only
 later zone directives.
 .TP

+\fBadmin\fP \fIemail\-address\fP
+Specifies the email address of the local administrator.  This is used
+in the From: line of mails sent out, and will also receive copies of
+the reports.  There is no default.
+.TP

 \fBdefault\-dir\fP \fIdirectory\fP
 Makes
 .I directory
 \fBdefault\-dir\fP \fIdirectory\fP
 Makes
 .I directory


@@ -143,6 +162,20 @@ believes that only the reverse lookup namespaces are conventionally
 devoid of nameservers, and therefore fine to provide glueless
 referrals for.  See GLUELESSNESS below.
 .TP
 devoid of nameservers, and therefore fine to provide glueless
 referrals for.  See GLUELESSNESS below.
 .TP

+\fBmail\-state\-dir\fP \fIdirectory\fP
+Uses
+.I directory
+for storing information about recent failures for mailing to zone
+admins.  See \-\-mail\-first et al.  Old files in here should be
+cleaned up periodically out of cron.  There is no default.
+.TP
+\fBmail\-max\-warnfreq\fP \fIpercentage\fP
+When \-\-mail\-final is used, a mail will be sent to all zones which
+had warnings or errors more than
+.IR percentage %
+of the times \-\-mail\-* was used (since the last \-\-mail\-first).
+The default is 50%.
+.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


@@ -171,11 +204,18 @@ 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
 .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.
+records.  There is no default.  Any trailing * is replaced by the name
+of the zone being checked, so for example
+.B self\-ns isp.ns.*
+before the zone example.com would mean to expect us to be listed as
+isp.ns.example.com
+in the NS RRset.

 .TP
 \fBself\-soa\fP \fIfqdn ...\fP
 Specifies the list of names that this server may be known by in
 .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.
+the ORIGIN field of SOA records.  There is no default.  Any trailing
+* is replaced by the name of the zone, as for
+.BR self\-ns .

 .TP
 .BI self " fqdn ..."
 Equivalent to both
 .TP
 .BI self " fqdn ..."
 Equivalent to both


@@ -196,14 +236,14 @@ 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

-.BR primary [ * | ? "] \fIzone filename\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

-.BR primary\-dir [ * | ? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
+.BR primary\-dir [ * | ? | @ | @@ | ~ "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]

 Search
 .I directory
 for files whose names start with
 Search
 .I directory
 for files whose names start with


@@ -232,16 +272,16 @@ be the prefix.  If no
 is specified then the default is
 .BR _db .
 .TP
 is specified then the default is
 .BR _db .
 .TP

-.BR published [ * | ? "] \fIzone origin\-addr\fP"
+.BR published [ * | ? | @ | @@ | ~ "] \fIzone origin\-addr\fP"

 Specifies that this server is supposed to be a published slave
 nameserver for the zone in question.
 .TP
 Specifies that this server is supposed to be a published slave
 nameserver for the zone in question.
 .TP

-.BR stealth [ * | ? "] \fIzone server\-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.
 .SS ZONE DIRECTIVE STYLE MODIFIERS
 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:
+Each of the zone directives may optionally be followed by one or more
+of the following characters:

 .TP
 .B *
 Indicates that the zone is unofficial, ie that it is not delegated as
 .TP
 .B *
 Indicates that the zone is unofficial, ie that it is not delegated as


@@ -251,6 +291,19 @@ 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
 namespace which are reserved for private use, or belong to the actual
 zone maintainer.
 .TP

+.B @
+Indicates that mails should be sent about the zone to the nameserver
+admin rather than to the zone SOA MNAME.  This is always done for
+stealth zones.
+.TP
+.B @@
+Indicates that no mails should be sent about the zone to anyone.
+.TP
+.B ~
+Indicates that the zone's delegation is known to be glueless, and that
+lack of glue should not be flagged.  Not recommended - see the section
+GLUELESSNESS, below.
+.TP

 .B ?
 Indicates that the zone is known to be broken and no checks should be
 carried out on it, unless the
 .B ?
 Indicates that the zone is known to be broken and no checks should be
 carried out on it, unless the


@@ -426,4 +479,19 @@ This can lead to somewhat unhelpful error reporting for lookup
 failures.
 .SH AUTHOR
 .B chiark\-named\-conf
 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.