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
  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
  22 .B *
  23 after the serial number.
  24 .SH OPTIONS
  25
  26 .SS MODE OPTIONS
  27 If one of the options
  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
  33 the nameserver:
  34 .TP
  35 .BR \-y | \-\-yes
  36 Generate and install new nameserver config, as well as checking
  37 configuration, for all listed zones.
  38 .TP
  39 .BR \-n | \-\-no
  40 Check configuration, for all listed zones, but
  41 do not generate new nameserver config.
  42 .TP
  43 .BR \-f | \-\-force
  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.)
  47 .LP
  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.
  52
  53 .SS ADDITIONAL OPTIONS
  54 .TP
  55 .BR \-A | \-\-all
  56 Checks even zones known to be broken.  Ie, ignores the
  57 .B ?
  58 zone style modifier in the configuration.
  59 .TP
  60 .BR \-C | \-\-config " \fIconfig\-file\fP"
  61 Use
  62 .I config\-file
  63 instead of
  64 .BR /etc/bind/chiark-conf-gen.zones .
  65 Also changes the default directory.
  66 .TP
  67 .BR \-D
  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
  71 .BR -DD .)
  72 .TP
  73 .BR \-g | \-\-glueless
  74 Do not warn about glueless referrals.  Not recommended.  Note that
  75 glueless referrals usually cause extra delays looking up names, and
  76 can make lookups fail even if in theory they could succeed.  There is
  77 no generally agreed convention or standard for avoiding circular
  78 glueless situations such as
  79 .br
  80 .B example.com NS ns0.example.net.uk
  81 .br
  82 .B example.com NS ns1.example.net.uk
  83 .br
  84 .B example.net.uk NS ns0.example.com
  85 .br
  86 .B example.net.uk NS ns1.example.com
  87 .br
  88 where gluelessness would completely prevent lookups inside
  89 example.net.uk and example.com.  The best way to be sure to avoid this
  90 is to avoid gluelessness.
  91 .TP
  92 .BR \-l | \-\-local
  93 Only checks for mistakes which are the responsibility of the local
  94 administrator (to fix or get fixed).  This means that for published
  95 and stealth zones we only check that we're slaving from the right
  96 place and that any names and addresses for ourself are right.  For
  97 primary zones all checks are still done.  It is a mistake to specify
  98 .B \-l
  99 with foreign zones (zones supplied explictly on the command line but
 100 not relevant to the local server); doing so produces a warning.
 101 .TP
 102 .BR \-q | \-\-quiet
 103 Suppress the usual report of the list of nameservers for each zone and
 104 the serial number from each.  When specified twice, do not print any
 105 information except warnings.
 106 .TP
 107 .BR \-r | \-\-repeat
 108 When a problem is detected, warn for all sources of the same imperfect
 109 data, rather than only the first we come across
 110 .TP
 111 .BR \-v | \-\-verbose
 112 Print additional information about what is being checked, as we go
 113 along.
 114 .SH USAGE
 115 The file
 116 .B /etc/bind/chiark-conf-gen.zones
 117 (or other file specified with the
 118 .B \-C
 119 option) contains a sequence of directives, one per line.  Blank lines
 120 are permitted.  Leading and trailing whitespace on each line is
 121 ignored.  Comments are lines starting with
 122 .BR # .
 123 Ending a line with a
 124 .BR \\
 125 joins it to the next line, so that long directives can be split across
 126 several physical lines.
 127 .SS GENERAL DIRECTIVES
 128 These directives specify general configuration details.  They should
 129 appear before directives specifying zones, as each will affect only
 130 later zone directives.
 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 \fBforbid\-addr\fP [\fIip-address ...\fP]
 144 Specifies the list of addresses that are forbidden as any nameserver
 145 for any zone.  The default is no such addresses.
 146 .TP
 147 \fBserverless\-glueless\fP \fIdomain ...\fP
 148 Specifies a list of domains under which we do not expect to find any
 149 nameservers; for these zones it is OK to find glueless referrals.
 150 Each domain listed names a complete subtree of the DNS, starting at
 151 the named point.  The default is
 152 .BR "in\-addr.arpa ip6.arpa ip6.int" .
 153
 154 To avoid indefinitely long or even circularly glueless referrals
 155 (which delay or prevent lookups) it is necessary for all sites to
 156 effectively implement similar conventions; currently the author
 157 believes that only the reverse lookup namespaces are conventionally
 158 devoid of nameservers, and therefore fine to provide glueless
 159 referrals for.
 160 .TP
 161 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 162 Arranges that each
 163 .I filename
 164 will be overwritten when
 165 .BR -y " or " -f
 166 are used; its new contents will be configuration
 167 directives for the zones which follow for the
 168 nameserver in question.  Currently the only
 169 .I format
 170 supported is
 171 .B bind8
 172 which indicates new-style BIND 8.  If no zones follow, then each
 173 file will still be overwritten, by an effectively empty file.
 174 Default: if there is no
 175 .B output
 176 directive in the configuration then the default is to use
 177 .BR bind8 " " chiark-conf-gen.bind8 ;
 178 otherwise it is an error for there to be any zones in the
 179 configuration before the first
 180 .B output
 181 directive.
 182 .TP
 183 \fBself\-addr\fP \fIip-address ...\fP
 184 Specifies the list of addresses that this server may be known by in
 185 A records.  There is no default.
 186 .TP
 187 \fBself\-ns\fP \fIfqdn ...\fP
 188 Specifies the list of names that this server may be known by in NS
 189 records.  There is no default.
 190 .TP
 191 \fBself\-soa\fP \fIfqdn ...\fP
 192 Specifies the list of names that this server may be known by in
 193 the ORIGIN field of SOA records.  There is no default.
 194 .TP
 195 .BI self " fqdn ..."
 196 Equivalent to both
 197 .B self\-ns " and " self\-soa
 198 with the same set of names.
 199 .TP
 200 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
 201 Specifies the directory in which slave (published and stealth)
 202 zonefiles should be placed.  The default
 203 .I directory
 204 is
 205 .BR /var/cache/bind/chiark-slave .
 206 The default
 207 .IR suffix " and " prefix
 208 are empty; they also will be reset to these defaults by a
 209 .B slave\-dir
 210 directive which does not specify them.
 211 .SS ZONE DIRECTIVES
 212 These directives specify one or more zones.
 213 .TP
 214 .BR primary [ * | ? "] \fIzone filename\fP"
 215 Specifies that this server is supposed to be the primary nameserver
 216 for
 217 .I zone
 218 and that the zone data is to be found in
 219 .IR filename .
 220 .TP
 221 .BR primary\-dir [ * | ? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]]
 222 Search
 223 .I directory
 224 for files whose names start with
 225 .I prefix
 226 and end with
 227 .IR suffix .
 228 Each such file is taken to represent a zone file for which this server
 229 is supposed to be the primary; the part of the filename between
 230 .IR prefix " and " suffix
 231 is the name of the zone.
 232
 233 If
 234 .BI / subfile
 235 is specified, then instead of looking for files, we search for
 236 directories containing
 237 .IR subfile ;
 238 directories which do not contain the subfile are simply skipped.
 239
 240 If
 241 .IR directory [\fB/\fP prefix ]
 242 exists as specified and is a directory then it is interpreted as
 243 .I directory
 244 with an empty prefix; otherwise the final path component is assumed to
 245 be the prefix.  If no
 246 .IB suffix / subfile
 247 is specified then the default is
 248 .BR _db .
 249 .TP
 250 .BR published [ * | ? "] \fIzone origin\-addr\fP"
 251 Specifies that this server is supposed to be a published slave
 252 nameserver for the zone in question.
 253 .TP
 254 .BR stealth [ * | ? "] \fIzone server\-addr ...\fP"
 255 Specifies that this server is supposed to be an unpublished secondary
 256 (aka stealth secondary) for the zone in question.
 257 .SS ZONE DIRECTIVE STYLE MODIFIERS
 258 Each of the zone directives may optionally be followed by one of the
 259 following characters:
 260 .TP
 261 .B *
 262 Indicates that the zone is unofficial, ie that it is not delegated as
 263 part of the global Internet DNS and that no attempt should be made to
 264 find the superzone and check delegations.  Note that unofficial, local
 265 zones should be created with caution.  They should be in parts of the
 266 namespace which are reserved for private use, or belong to the actual
 267 zone maintainer.
 268 .TP
 269 .B ?
 270 Indicates that the zone is known to be broken and no checks should be
 271 carried out on it, unless the
 272 .B \-A
 273 option is specified.
 274 .SS OTHER DIRECTIVES
 275 .TP
 276 \fBinclude\fP \fIfile\fP
 277 Reads
 278 .I file
 279 as if it were included here.
 280 .TP
 281 \fBend\fP
 282 Ends processing of this file; any data beyond this point is ignored.
 283 .SH CHECKS
 284 chiark\-named\-conf makes the following checks:
 285
 286 Delegations: Each delegation from a server for the superzone should
 287 contain the same set of nameservers.  None of the delegations should
 288 lack glue.  The glue addresses should be the same in each delegation,
 289 and agree with the local default nameserver.
 290
 291 Delegated servers: Each server mentioned in the delegation should have
 292 the same SOA record (and obviously, should be authoritative).
 293
 294 All published nameservers - including delegated servers and servers
 295 named in the zone's nameserver set: All nameservers for the zone
 296 should supply the same list of nameservers for the zone, and none of
 297 this authority information should be glueless.  All the glue should
 298 always give the same addresses.
 299
 300 Origin server's data: The set of nameservers in the origin server's
 301 version of the zone should be a superset of those in the delegations.
 302
 303 Our zone configuration: For primary zones, the SOA origin should be
 304 one of the names specified with
 305 .BR self\-soa " (or " self ).
 306 For published zones, the address should be that of the SOA origin.
 307 For stealth zones, the address should be that of the SOA origin or one
 308 of the published nameservers.
 309 .SH SECURITY
 310 chiark\-named\-conf is supposed to be resistant to malicious data in
 311 the DNS.  It is not resistant to malicious data in its own options,
 312 configuration file or environment.  It is not supposed to read its
 313 stdin, but is not guaranteed to be safe if stdin is dangerous.
 314 .LP
 315 Killing chiark-named-conf suddenly should be safe, even with
 316 .BR -y " or " -f
 317 (though of course it may not complete its task if killed), provided
 318 that only one invocation is made at once.
 319 .LP
 320 Slow remote nameservers will cause chiark-named-conf to take
 321 excessively long.
 322 .SH EXIT STATUS
 323 .TP
 324 .B 0
 325 All went well and there were no warnings.
 326 .TP
 327 any other
 328 There were warnings or errors.
 329 .SH FILES
 330 .TP
 331 .B /etc/bind/chiark-conf-gen.zones
 332 Default input configuration file.  (Override with
 333 .BR -C .)
 334 .TP
 335 .B /etc/bind
 336 Default directory.  (Override with
 337 .BR -C " or " default\-dir .)
 338 .TP
 339 .IB dir /chiark-conf-gen.bind8
 340 Default output file.
 341 .TP
 342 .B /var/cache/bind/chiark-slave
 343 Default location for slave zones.
 344 .SH ENVIRONMENT
 345 .LP
 346 Setting variables used by
 347 .BR dig (1)
 348 and
 349 .BR adnshost (1)
 350 will affect the operation of chiark\-named\-conf.
 351 Avoid messing with these if possible.
 352 .LP
 353 .B PATH
 354 is used to find subprograms such as
 355 .BR dig " and " adnshost .
 356 .SH BUGS
 357 The determination of the parent zone for each zone to be checked, and
 358 its nameservers, is done simply using the system default nameserver.
 359
 360 The processing of output from
 361 .B dig
 362 is not very reliable or robust, but this is mainly the fault of dig.
 363 This can lead to somewhat unhelpful error reporting for lookup
 364 failures.
 365 .SH AUTHOR
 366 .B chiark\-named\-conf
 367 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.