2 Domain Name Server Configuration Utilities -- NSC 4.0
4 (c) 1997--2011 Martin Mares <mj@ucw.cz>
6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9 ------------------------------------------------------------------------------------
10 WARNING: There were several incompatible changes between versions 3.1 and 4.0.
11 See NEWS for the summary of changes.
12 ------------------------------------------------------------------------------------
15 NSC is a set of shell and M4 scripts for easy maintenance of DNS zone files
16 and name server daemon configuration (currently available only for BIND 8.x/9.x,
17 but easily portable for other daemons). It has been designed to make administration
18 of a DNS server a piece of cake (unlike other utilities which resemble more
19 an English pudding :-) ), which includes automatic generation of reverse records
20 for all your hosts, handling of classless reverse delegations and support for IPv6
21 (AAAA and PTR in ip6.arpa, not A6 and DNAME which seem to be dying out).
23 NSC requires GNU m4, a POSIX-compatible shell and the `md5sum' utility (which
24 is present for examile in GNU coreutils). Some of the extra utilities require
25 Perl 5. I've tested everything on Linux (Debian Squeeze), but the whole package
26 should run on other unices as well.
28 The whole package can be used and distributed according to the terms of the
29 GNU General Public License. See file COPYING in any of the GNU utility archives
30 (you should have one as you are expected to have at least GNU M4 ;-)).
33 0. Quick Howto for the Impatient
34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35 (everything will be explained in more detail in the subsequent sections)
37 - Create a directory where all NSC files will reside (e.g., /etc/named)
38 and copy everything from the NSC distribution here.
40 - Add an include directive to your BIND configuration file (usually
41 /etc/bind/named.conf), referring to /etc/named/named.conf.
43 - Change directory to /etc/named
45 - Edit cf/domains to suit your needs -- replace the example domains
48 - Create cf/<domain-name> for all domains (again, you can easily follow
51 - If you are using BIND 9.x, make the `bak' directory writable
54 - Run bin/nsconfig (Makefile and named.conf will be generated).
58 - Enjoy your new DNS setup. If everything goes OK, be happy. Else
59 write a bug report :-)
61 - Every time you modify the domain files, re-run make. If you have
62 added or removed domains or changed options which affect named.conf,
63 re-run bin/nsconfig before make.
65 An interesting companion to this package is the DNS Sleuth -- a DNS zone
66 consistency checker. It's a simple utility written in Perl with help of the
67 DNS module and it should be able to detect all common errors in DNS setup
68 (I have written it after much disappointment with the other checkers).
69 The Sleuth is available online on http://atrey.karlin.mff.cuni.cz/~mj/sleuth/,
70 follow the links to download the source.
73 1. Directory structure
74 ~~~~~~~~~~~~~~~~~~~~~~
75 The NSC directory (/etc/named in the above example) contains the following
76 files and subdirectories:
78 cf/ - user-defined configuration files
79 cf/domains - the domain list (see Section 2)
80 cf/config - global settings (see Section 3)
81 cf/<domain> - each domain has its own config file
82 bin/ - commands (e.g., nsconfig)
83 m4/ - M4 scripts (used by the commands)
84 zone/ - primary zone files
85 bak/ - backups of zones we serve as a secondary NS for
86 hash/ - hashes of zone files used for detection of changes
87 ver/ - version files where NSC remembers version
88 numbers of the primary zones
90 How are different files created:
92 - You create everything in cf/.
93 - Then you run bin/nsconfig.
94 - Makefile and named.conf gets created according to cf/domains.
96 - The Makefile creates primary zone files in zone/ and version files
97 in ver/ and tells BIND to reload its configuration.
98 - BIND downloads contents of secondary zones and puts them to bak/.
101 2. The Domain List File
102 ~~~~~~~~~~~~~~~~~~~~~~~
103 The domain list contains configuration commands describing all domains handled
104 by your server and their parameters. In fact, it's a M4 script, but viewing it as
105 a config file is a good approximation (however, see Section 8 for some caveats).
106 Lines starting with a semicolon are treated as comments and ignored. Text outside
107 declarations is silently ignored.
111 PRIMARY(zone, [extra-files...])
112 Define a zone (domain) we run a primary name server for.
113 The contents of the zone are described in cf/<zone>
114 and possibly in other specified cf files (all files are
115 concatenated to produce a single configuration). See the next
116 section for a look inside these files.
118 When the zone name contains a slash (as happens in classless
119 reverse zones), it is replaced by "@" in the cf file name.
121 SECONDARY(zone, primary)
122 Define a zone we run a secondary name server for.
123 "primary" is an IP address of the primary name server.
125 REVERSE(network, primary-files...)
126 Define a reverse zone for the given network. The network name
127 consists of several numbers separated by dots, just like an IP
128 address does, but the network usually has only 3 components.
129 Each reverse zone has its own config file cf/<network> which
130 can of course specify the contents of the zone.
132 However, there is a more convenient method to generate the PTR
133 records directly from the A records: just specify the REVERSE
134 directive in cf/<network> and then include all the config files
135 for the primary zones containing hosts from this network. The
136 automatic concatenation of multiple primary-files comes very
139 In fact, REVERSE(network, p-f...) is almost an equivalent of
140 PRIMARY(REV(network), p-f...) where REV(network) is a macro
141 translating network numbers to names of the corresponding
142 reverse zones [e.g., REV(1.2.3) equals 3.2.1.in-addr.arpa].
143 The only difference is that although the domain name is translated
144 by REV, the config file is still named according to the network.
145 You can also use the REV macro explicitly, which can be handy
146 for example in SECONDARY declarations.
149 Insert a definition of hints for reaching root servers into named.conf.
150 This is necessary if you want your DNS server to resolve foreign
151 domains; otherwise, it will only give out authoritative answers
152 for locally defined zones and forward queries. The location of the
153 file with the hints can be set by the ROOTCACHE directive (see below).
155 FORWARDED(zone, ip...)
156 Define a forwarding zone. All queries are forwarded to the
157 specified name servers.
160 Define an empty zone according to RFC 6303. This is usually done
161 for zones for which clients are known to erroneously ask queries
162 (e.g., reverse resolving of link-local addresses). The contents
163 served for these zones is taken from cf/blackhole.
165 ZONE_OPTIONS(`options;
168 Define options to be inserted to all subsequent zone declarations
169 until the next ZONE_OPTIONS command. Please keep in mind that the
170 semicolon character act as M4 comment, so you need to put the
171 closing quote at a separate line. See our example cf/domains.
174 Insert user data to named.conf, again beware of semicolons.
177 Insert user data to Makefile.
182 The domain files contain descriptions of all DNS records for the given
183 domain, starting with the SOA record. Again, these are M4 scripts and the
184 declarations are macro calls. Lines starting with a semicolon are treated
185 as comments and just copied to the generated zone file. Text outside
186 declarations is copied to the zone file as well, so you can spice up the NSC
187 output with your own records.
189 All host or domain names are either names relative to the current domain
190 with no dots inside or absolute names (in this case, NSC automatically
191 ensures that the trailing dot is present in the resource records). Relative
192 names with dots are not supported, but they are rare and you can always write
193 them as absolute anyway.
198 Generate a SOA record for the domain. This must be the first
199 declaration in the config file. The parameters of the SOA
200 are taken from configuration variables (see below). The
201 serial number is calculated from the version number remembered
202 in the version file, following the usual practice of encoding
203 current date and a sequence number within the current day
204 in the serial number, which is guaranteed to be strictly
205 increasing unless you perform more than 99 updates in a single
206 day (in which case NSC stops and tells you to tweak the serial
209 The SOA record otherwise acts like a sub-domain (D) declaration,
210 therefore it can be followed by other records like NS (mandatory)
214 Start declaration of a host. Doesn't generate anything, only
215 remembers the host's name.
218 Specify addresses for the current host. In the normal mode, it
219 creates A records, in the reverse mode, PTR records.
222 A shortcut for H(host) ADDR(addr...) -- in many cases everything
223 you need for a single host.
226 Like ADDR, but suppresses PTR records. (This one is useful if you
227 have a single IP address used for zillions of names and you want
228 to avoid having zillions of PTR records for the same address.)
231 A shortcut for H(host) DADDR(addr...)
234 Start declaration of a sub-domain. Technically the same as H(domain),
235 but this one should be more intuitive.
238 Specify a glue record for a name server contained within a sub-domain
239 it's a primary for. Currently it's an equivalent of DH(ns, addr...).
242 Specify a list of name server names for the current domain
243 (started by either a SOA or D declaration). Generates NS records.
246 Specify a list of mail exchangers for the current host or domain.
247 Each mail exchanger should be preceded by a priority. Generates
251 Specify a HINFO record for the current host. Very rare in the
255 Specify a list of aliases for the current host or domain.
256 Generates a series of CNAME records pointing from the aliases
257 to the current host/domain.
260 Specify a TXT record for the current host or domain.
263 Specify a RP (responsible person) record for the current host or domain.
264 The first argument is a mail address in DNS notation (with `@' replaced
265 by `.' as in the SOA record), the second one is a name of a TXT record
266 with contact information.
268 SRV(service, protocol, priority, weight, port, target)
269 Specify a SRV (service) record for the current host or domain.
272 Generate a CNAME record -- "src" points to "dest".
275 Generate a PTR record -- "src" points to "dest". It's a common
276 record in reverse zones (and although it's legal in forward
277 zones as well, such use is very rare), however it's more convenient
278 to have your PTR's generated by the REVERSE directive. But if you
279 need anything special, here is the tool.
281 REVBLOCK(subdomain, min, max)
282 Generate a series of CNAME records numbered from `min' to `max'
283 and pointing to the same name in the given sub-domain, finally
284 declaring the sub-domain as well, so you can continue with its
287 Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields
294 This is a very common construct for classless reverse delegations,
295 see Section 6 for more details.
298 Switch to reverse mode. From this point on, all output is suppressed
299 except for ADDR declarations belonging to the specified network which
300 are automatically converted to PTR records.
302 With help of this feature, defining reverse zones can be as easy as:
304 ; Reverse zone for 10.0.0.0/24 a.k.a. 0.0.10.in-addr.arpa.
306 NS(ns1.example.com, ns2.example.com)
308 ; Include all primary zones containing ADDR's from this range,
309 ; which can be accomplished by a multi-file REVERSE declaration
313 4. Configuration variables
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~
315 There is a fair amount of configuration variables (which are in reality normal
316 M4 macros). Each variable has a hard-wired default value which can be overridden
317 in cf/config by re-defining the variable. Also, all other config files can specify
318 their local definitions, but you need to be careful to change the variable before
319 it is used for the first time.
321 To change the setting, use
323 define(`variable', `value')
325 As usually, even this config file is a M4 script. Comments can be started by
326 semicolons, text outside macros is ignored.
328 The following variables are available:
330 NAMED_RESTART_CMD Shell command for restarting the name server daemon
331 (default: rndc reload)
333 ROOT Root directory of the whole package (default: /etc/named)
334 CFDIR Directory with config files (default: cf)
335 ZONEDIR Directory with zone files (default: zone)
336 BAKDIR Directory with backup files (default: bak)
337 HASHDIR Directory with zone hashes (default: hash)
338 VERSDIR Directory with version files (default: var)
339 ROOTCACHE File with the cache of root name servers
341 REFRESH SOA record parameters
345 NSNAME Origin server (default: hostname of your machine)
346 MAINTNAME Domain maintainer name (default: root@NSNAME)
348 For the timing parameters, the following shortcuts are available:
350 HOURS(n) Convert hours to seconds
351 MINUTES(n) Convert minutes to seconds
352 DAYS(n) Convert days to seconds
357 The Makefile generated by NSC offers the following targets:
359 all (default) - update all zone files and reload the daemon
360 clean - clean all generated zone files, backups, and hashes
361 clobber - clean + delete Makefile and named.conf
362 (wise to do after major reconfigurations)
363 distclean - clobber + delete all version files (use only
364 if you really know what you are doing as the
365 serial number information in newly generated
366 files might be inconsistent then).
369 6. Classless reverse delegations
370 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371 NSC also supports classless delegations for reverse zones using the mechanism
372 described in RFC 2317, i.e. by putting CNAME records to the reverse zone which
373 point to records of the same name in a sub-domain which you can delegate directly.
375 For example if you want to delegate 64-127 in 0.0.10.in-addr.arpa to ns.example.net,
376 you create a 64/26 sub-domain (26 is the network prefix length) and add the following
377 records to 0.0.10.in-addr.arpa:
379 64 CNAME 64.64/26.0.0.10.in-addr.arpa.
380 65 CNAME 65.64/26.0.0.10.in-addr.arpa.
382 127 CNAME 127.64/26.0.0.10.in-addr.arpa.
384 64/26 NS ns.example.net.
386 Then you configure ns.example.net to be a primary name server for the zone
387 64/26.0.0.10.in-addr.arpa and put the PTR records there:
389 64 PTR sixty-four.example.net.
390 65 PTR sixty-five.example.net.
392 127 PTR two-to-seven-minus-one.example.net.
394 NSC offers special primitives for configuring such delegations, but not limited
395 to the sub-domain name syntax shown above (which is recommended by the RFC, but it's
396 far from being the only one used in the real world, other possibilities being for
397 example 64-127, 64+64 etc.).
399 The CNAME block can be generated by the REVBLOCK(subdomain-name, low-addr, high-addr)
400 directive in the configuration of the whole reverse zone. The example above would
403 REVBLOCK(64/26, 64, 127)
405 The sub-zone can be created automatically like any another reverse zone, you only
406 need to use the three-parameter form of the REVERSE directive to specify the
407 address range in order to filter out possible hosts falling outside your range.
409 CAVEAT: The slashes in zone names are automatically translated to @'s when forming
412 Again for the example above, you need to put the following to cf/domains:
414 REVERSE(10.0.0.64/26, <list-of-domains-to-gather-the-addresses-from>)
416 And to cf/64@26.0.0.10:
418 SOA(REV(10.0.0.64/26))
419 NS(<list-of-name-servers>)
420 REVERSE(10.0.0, 64, 127)
422 NOTE: It's usually helpful to configure the primary name server for the parent
423 domain (i.e., the one where you configure the delegation and create the CNAME's)
424 as a secondary for the sub-zone as well, so if it replies with the CNAME, it will
425 include the PTR record pointed to by the CNAME in the additional section of its
426 reply, eliminating the need for an extra query.
431 NSC also supports IPv6 in a pretty straightforward form: wherever you can write
432 an IPv4 address, you can use an IPv6 address as well. Incomplete IP addresses
433 or ranges used for specifying address blocks for reverse delegations are replaced
434 by network prefixes of the standard form <address>/<prefix-length>.
438 H(ianus, 1.2.3.4, fec0::1234:5678:9abc:def0)
440 specifies a dual-stack host with both an A record and an AAAA record.
442 CAVEAT: The backward-compatible IPv6 address syntax with ":v.w.x.y" at the end
443 is not supported. All other syntaxes and quirks hopefully are.
446 8. Interaction with M4
447 ~~~~~~~~~~~~~~~~~~~~~~
448 All config files are fully-fledged M4 scripts, so you can use any M4 features
449 you need, the most helpful one being definition of your own macros by
451 define(`macro_name', `expansion')
453 However, there is a couple of things you need to care about:
455 o The comment character is redefined to `;'. I.e., wherever a semicolon
456 occurs, the rest of the line is a comment which is copied verbatim
457 to the output file (if the output is not suppressed like in case
458 of the cf/domains file).
460 o Names starting with 'nsc_' or spelled in all caps are reserved
461 for the NSC itself and unless documented, messing with them can
462 bring surprising results. If you need to use such a name in your
463 zone file (maybe you like to shout in your host names :-) ),
464 quote it like `this'.
466 o Don't use commas, quotes nor parentheses in your record names.
471 convert A simple Perl script for conversion of zone files to NSC
472 domain files. Requires the Net::DNS module (available from
473 CPAN at ftp.cpan.org; present in recent versions of Perl).
474 Keep in mind that the script is very simple and its craft
475 is of a very limited kind, so check its output carefully.
477 chkdel A simple Perl script for checking of domain delegations --
478 it checks all PRIMARY and SECONDARY records in cf/domains
479 against NS records. Requires the Net::DNS module and also
480 some tweaking of parameters at the top of the script.