2 Domain Name Server Configuration Utilities -- NSC 3.1
4 (c) 1997--2008 Martin Mares <mj@ucw.cz>
6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9 ------------------------------------------------------------------------------------
10 WARNING: NSC has undergone significant changes between versions 2.3 and 2.99b.
11 See NEWS for the summary of changes. Most importantly, the configuration files are
12 NOT compatible with the old releases.
13 ------------------------------------------------------------------------------------
16 NSC is a set of shell and M4 scripts for easy maintenance of DNS zone files
17 and name server daemon configuration (currently available only for BIND 8.X,
18 but easily portable for other daemons). It has been designed to make administration
19 of a DNS server a piece of cake (unlike other utilities which resemble more
20 an English pudding :-) ), which includes automatic generation of reverse records
21 for all your hosts, handling of classless reverse delegations and support for IPv6
22 (AAAA and PTR in in6.arpa, not A6 and DNAME which seem to be dying out).
24 NSC requires GNU m4 and a POSIX-compatible shell, some of the extra utilities
25 require Perl 5. I've tested everything on Linux (Debian Woody), but the whole
26 package 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 - Symlink /etc/bind/named.conf (or /etc/named.conf or where the config file
41 of your installation of BIND resides) 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 - Run bin/nsconfig (Makefile and named.conf will be generated).
55 - Enjoy your new DNS setup. If everything goes OK, be happy. Else
56 write a bug report :-)
58 - Every time you modify the domain files
60 An interesting companion to this package is the DNS Sleuth -- a DNS zone
61 consistency checker. It's a simple utility written in Perl with help of the
62 DNS module and it should be able to detect all common errors in DNS setup
63 (I have written it after much disappointment with the other checkers).
64 The Sleuth is available online on http://atrey.karlin.mff.cuni.cz/~mj/sleuth/,
65 follow the links to download the source.
68 1. Directory structure
69 ~~~~~~~~~~~~~~~~~~~~~~
70 The NSC directory (/etc/named in the above example) contains the following
71 files and subdirectories:
73 cf/ - user-defined configuration files
74 cf/domains - the domain list (see Section 2)
75 cf/config - global settings (see Section 3)
76 cf/<domain> - each domain has its own config file
77 bin/ - commands (e.g., nsconfig)
78 m4/ - M4 scripts (used by the commands)
79 zone/ - primary zone files
80 bak/ - backups of zones we serve as a secondary NS for
81 ver/ - version files where NSC remembers version
82 numbers of the primary zones
84 How are different files created:
86 - You create everything in cf/.
87 - Then you run bin/nsconfig.
88 - Makefile and named.conf gets created according to cf/domains.
90 - The Makefile creates primary zone files in zone/ and version files
91 in ver/ and tells BIND to reload its configuration.
92 - BIND downloads contents of secondary zones and puts them to bak/.
95 2. The Domain List File
96 ~~~~~~~~~~~~~~~~~~~~~~~
97 The domain list contains configuration commands describing all domains handled
98 by your server and their parameters. In fact, it's a M4 script, but viewing it as
99 a config file is a good approximation (however, see Section 8 for some caveats).
100 Lines starting with a semicolon are treated as comments and ignored. Text outside
101 declarations is silently ignored.
105 PRIMARY(zone, [extra-files...])
106 Define a zone (domain) we run a primary name server for.
107 The contents of the zone are described in cf/<zone>
108 and possibly in other specified cf files (all files are
109 concatenated to produce a single configuration). See the next
110 section for a look inside these files.
112 SECONDARY(zone, primary)
113 Define a zone we run a secondary name server for.
114 "primary" is an IP address of the primary name server.
116 REVERSE(network, primary-files...)
117 Define a reverse zone for the given network. The network name
118 consists of several numbers separated by dots, just like an IP
119 address does, but the network usually has only 3 components.
120 Each reverse zone has its own config file cf/<network> which
121 can of course specify the contents of the zone.
123 However, there is a more convenient method to generate the PTR
124 records directly from the A records: just specify the REVERSE
125 directive in cf/<network> and then include all the config files
126 for the primary zones containing hosts from this network. The
127 automatic concatenation of multiple primary-files comes very
130 In fact, REVERSE(network, p-f...) is almost an equivalent of
131 PRIMARY(REV(network), p-f...) where REV(network) is a macro
132 translating network numbers to names of the corresponding
133 reverse zones [e.g., REV(1.2.3) equals 3.2.1.in-addr.arpa].
134 The only difference is that although the domain name is translated
135 by REV, the config file is still named according to the network.
136 You can also use the REV macro explicitly, which can be handy
137 for example in SECONDARY declarations.
139 FORWARDED(zone, ip...)
140 Define a forwarding zone. All queries are forwarded to the
141 specified name servers.
143 ZONE_OPTIONS(`options;
146 Define options to be inserted to all subsequent zone declarations
147 until the next ZONE_OPTIONS command. Please keep in mind that the
148 semicolon character act as M4 comment, so you need to put the
149 closing quote at a separate line. See our example cf/domains.
152 Insert user data to named.conf, again beware of semicolons.
155 Insert user data to Makefile.
160 The domain files contain descriptions of all DNS records for the given
161 domain, starting with the SOA record. Again, these are M4 scripts and the
162 declarations are macro calls. Lines starting with a semicolon are treated
163 as comments and just copied to the generated zone file. Text outside
164 declarations is copied to the zone file as well, so you can spice up the NSC
165 output with your own records.
167 All host or domain names are either names relative to the current domain
168 with no dots inside or absolute names (in this case, NSC automatically
169 ensures that the trailing dot is present in the resource records). Relative
170 names with dots are not supported, but they are rare and you can always write
171 them as absolute anyway.
176 Generate a SOA record for the domain. This must be the first
177 declaration in the config file. The parameters of the SOA
178 are taken from configuration variables (see below). The
179 serial number is calculated from the version number remembered
180 in the version file, following the usual practice of encoding
181 current date and a sequence number within the current day
182 in the serial number, which is guaranteed to be strictly
183 increasing unless you perform more than 99 updates in a single
184 day (in which case NSC stops and tells you to tweak the serial
187 The SOA record otherwise acts like a sub-domain (D) declaration,
188 therefore it can be followed by other records like NS (mandatory)
192 Start declaration of a host. Doesn't generate anything, only
193 remembers the host's name.
196 Specify addresses for the current host. In the normal mode, it
197 creates A records, in the reverse mode, PTR records.
200 A shortcut for H(host) ADDR(addr...) -- in many cases everything
201 you need for a single host.
204 Like ADDR, but suppresses PTR records. (This one is useful if you
205 have a single IP address used for zillions of names and you want
206 to avoid having zillions of PTR records for the same address.)
209 A shortcut for H(host) DADDR(addr...)
212 Start declaration of a sub-domain. Technically the same as H(domain),
213 but this one should be more intuitive.
216 Specify a glue record for a name server contained within a sub-domain
217 it's a primary for. Currently it's an equivalent of DH(ns, addr...).
220 Specify a list of name server names for the current domain
221 (started by either a SOA or D declaration). Generates NS records.
224 Specify a list of mail exchangers for the current host or domain.
225 Each mail exchanger should be preceded by a priority. Generates
229 Specify a HINFO record for the current host. Very rare in the
233 Specify a list of aliases for the current host or domain.
234 Generates a series of CNAME records pointing from the aliases
235 to the current host/domain.
238 Specify a TXT record for the current host or domain.
241 Specify a RP (responsible person) record for the current host or domain.
242 The first argument is a mail address in DNS notation (with `@' replaced
243 by `.' as in the SOA record), the second one is a name of a TXT record
244 with contact information.
246 SRV(service, protocol, priority, weight, port, target)
247 Specify a SRV (service) record for the current host or domain.
250 Generate a CNAME record -- "src" points to "dest".
253 Generate a PTR record -- "src" points to "dest". It's a common
254 record in reverse zones (and although it's legal in forward
255 zones as well, such use is very rare), however it's more convenient
256 to have your PTR's generated by the REVERSE directive. But if you
257 need anything special, here is the tool.
259 REVBLOCK(subdomain, min, max)
260 Generate a series of CNAME records numbered from `min' to `max'
261 and pointing to the same name in the given sub-domain, finally
262 declaring the sub-domain as well, so you can continue with its
265 Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields
272 This is a very common construct for classless reverse delegations,
273 see Section 6 for more details.
276 Switch to reverse mode. From this point on, all output is suppressed
277 except for ADDR declarations belonging to the specified network which
278 are automatically converted to PTR records.
280 With help of this feature, defining reverse zones can be as easy as:
282 ; Reverse zone for 10.0.0.0/24 a.k.a. 0.0.10.in-addr.arpa.
284 NS(ns1.example.com, ns2.example.com)
286 ; Include all primary zones containing ADDR's from this range,
287 ; which can be accomplished by a multi-file REVERSE declaration
291 4. Configuration variables
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~
293 There is a fair amount of configuration variables (which are in reality normal
294 M4 macros). Each variable has a hard-wired default value which can be overridden
295 in cf/config by re-defining the variable. Also, all other config files can specify
296 their local definitions, but you need to be careful to change the variable before
297 it is used for the first time.
299 To change the setting, use
301 define(`variable', `value')
303 As usually, even this config file is a M4 script. Comments can be started by
304 semicolons, text outside macros is ignored.
306 The following variables are available:
308 NAMED_RESTART_CMD Shell command for restarting the name server daemon
309 (default: ndc restart)
311 ROOT Root directory of the whole package (default: /etc/named)
312 CFDIR Directory with config files (default: cf)
313 ZONEDIR Directory with zone files (default: zone)
314 BAKDIR Directory with backup files (default: bak)
315 VERSDIR Directory with version files (default: var)
316 ROOTCACHE File with the cache of root name servers
318 REFRESH SOA record parameters
322 NSNAME Origin server (default: hostname of your machine)
323 MAINTNAME Domain maintainer name (default: root@NSNAME)
325 BIND_OPTIONS Extra options to put to the options { ... } section of named.conf
327 For the timing parameters, the following shortcuts are available:
329 HOURS(n) Convert hours to seconds
330 MINUTES(n) Convert minutes to seconds
331 DAYS(n) Convert days to seconds
333 For the BIND_OPTIONS, we offer:
335 FORWARD(ip...) Try to ask the given name servers first to see if they
336 have the reply cached.
337 SLAVE(ip...) Pass all non-local requests to the given name servers.
342 The Makefile generated by NSC offers the following targets:
344 all (default) - update all zone files and reload the daemon
345 clean - clean all generated zone files and backups
346 clobber - clean + delete Makefile and named.conf
347 (wise to do after major reconfigurations)
348 distclean - clobber + delete all version files (use only
349 if you really know what you are doing as the
350 serial number information in newly generated
351 files might be inconsistent then).
354 6. Classless reverse delegations
355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
356 NSC also supports classless delegations for reverse zones using the mechanism
357 described in RFC 2317, i.e. by putting CNAME records to the reverse zone which
358 point to records of the same name in a sub-domain which you can delegate directly.
360 For example if you want to delegate 64-127 in 0.0.10.in-addr.arpa to ns.example.net,
361 you create a 64/26 sub-domain (26 is the network prefix length) and add the following
362 records to 0.0.10.in-addr.arpa:
364 64 CNAME 64.64/26.0.0.10.in-addr.arpa.
365 65 CNAME 65.64/26.0.0.10.in-addr.arpa.
367 127 CNAME 127.64/26.0.0.10.in-addr.arpa.
369 64/26 NS ns.example.net.
371 Then you configure ns.example.net to be a primary name server for the zone
372 64/26.0.0.10.in-addr.arpa and put the PTR records there:
374 64 PTR sixty-four.example.net.
375 65 PTR sixty-five.example.net.
377 127 PTR two-to-seven-minus-one.example.net.
379 NSC offers special primitives for configuring such delegations, but not limited
380 to the sub-domain name syntax shown above (which is recommended by the RFC, but it's
381 far from being the only one used in the real world, other possibilities being for
382 example 64-127, 64+64 etc.).
384 The CNAME block can be generated by the REVBLOCK(subdomain-name, low-addr, high-addr)
385 directive in the configuration of the whole reverse zone. The example above would
388 REVBLOCK(64/26, 64, 127)
390 The sub-zone can be created automatically like any another reverse zone, you only
391 need to use the three-parameter form of the REVERSE directive to specify the
392 address range in order to filter out possible hosts falling outside your range.
394 CAVEAT: The slashes in zone names are automatically translated to @'s when forming
397 Again for the example above, you need to put the following to cf/domains:
399 REVERSE(10.0.0.64/26, <list-of-domains-to-gather-the-addresses-from>)
401 And to cf/64@26.0.0.10:
403 SOA(REV(10.0.0.64/26))
404 NS(<list-of-name-servers>)
405 REVERSE(10.0.0, 64, 127)
407 NOTE: It's usually helpful to configure the primary name server for the parent
408 domain (i.e., the one where you configure the delegation and create the CNAME's)
409 as a secondary for the sub-zone as well, so if it replies with the CNAME, it will
410 include the PTR record pointed to by the CNAME in the additional section of its
411 reply, eliminating the need for an extra query.
416 NSC also supports IPv6 in a pretty straightforward form: wherever you can write
417 an IPv4 address, you can use an IPv6 address as well. Incomplete IP addresses
418 or ranges used for specifying address blocks for reverse delegations are replaced
419 by network prefixes of the standard form <address>/<prefix-length>.
423 H(ianus, 1.2.3.4, fec0::1234:5678:9abc:def0)
425 specifies a dual-stack host with both an A record and an AAAA record.
427 CAVEAT: The backward-compatible IPv6 address syntax with ":v.w.x.y" at the end
428 is not supported. All other syntaxes and quirks hopefully are.
431 8. Interaction with M4
432 ~~~~~~~~~~~~~~~~~~~~~~
433 All config files are fully-fledged M4 scripts, so you can use any M4 features
434 you need, the most helpful one being definition of your own macros by
436 define(`macro_name', `expansion')
438 However, there is a couple of things you need to care about:
440 o The comment character is redefined to `;'. I.e., wherever a semicolon
441 occurs, the rest of the line is a comment which is copied verbatim
442 to the output file (if the output is not suppressed like in case
443 of the cf/domains file).
445 o Names starting with 'nsc_' or spelled in all caps are reserved
446 for the NSC itself and unless documented, messing with them can
447 bring surprising results. If you need to use such a name in your
448 zone file (maybe you like to shout in your host names :-) ),
449 quote it with ` and '.
451 o Don't use commas, quotes nor parentheses in your record names.
456 convert A simple Perl script for conversion of zone files to NSC
457 domain files. Requires the Net::DNS module (available from
458 CPAN at ftp.cpan.org; present in recent versions of Perl).
459 Keep in mind that the script is very simple and its craft
460 is of a very limited kind, so check its output carefully.
462 chkdel A simple Perl script for checking of domain delegations --
463 it checks all PRIMARY and SECONDARY records in cf/domains
464 against NS records. Requires the Net::DNS module and also
465 some tweaking of parameters at the top of the script.