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, and to generate a
  16 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 \-D
  63 Enables debugging.  Useful for debugging chiark\-named\-conf, but
  64 probably not useful for debugging your DNS configuration.
  65 .SH CONFIGURATION
  66 The file
  67 .B /etc/bind/chiark-conf-gen.zones
  68 (or other file specified with the
  69 .B \-C
  70 option) contains a sequence of directives, one per line.  Blank lines
  71 are permitted.  Leading and trailing whitespace on each line is
  72 ignored.  Comments are lines starting with
  73 .BR # .
  74 .SS GENERAL DIRECTIVES
  75 These directives specify general configuration details.  They should
  76 appear before directives specifying zones, as each will affect only
  77 later zone directives.
  78 .TP
  79 \fBself\-ns\fP \fIfqdn ...\fP
  80 Specifies the list of names that this server may be known by in NS
  81 records.  There is no default.
  82 .TP
  83 \fBself\-soa\fP \fIfqdn ...\fP
  84 Specifies the list of names that this server may be known by in
  85 the ORIGIN field of SOA records.  There is no default.
  86 .TP
  87 \fBself\fP \fIfqdn ...\fP
  88 Equivalent to both
  89 .BR self\-ns " and " self-\soa
  90 with the same set of names.
  91 .TP
  92 \fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
  93 Specifies the directory in which slave (secondary and stealth)
  94 zonefiles should be placed.  The default
  95 .I directory
  96 is
  97 .BR /var/cache/bind/chiark-slave .
  98 The default
  99 .IR suffix " and " prefix
 100 are empty; they also will be reset to these defaults by a
 101 .B slave\-dir
 102 directive which does not specify them.
 103 .TP
 104 \fBdefault\-dir\fP \fIdirectory\fP
 105 Makes
 106 .I directory
 107 be the default directory (which affects the interpretation of
 108 relative filenames).  The default is the directory containing
 109 the main configuration file, ie
 110 .BR /etc/bind
 111 if no
 112 .B -C
 113 option is specified.
 114 .TP
 115 \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP]
 116 Arranges that each
 117 .I filename
 118 will be overwritten when
 119 .BR -y " or " -f
 120 are used; its new contents will be configuration
 121 directives for the zones which follow for the
 122 nameserver in question.  Currently the only
 123 .I format
 124 supported is
 125 .B bind8
 126 which indicates new-style BIND 8.  If no zones follow, then each
 127 file will still be overwritten, by an effectively empty file.
 128 Default: if there is no
 129 .B output
 130 directive in the configuration then the default is to use
 131 .BR bind8 " " chiark-conf-gen.bind8 ;
 132 otherwise it is an error for there to be any zones in the
 133 configuration before the first
 134 .B output
 135 directive.
 136 .SS ZONE DIRECTIVES
 137 These directives specify one or more zones.
 138 .TP
 139 \fBprimary\fP \fIzone\fP \fIfilename\fP
 140 Specifies that this server is supposed to be the primary nameserver
 141 for
 142 .I zone
 143 and that the zone data is to be found in
 144 .IR filename .
 145 .TP
 146 \fBprimary-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]
 147 Search
 148 .I directory
 149 for files whose names match the glob pattern
 150 .IR suffix * prefix .
 151 Each such file is taken to represent a zone file for which this server
 152 is supposed to be the primary.  * is the name of the zone.  The
 153 default for
 154 .I suffix
 155 is
 156 .BR _db ;
 157 the default for
 158 .I prefix
 159 is empty.
 160 .TP
 161 \fBsecondary\fP \fIzone\fP \fIorigin\-addr\fP
 162 Specifies that this server is supposed to be a published secondary for
 163 the zone in question.
 164 .TP
 165 \fBstealth\fP \fIzone\fP \fIserver\-addr ...\fP
 166 Specifies that this server is supposed to be an unpublished secondary
 167 (aka stealth secondary) for the zone in question.
 168 .SS OTHER DIRECTIVES
 169 .TP
 170 \fBinclude\fP \fIfile\fP
 171 Reads
 172 .I file
 173 as if it were included here.
 174 .TP
 175 \fBend\fP
 176 Ends processing of this file; any data beyond this point is ignored.
 177 .SH CHECKS
 178 chiark\-named\-conf makes the following checks:
 179
 180 Delegations: Each delegation from a server for the superzone should
 181 contain the same set of nameservers.  None of the delegations should
 182 lack glue.  The glue addresses should be the same in each delegation,
 183 and agree with the local default nameserver.
 184
 185 Delegated servers: Each server mentioned in the delegation should have
 186 the same SOA record (and obviously, should be authoritative).
 187
 188 All published nameservers - including delegated servers and servers
 189 named in the zone's nameserver set: All nameservers for the zone
 190 should supply the same list of nameservers for the zone, and none of
 191 this authority information should be glueless.  All the glue should
 192 always give the same addresses.
 193
 194 Origin server's data: The set of nameservers in the origin server's
 195 version of the zone should be a superset of those in the delegations.
 196
 197 Our zone configuration: For
 198 .B primary
 199 zones, the SOA origin should be one of the names specified with
 200 .BR self\-soa " (or " self ).  For
 201 .B secondary
 202 zones, the address should be that of the SOA origin.  For
 203 .B stealth
 204 zones, the address should be that of the SOA origin or one of the
 205 published nameservers.
 206 .SH FILES
 207 .TP
 208 .B /etc/bind/chiark-conf-gen.zones
 209 Default input configuration file.  (Override with
 210 .BR -C .)
 211 .TP
 212 .B /etc/bind
 213 Default directory.  (Override with
 214 .BR -C " or " default\-dir .)
 215 .TP
 216 .IB dir /chiark-conf-gen.bind8
 217 Default output file.
 218 .TP
 219 .B /var/cache/bind/chiark-slave
 220 Default location for slave zones.
 221 .SH AUTHOR
 222 .B chiark\-named\-conf
 223 and this manpage were written by Ian Jackson <ian@chiark.greenend.org.uk>.