2 Domain Name Server Configuration Utilities -- NSC 3.0
4 (c) 1997--2003 Martin Mares <mj@ucw.cz>
6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8 NSC is a set of shell and M4 scripts for easy maintenance of DNS zone files
9 and name server daemon configuration (currently available only for BIND 8.X,
10 but easily portable for other daemons). It has been designed to make administration
11 of a DNS server a piece of cake (unlike other utilities which resemble more
12 an English pudding :-) ), which includes automatic generation of reverse records
13 for all your hosts, handling of classless reverse delegations and support for IPv6
14 (AAAA and PTR in in6.arpa, not A6 and DNAME which seem to be dying out).
16 NSC requires GNU m4 and a POSIX-compatible shell, some of the extra utilities
17 require Perl 5. I've tested everything on Linux (Debian Woody), but the whole
18 package should run on other unices as well.
20 The whole package can be used and distributed according to the terms of the
21 GNU General Public License. See file COPYING in any of the GNU utility archives
22 (you should have one as you are expected to have at least GNU M4 ;-)).
25 1. Quick Howto for the Impatient
26 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
27 (everything will be explained in more detail in the subsequent sections)
29 - Create a directory where all NSC files will reside (e.g., /etc/named)
30 and copy everything from the NSC distribution here.
32 - Symlink /etc/bind/named.conf (or /etc/named.conf or where the config file
33 of your installation of BIND resides) to /etc/named/named.conf
35 - Change directory to /etc/named
37 - Edit cf/domains to suit your needs -- replace the example domains
40 - Create cf/<domain-name> for all domains (again, you can easily follow
43 - Run bin/nsconfig (Makefile and named.conf will be generated).
47 - Enjoy your new DNS setup. If everything goes OK, be happy. Else
48 write a bug report :-)
50 - Every time you modify the domain files
52 An interesting companion to this package is the DNS Sleuth -- a DNS zone
53 consistency checker. It's a simple utility written in Perl with help of the
54 DNS module and it should be able to detect all common errors in DNS setup
55 (I have written it after much disappointment with the other checkers).
56 The Sleuth is available online on http://atrey.karlin.mff.cuni.cz/~mj/sleuth/,
57 follow the links to download the source.
60 2. Directory structure
61 ~~~~~~~~~~~~~~~~~~~~~~
62 The NSC directory (/etc/named in the above example) contains the following
63 files and subdirectories:
65 cf/ - user-defined configuration files
66 cf/domains - the domain list (see Section 3)
67 cf/config - global settings (see Section XXX)
68 cf/<domain> - each domain has its own config file
69 bin/ - commands (e.g., nsconfig)
70 m4/ - M4 scripts (used by the commands)
71 zone/ - primary zone files
72 bak/ - backups of zones we serve as a secondary NS for
73 ver/ - version files where NSC remembers version
74 numbers of the primary zones
76 How are different files created:
78 - You create everything in cf/.
79 - Then you run bin/nsconfig.
80 - Makefile and named.conf gets created according to cf/domains.
82 - The Makefile creates primary zone files in zone/ and version files
83 in ver/ and tells BIND to reload its configuration.
84 - BIND downloads contents of secondary zones and puts them to bak/.
87 2. The Domain List File
88 ~~~~~~~~~~~~~~~~~~~~~~~
89 The domain list contains configuration commands describing all domains handled
90 by your server and their parameters. In fact, it's a M4 script, but viewing it as
91 a config file is a good approximation (however, see Section XXX for some caveats).
92 Lines starting with a semicolon are treated as comments and ignored. Text outside
93 declarations is silently ignored.
97 PRIMARY(zone, [extra-files...])
98 Define a zone (domain) we run a primary name server for.
99 The contents of the zone are described in cf/<zone>
100 and possibly in other specified cf files (all files are
101 concatenated to produce a single configuration). See the next
102 section for a look inside these files.
104 SECONDARY(zone, primary)
105 Define a zone we run a secondary name server for.
106 "primary" is an IP address of the primary name server.
108 REVERSE(network, primary-files...)
109 Define a reverse zone for the given network. The network name
110 consists of several numbers separated by dots, just like an IP
111 address does, but the network usually has only 3 components.
112 Each reverse zone has its own config file cf/<network> which
113 can of course specify the contents of the zone.
115 However, there is a more convenient method to generate the PTR
116 records directly from the A records: just specify the REVERSE
117 directive in cf/<network> and then include all the config files
118 for the primary zones containing hosts from this network. The
119 automatic concatenation of multiple primary-files comes very
122 In fact, REVERSE(network, p-f...) is almost an equivalent of
123 PRIMARY(REV(network), p-f...) where REV(network) is a macro
124 translating network numbers to names of the corresponding
125 reverse zones [e.g., REV(1.2.3) equals 3.2.1.in-addr.arpa].
126 The only difference is that although the domain name is translated
127 by REV, the config file is still named according to the network.
128 You can also use the REV macro explicitly, which can be handy
129 for example in SECONDARY declarations.
131 CONFIG(...) - insert user data to named.conf
133 MAKEFILE(...) - insert user data to Makefile
138 The domain files contain descriptions of all DNS records for the given
139 domain, starting with the SOA record. Again, these are M4 scripts and the
140 declarations are macro calls. Lines starting with a semicolon are treated
141 as comments and just copied to the generated zone file. Text outside
142 declarations is copied to the zone file as well, so you can spice up the NSC
143 output with your own records.
148 Generate a SOA record for the domain. This must be the first
149 declaration in the config file. The parameters of the SOA
150 are taken from configuration variables (see below). The
151 serial number is calculated from the version number remembered
152 in the version file, following the usual practice of encoding
153 current date and a sequence number within the current day
154 in the serial number, which is guaranteed to be strictly
155 increasing unless you perform more than 99 updates in a single
156 day (in which case NSC stops and tells you to tweak the serial
159 The SOA record otherwise acts like a subdomain (D) declaration,
160 therefore it can be followed by other records like NS (mandatory)
164 Start declaration of a host. Doesn't generate anything, only
165 remembers the host's name.
168 Specify addresses for the current host. In the normal mode, it
169 creates A records, in the reverse mode, PTR records.
172 A shortcut for H(host) ADDR(addr...) -- in many cases everything
173 you need for a single host.
176 Like ADDR, but supresses PTR records. (This one is useful if you
177 have a single IP address used for zillions of names and you want
178 to avoid having zillions of PTR records for the same address.)
181 A shortcut for H(host) DADDR(addr...)
184 Start declaration of a subdomain. Technically the same as H(domain),
185 but this one should be more intuitive.
188 Specify a glue record for a name server contained within a subdomain
189 it's a primary for. Currently it's an equivalent of DH(ns, addr...).
192 Specify a list of name server names for the current domain
193 (started by either a SOA or D declaration). Generates NS records.
196 Specify a list of mail exchangers for the current host or domain.
197 Each mail exchanger should be preceded by a priority. Generates
201 Specify a HINFO record for the current host. Very rare in the
205 Specify a list of aliases for the current host or domain.
206 Generates a series of CNAME records pointing from the aliases
207 to the current host/domain.
210 Generate a CNAME record -- "src" points to "dest".
213 Generate a PTR record -- "src" points to "dest". It's a common
214 record in reverse zones (and although it's legal in forward
215 zones as well, such use is very rare), however it's more convenient
216 to have your PTR's generated by the REVERSE directive. But if you
217 need anything special, here is the tool.
219 REVBLOCK(subdomain, min, max)
220 Generate a series of CNAME records numbered from `min' to `max'
221 and pointing to the same name in the given subdomain, finally
222 declaring the subdomain as well, so you can continue with its
225 Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields
232 This is a very common construct for classless reverse delegations,
233 see Section XXX for more details.
236 Switch to reverse mode. From this point on, all output is supressed
237 except for ADDR declarations belonging to the specified network which
238 are automatically converted to PTR records.
240 With help of this feature, defining reverse zones can be as easy as:
242 ; Reverse zone for 10.0.0.0/24 a.k.a. 0.0.10.in-addr.arpa.
244 NS(ns1.example.com, ns2.example.com)
246 ; Include all primary zones containing ADDR's from this range,
247 ; which can be accomplished by a multi-file REVERSE declaration
251 4. Configuration variables
252 ~~~~~~~~~~~~~~~~~~~~~~~~~~
253 There is a fair amount of configuration variables (which are in reality normal
254 M4 macros). Each variable has a hard-wired default value which can be overriden
255 in cf/config by re-defining the variable. Also, all other config files can specify
256 their local definitions, but you need to be careful to change the variable before
257 it is used for the first time.
259 To change the setting, use
261 define(`variable', `value')
263 As usually, even this config file is a M4 script. Comments can be started by
264 semicolons, text outside macros is ignored.
266 The following variables are available:
268 NAMED_RESTART_CMD Shell command for restarting the name server daemon
269 (default: ndc restart)
271 ROOT Root directory of the whole package (default: /etc/named)
272 CFDIR Directory with config files (default: cf)
273 ZONEDIR Directory with zone files (default: zone)
274 BAKDIR Directory with backup files (default: bak)
275 VERSDIR Directory with version files (default: var)
276 ROOTCACHE File with the cache of root nameservers
278 REFRESH SOA record parameters
282 NSNAME Origin server (default: hostname of your machine)
283 MAINTNAME Domain maintainer name (default: root@NSNAME)
285 BIND_OPTIONS Extra options to put to the options { ...} section of named.conf
287 For the timing parameters, the following shortcuts are avaiable:
289 HOURS(n) Convert hours to seconds
290 MINUTES(n) Convert minutes to seconds
291 DAYS(n) Convert days to seconds
293 For the BIND_OPTIONS, we offer:
295 FORWARD(ip...) Try to ask the given nameservers first to see if they
296 have the reply cached.
297 SLAVE(ip...) Pass all non-local requests to the given nameservers.
302 The Makefile generated by NSC offers the following targets:
304 all (default) - update all zone files and reload the daemon
305 clean - clean all generated zone files and backups
306 clobber - clean + delete Makefile and named.conf
307 (wise to do after major reconfigurations)
308 distclean - clobber + delete all version files (use only
309 if you really know what you are doing as the
310 serial number information in newly generated
311 files might be inconsistent then).
314 6. Classless reverse delegations
315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
323 in style of RFC 2317. The RFC recommends syntax `net/prefix-len'
324 for the subdomains (which is especially nasty for all systems
325 storing domains in files with the same name :) ; NSC avoids this
326 by automagically translating all slashes in domain names to @'s
327 when creating file names)
330 8. Interaction with M4
331 ~~~~~~~~~~~~~~~~~~~~~~
337 chkdom Checks domains for correctness using the 'host' utility
338 (check ftp://ftp.nikhef.nl/pub/network for latest version).
339 Use chkdom <domain> <NS> to check specific domain or no
340 parameters to check all domains mentioned in cf/domains.
341 It's even better to use the Sleuth script mentioned in
344 convert A simple perl script for conversion of zone files to NSC
345 domain files. Requires the DNS module (available from CPAN at
348 chkdel A simple perl script for checking of domain delegations --
349 it checks all PRIMARY and SECONDARY records in cf/domains
350 against NS records. Requires the DNS Perl module and also
351 some tweaking of parameters at the top of the script.