1 .\" Hey, Emacs! This is an -*- nroff -*- source file.
2 .TH CHIARK\-NAMED\-CONF 8 "12th January 2002" "Greenend" "chiark utilities"
4 chiark\-named\-conf \- check and generate nameserver configuration
6 .BR chiark\-named\-conf " [\fIoptions\fP] " \-n | \-y | \-f
8 \fBchiark\-named\-conf\fP [\fIoptions\fP] \fIzone ...\fP
10 .B chiark\-named\-conf
11 is a tool for managing nameserver configurations and checking for
12 suspected DNS problems. Its main functions are to check that
13 delegations are appropriate and working, that secondary zones are
14 slaved from the right places, and to generate a configuration for
16 from its own input file.
18 By default, for each zone, in addition to any warnings, the output
19 lists the zone's configuration type. If the zone is checked, the
20 serial number at each of the nameservers is shown, with any
21 unpublished primary having
23 after the serial number.
28 .BR -n ", " -y ", or " -f
29 is supplied then chiark-named-conf will read its main configuration
30 file for the list of relevant zones. It will then check the
31 configuration and delegation for each zone
32 and/or generate and install a new configuration file for
36 Generate and install new nameserver config, as well as checking
37 configuration, for all listed zones.
40 Check configuration, for all listed zones, but
41 do not generate new nameserver config.
44 Generate and install new nameserver config, without doing any
45 configuration cross-checking. (Syntax errors in our input
46 configuration will still abort this operation.)
49 Do nothing: do no checks, and don't write a new config. This can be
50 used to get a list of the zones being processed.
52 .BR \-\-mail\-first " | " \-\-mail\-middle " | " \-\-mail\-final
53 Send mails to zone SOA MNAMEs reporting zones with problems. You must
54 call chiark\-named\-conf at least twice, once with \-\-mail\-first,
55 and later with \-\-mail\-final, and preferably with one or more calls
56 to \-\-mail\-middle in between. All three options carry out a check
57 and store the results; \-\-mail\-final also sends a mail to the zone
58 SOA MNAME or local administrator, if too many of the calls had errors
59 or warnings (calls before the most recent \-\-mail\-first being
62 Alternatively, one or more zone names may be supplied as arguments, in
63 which case their delegations will be checked, and compared with the
64 data for that zone in the main configuration (if any). In this case
65 no new configuration file for the nameserver will be made.
67 .SS ADDITIONAL OPTIONS
70 Checks even zones known to be broken. Ie, ignores the
72 zone style modifier in the configuration.
74 .BR \-C | \-\-config " \fIconfig\-file\fP"
78 .BR /etc/bind/chiark-conf-gen.zones .
79 Also changes the default directory.
82 Enables debugging. Useful for debugging chiark\-named\-conf, but
83 probably not useful for debugging your DNS configuration. Repeat to
84 increase the debugging level. (Maximum is
87 .BR \-g | \-\-glueless
88 Do not warn about glueless referrals. Not recommended - see
89 the section GLUELESSNESS, below.
92 Only checks for mistakes which are the responsibility of the local
93 administrator (to fix or get fixed). This means that for published
94 and stealth zones we only check that we're slaving from the right
95 place and that any names and addresses for ourself are right. For
96 primary zones all checks are still done. It is a mistake to specify
98 with foreign zones (zones supplied explictly on the command line but
99 not relevant to the local server); doing so produces a warning.
102 Suppress the usual report of the list of nameservers for each zone and
103 the serial number from each. When specified twice, do not print any
104 information except warnings.
107 When a problem is detected, warn for all sources of the same imperfect
108 data, rather than only the first we come across
110 .BR \-v | \-\-verbose
111 Print additional information about what is being checked, as we go
115 .B /etc/bind/chiark-conf-gen.zones
116 (or other file specified with the
118 option) contains a sequence of directives, one per line. Blank lines
119 are permitted. Leading and trailing whitespace on each line is
120 ignored. Comments are lines starting with
124 joins it to the next line, so that long directives can be split across
125 several physical lines.
126 .SS GENERAL DIRECTIVES
127 These directives specify general configuration details. They should
128 appear before directives specifying zones, as each will affect only
129 later zone directives.
131 \fBadmin\fP \fIemail\-address\fP
132 Specifies the email address of the local administrator. This is used
133 in the From: line of mails sent out, and will also receive copies of
134 the reports. There is no default.
136 \fBdefault\-dir\fP \fIdirectory\fP
139 be the default directory (which affects the interpretation of
140 relative filenames). The default is the directory containing
141 the main configuration file, ie
147 \fBforbid\-addr\fP [\fIip-address ...\fP]
148 Specifies the list of addresses that are forbidden as any nameserver
149 for any zone. The default is no such addresses.
151 \fBserverless\-glueless\fP \fIdomain ...\fP
152 Specifies a list of domains under which we do not expect to find any
153 nameservers; for these zones it is OK to find glueless referrals.
154 Each domain listed names a complete subtree of the DNS, starting at
155 the named point. The default is
156 .BR "in\-addr.arpa ip6.arpa ip6.int" .
158 To avoid indefinitely long or even circularly glueless referrals
159 (which delay or prevent lookups) it is necessary for all sites to
160 effectively implement similar conventions; currently the author
161 believes that only the reverse lookup namespaces are conventionally
162 devoid of nameservers, and therefore fine to provide glueless
163 referrals for. See GLUELESSNESS below.
165 \fBmail\-state\-dir\fP \fIdirectory\fP
168 for storing information about recent failures for mailing to zone
169 admins. See \-\-mail\-first et al. Old files in here should be
170 cleaned up periodically out of cron. There is no default.
172 \fBmail\-max\-warnfreq\fP \fIpercentage\fP
173 When \-\-mail\-final is used, a mail will be sent to all zones which
174 had warnings or errors more than
176 of the times \-\-mail\-* was used (since the last \-\-mail\-first).
179 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
182 will be overwritten when
184 are used; its new contents will be configuration
185 directives for the zones which follow for the
186 nameserver in question. Currently the only
190 which indicates new-style BIND 8. If no zones follow, then each
191 file will still be overwritten, by an effectively empty file.
192 Default: if there is no
194 directive in the configuration then the default is to use
195 .BR bind8 " " chiark-conf-gen.bind8 ;
196 otherwise it is an error for there to be any zones in the
197 configuration before the first
201 \fBself\-addr\fP \fIip-address ...\fP
202 Specifies the list of addresses that this server may be known by in
203 A records. There is no default.
205 \fBself\-ns\fP \fIfqdn ...\fP
206 Specifies the list of names that this server may be known by in NS
207 records. There is no default. Any trailing * is replaced by the name
208 of the zone being checked, so for example
210 before the zone example.com would mean to expect us to be listed as
214 \fBself\-soa\fP \fIfqdn ...\fP
215 Specifies the list of names that this server may be known by in
216 the ORIGIN field of SOA records. There is no default. Any trailing
217 * is replaced by the name of the zone, as for
222 .B self\-ns " and " self\-soa
223 with the same set of names.
225 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
226 Specifies the directory in which slave (published and stealth)
227 zonefiles should be placed. The default
230 .BR /var/cache/bind/chiark-slave .
232 .IR suffix " and " prefix
233 are empty; they also will be reset to these defaults by a
235 directive which does not specify them.
237 These directives specify one or more zones.
239 .BR primary [ * | ? | @ | @@ | ~ "] \fIzone filename\fP"
240 Specifies that this server is supposed to be the primary nameserver
243 and that the zone data is to be found in
246 .BR primary\-dir [ * | ? | @ | @@ | ~ "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
249 for files whose names start with
253 Each such file is taken to represent a zone file for which this server
254 is supposed to be the primary; the part of the filename between
255 .IR prefix " and " suffix
256 is the name of the zone.
260 is specified, then instead of looking for files, we search for
261 directories containing
263 directories which do not contain the subfile are simply skipped.
266 .IR directory [\fB/\fP prefix ]
267 exists as specified and is a directory then it is interpreted as
269 with an empty prefix; otherwise the final path component is assumed to
272 is specified then the default is
275 .BR published [ * | ? | @ | @@ | ~ "] \fIzone origin\-addr\fP"
276 Specifies that this server is supposed to be a published slave
277 nameserver for the zone in question.
279 .BR stealth [ * | ? | @ | @@ | ~ "] \fIzone server\-addr ...\fP"
280 Specifies that this server is supposed to be an unpublished secondary
281 (aka stealth secondary) for the zone in question.
282 .SS ZONE DIRECTIVE STYLE MODIFIERS
283 Each of the zone directives may optionally be followed by one or more
284 of the following characters:
287 Indicates that the zone is unofficial, ie that it is not delegated as
288 part of the global Internet DNS and that no attempt should be made to
289 find the superzone and check delegations. Note that unofficial, local
290 zones should be created with caution. They should be in parts of the
291 namespace which are reserved for private use, or belong to the actual
295 Indicates that mails should be sent about the zone to the nameserver
296 admin rather than to the zone SOA MNAME. This is always done for
300 Indicates that no mails should be sent about the zone to anyone.
303 Indicates that the zone's delegation is known to be glueless, and that
304 lack of glue should not be flagged. Not recommended - see the section
308 Indicates that the zone is known to be broken and no checks should be
309 carried out on it, unless the
314 \fBinclude\fP \fIfile\fP
317 as if it were included here.
320 Ends processing of this file; any data beyond this point is ignored.
322 chiark\-named\-conf makes the following checks:
324 Delegations: Each delegation from a server for the superzone should
325 contain the same set of nameservers. None of the delegations should
326 lack glue. The glue addresses should be the same in each delegation,
327 and agree with the local default nameserver.
329 Delegated servers: Each server mentioned in the delegation should have
330 the same SOA record (and obviously, should be authoritative).
332 All published nameservers - including delegated servers and servers
333 named in the zone's nameserver set: All nameservers for the zone
334 should supply the same list of nameservers for the zone, and none of
335 this authority information should be glueless. All the glue should
336 always give the same addresses.
338 Origin server's data: The set of nameservers in the origin server's
339 version of the zone should be a superset of those in the delegations.
341 Our zone configuration: For primary zones, the SOA origin should be
342 one of the names specified with
343 .BR self\-soa " (or " self ).
344 For published zones, the address should be that of the SOA origin.
345 For stealth zones, the address should be that of the SOA origin or one
346 of the published nameservers.
348 Glue is the name given for the addresses of nameservers which are
349 often supplied in a referral. In fact, it turns out that it is
350 important for the reliability and performance of the DNS that
351 referrals, in general, always come with glue.
353 Firstly, glueless referrals usually cause extra delays looking up
354 names. BIND 8, when it receives a completely glueless referral and
355 does not have the nameservers' addresses in its cache, will start
356 queries for the nameserver addresses; but it will throw the original
357 client's question away, so that when these queries arrive, it won't
358 restart the query from where it left off. This means that the client
359 won't get its answer until it retries, typically at least 1 second
360 later - longer if you have more than one nameserver listed. Worse, if
361 the nameserver to which the glueless referral points is itself under
362 another glueless referral, another retry will be required.
364 Even for better resolvers than BIND 8, long chains of glueless
365 referrals can cause performance and reliability problems, turning a
366 simple two or three query exchange into something needing more than a
369 Even worse, one might accidentally create a set of circularly glueless
372 .B example.com NS ns0.example.net.uk
374 .B example.com NS ns1.example.net.uk
376 .B example.net.uk NS ns0.example.com
378 .B example.net.uk NS ns1.example.com
380 Here it is impossible to look up anything in either example.com or
383 There are, as far as the author is aware, no generally agreed
384 conventions or standards for avoiding unreasonably long glueless
385 chains, or even circular glueless situations. The only way to
386 guarantee that things will work properly is therefore to always supply
389 However, the situation is further complicated by the fact that many
390 implementations (including BIND 8.2.3, and many registry systems),
391 will refuse to accept glue RRs for delegations in a parent zonefile
392 unless they are under the parent's zone apex. In these cases it can
393 be necessary to create names for the child's nameservers which are
394 underneath the child's apex, so that the glue records are both in the
395 parent's bailiwick and obviously necessary.
397 Even worse, the horrid `shared registry system' managing .com, .net
398 and .org does not allow a single IPv4 address to be used for more than
399 one nameserver name! It does, however, give out glue for any
400 nameserver properly registered in the system. I therefore recommend
401 that you create a single name for your nameserver somewhere
402 in .com, .net or .org, and use that for all the delegations
403 from .com, .net and .org. At the time of writing (January 2002) this
404 seems to produce correct and glueful referrals.
406 Finally, a note about `reverse' zones, such as those in in-addr.arpa:
407 It does not seem at all common practice to create nameservers in
408 in-addr.arpa zones (ie, no NS RRs seem to point into in-addr.arpa,
409 even those for in-addr.arpa zones). Current practice seems to be to
410 always use nameservers for in-addr.arpa which are in the normal,
411 forward, address space. If everyone sticks to the rule of always
412 publishing nameservers names in the `main' part of the namespace, and
413 publishing glue for them, there is no chance of anything longer than a
414 1-step glueless chain might occur for a in-addr.arpa zone. It is
415 probably best to maintain this as the status quo, despite the
416 performance problem this implies for BIND 8 caches. This is what the
417 serverless\-glueless directive is for.
419 Dan Bernstein has some information and examples about this at
420 .UR http://cr.yp.to/djbdns/notes.html#gluelessness
421 http://cr.yp.to/djbdns/notes.html#gluelessness
423 but be warned that it is rather opinionated.
425 chiark\-named\-conf is supposed to be resistant to malicious data in
426 the DNS. It is not resistant to malicious data in its own options,
427 configuration file or environment. It is not supposed to read its
428 stdin, but is not guaranteed to be safe if stdin is dangerous.
430 Killing chiark-named-conf suddenly should be safe, even with
432 (though of course it may not complete its task if killed), provided
433 that only one invocation is made at once.
435 Slow remote nameservers will cause chiark-named-conf to take
440 All went well and there were no warnings.
443 There were warnings or errors.
446 .B /etc/bind/chiark-conf-gen.zones
447 Default input configuration file. (Override with
451 Default directory. (Override with
452 .BR -C " or " default\-dir .)
454 .IB dir /chiark-conf-gen.bind8
457 .B /var/cache/bind/chiark-slave
458 Default location for slave zones.
461 Setting variables used by
465 will affect the operation of chiark\-named\-conf.
466 Avoid messing with these if possible.
469 is used to find subprograms such as
470 .BR dig " and " adnshost .
472 The determination of the parent zone for each zone to be checked, and
473 its nameservers, is done simply using the system default nameserver.
475 The processing of output from
477 is not very reliable or robust, but this is mainly the fault of dig.
478 This can lead to somewhat unhelpful error reporting for lookup
481 .B chiark\-named\-conf
482 and this manpage were written by Ian Jackson
483 <ian@chiark.greenend.org.uk>. They are Copyright 2002 Ian Jackson.
485 chiark\-named\-conf and this manpage are free software; you can
486 redistribute it and/or modify it under the terms of the GNU General
487 Public License as published by the Free Software Foundation; either
488 version 2, or (at your option) any later version.
490 This is distributed in the hope that it will be useful, but WITHOUT ANY
491 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
492 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
495 You should have received a copy of the GNU General Public License along
496 with this program; if not, write to the Free Software Foundation, Inc.,
497 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
~ian / chiark-utils.git / blob