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
48 \fB\-C\fP|\-\-config \fIconfig\-file\fP
52 .BR /etc/bind/chiark-conf-gen.zones .
55 Do not print any information about zone(s) which do not have warnings.
58 Only checks for mistakes which are the responsibility of the local
59 administrator. This means that for secondary and stealth zones we
60 only check that we're slaving from the right place. For primary zones
61 all checks are still done, unless the
63 option is repeated. It is a mistake to specify
65 with foreign zones (zones supplied explictly on the command line but
66 not relevant to the local server), so this counts as a warning.
69 Print additional information about each zone.
71 .BR \-g | \-\-glueless-ok
72 Do not warn about glueless referrals. Not recommended. Note that
73 glueless referrals usually causes extra delays looking up names, and
74 can cause lookups to fail even if in theory they could succeed. There
75 is no generally agreed convention or standard for avoiding circular
76 glueless situations such as
78 .B example.com NS ns0.example.net.uk
80 .B example.com NS ns1.example.net.uk
82 .B example.net.uk NS ns0.example.com
84 .B example.net.uk NS ns1.example.com
86 where gluelessness would completely prevent lookups inside
87 example.net.uk and example.com. The best way to be sure to avoid this
88 is to avoid gluelessness.
91 Enables debugging. Useful for debugging chiark\-named\-conf, but
92 probably not useful for debugging your DNS configuration.
95 .B /etc/bind/chiark-conf-gen.zones
96 (or other file specified with the
98 option) contains a sequence of directives, one per line. Blank lines
99 are permitted. Leading and trailing whitespace on each line is
100 ignored. Comments are lines starting with
102 .SS GENERAL DIRECTIVES
103 These directives specify general configuration details. They should
104 appear before directives specifying zones, as each will affect only
105 later zone directives.
107 \fBself\-ns\fP \fIfqdn ...\fP
108 Specifies the list of names that this server may be known by in NS
109 records. There is no default.
111 \fBself\-soa\fP \fIfqdn ...\fP
112 Specifies the list of names that this server may be known by in
113 the ORIGIN field of SOA records. There is no default.
117 .B self\-ns " and " self\-soa
118 with the same set of names.
120 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
121 Specifies the directory in which slave (secondary and stealth)
122 zonefiles should be placed. The default
125 .BR /var/cache/bind/chiark-slave .
127 .IR suffix " and " prefix
128 are empty; they also will be reset to these defaults by a
130 directive which does not specify them.
132 \fBdefault\-dir\fP \fIdirectory\fP
135 be the default directory (which affects the interpretation of
136 relative filenames). The default is the directory containing
137 the main configuration file, ie
143 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
146 will be overwritten when
148 are used; its new contents will be configuration
149 directives for the zones which follow for the
150 nameserver in question. Currently the only
154 which indicates new-style BIND 8. If no zones follow, then each
155 file will still be overwritten, by an effectively empty file.
156 Default: if there is no
158 directive in the configuration then the default is to use
159 .BR bind8 " " chiark-conf-gen.bind8 ;
160 otherwise it is an error for there to be any zones in the
161 configuration before the first
165 These directives specify one or more zones.
167 \fBprimary\fP \fIzone\fP \fIfilename\fP
168 Specifies that this server is supposed to be the primary nameserver
171 and that the zone data is to be found in
174 \fBprimary-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
177 for files whose names match the glob pattern
178 .IR suffix * prefix .
179 Each such file is taken to represent a zone file for which this server
180 is supposed to be the primary. * is the name of the zone. The
189 \fBsecondary\fP \fIzone\fP \fIorigin\-addr\fP
190 Specifies that this server is supposed to be a published secondary for
191 the zone in question.
193 \fBstealth\fP \fIzone\fP \fIserver\-addr ...\fP
194 Specifies that this server is supposed to be an unpublished secondary
195 (aka stealth secondary) for the zone in question.
198 \fBinclude\fP \fIfile\fP
201 as if it were included here.
204 Ends processing of this file; any data beyond this point is ignored.
206 chiark\-named\-conf makes the following checks:
208 Delegations: Each delegation from a server for the superzone should
209 contain the same set of nameservers. None of the delegations should
210 lack glue. The glue addresses should be the same in each delegation,
211 and agree with the local default nameserver.
213 Delegated servers: Each server mentioned in the delegation should have
214 the same SOA record (and obviously, should be authoritative).
216 All published nameservers - including delegated servers and servers
217 named in the zone's nameserver set: All nameservers for the zone
218 should supply the same list of nameservers for the zone, and none of
219 this authority information should be glueless. All the glue should
220 always give the same addresses.
222 Origin server's data: The set of nameservers in the origin server's
223 version of the zone should be a superset of those in the delegations.
225 Our zone configuration: For
227 zones, the SOA origin should be one of the names specified with
228 .BR self\-soa " (or " self ). For
230 zones, the address should be that of the SOA origin. For
232 zones, the address should be that of the SOA origin or one of the
233 published nameservers.
236 .B /etc/bind/chiark-conf-gen.zones
237 Default input configuration file. (Override with
241 Default directory. (Override with
242 .BR -C " or " default\-dir .)
244 .IB dir /chiark-conf-gen.bind8
247 .B /var/cache/bind/chiark-slave
248 Default location for slave zones.
250 The determination of the parent zone for each zone to be checked, and
251 its nameservers, is done simply using the system default nameserver.
253 The processing of output from
255 is not very reliable or robust, but this is mainly the fault of dig.
256 This can lead to somewhat unhelpful error reporting for lookup
259 .B chiark\-named\-conf
260 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.