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