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 Also changes the default directory.
  54 .TP
  55 .BR \-D
  56 Enables debugging.  Useful for debugging chiark\-named\-conf, but
  57 probably not useful for debugging your DNS configuration.  Repeat to
  58 increase the debugging level.  (Maximum is
  59 .BR -DD .)
  60 .TP
  61 .BR \-g | \-\-glueless
  62 Warn only once about a glueless referral for each zone and server,
  63 rather than once for each parent which gave out a referral without
  64 glue.
  65
  66 When repeated, do not warn about glueless referrals at all.  Not
  67 recommended.  Note that glueless referrals usually cause extra delays
  68 looking up names, and can make lookups fail even if in theory they
  69 could succeed.  There is no generally agreed convention or standard
  70 for avoiding circular glueless situations such as
  71 .br
  72 .B example.com NS ns0.example.net.uk
  73 .br
  74 .B example.com NS ns1.example.net.uk
  75 .br
  76 .B example.net.uk NS ns0.example.com
  77 .br
  78 .B example.net.uk NS ns1.example.com
  79 .br
  80 where gluelessness would completely prevent lookups inside
  81 example.net.uk and example.com.  The best way to be sure to avoid this
  82 is to avoid gluelessness.
  83 .TP
  84 .BR \-l | \-\-local
  85 Only checks for mistakes which are the responsibility of the local
  86 administrator.  This means that for secondary and stealth zones we
  87 only check that we're slaving from the right place.  For primary zones
  88 all checks are still done.  It is a mistake to specify
  89 .B \-l
  90 with foreign zones (zones supplied explictly on the command line but
  91 not relevant to the local server); doing so produces a warning.
  92 .TP
  93 .BR \-q | \-\-quiet
  94 Do not print any information about zone(s) which do not have warnings.
  95 .TP
  96 .BR \-v | \-\-verbose
  97 Print additional information about each zone.
  98 .SH USAGE
  99 The file
 100 .B /etc/bind/chiark-conf-gen.zones
 101 (or other file specified with the
 102 .B \-C
 103 option) contains a sequence of directives, one per line.  Blank lines
 104 are permitted.  Leading and trailing whitespace on each line is
 105 ignored.  Comments are lines starting with
 106 .BR # .
 107 .SS GENERAL DIRECTIVES
 108 These directives specify general configuration details.  They should
 109 appear before directives specifying zones, as each will affect only
 110 later zone directives.
 111 .TP
 112 \fBself\-ns\fP \fIfqdn ...\fP
 113 Specifies the list of names that this server may be known by in NS
 114 records.  There is no default.
 115 .TP
 116 \fBself\-soa\fP \fIfqdn ...\fP
 117 Specifies the list of names that this server may be known by in
 118 the ORIGIN field of SOA records.  There is no default.
 119 .TP
 120 .BI self " fqdn ..."
 121 Equivalent to both
 122 .B self\-ns " and " self\-soa
 123 with the same set of names.
 124 .TP
 125 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
 126 Specifies the directory in which slave (secondary and stealth)
 127 zonefiles should be placed.  The default
 128 .I directory
 129 is
 130 .BR /var/cache/bind/chiark-slave .
 131 The default
 132 .IR suffix " and " prefix
 133 are empty; they also will be reset to these defaults by a
 134 .B slave\-dir
 135 directive which does not specify them.
 136 .TP
 137 \fBdefault\-dir\fP \fIdirectory\fP
 138 Makes
 139 .I directory
 140 be the default directory (which affects the interpretation of
 141 relative filenames).  The default is the directory containing
 142 the main configuration file, ie
 143 .BR /etc/bind
 144 if no
 145 .B -C
 146 option is specified.
 147 .TP
 148 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 149 Arranges that each
 150 .I filename
 151 will be overwritten when
 152 .BR -y " or " -f
 153 are used; its new contents will be configuration
 154 directives for the zones which follow for the
 155 nameserver in question.  Currently the only
 156 .I format
 157 supported is
 158 .B bind8
 159 which indicates new-style BIND 8.  If no zones follow, then each
 160 file will still be overwritten, by an effectively empty file.
 161 Default: if there is no
 162 .B output
 163 directive in the configuration then the default is to use
 164 .BR bind8 " " chiark-conf-gen.bind8 ;
 165 otherwise it is an error for there to be any zones in the
 166 configuration before the first
 167 .B output
 168 directive.
 169 .SS ZONE DIRECTIVES
 170 These directives specify one or more zones.
 171 .TP
 172 \fBprimary\fP \fIzone\fP \fIfilename\fP
 173 Specifies that this server is supposed to be the primary nameserver
 174 for
 175 .I zone
 176 and that the zone data is to be found in
 177 .IR filename .
 178 .TP
 179 \fBprimary-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
 180 Search
 181 .I directory
 182 for files whose names match the glob pattern
 183 .IR suffix * prefix .
 184 Each such file is taken to represent a zone file for which this server
 185 is supposed to be the primary.  * is the name of the zone.  The
 186 default for
 187 .I suffix
 188 is
 189 .BR _db ;
 190 the default for
 191 .I prefix
 192 is empty.
 193 .TP
 194 \fBsecondary\fP \fIzone\fP \fIorigin\-addr\fP
 195 Specifies that this server is supposed to be a published secondary for
 196 the zone in question.
 197 .TP
 198 \fBstealth\fP \fIzone\fP \fIserver\-addr ...\fP
 199 Specifies that this server is supposed to be an unpublished secondary
 200 (aka stealth secondary) for the zone in question.
 201 .SS OTHER DIRECTIVES
 202 .TP
 203 \fBinclude\fP \fIfile\fP
 204 Reads
 205 .I file
 206 as if it were included here.
 207 .TP
 208 \fBend\fP
 209 Ends processing of this file; any data beyond this point is ignored.
 210 .SH CHECKS
 211 chiark\-named\-conf makes the following checks:
 212
 213 Delegations: Each delegation from a server for the superzone should
 214 contain the same set of nameservers.  None of the delegations should
 215 lack glue.  The glue addresses should be the same in each delegation,
 216 and agree with the local default nameserver.
 217
 218 Delegated servers: Each server mentioned in the delegation should have
 219 the same SOA record (and obviously, should be authoritative).
 220
 221 All published nameservers - including delegated servers and servers
 222 named in the zone's nameserver set: All nameservers for the zone
 223 should supply the same list of nameservers for the zone, and none of
 224 this authority information should be glueless.  All the glue should
 225 always give the same addresses.
 226
 227 Origin server's data: The set of nameservers in the origin server's
 228 version of the zone should be a superset of those in the delegations.
 229
 230 Our zone configuration: For
 231 .B primary
 232 zones, the SOA origin should be one of the names specified with
 233 .BR self\-soa " (or " self ).  For
 234 .B secondary
 235 zones, the address should be that of the SOA origin.  For
 236 .B stealth
 237 zones, the address should be that of the SOA origin or one of the
 238 published nameservers.
 239 .SH SECURITY
 240 chiark\-named\-conf is supposed to be resistant to malicious data in
 241 the DNS.  It is not resistant to malicious data in its own options,
 242 configuration file or environment.  It is not supposed to read its
 243 stdin, but is not guaranteed to be safe if stdin is dangerous.
 244 .LP
 245 Killing chiark-named-conf suddenly should be safe, even with
 246 .BR -y " or " -f
 247 (though of course it may not complete its task if killed), provided
 248 that only one invocation is made at once.
 249 .LP
 250 Slow remote nameservers will cause chiark-named-conf to take
 251 excessively long.
 252 .SH EXIT STATUS
 253 .TP
 254 .B 0
 255 All went well and there were no warnings.
 256 .TP
 257 any other
 258 There were warnings or errors.
 259 .SH FILES
 260 .TP
 261 .B /etc/bind/chiark-conf-gen.zones
 262 Default input configuration file.  (Override with
 263 .BR -C .)
 264 .TP
 265 .B /etc/bind
 266 Default directory.  (Override with
 267 .BR -C " or " default\-dir .)
 268 .TP
 269 .IB dir /chiark-conf-gen.bind8
 270 Default output file.
 271 .TP
 272 .B /var/cache/bind/chiark-slave
 273 Default location for slave zones.
 274 .SH ENVIRONMENT
 275 .LP
 276 Setting variables used by
 277 .BR dig (1)
 278 and
 279 .BR adnshost (1)
 280 will affect the operation of chiark\-named\-conf.
 281 Avoid messing with these if possible.
 282 .LP
 283 .B PATH
 284 Used to find subprograms such as
 285 .BR dig " and " adnshost .
 286 .SH BUGS
 287 The determination of the parent zone for each zone to be checked, and
 288 its nameservers, is done simply using the system default nameserver.
 289
 290 The processing of output from
 291 .B dig
 292 is not very reliable or robust, but this is mainly the fault of dig.
 293 This can lead to somewhat unhelpful error reporting for lookup
 294 failures.
 295 .SH AUTHOR
 296 .B chiark\-named\-conf
 297 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.