Provided by: chiark-scripts_4.4.2build1_all 
NAME
chiark-named-conf - check and generate nameserver configuration
SYNOPSIS
chiark-named-conf [options] -n|-y|-f
chiark-named-conf [options] zone ...
DESCRIPTION
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, that secondary zones are slaved from the right places, and to generate a
configuration for 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 * after the serial number.
OPTIONS
MODE OPTIONS
If one of the options -n, -y, or -f is supplied then chiark-named-conf will read its main
configuration file for the list of relevant zones. It will then check the configuration
and delegation for each zone and/or generate and install a new configuration file for the
nameserver:
-y|--yes
Generate and install new nameserver config, as well as checking configuration, for
all listed zones.
-n|--no
Check configuration, for all listed zones, but do not generate new nameserver
config.
-f|--force
Generate and install new nameserver config, without doing any configuration cross-
checking. (Syntax errors in our input configuration will still abort this
operation.)
--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.
--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).
-mail-final-test
just like --mail-final except that it always sends mail to the local server admin
and never to remote zone contacts, adding (testing!) to the start of the To:
field.
Alternatively, one or more zone names may be supplied as arguments, in which case their
delegations will be checked, and compared with the data for that zone in the main
configuration (if any). In this case no new configuration file for the nameserver will be
made.
ADDITIONAL OPTIONS
-A|--all
Checks even zones known to be broken. Ie, ignores the ? zone style modifier in
the configuration.
-C|--config config-file
Use config-file instead of /etc/bind/chiark-conf-gen.zones. Also changes the
default directory.
-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 -DD.)
-g|--glueless
Do not warn about glueless referrals (strictly, makes the zone style modifier ~ the
default). Not recommended - see the section GLUELESSNESS, below.
-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 -l with foreign zones (zones supplied explictly on the command line but
not relevant to the local server); doing so produces a warning.
-mgroup!*$@~?
Overrides a modifiers directive in the configuration file. The modifiers specified
in the directive are completely replaced by those specified in this command line
option. (Note that modifiers specified in per-zone directives still override these
per-group settings.) If more than one modifiers directive specifies the same
group, they are all affected. modifiers directives which don't specify a group
cannot be affected. It is an error if the group does not appear in the config
file. See ZONE STYLE MODIFIERS, below.
The special group foreign is used for zones which don't appear in the configuration file.
-q|--quiet
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.
-r|--repeat
When a problem is detected, warn for all sources of the same imperfect data, rather
than only the first we come across
-v|--verbose
Print additional information about what is being checked, as we go along.
USAGE
The file /etc/bind/chiark-conf-gen.zones (or other file specified with the -C 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 #. Ending
a line with a .ft R joins it to the next line, so that long directives can be split across
several physical lines.
GENERAL DIRECTIVES
These directives specify general configuration details. They should appear before
directives specifying zones, as each will affect only later zone directives. Foreign
zones (zones explicitly specified on the command line but not mentioned in the
configuration) use the configuration settings prevailing at the end of the config file.
admin email-address
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.
default-dir directory
Makes directory be the default directory (which affects the interpretation of
relative filenames). The default is the directory containing the main
configuration file, ie /etc/bind if no -C option is specified.
forbid-addr [ip-address ...]
Specifies the list of addresses that are forbidden as any nameserver for any zone.
The default is no such addresses.
forbid-addr [ip-address ...]
Specifies the list of addresses that are forbidden as a nameserver for a zone for
which we are the primary - ie, the list of our old or to-be-obsoleted slaves. The
default is no such addresses.
serverless-glueless domain ...
Specifies a list of domains under which we do not expect to find any nameservers
without glue; 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 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 (glueless) nameservers, and therefore fine to provide
glueless referrals for. See GLUELESSNESS below.
allow--indirect-glue nameserver-superdomain ...
Specifies a list of domains under which we expect to find glueless nameservers,
with up to one layer of indirection. For nameservers under these domains it is OK
to to find glueless referrals, but only when listed as a nameserver for a zone
which is not itself a subdomain of an allow-indirect-glue nameserver-superdomain.
This supports to common configuration style where DNS operator(s) set up all of
their nameservers with names within a small subsection of the DNS (the portions
under nameserver-superdomains), and provide glueless referrals naming these
nameservers for all other zones. This provides at most one level of missing glue.
Note that if the DNS administrators collectively able to influence the service for
some zone (including the admins for its superzones, the zones containing its
nameservers, and their superzones and so forth) are not in sufficiently close
communication do not all agree on the proper set of nameserver-superdomain then
they might still set up circular glue and chiark-named-conf would not necessarily
be able to detect this even if it was run on every relevant nameserver.
mail-state-dir directory
Uses 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.
mail-max-warnfreq percentage
When --mail-final is used, a mail will be sent to all zones which had warnings or
errors more than percentage% of the times --mail-* was used (since the last
--mail-first). The default is 50%.
modifiers !*$@~?] [group]
Applies the specified zone style modifiers (see below) to subsequently declared
zones (until the next modifiers directive), as if the modifiers specified were
written out for each zone. You must specify at least one character for the
modifiers; if you want to reset everything to the default, just say !. If style
modifiers specified in the zone directive conflict with the modifiers directive,
those specified in the zone directive take effect. group may contain alphanumerics
and underscores, and is used for the -m command-line option.
self-addr ip-address ...
Specifies the list of addresses that this server may be known by in A records.
There is no default.
output format filename [format filename ...]
Arranges that each filename will be overwritten when -y or -f are used; its new
contents will be configuration directives for the zones which follow for the
nameserver in question. Currently the only format supported is bind8 which
indicates new-style BIND 8. If no zones follow, then each file will still be
overwritten, by an effectively empty file. Default: if there is no output
directive in the configuration then the default is to use bind8 chiark-conf-
gen.bind8; otherwise it is an error for there to be any zones in the configuration
before the first output directive.
self-ns fqdn ...
Specifies the list of names that this server may be known by in NS records. There
is no default. Any trailing * is replaced by the name of the zone being checked,
so for example 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.
self-soa fqdn ...
Specifies the list of names that this server may be known by in the ORIGIN field of
SOA records. There is no default. Any trailing * is replaced by the name of the
zone, as for self-ns.
self fqdn ...
Equivalent to both self-ns and self-soa with the same set of names.
slave-dir directory [[prefix] suffix]
Specifies the directory in which slave (published and stealth) zonefiles should be
placed. The default directory is /var/cache/bind/chiark-slave. The default suffix
and prefix are empty; they also will be reset to these defaults by a slave-dir
directive which does not specify them.
ZONE DIRECTIVES
These directives specify one or more zones.
primary[!*$@~?] zone filename
Specifies that this server is supposed to be the primary nameserver for zone and
that the zone data is to be found in filename.
primary-dir[!*$@~?] directory[/prefix] [suffix[/subfile]]
Search directory for files whose names start with prefix and end with 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 prefix and suffix is the name of the
zone.
If /subfile is specified, then instead of looking for files, we search for
directories containing subfile; directories which do not contain the subfile are
simply skipped.
If directory[/prefix] exists as specified and is a directory then it is interpreted
as directory with an empty prefix; otherwise the final path component is assumed to
be the prefix. If no suffix/subfile is specified then the default is _db.
published[!*$@~?] zone origin-addr
Specifies that this server is supposed to be a published slave nameserver for the
zone in question.
stealth[!*$@~?] zone server-addr ...
Specifies that this server is supposed to be an unpublished secondary (aka stealth
secondary) for the zone in question.
ZONE STYLE MODIFIERS
Each of the zone directives may optionally be followed by one or more of the following
characters (each at most once):
! Reverses the meaning of all style modifiers after the !. Only one ! must appear
in the modifier list. In this list, other modifiers which default to `enabled' are
described by describing the effect of their inverse - see the description for !@
below.
* 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.
$ Indicates that any mails should be sent about the zone to the nameserver admin
rather than to the zone SOA MNAME. This is the default unless we are supposedly a
published server for the zone.
!@ Indicates that no mails should be sent about the zone to anyone.
~ 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.
? Indicates that the zone is known to be broken and no checks should be carried out
on it, unless the -A option is specified.
OTHER DIRECTIVES
include file
Reads file as if it were included here.
end Ends processing of this file; any data beyond this point is ignored.
CHECKS
chiark-named-conf makes the following checks:
Delegations: Each delegation from a server for the superzone should contain the same set
of nameservers. None of the delegations should lack glue. The glue addresses should be
the same in each delegation, and agree with the local default nameserver.
Delegated servers: Each server mentioned in the delegation should have the same SOA record
(and obviously, should be authoritative).
All published nameservers - including delegated servers and servers named in the zone's
nameserver set: All nameservers for the zone should supply the same list of nameservers
for the zone, and none of this authority information should be glueless. All the glue
should 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.
Our zone configuration: For primary zones, the SOA origin should be one of the names
specified with 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.
GLUELESSNESS
Glue is the name given for the addresses of nameservers which are often supplied in a
referral. In fact, it turns out that it is important for the reliability and performance
of the DNS that referrals, in general, always come with glue.
Firstly, glueless referrals usually cause extra delays looking up names. BIND 8, when it
receives a completely glueless referral and does not have the nameservers' addresses in
its cache, will start queries for the nameserver addresses; but it will throw the original
client's question away, so that when these queries arrive, it won't restart the query from
where it left off. This means that the client won't get its answer until it retries,
typically at least 1 second later - longer if you have more than one nameserver listed.
Worse, if the nameserver to which the glueless referral points is itself under another
glueless referral, another retry will be required.
Even for better resolvers than BIND 8, long chains of glueless referrals can cause
performance and reliability problems, turning a simple two or three query exchange into
something needing more than a dozen queries.
Even worse, one might accidentally create a set of circularly glueless referrals such as
example.com NS ns0.example.net.uk
example.com NS ns1.example.net.uk
example.net.uk NS ns0.example.com
example.net.uk NS ns1.example.com
Here it is impossible to look up anything in either example.com or example.net.uk.
There are, as far as the author is aware, no generally agreed conventions or standards for
avoiding unreasonably long glueless chains, or even circular glueless situations. The
only way to guarantee that things will work properly is therefore to always supply glue.
However, the situation is further complicated by the fact that many implementations
(including BIND 8.2.3, and many registry systems), will refuse to accept glue RRs for
delegations in a parent zonefile unless they are under the parent's zone apex. In these
cases it can be necessary to create names for the child's nameservers which are underneath
the child's apex, so that the glue records are both in the parent's bailiwick and
obviously necessary.
In the past, the `shared registry system' managing .com, .net and .org did not allow a
single IPv4 address to be used for more than one nameserver name. However, at the time of
writing (October 2002) this problem seems to have been fixed, and the workaround I
previously recommended (creating a single name for your nameserver somewhere in .com, .net
or .org, and using that for all the delegations from .com, .net and .org) should now be
avoided.
Finally, a note about `reverse' zones, such as those in in-addr.arpa: It does not seem at
all common practice to create nameservers in in-addr.arpa zones (ie, no NS RRs seem to
point into in-addr.arpa, even those for in-addr.arpa zones). Current practice seems to be
to always use nameservers for in-addr.arpa which are in the normal, forward, address
space. If everyone sticks to the rule of always publishing nameservers names in the
`main' part of the namespace, and publishing glue for them, there is no chance of anything
longer than a 1-step glueless chain might occur for a in-addr.arpa zone. It is probably
best to maintain this as the status quo, despite the performance problem this implies for
BIND 8 caches. This is what the serverless-glueless directive is for.
Dan Bernstein has some information and examples about this at
http://cr.yp.to/djbdns/notes.html#gluelessness
⟨http://cr.yp.to/djbdns/notes.html#gluelessness⟩ but be warned that it is rather
opinionated.
GLUELESSNESS SUMMARY
I recommend that every nameserver should have its own name in every forward zone that it
serves. For example:
zone.example.com NS servus.ns.example.com
servus.ns.example.com A 127.0.0.2
2.0.0.127.in-addr.arpa PTR servus.example.net
servus.example.net A 127.0.0.2
Domain names in in-addr.arpa should not be used in the right hand side of NS records.
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.
Killing chiark-named-conf suddenly should be safe, even with -y or -f (though of course it
may not complete its task if killed), provided that only one invocation is made at once.
Slow remote nameservers will cause chiark-named-conf to take excessively long.
EXIT STATUS
0 All went well and there were no warnings.
any other
There were warnings or errors.
FILES
/etc/bind/chiark-conf-gen.zones
Default input configuration file. (Override with -C.)
/etc/bind
Default directory. (Override with -C or default-dir.)
dir/chiark-conf-gen.bind8
Default output file.
/var/cache/bind/chiark-slave
Default location for slave zones.
ENVIRONMENT
Setting variables used by dig(1) and adnshost(1) will affect the operation of
chiark-named-conf. Avoid messing with these if possible.
PATH is used to find subprograms such as dig and adnshost.
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 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.
AUTHOR
chiark-named-conf 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, consult the Free Software Foundation's website at www.fsf.org, or the GNU Project
website at www.gnu.org.