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.
21 .BR -n ", " -y ", or " -f
22 is supplied then chiark-named-conf will read its main configuration
23 file for the list of relevant zones. It will then check the
24 configuration and delegation for each zone
25 and/or generate and install a new configuration file for
29 Generate and install new nameserver config, as well as checking
30 configuration, for all listed zones.
33 Check configuration, for all listed zones, but
34 do not generate new nameserver config.
37 Generate and install new nameserver config, without doing any
38 configuration cross-checking. (Syntax errors in our input
39 configuration will still abort this operation.)
41 Alternatively, one or more zone names may be supplied as arguments, in
42 which case their delegations will be checked, and compared with the
43 data for that zone in the main configuration (if any). In this case
44 no new configuration file for the nameserver will be made.
46 .SS ADDITIONAL OPTIONS
49 Checks even zones known to be broken. Ie, ignores the
51 zone style modifier in the configuration.
53 .BR \-C | \-\-config " \fIconfig\-file\fP"
57 .BR /etc/bind/chiark-conf-gen.zones .
58 Also changes the default directory.
61 Enables debugging. Useful for debugging chiark\-named\-conf, but
62 probably not useful for debugging your DNS configuration. Repeat to
63 increase the debugging level. (Maximum is
66 .BR \-g | \-\-glueless
67 Warn only once about a glueless referral for each zone and server,
68 rather than once for each parent which gave out a referral without
71 When repeated, do not warn about glueless referrals at all. Not
72 recommended. Note that glueless referrals usually cause extra delays
73 looking up names, and can make lookups fail even if in theory they
74 could succeed. There is no generally agreed convention or standard
75 for avoiding circular glueless situations such as
77 .B example.com NS ns0.example.net.uk
79 .B example.com NS ns1.example.net.uk
81 .B example.net.uk NS ns0.example.com
83 .B example.net.uk NS ns1.example.com
85 where gluelessness would completely prevent lookups inside
86 example.net.uk and example.com. The best way to be sure to avoid this
87 is to avoid gluelessness.
90 Only checks for mistakes which are the responsibility of the local
91 administrator (to fix or get fixed). This means that for published
92 and stealth zones we only check that we're slaving from the right
93 place and that any names and addresses for ourself are right. For
94 primary zones all checks are still done. It is a mistake to specify
96 with foreign zones (zones supplied explictly on the command line but
97 not relevant to the local server); doing so produces a warning.
100 Do not print any information about zone(s) which do not have warnings.
102 .BR \-v | \-\-verbose
103 Print additional information about each zone.
106 .B /etc/bind/chiark-conf-gen.zones
107 (or other file specified with the
109 option) contains a sequence of directives, one per line. Blank lines
110 are permitted. Leading and trailing whitespace on each line is
111 ignored. Comments are lines starting with
115 joins it to the next line, so that long directives can be split across
116 several physical lines.
117 .SS GENERAL DIRECTIVES
118 These directives specify general configuration details. They should
119 appear before directives specifying zones, as each will affect only
120 later zone directives.
122 \fBdefault\-dir\fP \fIdirectory\fP
125 be the default directory (which affects the interpretation of
126 relative filenames). The default is the directory containing
127 the main configuration file, ie
133 \fBforbid\-addr\fP [\fIip-address ...\fP]
134 Specifies the list of addresses that are forbidden as any nameserver
135 for any zone. The default is no such addresses.
137 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
140 will be overwritten when
142 are used; its new contents will be configuration
143 directives for the zones which follow for the
144 nameserver in question. Currently the only
148 which indicates new-style BIND 8. If no zones follow, then each
149 file will still be overwritten, by an effectively empty file.
150 Default: if there is no
152 directive in the configuration then the default is to use
153 .BR bind8 " " chiark-conf-gen.bind8 ;
154 otherwise it is an error for there to be any zones in the
155 configuration before the first
159 \fBself\-addr\fP \fIip-address ...\fP
160 Specifies the list of addresses that this server may be known by in
161 A records. There is no default.
163 \fBself\-ns\fP \fIfqdn ...\fP
164 Specifies the list of names that this server may be known by in NS
165 records. There is no default.
167 \fBself\-soa\fP \fIfqdn ...\fP
168 Specifies the list of names that this server may be known by in
169 the ORIGIN field of SOA records. There is no default.
173 .B self\-ns " and " self\-soa
174 with the same set of names.
176 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
177 Specifies the directory in which slave (published and stealth)
178 zonefiles should be placed. The default
181 .BR /var/cache/bind/chiark-slave .
183 .IR suffix " and " prefix
184 are empty; they also will be reset to these defaults by a
186 directive which does not specify them.
188 These directives specify one or more zones.
190 .BR primary [ * | ? "] \fIzone filename\fP"
191 Specifies that this server is supposed to be the primary nameserver
194 and that the zone data is to be found in
197 .BR primary\-dir [ * | ? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
200 for files whose names start with
204 Each such file is taken to represent a zone file for which this server
205 is supposed to be the primary; the part of the filename between
206 .IR prefix " and " suffix
207 is the name of the zone.
211 is specified, then instead of looking for files, we search for
212 directories containing
214 directories which do not contain the subfile are simply skipped.
217 .IR directory [\fB/\fP prefix ]
218 exists as specified and is a directory then it is interpreted as
220 with an empty prefix; otherwise the final path component is assumed to
223 is specified then the default is
226 .BR published [ * | ? "] \fIzone origin\-addr\fP"
227 Specifies that this server is supposed to be a published slave
228 nameserver for the zone in question.
230 .BR stealth [ * | ? "] \fIzone server\-addr ...\fP"
231 Specifies that this server is supposed to be an unpublished secondary
232 (aka stealth secondary) for the zone in question.
233 .SS ZONE DIRECTIVE STYLE MODIFIERS
234 Each of the zone directives may optionally be followed by one of the
235 following characters:
238 Indicates that the zone is unofficial, ie that it is not delegated as
239 part of the global Internet DNS and that no attempt should be made to
240 find the superzone and check delegations. Note that unofficial, local
241 zones should be created with caution. They should be in parts of the
242 namespace which are reserved for private use, or belong to the actual
246 Indicates that the zone is known to be broken and no checks should be
247 carried out on it, unless the
252 \fBinclude\fP \fIfile\fP
255 as if it were included here.
258 Ends processing of this file; any data beyond this point is ignored.
260 chiark\-named\-conf makes the following checks:
262 Delegations: Each delegation from a server for the superzone should
263 contain the same set of nameservers. None of the delegations should
264 lack glue. The glue addresses should be the same in each delegation,
265 and agree with the local default nameserver.
267 Delegated servers: Each server mentioned in the delegation should have
268 the same SOA record (and obviously, should be authoritative).
270 All published nameservers - including delegated servers and servers
271 named in the zone's nameserver set: All nameservers for the zone
272 should supply the same list of nameservers for the zone, and none of
273 this authority information should be glueless. All the glue should
274 always give the same addresses.
276 Origin server's data: The set of nameservers in the origin server's
277 version of the zone should be a superset of those in the delegations.
279 Our zone configuration: For primary zones, the SOA origin should be
280 one of the names specified with
281 .BR self\-soa " (or " self ).
282 For published zones, the address should be that of the SOA origin.
283 For stealth zones, the address should be that of the SOA origin or one
284 of the published nameservers.
286 chiark\-named\-conf is supposed to be resistant to malicious data in
287 the DNS. It is not resistant to malicious data in its own options,
288 configuration file or environment. It is not supposed to read its
289 stdin, but is not guaranteed to be safe if stdin is dangerous.
291 Killing chiark-named-conf suddenly should be safe, even with
293 (though of course it may not complete its task if killed), provided
294 that only one invocation is made at once.
296 Slow remote nameservers will cause chiark-named-conf to take
301 All went well and there were no warnings.
304 There were warnings or errors.
307 .B /etc/bind/chiark-conf-gen.zones
308 Default input configuration file. (Override with
312 Default directory. (Override with
313 .BR -C " or " default\-dir .)
315 .IB dir /chiark-conf-gen.bind8
318 .B /var/cache/bind/chiark-slave
319 Default location for slave zones.
322 Setting variables used by
326 will affect the operation of chiark\-named\-conf.
327 Avoid messing with these if possible.
330 is used to find subprograms such as
331 .BR dig " and " adnshost .
333 The determination of the parent zone for each zone to be checked, and
334 its nameservers, is done simply using the system default nameserver.
336 The processing of output from
338 is not very reliable or robust, but this is mainly the fault of dig.
339 This can lead to somewhat unhelpful error reporting for lookup
342 .B chiark\-named\-conf
343 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.