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