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
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
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.