.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
configuration for
.BR BIND ,
from its own input file.
-
.SH OPTIONS
+
.SS MODE OPTIONS
If one of the options
.BR -n ", " -y ", or " -f
.SS ADDITIONAL OPTIONS
.TP
+.BR \-A | \-\-all
+Checks even zones known to be broken. Ie, ignores the
+.B ?
+zone style modifier in the configuration.
+.TP
\fB\-C\fP|\-\-config \fIconfig\-file\fP
Use
.I config\-file
instead of
.BR /etc/bind/chiark-conf-gen.zones .
+Also changes the default directory.
+.TP
+.BR \-D
+Enables debugging. Useful for debugging chiark\-named\-conf, but
+probably not useful for debugging your DNS configuration. Repeat to
+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
+.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 \-l | \-\-local
+Only checks for mistakes which are the responsibility of the local
+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.
.TP
.BR \-q | \-\-quiet
Do not print any information about zone(s) which do not have warnings.
.TP
.BR \-v | \-\-verbose
Print additional information about each zone.
-.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
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]
-Specifies the directory in which slave (secondary and stealth)
+Specifies the directory in which slave (published and stealth)
zonefiles should be placed. The default
.I directory
is
.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
-\fBprimary-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
+.BR primary\-dir [ * | ? "] \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]"
Search
.I directory
for files whose names match the glob pattern
.I prefix
is empty.
.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
-\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.
+.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
.B primary
zones, the SOA origin should be one of the names specified with
.BR self\-soa " (or " self ). For
-.B secondary
+.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.
+.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,
+configuration file or environment. It is not supposed to read its
+stdin, but is not guaranteed to be safe if stdin is dangerous.
+.LP
+Killing chiark-named-conf suddenly should be safe, even with
+.BR -y " or " -f
+(though of course it may not complete its task if killed), provided
+that only one invocation is made at once.
+.LP
+Slow remote nameservers will cause chiark-named-conf to take
+excessively long.
+.SH EXIT STATUS
+.TP
+.B 0
+All went well and there were no warnings.
+.TP
+any other
+There were warnings or errors.
.SH FILES
.TP
.B /etc/bind/chiark-conf-gen.zones
.TP
.B /var/cache/bind/chiark-slave
Default location for slave zones.
+.SH ENVIRONMENT
+.LP
+Setting variables used by
+.BR dig (1)
+and
+.BR adnshost (1)
+will affect the operation of chiark\-named\-conf.
+Avoid messing with these if possible.
+.LP
+.B PATH
+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
+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>.
~ian / chiark-utils.git / blobdiff