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
   6 .SH SYNOPSIS
   7 .B chiark\-named\-conf [\fIoptions\fP] \-n|\-y|\-f
   8 .br
   9 .B chiark\-named\-conf [\fIoptions\fP] \fIzone ...\fP
  10
  11 .SH DESCRIPTION
  12 .B chiark\-named\-conf
  13 is a tool for managing nameserver configurations and checking for
  14 suspected DNS problems.  Its main functions are to check that
  15 delegations are appropriate and working, optionally from the root zone
  16 down, and to generate a configuration for
  17 .BR BIND ,
  18 from its own input file.
  19
  20 .SH OPTIONS
  21 .SS MODE OPTIONS
  22 If one of the options
  23 .BR -n ", " -y ", or " -f
  24 is supplied then chiark-named-conf will read its main configuration
  25 file for the list of relevant zones.  It will then check the
  26 configuration and delegation for each zone
  27 and/or generate and install a new configuration file for
  28 the nameserver:
  29 .TP
  30 .BR \-y | \-\-yes
  31 Generate and install new nameserver config, as well as checking
  32 configuration, for all listed zones.
  33 .TP
  34 .BR \-n | \-\-no
  35 Check configuration, for all listed zones, but
  36 do not generate new nameserver config.
  37 .TP
  38 .BR \-f | \-\-force
  39 Generate and install new nameserver config, without doing any
  40 configuration cross-checking.  (Syntax errors in our input
  41 configuration will still abort this operation.)
  42 .LP
  43 Alternatively, one or more zone names may be supplied as arguments, in
  44 which case their delegations will be checked, and compared with the
  45 data for that zone in the main configuration (if any).  In this case
  46 no new configuration file for the nameserver will be made.
  47
  48 .SS ADDITIONAL OPTIONS
  49 .TP
  50 \fB\-C\fP|\-\-config \fIconfig\-file\fP
  51 Use
  52 .I config\-file
  53 instead of
  54 .BR /etc/bind/chiark-conf-gen.zones .
  55 .TP
  56 .BR \-q | \-\-quiet
  57 Do not print any information about zone(s) which do not have warnings.
  58 .TP
  59 .BR \-v | \-\-verbose
  60 Print additional information about each zone.
  61 .TP
  62 .BR \-r | \-\-root
  63 Check the delegation all the way to the root zone.  By default,
  64 checks are only carried out on the delegations supplied by (all) the
  65 nameservers for the immediate superzone.
  66 .SH CONFIGURATION
  67 The file
  68 .B /etc/bind/chiark-conf-gen.zones
  69 (or other file specified with the
  70 .B \-C
  71 option) contains a sequence of directives, one per line.  Blank lines
  72 are permitted.  Leading and trailing whitespace on each line is
  73 ignored.  Comments are lines starting with
  74 .BR # .
  75 .SS GENERAL DIRECTIVES
  76 These directives specify general configuration details.  They should
  77 appear before directives specifying zones, as each will affect only
  78 later zone directives.
  79 .TP
  80 \fBself\-ns\fP \fIfqdn ...\fP
  81 Specifies the list of names that this server may be known by in NS
  82 records.  There is no default.
  83 .TP
  84 \fBself\-soa\fP \fIfqdn ...\fP
  85 Specifies the list of names that this server may be known by in
  86 the ORIGIN field of SOA records.  There is no default.
  87 .TP
  88 \fBself\fP \fIfqdn ...\fP
  89 Equivalent to both
  90 .BR self\-ns " and " self-\soa
  91 with the same set of names.
  92 .TP
  93 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
  94 Specifies the directory in which slave (secondary and stealth)
  95 zonefiles should be placed.  The default
  96 .I directory
  97 is
  98 .BR /var/cache/bind/chiark-slave .
  99 The default
 100 .IR suffix " and " prefix
 101 are empty; they also will be reset to these defaults by a
 102 .B slave\-dir
 103 directive which does not specify them.
 104 .TP
 105 \fBdefault\-dir\fP \fIdirectory\fP
 106 Makes
 107 .I directory
 108 be the default directory (which affects the interpretation of
 109 relative filenames).  The default is the directory containing
 110 the main configuration file, ie
 111 .BR /etc/bind
 112 if no
 113 .B -C
 114 option is specified.
 115 .TP
 116 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 117 Arranges that each
 118 .I filename
 119 will be overwritten when
 120 .BR -y " or " -f
 121 are used; its new contents will be configuration
 122 directives for the zones which follow for the
 123 nameserver in question.  Currently the only
 124 .I format
 125 supported is
 126 .B bind8
 127 which indicates new-style BIND 8.  If no zones follow, then each
 128 file will still be overwritten, by an effectively empty file.
 129 Default: if there is no
 130 .B output
 131 directive in the configuration then the default is to use
 132 .BR bind8 " " chiark-conf-gen.bind8 ;
 133 otherwise it is an error for there to be any zones in the
 134 configuration before the first
 135 .B output
 136 directive.
 137 .SS ZONE DIRECTIVES
 138 These directives specify one or more zones.
 139 .TP
 140 \fBprimary\fP \fIzone\fP \fIfilename\fP
 141 Specifies that this server is supposed to be the primary nameserver
 142 for
 143 .I zone
 144 and that the zone data is to be found in
 145 .IR filename .
 146 .TP
 147 \fBprimary-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
 148 Search
 149 .I directory
 150 for files whose names match the glob pattern
 151 .IR suffix * prefix .
 152 Each such file is taken to represent a zone file for which this server
 153 is supposed to be the primary.  * is the name of the zone.  The
 154 default for
 155 .I suffix
 156 is
 157 .BR _db ;
 158 the default for
 159 .I prefix
 160 is empty.
 161 .TP
 162 \fBsecondary\fP \fIzone\fP \fIorigin\-addr\fP
 163 Specifies that this server is supposed to be a published secondary for
 164 the zone in question.
 165 .TP
 166 \fBstealth\fP \fIzone\fP \fIserver\-addr ...\fP
 167 Specifies that this server is supposed to be an unpublished secondary
 168 (aka stealth secondary) for the zone in question.
 169 .SS OTHER DIRECTIVES
 170 .TP
 171 \fBinclude\fP \fIfile\fP
 172 Reads
 173 .I file
 174 as if it were included here.
 175 .TP
 176 \fBend\fP
 177 Ends processing of this file; any data beyond this point is ignored.
 178 .SH CHECKS
 179 chiark\-named\-conf makes the following checks:
 180
 181 Delegations: Each delegation from a server for the superzone should
 182 contain the same set of nameservers.  None of the delegations should
 183 lack glue.  The glue addresses should be the same in each delegation,
 184 and agree with the local default nameserver.
 185
 186 Delegated servers: Each server mentioned in the delegation should have
 187 the same SOA record (and obviously, should be authoritative).
 188
 189 Origin server's data: The set of nameservers in the origin server's
 190 version of the zone should be a superset of those in the delegations.
 191 (The addresses of any additional servers will be acquired from the
 192 local default nameserver at this point.)
 193
 194 All published nameservers - including delegated servers and servers
 195 named in the zone's nameserver set: All nameservers for the zone
 196 should supply the same list of nameservers for the zone as the origin
 197 server does, and none of this authority information should be
 198 glueless.  All the glue should always give the same addresses.
 199
 200 Our zone configuration: For
 201 .B primary
 202 zones, the SOA origin should be one of the names specified with
 203 .BR self\-soa " (or " self ).  For
 204 .B secondary
 205 zones, the address should be that of the SOA origin.  For
 206 .B stealth
 207 zones, the address should be that of the SOA origin or one of the
 208 published nameservers.
 209 .SH FILES
 210 .TP
 211 .B /etc/bind/chiark-conf-gen.zones
 212 Default input configuration file.  (Override with
 213 .BR -C .)
 214 .TP
 215 .B /etc/bind
 216 Default directory.  (Override with
 217 .BR -C " or " default\-dir .)
 218 .TP
 219 .IB dir /chiark-conf-gen.bind8
 220 Default output file.
 221 .TP
 222 .B /var/cache/bind/chiark-slave
 223 Default location for slave zones.
 224 .SH AUTHOR
 225 .B chiark\-named\-conf
 226 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.