1 .\" Hey, Emacs! This is an -*- nroff -*- source file.
2 .TH CHIARK\-NAMED\-CONF 8 "30th December 2001" "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, and to generate a
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.)
48 Alternatively, one or more zone names may be supplied as arguments, in
49 which case their delegations will be checked, and compared with the
50 data for that zone in the main configuration (if any). In this case
51 no new configuration file for the nameserver will be made.
53 .SS ADDITIONAL OPTIONS
56 Checks even zones known to be broken. Ie, ignores the
58 zone style modifier in the configuration.
60 .BR \-C | \-\-config " \fIconfig\-file\fP"
64 .BR /etc/bind/chiark-conf-gen.zones .
65 Also changes the default directory.
68 Enables debugging. Useful for debugging chiark\-named\-conf, but
69 probably not useful for debugging your DNS configuration. Repeat to
70 increase the debugging level. (Maximum is
73 .BR \-g | \-\-glueless
74 Do not warn about glueless referrals. Not recommended - see
75 the section GLUELESSNESS, below.
78 Only checks for mistakes which are the responsibility of the local
79 administrator (to fix or get fixed). This means that for published
80 and stealth zones we only check that we're slaving from the right
81 place and that any names and addresses for ourself are right. For
82 primary zones all checks are still done. It is a mistake to specify
84 with foreign zones (zones supplied explictly on the command line but
85 not relevant to the local server); doing so produces a warning.
88 Suppress the usual report of the list of nameservers for each zone and
89 the serial number from each. When specified twice, do not print any
90 information except warnings.
93 When a problem is detected, warn for all sources of the same imperfect
94 data, rather than only the first we come across
97 Print additional information about what is being checked, as we go
101 .B /etc/bind/chiark-conf-gen.zones
102 (or other file specified with the
104 option) contains a sequence of directives, one per line. Blank lines
105 are permitted. Leading and trailing whitespace on each line is
106 ignored. Comments are lines starting with
110 joins it to the next line, so that long directives can be split across
111 several physical lines.
112 .SS GENERAL DIRECTIVES
113 These directives specify general configuration details. They should
114 appear before directives specifying zones, as each will affect only
115 later zone directives.
117 \fBdefault\-dir\fP \fIdirectory\fP
120 be the default directory (which affects the interpretation of
121 relative filenames). The default is the directory containing
122 the main configuration file, ie
128 \fBforbid\-addr\fP [\fIip-address ...\fP]
129 Specifies the list of addresses that are forbidden as any nameserver
130 for any zone. The default is no such addresses.
132 \fBserverless\-glueless\fP \fIdomain ...\fP
133 Specifies a list of domains under which we do not expect to find any
134 nameservers; for these zones it is OK to find glueless referrals.
135 Each domain listed names a complete subtree of the DNS, starting at
136 the named point. The default is
137 .BR "in\-addr.arpa ip6.arpa ip6.int" .
139 To avoid indefinitely long or even circularly glueless referrals
140 (which delay or prevent lookups) it is necessary for all sites to
141 effectively implement similar conventions; currently the author
142 believes that only the reverse lookup namespaces are conventionally
143 devoid of nameservers, and therefore fine to provide glueless
144 referrals for. See GLUELESSNESS below.
146 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
149 will be overwritten when
151 are used; its new contents will be configuration
152 directives for the zones which follow for the
153 nameserver in question. Currently the only
157 which indicates new-style BIND 8. If no zones follow, then each
158 file will still be overwritten, by an effectively empty file.
159 Default: if there is no
161 directive in the configuration then the default is to use
162 .BR bind8 " " chiark-conf-gen.bind8 ;
163 otherwise it is an error for there to be any zones in the
164 configuration before the first
168 \fBself\-addr\fP \fIip-address ...\fP
169 Specifies the list of addresses that this server may be known by in
170 A records. There is no default.
172 \fBself\-ns\fP \fIfqdn ...\fP
173 Specifies the list of names that this server may be known by in NS
174 records. There is no default.
176 \fBself\-soa\fP \fIfqdn ...\fP
177 Specifies the list of names that this server may be known by in
178 the ORIGIN field of SOA records. There is no default.
182 .B self\-ns " and " self\-soa
183 with the same set of names.
185 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
186 Specifies the directory in which slave (published and stealth)
187 zonefiles should be placed. The default
190 .BR /var/cache/bind/chiark-slave .
192 .IR suffix " and " prefix
193 are empty; they also will be reset to these defaults by a
195 directive which does not specify them.
197 These directives specify one or more zones.
199 .BR primary [ * | ? "] \fIzone filename\fP"
200 Specifies that this server is supposed to be the primary nameserver
203 and that the zone data is to be found in
206 .BR primary\-dir [ * | ? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
209 for files whose names start with
213 Each such file is taken to represent a zone file for which this server
214 is supposed to be the primary; the part of the filename between
215 .IR prefix " and " suffix
216 is the name of the zone.
220 is specified, then instead of looking for files, we search for
221 directories containing
223 directories which do not contain the subfile are simply skipped.
226 .IR directory [\fB/\fP prefix ]
227 exists as specified and is a directory then it is interpreted as
229 with an empty prefix; otherwise the final path component is assumed to
232 is specified then the default is
235 .BR published [ * | ? "] \fIzone origin\-addr\fP"
236 Specifies that this server is supposed to be a published slave
237 nameserver for the zone in question.
239 .BR stealth [ * | ? "] \fIzone server\-addr ...\fP"
240 Specifies that this server is supposed to be an unpublished secondary
241 (aka stealth secondary) for the zone in question.
242 .SS ZONE DIRECTIVE STYLE MODIFIERS
243 Each of the zone directives may optionally be followed by one of the
244 following characters:
247 Indicates that the zone is unofficial, ie that it is not delegated as
248 part of the global Internet DNS and that no attempt should be made to
249 find the superzone and check delegations. Note that unofficial, local
250 zones should be created with caution. They should be in parts of the
251 namespace which are reserved for private use, or belong to the actual
255 Indicates that the zone is known to be broken and no checks should be
256 carried out on it, unless the
261 \fBinclude\fP \fIfile\fP
264 as if it were included here.
267 Ends processing of this file; any data beyond this point is ignored.
269 chiark\-named\-conf makes the following checks:
271 Delegations: Each delegation from a server for the superzone should
272 contain the same set of nameservers. None of the delegations should
273 lack glue. The glue addresses should be the same in each delegation,
274 and agree with the local default nameserver.
276 Delegated servers: Each server mentioned in the delegation should have
277 the same SOA record (and obviously, should be authoritative).
279 All published nameservers - including delegated servers and servers
280 named in the zone's nameserver set: All nameservers for the zone
281 should supply the same list of nameservers for the zone, and none of
282 this authority information should be glueless. All the glue should
283 always give the same addresses.
285 Origin server's data: The set of nameservers in the origin server's
286 version of the zone should be a superset of those in the delegations.
288 Our zone configuration: For primary zones, the SOA origin should be
289 one of the names specified with
290 .BR self\-soa " (or " self ).
291 For published zones, the address should be that of the SOA origin.
292 For stealth zones, the address should be that of the SOA origin or one
293 of the published nameservers.
295 Glue is the name given for the addresses of nameservers which are
296 often supplied in a referral. In fact, it turns out that it is
297 important for the reliability and performance of the DNS that
298 referrals, in general, always come with glue.
300 Firstly, glueless referrals usually cause extra delays looking up
301 names. BIND 8, when it receives a completely glueless referral and
302 does not have the nameservers' addresses in its cache, will start
303 queries for the nameserver addresses; but it will throw the original
304 client's question away, so that when these queries arrive, it won't
305 restart the query from where it left off. This means that the client
306 won't get its answer until it retries, typically at least 1 second
307 later - longer if you have more than one nameserver listed. Worse, if
308 the nameserver to which the glueless referral points is itself under
309 another glueless referral, another retry will be required.
311 Even for better resolvers than BIND 8, long chains of glueless
312 referrals can cause performance and reliability problems, turning a
313 simple two or three query exchange into something needing more than a
316 Even worse, one might accidentally create a set of circularly glueless
319 .B example.com NS ns0.example.net.uk
321 .B example.com NS ns1.example.net.uk
323 .B example.net.uk NS ns0.example.com
325 .B example.net.uk NS ns1.example.com
327 Here it is impossible to look up anything in either example.com or
330 There are, as far as the author is aware, no generally agreed
331 conventions or standards for avoiding unreasonably long glueless
332 chains, or even circular glueless situations. The only way to
333 guarantee that things will work properly is therefore to always supply
336 However, the situation is further complicated by the fact that many
337 implementations (including BIND 8.2.3, and many registry systems),
338 will refuse to accept glue RRs for delegations in a parent zonefile
339 unless they are under the parent's zone apex. In these cases it can
340 be necessary to create names for the child's nameservers which are
341 underneath the child's apex, so that the glue records are both in the
342 parent's bailiwick and obviously necessary.
344 Even worse, the horrid `shared registry system' managing .com, .net
345 and .org does not allow a single IPv4 address to be used for more than
346 one nameserver name! It does, however, give out glue for any
347 nameserver properly registered in the system. I therefore recommend
348 that you create a single name for your nameserver somewhere
349 in .com, .net or .org, and use that for all the delegations
350 from .com, .net and .org. At the time of writing (January 2002) this
351 seems to produce correct and glueful referrals.
353 Finally, a note about `reverse' zones, such as those in in-addr.arpa:
354 It does not seem at all common practice to create nameservers in
355 in-addr.arpa zones (ie, no NS RRs seem to point into in-addr.arpa,
356 even those for in-addr.arpa zones). Current practice seems to be to
357 always use nameservers for in-addr.arpa which are in the normal,
358 forward, address space. If everyone sticks to the rule of always
359 publishing nameservers names in the `main' part of the namespace, and
360 publishing glue for them, there is no chance of anything longer than a
361 1-step glueless chain might occur for a in-addr.arpa zone. It is
362 probably best to maintain this as the status quo, despite the
363 performance problem this implies for BIND 8 caches. This is what the
364 serverless\-glueless directive is for.
366 Dan Bernstein has some information and examples about this at
367 .UR http://cr.yp.to/djbdns/notes.html#gluelessness
368 http://cr.yp.to/djbdns/notes.html#gluelessness
370 but be warned that it is rather opinionated.
372 chiark\-named\-conf is supposed to be resistant to malicious data in
373 the DNS. It is not resistant to malicious data in its own options,
374 configuration file or environment. It is not supposed to read its
375 stdin, but is not guaranteed to be safe if stdin is dangerous.
377 Killing chiark-named-conf suddenly should be safe, even with
379 (though of course it may not complete its task if killed), provided
380 that only one invocation is made at once.
382 Slow remote nameservers will cause chiark-named-conf to take
387 All went well and there were no warnings.
390 There were warnings or errors.
393 .B /etc/bind/chiark-conf-gen.zones
394 Default input configuration file. (Override with
398 Default directory. (Override with
399 .BR -C " or " default\-dir .)
401 .IB dir /chiark-conf-gen.bind8
404 .B /var/cache/bind/chiark-slave
405 Default location for slave zones.
408 Setting variables used by
412 will affect the operation of chiark\-named\-conf.
413 Avoid messing with these if possible.
416 is used to find subprograms such as
417 .BR dig " and " adnshost .
419 The determination of the parent zone for each zone to be checked, and
420 its nameservers, is done simply using the system default nameserver.
422 The processing of output from
424 is not very reliable or robust, but this is mainly the fault of dig.
425 This can lead to somewhat unhelpful error reporting for lookup
428 .B chiark\-named\-conf
429 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.
~ian / chiark-utils.git / blob