chiark / gitweb /
Bugfixes etc.
[chiark-utils.git] / scripts / named-conf.8
1 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
2 .TH CHIARK\-NAMED\-CONF 8 "30th December 2001" "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, and to generate a
14 configuration for
15 .BR BIND ,
16 from its own input file.
17 .SH OPTIONS
18
19 .SS MODE OPTIONS
20 If one of the options
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
26 the nameserver:
27 .TP
28 .BR \-y | \-\-yes
29 Generate and install new nameserver config, as well as checking
30 configuration, for all listed zones.
31 .TP
32 .BR \-n | \-\-no
33 Check configuration, for all listed zones, but
34 do not generate new nameserver config.
35 .TP
36 .BR \-f | \-\-force
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.)
40 .LP
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.
45
46 .SS ADDITIONAL OPTIONS
47 .TP
48 .BR \-A | \-\-all
49 Checks even zones known to be broken.  Ie, ignores the
50 .B ?
51 zone style modifier in the configuration.
52 .TP
53 \fB\-C\fP|\-\-config \fIconfig\-file\fP
54 Use
55 .I config\-file
56 instead of
57 .BR /etc/bind/chiark-conf-gen.zones .
58 Also changes the default directory.
59 .TP
60 .BR \-D
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
64 .BR -DD .)
65 .TP
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
69 glue.
70
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
76 .br
77 .B example.com NS ns0.example.net.uk
78 .br
79 .B example.com NS ns1.example.net.uk
80 .br
81 .B example.net.uk NS ns0.example.com
82 .br
83 .B example.net.uk NS ns1.example.com
84 .br
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.
88 .TP
89 .BR \-l | \-\-local
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
95 .B \-l
96 with foreign zones (zones supplied explictly on the command line but
97 not relevant to the local server); doing so produces a warning.
98 .TP
99 .BR \-q | \-\-quiet
100 Do not print any information about zone(s) which do not have warnings.
101 .TP
102 .BR \-v | \-\-verbose
103 Print additional information about each zone.
104 .SH USAGE
105 The file
106 .B /etc/bind/chiark-conf-gen.zones
107 (or other file specified with the
108 .B \-C
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
112 .BR # .
113 .SS GENERAL DIRECTIVES
114 These directives specify general configuration details.  They should
115 appear before directives specifying zones, as each will affect only
116 later zone directives.
117 .TP
118 \fBself\-addr\fP \fIfqdn ...\fP
119 Specifies the list of addresses that this server may be known by in
120 A records.  There is no default.
121 .TP
122 \fBself\-ns\fP \fIfqdn ...\fP
123 Specifies the list of names that this server may be known by in NS
124 records.  There is no default.
125 .TP
126 \fBself\-soa\fP \fIfqdn ...\fP
127 Specifies the list of names that this server may be known by in
128 the ORIGIN field of SOA records.  There is no default.
129 .TP
130 .BI self " fqdn ..."
131 Equivalent to both
132 .B self\-ns " and " self\-soa
133 with the same set of names.
134 .TP
135 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
136 Specifies the directory in which slave (published and stealth)
137 zonefiles should be placed.  The default
138 .I directory
139 is
140 .BR /var/cache/bind/chiark-slave .
141 The default
142 .IR suffix " and " prefix
143 are empty; they also will be reset to these defaults by a
144 .B slave\-dir
145 directive which does not specify them.
146 .TP
147 \fBdefault\-dir\fP \fIdirectory\fP
148 Makes
149 .I directory
150 be the default directory (which affects the interpretation of
151 relative filenames).  The default is the directory containing
152 the main configuration file, ie
153 .BR /etc/bind
154 if no
155 .B -C
156 option is specified.
157 .TP
158 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
159 Arranges that each
160 .I filename
161 will be overwritten when
162 .BR -y " or " -f
163 are used; its new contents will be configuration
164 directives for the zones which follow for the
165 nameserver in question.  Currently the only
166 .I format
167 supported is
168 .B bind8
169 which indicates new-style BIND 8.  If no zones follow, then each
170 file will still be overwritten, by an effectively empty file.
171 Default: if there is no
172 .B output
173 directive in the configuration then the default is to use
174 .BR bind8 " " chiark-conf-gen.bind8 ;
175 otherwise it is an error for there to be any zones in the
176 configuration before the first
177 .B output
178 directive.
179 .SS ZONE DIRECTIVES
180 These directives specify one or more zones.
181 .TP
182 .BR primary [ * | ? "] \fIzone filename\fP"
183 Specifies that this server is supposed to be the primary nameserver
184 for
185 .I zone
186 and that the zone data is to be found in
187 .IR filename .
188 .TP
189 .BR primary\-dir [ * | ? "] \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]"
190 Search
191 .I directory
192 for files whose names match the glob pattern
193 .IR suffix * prefix .
194 Each such file is taken to represent a zone file for which this server
195 is supposed to be the primary.  * is the name of the zone.  The
196 default for
197 .I suffix
198 is
199 .BR _db ;
200 the default for
201 .I prefix
202 is empty.
203 .TP
204 .BR published [ * | ? "] \fIzone origin\-addr\fP"
205 Specifies that this server is supposed to be a published slave
206 nameserver for the zone in question.
207 .TP
208 .BR stealth [ * | ? "] \fIzone server\-addr ...\fP"
209 Specifies that this server is supposed to be an unpublished secondary
210 (aka stealth secondary) for the zone in question.
211 .SS ZONE DIRECTIVE STYLE MODIFIERS
212 Each of the zone directives may optionally be followed by one of the
213 following characters:
214 .TP
215 .B *
216 Indicates that the zone is unofficial, ie that it is not delegated as
217 part of the global Internet DNS and that no attempt should be made to
218 find the superzone and check delegations.  Note that unofficial, local
219 zones should be created with caution.  They should be in parts of the
220 namespace which are reserved for private use, or belong to the actual
221 zone maintainer.
222 .TP
223 .B ?
224 Indicates that the zone is known to be broken and no checks should be
225 carried out on it, unless the
226 .B \-A
227 option is specified.
228 .SS OTHER DIRECTIVES
229 .TP
230 \fBinclude\fP \fIfile\fP
231 Reads
232 .I file
233 as if it were included here.
234 .TP
235 \fBend\fP
236 Ends processing of this file; any data beyond this point is ignored.
237 .SH CHECKS
238 chiark\-named\-conf makes the following checks:
239
240 Delegations: Each delegation from a server for the superzone should
241 contain the same set of nameservers.  None of the delegations should
242 lack glue.  The glue addresses should be the same in each delegation,
243 and agree with the local default nameserver.
244
245 Delegated servers: Each server mentioned in the delegation should have
246 the same SOA record (and obviously, should be authoritative).
247
248 All published nameservers - including delegated servers and servers
249 named in the zone's nameserver set: All nameservers for the zone
250 should supply the same list of nameservers for the zone, and none of
251 this authority information should be glueless.  All the glue should
252 always give the same addresses.
253
254 Origin server's data: The set of nameservers in the origin server's
255 version of the zone should be a superset of those in the delegations.
256
257 Our zone configuration: For
258 .B primary
259 zones, the SOA origin should be one of the names specified with
260 .BR self\-soa " (or " self ).  For
261 .B published
262 zones, the address should be that of the SOA origin.  For
263 .B stealth
264 zones, the address should be that of the SOA origin or one of the
265 published nameservers.
266 .SH SECURITY
267 chiark\-named\-conf is supposed to be resistant to malicious data in
268 the DNS.  It is not resistant to malicious data in its own options,
269 configuration file or environment.  It is not supposed to read its
270 stdin, but is not guaranteed to be safe if stdin is dangerous.
271 .LP
272 Killing chiark-named-conf suddenly should be safe, even with
273 .BR -y " or " -f
274 (though of course it may not complete its task if killed), provided
275 that only one invocation is made at once.
276 .LP
277 Slow remote nameservers will cause chiark-named-conf to take
278 excessively long.
279 .SH EXIT STATUS
280 .TP
281 .B 0
282 All went well and there were no warnings.
283 .TP
284 any other
285 There were warnings or errors.
286 .SH FILES
287 .TP
288 .B /etc/bind/chiark-conf-gen.zones
289 Default input configuration file.  (Override with
290 .BR -C .)
291 .TP
292 .B /etc/bind
293 Default directory.  (Override with
294 .BR -C " or " default\-dir .)
295 .TP
296 .IB dir /chiark-conf-gen.bind8
297 Default output file.
298 .TP
299 .B /var/cache/bind/chiark-slave
300 Default location for slave zones.
301 .SH ENVIRONMENT
302 .LP
303 Setting variables used by
304 .BR dig (1)
305 and
306 .BR adnshost (1)
307 will affect the operation of chiark\-named\-conf.  
308 Avoid messing with these if possible.
309 .LP
310 .B PATH
311 Used to find subprograms such as
312 .BR dig " and " adnshost .
313 .SH BUGS
314 The determination of the parent zone for each zone to be checked, and
315 its nameservers, is done simply using the system default nameserver.
316
317 The processing of output from
318 .B dig
319 is not very reliable or robust, but this is mainly the fault of dig.
320 This can lead to somewhat unhelpful error reporting for lookup
321 failures.
322 .SH AUTHOR
323 .B chiark\-named\-conf
324 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.