- Domain Name Server Configuration Utilities -- NSC 4.0
+ Domain Name Server Configuration Utilities -- NSC 5.0
(c) 1997--2019 Martin Mares <mj@ucw.cz>
for all your hosts, handling of classless reverse delegations and support for IPv6
(AAAA and PTR in ip6.arpa, not A6 and DNAME which seem to be dying out).
- NSC requires GNU m4, a POSIX-compatible shell and the `md5sum' utility (which
-is present for examile in GNU coreutils). Some of the extra utilities require
-Perl 5. I've tested everything on Linux (Debian Squeeze), but the whole package
-should run on other unices as well.
+ NSC requires GNU m4, GNU Bash, the `md5sum' and `sha1sum' utilities (which
+are present for example in GNU coreutils), and utilities distributed with BIND.
+Some of the extra utilities require Perl 5. I've tested everything on Linux
+(Debian Stretch), but the whole package should run on other unices as well.
The whole package can be used and distributed according to the terms of the
-GNU General Public License. See file COPYING in any of the GNU utility archives
-(you should have one as you are expected to have at least GNU M4 ;-)).
+GNU General Public License, version 2 or higher. See file COPYING in any of the
+GNU utility archives (you should have one as you are expected to have at least
+GNU M4 ;-)).
0. Quick Howto for the Impatient
added or removed domains or changed options which affect named.conf,
re-run bin/nsconfig before make.
- An interesting companion to this package is the DNS Sleuth -- a DNS zone
+An interesting companion to this package is the DNS Sleuth -- a DNS zone
consistency checker. It's a simple utility written in Perl with help of the
DNS module and it should be able to detect all common errors in DNS setup
(I have written it after much disappointment with the other checkers).
The Sleuth is available online on http://atrey.karlin.mff.cuni.cz/~mj/sleuth/,
-follow the links to download the source.
+follow the links to download the source. However, I haven't updated Sleuth
+for a long time, so it does not know about DNSSEC yet.
1. Directory structure
m4/ - M4 scripts (used by the commands)
zone/ - primary zone files
bak/ - backups of zones we serve as a secondary NS for
- hash/ - hashes of zone files used for detection of changes
ver/ - version files where NSC remembers version
numbers of the primary zones
+ tmp/ - temporary files
+ hash/ - hashes of zone files used for detection of changes
+ dss/<domain> - DNSSEC DS records
+ keys/<domain>/ - DNSSEC keys
+ khash/ - hashes of DNSSEC keys used for detection of changes
How are different files created:
- You create everything in cf/.
- Then you run bin/nsconfig.
+ - If you want to use DNSSEC, create keys (see section 8)
- Makefile and named.conf gets created according to cf/domains.
- You run make.
- The Makefile creates primary zone files in zone/ and version files
MAKEFILE(...)
Insert user data to Makefile.
+DNSSEC(`declarations...')
+ Request DNSSEC signing for all zones declared within the block.
+
+DSFOR(zone)
+ Declare dependency of the previous PRIMARY/REVERSE domain on DS
+ records for the given zone configured in dss/*.
+
3. The Domain Files
~~~~~~~~~~~~~~~~~~~
Specify a list of name server names for the current domain
(started by either a SOA or D declaration). Generates NS records.
+DS()
+DS(dsset)
+ Include DS records for the current sub-domain. With no arguments,
+ they are loaded from dss/<sub-domain>. If the name of the sub-domain
+ does not match the name of the DSset (as it frequently happens with
+ reverse zones), you can specify the DSset name explicitly.
+
MX(mx...)
Specify a list of mail exchangers for the current host or domain.
Each mail exchanger should be preceded by a priority. Generates
NSNAME Origin server (default: hostname of your machine)
MAINTNAME Domain maintainer name (default: root@NSNAME)
+KEYGEN_OPTIONS Extra options given to dnssec-keygen
+ (by default, it selects key type and key size).
+SIGNZONE_OPTIONS Extra options given to dnssec-signzone
+ (by default, it specifies signature validity of 365 days).
+DSFROMKEY_OPTIONS Extra options given to dnssec-dsfromkey
+ (by default, there are none).
+
For the timing parameters, the following shortcuts are available:
HOURS(n) Convert hours to seconds
8. DNSSEC support
~~~~~~~~~~~~~~~~~
-FIXME: Write real docs!
+NSC knows the basics of DNSSEC. It does not handle key management (you need to
+schedule generation and retirement of your keys by other means), but once the
+keys are in place, it uses them for signing zones.
+
+=== Key management ===
+
+Keys live in keys/<zone>/*.(key|private) and they are stored in the usual BIND
+format. To generate a zone-signing key, you can use the following command after
+writing at least rudimentary cf/<zone>:
+
+ bin/key-gen <zone>
+
+If you want a key-signing key, use:
+
+ bin/key-gen <zone> -f KSK
+
+(Generally, you can add arbitrary arguments for BIND's dnssec-keygen. Default
+keygen options can be set in cf/config, see section 4.)
+
+To detect key changes, NSC keeps a hash of all keys for each domain.
+If you edit the keys manually (e.g., to delete a key), you need to recalculate
+the hash by:
+
+ bin/key-update <zone>
+
+(or without a zone to update all hashes).
+
+=== Domain signing ===
+
+All domains whose declarations in cf/domains are wrapped by DNSSEC(`...')
+are automatically signed using all set up keys. If you specify key validity
+period when generating the key, it is respected, but the domains are not
+re-signed automatically when a key becomes valid / ceases to be. If you
+want to modify dnssec-signzone arguments, you can do so in cf/config.
+
+Beware that all signatures have a limited lifetime (even if the keys do not
+expire). The default lifetime is 365 days, so you need to re-sign your zones
+at least once in a year. The recommended solution is to set up a cron job,
+which touches keys/resign-stamp. A change of timestamp of this file forces
+a re-sign on the next run of make.
+
+=== Subdomains ===
+
+If you want to delegate a signed sub-domain, you need to include DS records
+in the parent zone. Add a DS() macro after declaration of the sub-domain
+in the parent. It loads DS records from dss/<child>.
+
+If the sub-domain is also maintained by NSC, you can generate the DS record
+set automatically by:
+
+ bin/key-delegate <zone>
+
+=== Reverse zones ===
+
+Unlike primary/secondary zones, reverse zones have file names which differ
+from the full domain name. In such cases, keys are named after the file name
+and NSC constructs the full name whenever necessary.
-bin/key-gen example.com
-bin/key-gen -f KSK example.com
-bin/key-update
-keys/resign-stamp
+There is one exception where automatic construction is not available:
+delegation of sub-domain keys. In such cases, you need to pass the file
+name of the sub-zone to the DS macro.
9. Interaction with M4
projects / nsc-5.git / commitdiff