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 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 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 \fBself\-addr\fP \fIip-address ...\fP
 123 Specifies the list of addresses that this server may be known by in
 124 A records.  There is no default.
 125 .TP
 126 \fBself\-ns\fP \fIfqdn ...\fP
 127 Specifies the list of names that this server may be known by in NS
 128 records.  There is no default.
 129 .TP
 130 \fBself\-soa\fP \fIfqdn ...\fP
 131 Specifies the list of names that this server may be known by in
 132 the ORIGIN field of SOA records.  There is no default.
 133 .TP
 134 .BI self " fqdn ..."
 135 Equivalent to both
 136 .B self\-ns " and " self\-soa
 137 with the same set of names.
 138 .TP
 139 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
 140 Specifies the directory in which slave (published and stealth)
 141 zonefiles should be placed.  The default
 142 .I directory
 143 is
 144 .BR /var/cache/bind/chiark-slave .
 145 The default
 146 .IR suffix " and " prefix
 147 are empty; they also will be reset to these defaults by a
 148 .B slave\-dir
 149 directive which does not specify them.
 150 .TP
 151 \fBdefault\-dir\fP \fIdirectory\fP
 152 Makes
 153 .I directory
 154 be the default directory (which affects the interpretation of
 155 relative filenames).  The default is the directory containing
 156 the main configuration file, ie
 157 .BR /etc/bind
 158 if no
 159 .B -C
 160 option is specified.
 161 .TP
 162 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 163 Arranges that each
 164 .I filename
 165 will be overwritten when
 166 .BR -y " or " -f
 167 are used; its new contents will be configuration
 168 directives for the zones which follow for the
 169 nameserver in question.  Currently the only
 170 .I format
 171 supported is
 172 .B bind8
 173 which indicates new-style BIND 8.  If no zones follow, then each
 174 file will still be overwritten, by an effectively empty file.
 175 Default: if there is no
 176 .B output
 177 directive in the configuration then the default is to use
 178 .BR bind8 " " chiark-conf-gen.bind8 ;
 179 otherwise it is an error for there to be any zones in the
 180 configuration before the first
 181 .B output
 182 directive.
 183 .SS ZONE DIRECTIVES
 184 These directives specify one or more zones.
 185 .TP
 186 .BR primary [ * | ? "] \fIzone filename\fP"
 187 Specifies that this server is supposed to be the primary nameserver
 188 for
 189 .I zone
 190 and that the zone data is to be found in
 191 .IR filename .
 192 .TP
 193 .BR primary\-dir [ * | ? "] \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]"
 194 Search
 195 .I directory
 196 for files whose names match the glob pattern
 197 .IR suffix * prefix .
 198 Each such file is taken to represent a zone file for which this server
 199 is supposed to be the primary.  * is the name of the zone.  The
 200 default for
 201 .I suffix
 202 is
 203 .BR _db ;
 204 the default for
 205 .I prefix
 206 is empty.
 207 .TP
 208 .BR published [ * | ? "] \fIzone origin\-addr\fP"
 209 Specifies that this server is supposed to be a published slave
 210 nameserver for the zone in question.
 211 .TP
 212 .BR stealth [ * | ? "] \fIzone server\-addr ...\fP"
 213 Specifies that this server is supposed to be an unpublished secondary
 214 (aka stealth secondary) for the zone in question.
 215 .SS ZONE DIRECTIVE STYLE MODIFIERS
 216 Each of the zone directives may optionally be followed by one of the
 217 following characters:
 218 .TP
 219 .B *
 220 Indicates that the zone is unofficial, ie that it is not delegated as
 221 part of the global Internet DNS and that no attempt should be made to
 222 find the superzone and check delegations.  Note that unofficial, local
 223 zones should be created with caution.  They should be in parts of the
 224 namespace which are reserved for private use, or belong to the actual
 225 zone maintainer.
 226 .TP
 227 .B ?
 228 Indicates that the zone is known to be broken and no checks should be
 229 carried out on it, unless the
 230 .B \-A
 231 option is specified.
 232 .SS OTHER DIRECTIVES
 233 .TP
 234 \fBinclude\fP \fIfile\fP
 235 Reads
 236 .I file
 237 as if it were included here.
 238 .TP
 239 \fBend\fP
 240 Ends processing of this file; any data beyond this point is ignored.
 241 .SH CHECKS
 242 chiark\-named\-conf makes the following checks:
 243
 244 Delegations: Each delegation from a server for the superzone should
 245 contain the same set of nameservers.  None of the delegations should
 246 lack glue.  The glue addresses should be the same in each delegation,
 247 and agree with the local default nameserver.
 248
 249 Delegated servers: Each server mentioned in the delegation should have
 250 the same SOA record (and obviously, should be authoritative).
 251
 252 All published nameservers - including delegated servers and servers
 253 named in the zone's nameserver set: All nameservers for the zone
 254 should supply the same list of nameservers for the zone, and none of
 255 this authority information should be glueless.  All the glue should
 256 always give the same addresses.
 257
 258 Origin server's data: The set of nameservers in the origin server's
 259 version of the zone should be a superset of those in the delegations.
 260
 261 Our zone configuration: For primary zones, the SOA origin should be
 262 one of the names specified with
 263 .BR self\-soa " (or " self ).
 264 For published zones, the address should be that of the SOA origin.
 265 For stealth zones, the address should be that of the SOA origin or one
 266 of the published nameservers.
 267 .SH SECURITY
 268 chiark\-named\-conf is supposed to be resistant to malicious data in
 269 the DNS.  It is not resistant to malicious data in its own options,
 270 configuration file or environment.  It is not supposed to read its
 271 stdin, but is not guaranteed to be safe if stdin is dangerous.
 272 .LP
 273 Killing chiark-named-conf suddenly should be safe, even with
 274 .BR -y " or " -f
 275 (though of course it may not complete its task if killed), provided
 276 that only one invocation is made at once.
 277 .LP
 278 Slow remote nameservers will cause chiark-named-conf to take
 279 excessively long.
 280 .SH EXIT STATUS
 281 .TP
 282 .B 0
 283 All went well and there were no warnings.
 284 .TP
 285 any other
 286 There were warnings or errors.
 287 .SH FILES
 288 .TP
 289 .B /etc/bind/chiark-conf-gen.zones
 290 Default input configuration file.  (Override with
 291 .BR -C .)
 292 .TP
 293 .B /etc/bind
 294 Default directory.  (Override with
 295 .BR -C " or " default\-dir .)
 296 .TP
 297 .IB dir /chiark-conf-gen.bind8
 298 Default output file.
 299 .TP
 300 .B /var/cache/bind/chiark-slave
 301 Default location for slave zones.
 302 .SH ENVIRONMENT
 303 .LP
 304 Setting variables used by
 305 .BR dig (1)
 306 and
 307 .BR adnshost (1)
 308 will affect the operation of chiark\-named\-conf.
 309 Avoid messing with these if possible.
 310 .LP
 311 .B PATH
 312 is used to find subprograms such as
 313 .BR dig " and " adnshost .
 314 .SH BUGS
 315 The determination of the parent zone for each zone to be checked, and
 316 its nameservers, is done simply using the system default nameserver.
 317
 318 The processing of output from
 319 .B dig
 320 is not very reliable or robust, but this is mainly the fault of dig.
 321 This can lead to somewhat unhelpful error reporting for lookup
 322 failures.
 323 .SH AUTHOR
 324 .B chiark\-named\-conf
 325 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.