Working on new options -C and -g etc.

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

diff --git a/scripts/named-conf.8 b/scripts/named-conf.8
index 457d1521f79dd842a484033edbd7b9298d410bc7..4b41c02255bf24109d3d5685c80766ff58d21913 100644 (file)
--- a/scripts/named-conf.8
+++ b/scripts/named-conf.8
@@ -2,12 +2,10 @@
 .TH CHIARK\-NAMED\-CONF 8 "30th December 2001" "Greenend" "chiark utilities"
 .SH NAME
 chiark\-named\-conf \- check and generate nameserver configuration
-
 .SH SYNOPSIS
-.B chiark\-named\-conf [\fIoptions\fP] \-n|\-y|\-f
+.BR chiark\-named\-conf " [\fIoptions\fP] " \-n | \-y | \-f
 .br
-.B chiark\-named\-conf [\fIoptions\fP] \fIzone ...\fP
-
+\fBchiark\-named\-conf\fP [\fIoptions\fP] \fIzone ...\fP
 .SH DESCRIPTION
 .B chiark\-named\-conf
 is a tool for managing nameserver configurations and checking for
@@ -16,8 +14,8 @@ delegations are appropriate and working, and to generate a
 configuration for
 .BR BIND ,
 from its own input file.
-
 .SH OPTIONS
+
 .SS MODE OPTIONS
 If one of the options
 .BR -n ", " -y ", or " -f
@@ -56,13 +54,43 @@ instead of
 .BR \-q | \-\-quiet
 Do not print any information about zone(s) which do not have warnings.
 .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, unless the
+.B \-l
+option is repeated.  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), so this counts as a warning.
+.TP
 .BR \-v | \-\-verbose
 Print additional information about each zone.
 .TP
+.BR \-g | \-\-glueless-ok
+Do not warn about glueless referrals.  Not recommended.  Note that
+glueless referrals usually causes extra delays looking up names, and
+can cause lookups to 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.
+.TP
 .BR \-D
 Enables debugging.  Useful for debugging chiark\-named\-conf, but
 probably not useful for debugging your DNS configuration.
-.SH CONFIGURATION
+.SH USAGE
 The file
 .B /etc/bind/chiark-conf-gen.zones
 (or other file specified with the
@@ -84,9 +112,9 @@ records.  There is no default.
 Specifies the list of names that this server may be known by in
 the ORIGIN field of SOA records.  There is no default.
 .TP
-\fBself\fP \fIfqdn ...\fP
+.BI self " fqdn ..."
 Equivalent to both
-.BR self\-ns " and " self-\soa
+.B self\-ns " and " self\-soa
 with the same set of names.
 .TP
 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
@@ -218,6 +246,15 @@ Default output file.
 .TP
 .B /var/cache/bind/chiark-slave
 Default location for slave zones.
+.SH BUGS
+The determination of the parent zone for each zone to be checked, and
+its nameservers, is done simply using the system default nameserver.
+
+The processing of output from
+.B dig
+is not very reliable or robust, but this is mainly the fault of dig.
+This can lead to somewhat unhelpful error reporting for lookup
+failures.
 .SH AUTHOR
 .B chiark\-named\-conf
 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.