chiark / gitweb /
Working on new options -C and -g 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 \fB\-C\fP|\-\-config \fIconfig\-file\fP
49 Use
50 .I config\-file
51 instead of
52 .BR /etc/bind/chiark-conf-gen.zones .
53 .TP
54 .BR \-q | \-\-quiet
55 Do not print any information about zone(s) which do not have warnings.
56 .TP
57 .BR \-l | \-\-local
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
62 .B \-l
63 option is repeated.  It is a mistake to specify
64 .B \-l
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.
67 .TP
68 .BR \-v | \-\-verbose
69 Print additional information about each zone.
70 .TP
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
77 .br
78 .B example.com NS ns0.example.net.uk
79 .br
80 .B example.com NS ns1.example.net.uk
81 .br
82 .B example.net.uk NS ns0.example.com
83 .br
84 .B example.net.uk NS ns1.example.com
85 .br
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.
89 .TP
90 .BR \-D
91 Enables debugging.  Useful for debugging chiark\-named\-conf, but
92 probably not useful for debugging your DNS configuration.
93 .SH USAGE
94 The file
95 .B /etc/bind/chiark-conf-gen.zones
96 (or other file specified with the
97 .B \-C
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
101 .BR # .
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.
106 .TP
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.
110 .TP
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.
114 .TP
115 .BI self " fqdn ..."
116 Equivalent to both
117 .B self\-ns " and " self\-soa
118 with the same set of names.
119 .TP
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
123 .I directory
124 is
125 .BR /var/cache/bind/chiark-slave .
126 The default
127 .IR suffix " and " prefix
128 are empty; they also will be reset to these defaults by a
129 .B slave\-dir
130 directive which does not specify them.
131 .TP
132 \fBdefault\-dir\fP \fIdirectory\fP
133 Makes
134 .I directory
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
138 .BR /etc/bind
139 if no
140 .B -C
141 option is specified.
142 .TP
143 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
144 Arranges that each
145 .I filename
146 will be overwritten when
147 .BR -y " or " -f
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
151 .I format
152 supported is
153 .B bind8
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
157 .B output
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
162 .B output
163 directive.
164 .SS ZONE DIRECTIVES
165 These directives specify one or more zones.
166 .TP
167 \fBprimary\fP \fIzone\fP \fIfilename\fP
168 Specifies that this server is supposed to be the primary nameserver
169 for
170 .I zone
171 and that the zone data is to be found in
172 .IR filename .
173 .TP
174 \fBprimary-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
175 Search
176 .I directory
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
181 default for
182 .I suffix
183 is
184 .BR _db ;
185 the default for
186 .I prefix
187 is empty.
188 .TP
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.
192 .TP
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.
196 .SS OTHER DIRECTIVES
197 .TP
198 \fBinclude\fP \fIfile\fP
199 Reads
200 .I file
201 as if it were included here.
202 .TP
203 \fBend\fP
204 Ends processing of this file; any data beyond this point is ignored.
205 .SH CHECKS
206 chiark\-named\-conf makes the following checks:
207
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.
212
213 Delegated servers: Each server mentioned in the delegation should have
214 the same SOA record (and obviously, should be authoritative).
215
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.
221
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.
224
225 Our zone configuration: For
226 .B primary
227 zones, the SOA origin should be one of the names specified with
228 .BR self\-soa " (or " self ).  For
229 .B secondary
230 zones, the address should be that of the SOA origin.  For
231 .B stealth
232 zones, the address should be that of the SOA origin or one of the
233 published nameservers.
234 .SH FILES
235 .TP
236 .B /etc/bind/chiark-conf-gen.zones
237 Default input configuration file.  (Override with
238 .BR -C .)
239 .TP
240 .B /etc/bind
241 Default directory.  (Override with
242 .BR -C " or " default\-dir .)
243 .TP
244 .IB dir /chiark-conf-gen.bind8
245 Default output file.
246 .TP
247 .B /var/cache/bind/chiark-slave
248 Default location for slave zones.
249 .SH BUGS
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.
252
253 The processing of output from
254 .B dig
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
257 failures.
258 .SH AUTHOR
259 .B chiark\-named\-conf
260 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.