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