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