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