2 Domain Name Server Configuration Utilities -- NSC 5.0
4 (c) 1997--2019 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, GNU Bash, the `md5sum' and `sha1sum' utilities (which
24 are present for example in GNU coreutils), and utilities distributed with BIND.
25 Some of the extra utilities require Perl 5. I've tested everything on Linux
26 (Debian Stretch), but the whole 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, version 2 or higher. See file COPYING in any of the
30 GNU utility archives (you should have one as you are expected to have at least
34 0. Quick Howto for the Impatient
35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 (everything will be explained in more detail in the subsequent sections)
38 - Create a directory where all NSC files will reside (e.g., /etc/named)
39 and copy everything from the NSC distribution here.
41 - Add an include directive to your BIND configuration file (usually
42 /etc/bind/named.conf), referring to /etc/named/named.conf.
44 - Change directory to /etc/named
46 - Edit cf/domains to suit your needs -- replace the example domains
49 - Create cf/<domain-name> for all domains (again, you can easily follow
52 - If you are using BIND 9.x, make the `bak' directory writable
55 - Run bin/nsconfig (Makefile and named.conf will be generated).
59 - Enjoy your new DNS setup. If everything goes OK, be happy. Else
60 write a bug report :-)
62 - Every time you modify the domain files, re-run make. If you have
63 added or removed domains or changed options which affect named.conf,
64 re-run bin/nsconfig before make.
66 An interesting companion to this package is the DNS Sleuth -- a DNS zone
67 consistency checker. It's a simple utility written in Perl with help of the
68 DNS module and it should be able to detect all common errors in DNS setup
69 (I have written it after much disappointment with the other checkers).
70 The Sleuth is available online on http://atrey.karlin.mff.cuni.cz/~mj/sleuth/,
71 follow the links to download the source. However, I haven't updated Sleuth
72 for a long time, so it does not know about DNSSEC yet.
75 1. Directory structure
76 ~~~~~~~~~~~~~~~~~~~~~~
77 The NSC directory (/etc/named in the above example) contains the following
78 files and subdirectories:
80 cf/ - user-defined configuration files
81 cf/domains - the domain list (see Section 2)
82 cf/config - global settings (see Section 3)
83 cf/<domain> - each domain has its own config file
84 bin/ - commands (e.g., nsconfig)
85 m4/ - M4 scripts (used by the commands)
86 zone/ - primary zone files
87 bak/ - backups of zones we serve as a secondary NS for
88 ver/ - version files where NSC remembers version
89 numbers of the primary zones
90 tmp/ - temporary files
91 hash/ - hashes of zone files used for detection of changes
92 dss/<domain> - DNSSEC DS records
93 keys/<domain>/ - DNSSEC keys
94 khash/ - hashes of DNSSEC keys used for detection of changes
96 How are different files created:
98 - You create everything in cf/.
99 - Then you run bin/nsconfig.
100 - If you want to use DNSSEC, create keys (see section 8)
101 - Makefile and named.conf gets created according to cf/domains.
103 - The Makefile creates primary zone files in zone/ and version files
104 in ver/ and tells BIND to reload its configuration.
105 - BIND downloads contents of secondary zones and puts them to bak/.
108 2. The Domain List File
109 ~~~~~~~~~~~~~~~~~~~~~~~
110 The domain list contains configuration commands describing all domains handled
111 by your server and their parameters. In fact, it's a M4 script, but viewing it as
112 a config file is a good approximation (however, see Section 8 for some caveats).
113 Lines starting with a semicolon are treated as comments and ignored. Text outside
114 declarations is silently ignored.
118 PRIMARY(zone, [extra-files...])
119 Define a zone (domain) we run a primary name server for.
120 The contents of the zone are described in cf/<zone>
121 and possibly in other specified cf files (all files are
122 concatenated to produce a single configuration). See the next
123 section for a look inside these files.
125 When the zone name contains a slash (as happens in classless
126 reverse zones), it is replaced by "@" in the cf file name.
128 SECONDARY(zone, primary)
129 Define a zone we run a secondary name server for.
130 "primary" is an IP address of the primary name server.
132 REVERSE(network, primary-files...)
133 Define a reverse zone for the given network. The network name
134 consists of several numbers separated by dots, just like an IP
135 address does, but the network usually has only 3 components.
136 Each reverse zone has its own config file cf/<network> which
137 can of course specify the contents of the zone.
139 However, there is a more convenient method to generate the PTR
140 records directly from the A records: just specify the REVERSE
141 directive in cf/<network> and then include all the config files
142 for the primary zones containing hosts from this network. The
143 automatic concatenation of multiple primary-files comes very
146 In fact, REVERSE(network, p-f...) is almost an equivalent of
147 PRIMARY(REV(network), p-f...) where REV(network) is a macro
148 translating network numbers to names of the corresponding
149 reverse zones [e.g., REV(1.2.3) equals 3.2.1.in-addr.arpa].
150 The only difference is that although the domain name is translated
151 by REV, the config file is still named according to the network.
152 You can also use the REV macro explicitly, which can be handy
153 for example in SECONDARY declarations.
156 Insert a definition of hints for reaching root servers into named.conf.
157 This is necessary if you want your DNS server to resolve foreign
158 domains; otherwise, it will only give out authoritative answers
159 for locally defined zones and forward queries. The location of the
160 file with the hints can be set by the ROOTCACHE directive (see below).
162 FORWARDED(zone, ip...)
163 Define a forwarding zone. All queries are forwarded to the
164 specified name servers.
167 Define an empty zone according to RFC 6303. This is usually done
168 for zones for which clients are known to erroneously ask queries
169 (e.g., reverse resolving of link-local addresses). The contents
170 served for these zones is taken from cf/blackhole.
172 ZONE_OPTIONS(`options;
175 Define options to be inserted to all subsequent zone declarations
176 until the next ZONE_OPTIONS command. Please keep in mind that the
177 semicolon character act as M4 comment, so you need to put the
178 closing quote at a separate line. See our example cf/domains.
181 Insert user data to named.conf, again beware of semicolons.
184 Insert user data to Makefile.
186 DNSSEC(`declarations...')
187 Request DNSSEC signing for all zones declared within the block.
190 Declare dependency of the previous PRIMARY/REVERSE domain on DS
191 records for the given zone configured in dss/*.
196 The domain files contain descriptions of all DNS records for the given
197 domain, starting with the SOA record. Again, these are M4 scripts and the
198 declarations are macro calls. Lines starting with a semicolon are treated
199 as comments and just copied to the generated zone file. Text outside
200 declarations is copied to the zone file as well, so you can spice up the NSC
201 output with your own records.
203 All host or domain names are either names relative to the current domain
204 with no dots inside or absolute names (in this case, NSC automatically
205 ensures that the trailing dot is present in the resource records). Relative
206 names with dots are not supported, but they are rare and you can always write
207 them as absolute anyway.
212 Generate a SOA record for the domain. This must be the first
213 declaration in the config file. The parameters of the SOA
214 are taken from configuration variables (see below). The
215 serial number is calculated from the version number remembered
216 in the version file, following the usual practice of encoding
217 current date and a sequence number within the current day
218 in the serial number, which is guaranteed to be strictly
219 increasing unless you perform more than 99 updates in a single
220 day (in which case NSC stops and tells you to tweak the serial
223 The SOA record otherwise acts like a sub-domain (D) declaration,
224 therefore it can be followed by other records like NS (mandatory)
228 Start declaration of a host. Doesn't generate anything, only
229 remembers the host's name.
232 Specify addresses for the current host. In the normal mode, it
233 creates A/AAAA records, in the reverse mode, PTR records.
236 A shortcut for H(host) ADDR(addr...) -- in many cases everything
237 you need for a single host.
240 Like ADDR, but suppresses PTR records. (This one is useful if you
241 have a single IP address used for zillions of names and you want
242 to avoid having zillions of PTR records for the same address.)
245 A shortcut for H(host) DADDR(addr...)
248 Start declaration of a sub-domain. Technically the same as H(domain),
249 but this one should be more intuitive.
252 Specify a glue record for a name server contained within a sub-domain
253 it's a primary for. Currently it's an equivalent of DH(ns, addr...).
256 Specify a list of name server names for the current domain
257 (started by either a SOA or D declaration). Generates NS records.
261 Include DS records for the current sub-domain. With no arguments,
262 they are loaded from dss/<sub-domain>. If the name of the sub-domain
263 does not match the name of the DSset (as it frequently happens with
264 reverse zones), you can specify the DSset name explicitly.
267 Specify a list of mail exchangers for the current host or domain.
268 Each mail exchanger should be preceded by a priority. Generates
272 Specify a HINFO record for the current host. Very rare in the
276 Specify a list of aliases for the current host or domain.
277 Generates a series of CNAME records pointing from the aliases
278 to the current host/domain.
281 Specify a TXT record for the current host or domain.
284 Specify a RP (responsible person) record for the current host or domain.
285 The first argument is a mail address in DNS notation (with `@' replaced
286 by `.' as in the SOA record), the second one is a name of a TXT record
287 with contact information.
289 SRV(service, protocol, priority, weight, port, target)
290 Specify a SRV (service) record for the current host or domain.
293 Generate a CNAME record -- "src" points to "dest".
296 Generate a PTR record -- "src" points to "dest". It's a common
297 record in reverse zones (and although it's legal in forward
298 zones as well, such use is very rare), however it's more convenient
299 to have your PTR's generated by the REVERSE directive. But if you
300 need anything special, here is the tool.
302 REVBLOCK(subdomain, min, max)
303 Generate a series of CNAME records numbered from `min' to `max'
304 and pointing to the same name in the given sub-domain, finally
305 declaring the sub-domain as well, so you can continue with its
308 Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields
315 This is a very common construct for classless reverse delegations,
316 see Section 6 for more details.
319 Switch to reverse mode. From this point on, all output is suppressed
320 except for ADDR declarations belonging to the specified network which
321 are automatically converted to PTR records.
323 With help of this feature, defining reverse zones can be as easy as:
325 ; Reverse zone for 10.0.0.0/24 a.k.a. 0.0.10.in-addr.arpa.
327 NS(ns1.example.com, ns2.example.com)
329 ; Include all primary zones containing ADDR's from this range,
330 ; which can be accomplished by a multi-file REVERSE declaration
334 4. Configuration variables
335 ~~~~~~~~~~~~~~~~~~~~~~~~~~
336 There is a fair amount of configuration variables (which are in reality normal
337 M4 macros). Each variable has a hard-wired default value which can be overridden
338 in cf/config by re-defining the variable. Also, all other config files can specify
339 their local definitions, but you need to be careful to change the variable before
340 it is used for the first time.
342 To change the setting, use
344 define(`variable', `value')
346 As usually, even this config file is a M4 script. Comments can be started by
347 semicolons, text outside macros is ignored.
349 The following variables are available:
351 NAMED_RESTART_CMD Shell command for restarting the name server daemon
352 (default: rndc reload)
354 CFDIR Directory with config files (default: cf)
355 ROOTCACHE File with the cache of root name servers
357 REFRESH SOA record parameters
361 NSNAME Origin server (default: hostname of your machine)
362 MAINTNAME Domain maintainer name (default: root@NSNAME)
364 KEYGEN_OPTIONS Extra options given to dnssec-keygen
365 (by default, it selects key type and key size).
366 SIGNZONE_OPTIONS Extra options given to dnssec-signzone
367 (by default, it specifies signature validity of 365 days).
368 DSFROMKEY_OPTIONS Extra options given to dnssec-dsfromkey
369 (by default, there are none).
371 For the timing parameters, the following shortcuts are available:
373 HOURS(n) Convert hours to seconds
374 MINUTES(n) Convert minutes to seconds
375 DAYS(n) Convert days to seconds
380 The Makefile generated by NSC offers the following targets:
382 all (default) - update all zone files and reload the daemon
383 clean - clean all generated zone files, backups, and hashes
384 clobber - clean + delete Makefile and named.conf
385 (wise to do after major reconfigurations)
386 distclean - clobber + delete all version files (use only
387 if you really know what you are doing as the
388 serial number information in newly generated
389 files might be inconsistent then).
392 6. Classless reverse delegations
393 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
394 NSC also supports classless delegations for reverse zones using the mechanism
395 described in RFC 2317, i.e. by putting CNAME records to the reverse zone which
396 point to records of the same name in a sub-domain which you can delegate directly.
398 For example if you want to delegate 64-127 in 0.0.10.in-addr.arpa to ns.example.net,
399 you create a 64/26 sub-domain (26 is the network prefix length) and add the following
400 records to 0.0.10.in-addr.arpa:
402 64 CNAME 64.64/26.0.0.10.in-addr.arpa.
403 65 CNAME 65.64/26.0.0.10.in-addr.arpa.
405 127 CNAME 127.64/26.0.0.10.in-addr.arpa.
407 64/26 NS ns.example.net.
409 Then you configure ns.example.net to be a primary name server for the zone
410 64/26.0.0.10.in-addr.arpa and put the PTR records there:
412 64 PTR sixty-four.example.net.
413 65 PTR sixty-five.example.net.
415 127 PTR two-to-seven-minus-one.example.net.
417 NSC offers special primitives for configuring such delegations, but not limited
418 to the sub-domain name syntax shown above (which is recommended by the RFC, but it's
419 far from being the only one used in the real world, other possibilities being for
420 example 64-127, 64+64 etc.).
422 The CNAME block can be generated by the REVBLOCK(subdomain-name, low-addr, high-addr)
423 directive in the configuration of the whole reverse zone. The example above would
426 REVBLOCK(64/26, 64, 127)
428 The sub-zone can be created automatically like any another reverse zone, you only
429 need to use the three-parameter form of the REVERSE directive to specify the
430 address range in order to filter out possible hosts falling outside your range.
432 CAVEAT: The slashes in zone names are automatically translated to @'s when forming
435 Again for the example above, you need to put the following to cf/domains:
437 REVERSE(10.0.0.64/26, <list-of-domains-to-gather-the-addresses-from>)
439 And to cf/64@26.0.0.10:
441 SOA(REV(10.0.0.64/26))
442 NS(<list-of-name-servers>)
443 REVERSE(10.0.0, 64, 127)
445 NOTE: It's usually helpful to configure the primary name server for the parent
446 domain (i.e., the one where you configure the delegation and create the CNAME's)
447 as a secondary for the sub-zone as well, so if it replies with the CNAME, it will
448 include the PTR record pointed to by the CNAME in the additional section of its
449 reply, eliminating the need for an extra query.
454 NSC also supports IPv6 in a pretty straightforward form: wherever you can write
455 an IPv4 address, you can use an IPv6 address as well. Incomplete IP addresses
456 or ranges used for specifying address blocks for reverse delegations are replaced
457 by network prefixes of the standard form <address>/<prefix-length>.
461 H(ianus, 1.2.3.4, fec0::1234:5678:9abc:def0)
463 specifies a dual-stack host with both an A record and an AAAA record.
465 CAVEAT: The backward-compatible IPv6 address syntax with ":v.w.x.y" at the end
466 is not supported. All other syntaxes and quirks hopefully are.
471 NSC knows the basics of DNSSEC. It does not handle key management (you need to
472 schedule generation and retirement of your keys by other means), but once the
473 keys are in place, it uses them for signing zones.
475 === Key management ===
477 Keys live in keys/<zone>/*.(key|private) and they are stored in the usual BIND
478 format. To generate a zone-signing key, you can use the following command after
479 writing at least rudimentary cf/<zone>:
483 If you want a key-signing key, use:
485 bin/key-gen <zone> -f KSK
487 (Generally, you can add arbitrary arguments for BIND's dnssec-keygen. Default
488 keygen options can be set in cf/config, see section 4.)
490 To detect key changes, NSC keeps a hash of all keys for each domain.
491 If you edit the keys manually (e.g., to delete a key), you need to recalculate
494 bin/key-update <zone>
496 (or without a zone to update all hashes).
498 === Domain signing ===
500 All domains whose declarations in cf/domains are wrapped by DNSSEC(`...')
501 are automatically signed using all set up keys. If you specify key validity
502 period when generating the key, it is respected, but the domains are not
503 re-signed automatically when a key becomes valid / ceases to be. If you
504 want to modify dnssec-signzone arguments, you can do so in cf/config.
506 Beware that all signatures have a limited lifetime (even if the keys do not
507 expire). The default lifetime is 365 days, so you need to re-sign your zones
508 at least once in a year. The recommended solution is to set up a cron job,
509 which touches keys/resign-stamp. A change of timestamp of this file forces
510 a re-sign on the next run of make.
514 If you want to delegate a signed sub-domain, you need to include DS records
515 in the parent zone. Add a DS() macro after declaration of the sub-domain
516 in the parent. It loads DS records from dss/<child>.
518 If the sub-domain is also maintained by NSC, you can generate the DS record
519 set automatically by:
521 bin/key-delegate <zone>
523 === Reverse zones ===
525 Unlike primary/secondary zones, reverse zones have file names which differ
526 from the full domain name. In such cases, keys are named after the file name
527 and NSC constructs the full name whenever necessary.
529 There is one exception where automatic construction is not available:
530 delegation of sub-domain keys. In such cases, you need to pass the file
531 name of the sub-zone to the DS macro.
534 9. Interaction with M4
535 ~~~~~~~~~~~~~~~~~~~~~~
536 All config files are fully-fledged M4 scripts, so you can use any M4 features
537 you need, the most helpful one being definition of your own macros by
539 define(`macro_name', `expansion')
541 However, there is a couple of things you need to care about:
543 o The comment character is redefined to `;'. I.e., wherever a semicolon
544 occurs, the rest of the line is a comment which is copied verbatim
545 to the output file (if the output is not suppressed like in case
546 of the cf/domains file).
548 o Names starting with 'nsc_' or spelled in all caps are reserved
549 for the NSC itself and unless documented, messing with them can
550 bring surprising results. If you need to use such a name in your
551 zone file (maybe you like to shout in your host names :-) ),
552 quote it like `this'.
554 o Don't use commas, quotes nor parentheses in your record names.
559 convert A simple Perl script for conversion of zone files to NSC
560 domain files. Requires the Net::DNS module (available from
561 CPAN at ftp.cpan.org; present in recent versions of Perl).
562 Keep in mind that the script is very simple and its craft
563 is of a very limited kind, so check its output carefully.
565 chkdel A simple Perl script for checking of domain delegations --
566 it checks all PRIMARY and SECONDARY records in cf/domains
567 against NS records. Requires the Net::DNS module and also
568 some tweaking of parameters at the top of the script.