chiark / gitweb /
xbatmon-simple: Saner build rune.
[chiark-utils.git] / scripts / named-conf.8
1 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
2 .TH CHIARK\-NAMED\-CONF 8 "12th January 2002" "Greenend" "chiark utilities"
3 .SH NAME
4 chiark\-named\-conf \- check and generate nameserver configuration
5 .SH SYNOPSIS
6 .BR chiark\-named\-conf " [\fIoptions\fP] " \-n | \-y | \-f
7 .br
8 \fBchiark\-named\-conf\fP [\fIoptions\fP] \fIzone ...\fP
9 .SH DESCRIPTION
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
15 .BR BIND ,
16 from its own input file.
17
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
22 .B *
23 after the serial number.
24 .SH OPTIONS
25
26 .SS MODE OPTIONS
27 If one of the options
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
33 the nameserver:
34 .TP
35 .BR \-y | \-\-yes
36 Generate and install new nameserver config, as well as checking
37 configuration, for all listed zones.
38 .TP
39 .BR \-n | \-\-no
40 Check configuration, for all listed zones, but
41 do not generate new nameserver config.
42 .TP
43 .BR \-f | \-\-force
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.)
47 .TP
48 .BR \-\-nothing
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.
51 .TP
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
60 ignored).
61 .TP
62 .B \-mail\-final\-test
63 just like \-\-mail\-final except that it always sends mail to the
64 local server admin and never to remote zone contacts, adding
65 .B (testing!)
66 to the start of the To: field.
67 .LP
68 Alternatively, one or more zone names may be supplied as arguments, in
69 which case their delegations will be checked, and compared with the
70 data for that zone in the main configuration (if any).  In this case
71 no new configuration file for the nameserver will be made.
72
73 .SS ADDITIONAL OPTIONS
74 .TP
75 .BR \-A | \-\-all
76 Checks even zones known to be broken.  Ie, ignores the
77 .B ?
78 zone style modifier in the configuration.
79 .TP
80 .BR \-C | \-\-config " \fIconfig\-file\fP"
81 Use
82 .I config\-file
83 instead of
84 .BR /etc/bind/chiark-conf-gen.zones .
85 Also changes the default directory.
86 .TP
87 .BR \-D
88 Enables debugging.  Useful for debugging chiark\-named\-conf, but
89 probably not useful for debugging your DNS configuration.  Repeat to
90 increase the debugging level.  (Maximum is
91 .BR -DD .)
92 .TP
93 .BR \-g | \-\-glueless
94 Do not warn about glueless referrals (strictly, makes the zone style
95 modifier
96 .B ~
97 the default).  Not recommended - see the section GLUELESSNESS, below.
98 .TP
99 .BR \-l | \-\-local
100 Only checks for mistakes which are the responsibility of the local
101 administrator (to fix or get fixed).  This means that for published
102 and stealth zones we only check that we're slaving from the right
103 place and that any names and addresses for ourself are right.  For
104 primary zones all checks are still done.  It is a mistake to specify
105 .B \-l
106 with foreign zones (zones supplied explictly on the command line but
107 not relevant to the local server); doing so produces a warning.
108 .TP
109 .BI \-m group !*$@~?
110 Overrides a
111 .B modifiers
112 directive in the configuration file.  The modifiers specified in the
113 directive are completely replaced by those specified in this command
114 line option.  (Note that modifiers specified in per-zone directives
115 still override these per-group settings.)  If more than one
116 .B modifiers
117 directive specifies the same group, they are all affected.
118 .B modifiers
119 directives which don't specify a group cannot be affected.  It is an
120 error if the group does not appear in the config file.  See ZONE STYLE
121 MODIFIERS, below.
122 .PP
123 The special group
124 .B foreign
125 is used for zones which don't appear in the configuration file.
126 .TP
127 .BR \-q | \-\-quiet
128 Suppress the usual report of the list of nameservers for each zone and
129 the serial number from each.  When specified twice, do not print any
130 information except warnings.
131 .TP
132 .BR \-r | \-\-repeat
133 When a problem is detected, warn for all sources of the same imperfect
134 data, rather than only the first we come across
135 .TP
136 .BR \-v | \-\-verbose
137 Print additional information about what is being checked, as we go
138 along.
139 .SH USAGE
140 The file
141 .B /etc/bind/chiark-conf-gen.zones
142 (or other file specified with the
143 .B \-C
144 option) contains a sequence of directives, one per line.  Blank lines
145 are permitted.  Leading and trailing whitespace on each line is
146 ignored.  Comments are lines starting with
147 .BR # .
148 Ending a line with a
149 .BR \\
150 joins it to the next line, so that long directives can be split across
151 several physical lines.
152 .SS GENERAL DIRECTIVES
153 These directives specify general configuration details.  They should
154 appear before directives specifying zones, as each will affect only
155 later zone directives.  Foreign zones (zones explicitly specified on
156 the command line but not mentioned in the configuration) use the
157 configuration settings prevailing at the end of the config file.
158 .TP
159 \fBadmin\fP \fIemail\-address\fP
160 Specifies the email address of the local administrator.  This is used
161 in the From: line of mails sent out, and will also receive copies of
162 the reports.  There is no default.
163 .TP
164 \fBdefault\-dir\fP \fIdirectory\fP
165 Makes
166 .I directory
167 be the default directory (which affects the interpretation of
168 relative filenames).  The default is the directory containing
169 the main configuration file, ie
170 .BR /etc/bind
171 if no
172 .B -C
173 option is specified.
174 .TP
175 \fBforbid\-addr\fP [\fIip-address ...\fP]
176 Specifies the list of addresses that are forbidden as any nameserver
177 for any zone.  The default is no such addresses.
178 .TP
179 \fBforbid\-addr\fP [\fIip-address ...\fP]
180 Specifies the list of addresses that are forbidden as a nameserver
181 for a zone for which we are the primary - ie, the list of our old or
182 to-be-obsoleted slaves.  The default is no such addresses.
183 .TP
184 \fBserverless\-glueless\fP \fIdomain ...\fP
185 Specifies a list of domains under which we do not expect to find any
186 nameservers without glue; for these zones it is OK to find glueless
187 referrals.
188 Each domain listed names a complete subtree of the DNS, starting at
189 the named point.  The default is
190 .BR "in\-addr.arpa ip6.arpa ip6.int" .
191
192 To avoid indefinitely long or even circularly glueless referrals
193 (which delay or prevent lookups) it is necessary for all sites to
194 effectively implement similar conventions; currently the author
195 believes that only the reverse lookup namespaces are conventionally
196 devoid of (glueless) nameservers, and therefore fine to provide
197 glueless referrals for.  See GLUELESSNESS below.
198 .TP
199 \fBallow-\-indirect\-glue\fP \fInameserver-superdomain ...\fP
200 Specifies a list of domains under which we expect to find glueless
201 nameservers, with up to one layer of indirection.
202 For nameservers under these domains it is OK to to find glueless
203 referrals, but only when listed as a nameserver for a zone which is
204 not itself a subdomain of an \fBallow-indirect-glue\fR
205 \fInameserver-superdomain\fR.
206
207 This supports to common configuration style where DNS operator(s) set
208 up all of their nameservers with names within a small subsection of
209 the DNS (the portions under \fInameserver-superdomain\fRs), and
210 provide glueless referrals naming these nameservers for all other
211 zones.  This provides at most one level of missing glue.
212
213 Note that if the DNS administrators collectively able to influence the
214 service for some zone (including the admins for its superzones, the
215 zones containing its nameservers, and their superzones and so forth)
216 are not in sufficiently close communication do not all agree on the
217 proper set of \fInameserver-superdomain\fR then they might still set
218 up circular glue and \fBchiark-named-conf\fR would not necessarily be
219 able to detect this even if it was run on every relevant nameserver.
220 .TP
221 \fBmail\-state\-dir\fP \fIdirectory\fP
222 Uses
223 .I directory
224 for storing information about recent failures for mailing to zone
225 admins.  See \-\-mail\-first et al.  Old files in here should be
226 cleaned up periodically out of cron.  There is no default.
227 .TP
228 \fBmail\-max\-warnfreq\fP \fIpercentage\fP
229 When \-\-mail\-final is used, a mail will be sent to all zones which
230 had warnings or errors more than
231 .IR percentage %
232 of the times \-\-mail\-* was used (since the last \-\-mail\-first).
233 The default is 50%.
234 .TP
235 .BR modifiers " " !*$@~? "] [\fIgroup\fP]"
236 Applies the specified zone style modifiers (see below) to subsequently
237 declared zones (until the next
238 .B modifiers
239 directive), as if the modifiers specified were written out for
240 each zone.  You must specify at least one character for the modifiers;
241 if you want to reset everything to the default, just say
242 .BR ! .
243 If style modifiers specified in the zone directive
244 conflict with the
245 .B modifiers
246 directive, those specified in the zone directive take effect.
247 .I group
248 may contain alphanumerics and underscores, and is used for the
249 .B -m
250 command-line option.
251 .TP
252 \fBself\-addr\fP \fIip-address ...\fP
253 Specifies the list of addresses that this server may be known by in
254 A records.  There is no default.
255 .TP
256 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
257 Arranges that each
258 .I filename
259 will be overwritten when
260 .BR -y " or " -f
261 are used; its new contents will be configuration
262 directives for the zones which follow for the
263 nameserver in question.  Currently the only
264 .I format
265 supported is
266 .B bind8
267 which indicates new-style BIND 8.  If no zones follow, then each
268 file will still be overwritten, by an effectively empty file.
269 Default: if there is no
270 .B output
271 directive in the configuration then the default is to use
272 .BR bind8 " " chiark-conf-gen.bind8 ;
273 otherwise it is an error for there to be any zones in the
274 configuration before the first
275 .B output
276 directive.
277 .TP
278 \fBself\-ns\fP \fIfqdn ...\fP
279 Specifies the list of names that this server may be known by in NS
280 records.  There is no default.  Any trailing * is replaced by the name
281 of the zone being checked, so for example
282 .B self\-ns isp.ns.*
283 before the zone example.com would mean to expect us to be listed as
284 isp.ns.example.com
285 in the NS RRset.
286 .TP
287 \fBself\-soa\fP \fIfqdn ...\fP
288 Specifies the list of names that this server may be known by in
289 the ORIGIN field of SOA records.  There is no default.  Any trailing
290 * is replaced by the name of the zone, as for
291 .BR self\-ns .
292 .TP
293 .BI self " fqdn ..."
294 Equivalent to both
295 .B self\-ns " and " self\-soa
296 with the same set of names.
297 .TP
298 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
299 Specifies the directory in which slave (published and stealth)
300 zonefiles should be placed.  The default
301 .I directory
302 is
303 .BR /var/cache/bind/chiark-slave .
304 The default
305 .IR suffix " and " prefix
306 are empty; they also will be reset to these defaults by a
307 .B slave\-dir
308 directive which does not specify them.
309 .SS ZONE DIRECTIVES
310 These directives specify one or more zones.
311 .TP
312 .BR primary [ !*$@~? "] \fIzone filename\fP"
313 Specifies that this server is supposed to be the primary nameserver
314 for
315 .I zone
316 and that the zone data is to be found in
317 .IR filename .
318 .TP
319 .BR primary\-dir [ !*$@~? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
320 Search
321 .I directory
322 for files whose names start with
323 .I prefix
324 and end with
325 .IR suffix .
326 Each such file is taken to represent a zone file for which this server
327 is supposed to be the primary; the part of the filename between
328 .IR prefix " and " suffix
329 is the name of the zone.
330
331 If
332 .BI / subfile
333 is specified, then instead of looking for files, we search for
334 directories containing
335 .IR subfile ;
336 directories which do not contain the subfile are simply skipped.
337
338 If
339 .IR directory [\fB/\fP prefix ]
340 exists as specified and is a directory then it is interpreted as
341 .I directory
342 with an empty prefix; otherwise the final path component is assumed to
343 be the prefix.  If no
344 .IB suffix / subfile
345 is specified then the default is
346 .BR _db .
347 .TP
348 .BR published [ !*$@~? "] \fIzone origin\-addr\fP"
349 Specifies that this server is supposed to be a published slave
350 nameserver for the zone in question.
351 .TP
352 .BR stealth [ !*$@~? "] \fIzone server\-addr ...\fP"
353 Specifies that this server is supposed to be an unpublished secondary
354 (aka stealth secondary) for the zone in question.
355 .SS ZONE STYLE MODIFIERS
356 Each of the zone directives may optionally be followed by one or more
357 of the following characters (each at most once):
358 .TP
359 .B !
360 Reverses the meaning of all style modifiers after the
361 .BR ! .
362 Only one
363 .BR !
364 must appear in the modifier list.  In this list, other modifiers which
365 default to `enabled' are described by describing the effect of their
366 inverse - see the description for
367 .B !@
368 below.
369 .TP
370 .B *
371 Indicates that the zone is unofficial, ie that it is not delegated as
372 part of the global Internet DNS and that no attempt should be made to
373 find the superzone and check delegations.  Note that unofficial, local
374 zones should be created with caution.  They should be in parts of the
375 namespace which are reserved for private use, or belong to the actual
376 zone maintainer.
377 .TP
378 .B $
379 Indicates that any mails should be sent about the zone to the
380 nameserver admin rather than to the zone SOA MNAME.  This is the
381 default unless we are supposedly a published server for the zone.
382 .TP
383 .B !@
384 Indicates that no mails should be sent about the zone to anyone.
385 .TP
386 .B ~
387 Indicates that the zone's delegation is known to be glueless, and that
388 lack of glue should not be flagged.  Not recommended - see the section
389 GLUELESSNESS, below.
390 .TP
391 .B ?
392 Indicates that the zone is known to be broken and no checks should be
393 carried out on it, unless the
394 .B \-A
395 option is specified.
396 .SS OTHER DIRECTIVES
397 .TP
398 \fBinclude\fP \fIfile\fP
399 Reads
400 .I file
401 as if it were included here.
402 .TP
403 \fBend\fP
404 Ends processing of this file; any data beyond this point is ignored.
405 .SH CHECKS
406 chiark\-named\-conf makes the following checks:
407
408 Delegations: Each delegation from a server for the superzone should
409 contain the same set of nameservers.  None of the delegations should
410 lack glue.  The glue addresses should be the same in each delegation,
411 and agree with the local default nameserver.
412
413 Delegated servers: Each server mentioned in the delegation should have
414 the same SOA record (and obviously, should be authoritative).
415
416 All published nameservers - including delegated servers and servers
417 named in the zone's nameserver set: All nameservers for the zone
418 should supply the same list of nameservers for the zone, and none of
419 this authority information should be glueless.  All the glue should
420 always give the same addresses.
421
422 Origin server's data: The set of nameservers in the origin server's
423 version of the zone should be a superset of those in the delegations.
424
425 Our zone configuration: For primary zones, the SOA origin should be
426 one of the names specified with
427 .BR self\-soa " (or " self ).
428 For published zones, the address should be that of the SOA origin.
429 For stealth zones, the address should be that of the SOA origin or one
430 of the published nameservers.
431 .SH GLUELESSNESS
432 Glue is the name given for the addresses of nameservers which are
433 often supplied in a referral.  In fact, it turns out that it is
434 important for the reliability and performance of the DNS that
435 referrals, in general, always come with glue.
436
437 Firstly, glueless referrals usually cause extra delays looking up
438 names.  BIND 8, when it receives a completely glueless referral and
439 does not have the nameservers' addresses in its cache, will start
440 queries for the nameserver addresses; but it will throw the original
441 client's question away, so that when these queries arrive, it won't
442 restart the query from where it left off.  This means that the client
443 won't get its answer until it retries, typically at least 1 second
444 later - longer if you have more than one nameserver listed.  Worse, if
445 the nameserver to which the glueless referral points is itself under
446 another glueless referral, another retry will be required.
447
448 Even for better resolvers than BIND 8, long chains of glueless
449 referrals can cause performance and reliability problems, turning a
450 simple two or three query exchange into something needing more than a
451 dozen queries.
452
453 Even worse, one might accidentally create a set of circularly glueless
454 referrals such as
455 .br
456 .B example.com NS ns0.example.net.uk
457 .br
458 .B example.com NS ns1.example.net.uk
459 .br
460 .B example.net.uk NS ns0.example.com
461 .br
462 .B example.net.uk NS ns1.example.com
463 .br
464 Here it is impossible to look up anything in either example.com or
465 example.net.uk.
466
467 There are, as far as the author is aware, no generally agreed
468 conventions or standards for avoiding unreasonably long glueless
469 chains, or even circular glueless situations.  The only way to
470 guarantee that things will work properly is therefore to always supply
471 glue.
472
473 However, the situation is further complicated by the fact that many
474 implementations (including BIND 8.2.3, and many registry systems),
475 will refuse to accept glue RRs for delegations in a parent zonefile
476 unless they are under the parent's zone apex.  In these cases it can
477 be necessary to create names for the child's nameservers which are
478 underneath the child's apex, so that the glue records are both in the
479 parent's bailiwick and obviously necessary.
480
481 In the past, the `shared registry system' managing .com, .net and .org
482 did not allow a single IPv4 address to be used for more than one
483 nameserver name.  However, at the time of writing (October 2002) this
484 problem seems to have been fixed, and the workaround I previously
485 recommended (creating a single name for your nameserver somewhere
486 in .com, .net or .org, and using that for all the delegations
487 from .com, .net and .org) should now be avoided.
488
489 Finally, a note about `reverse' zones, such as those in in-addr.arpa:
490 It does not seem at all common practice to create nameservers in
491 in-addr.arpa zones (ie, no NS RRs seem to point into in-addr.arpa,
492 even those for in-addr.arpa zones).  Current practice seems to be to
493 always use nameservers for in-addr.arpa which are in the normal,
494 forward, address space.  If everyone sticks to the rule of always
495 publishing nameservers names in the `main' part of the namespace, and
496 publishing glue for them, there is no chance of anything longer than a
497 1-step glueless chain might occur for a in-addr.arpa zone.  It is
498 probably best to maintain this as the status quo, despite the
499 performance problem this implies for BIND 8 caches.  This is what the
500 serverless\-glueless directive is for.
501
502 Dan Bernstein has some information and examples about this at
503 .UR http://cr.yp.to/djbdns/notes.html#gluelessness
504 http://cr.yp.to/djbdns/notes.html#gluelessness
505 .UE
506 but be warned that it is rather opinionated.
507 .SS GLUELESSNESS SUMMARY
508
509 I recommend that every nameserver should have its own name in every
510 forward zone that it serves.  For example:
511 .br
512 .B zone.example.com NS servus.ns.example.com
513 .br
514 .B servus.ns.example.com A 127.0.0.2
515 .br
516 .B 2.0.0.127.in-addr.arpa PTR servus.example.net
517 .br
518 .B servus.example.net A 127.0.0.2
519 .LP
520 Domain names in
521 .B in-addr.arpa
522 should not be used in the right hand side of NS records.
523 .SH SECURITY
524 chiark\-named\-conf is supposed to be resistant to malicious data in
525 the DNS.  It is not resistant to malicious data in its own options,
526 configuration file or environment.  It is not supposed to read its
527 stdin, but is not guaranteed to be safe if stdin is dangerous.
528 .LP
529 Killing chiark-named-conf suddenly should be safe, even with
530 .BR -y " or " -f
531 (though of course it may not complete its task if killed), provided
532 that only one invocation is made at once.
533 .LP
534 Slow remote nameservers will cause chiark-named-conf to take
535 excessively long.
536 .SH EXIT STATUS
537 .TP
538 .B 0
539 All went well and there were no warnings.
540 .TP
541 any other
542 There were warnings or errors.
543 .SH FILES
544 .TP
545 .B /etc/bind/chiark-conf-gen.zones
546 Default input configuration file.  (Override with
547 .BR -C .)
548 .TP
549 .B /etc/bind
550 Default directory.  (Override with
551 .BR -C " or " default\-dir .)
552 .TP
553 .IB dir /chiark-conf-gen.bind8
554 Default output file.
555 .TP
556 .B /var/cache/bind/chiark-slave
557 Default location for slave zones.
558 .SH ENVIRONMENT
559 .LP
560 Setting variables used by
561 .BR dig (1)
562 and
563 .BR adnshost (1)
564 will affect the operation of chiark\-named\-conf.  
565 Avoid messing with these if possible.
566 .LP
567 .B PATH
568 is used to find subprograms such as
569 .BR dig " and " adnshost .
570 .SH BUGS
571 The determination of the parent zone for each zone to be checked, and
572 its nameservers, is done simply using the system default nameserver.
573
574 The processing of output from
575 .B dig
576 is not very reliable or robust, but this is mainly the fault of dig.
577 This can lead to somewhat unhelpful error reporting for lookup
578 failures.
579 .SH AUTHOR
580 .B chiark\-named\-conf
581 and this manpage were written by Ian Jackson
582 <ian@chiark.greenend.org.uk>.  They are Copyright 2002 Ian Jackson.
583
584 chiark\-named\-conf and this manpage are free software; you can
585 redistribute it and/or modify it under the terms of the GNU General
586 Public License as published by the Free Software Foundation; either
587 version 2, or (at your option) any later version.
588
589 This is distributed in the hope that it will be useful, but WITHOUT ANY
590 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
591 FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
592 details.
593
594 You should have received a copy of the GNU General Public License along
595 with this program; if not, consult the Free Software Foundation's
596 website at www.fsf.org, or the GNU Project website at www.gnu.org.