- Domain Name Server Configuration Utilities -- NSC 3.0.1
+ Domain Name Server Configuration Utilities -- NSC 5.0
- (c) 1997--2006 Martin Mares <mj@ucw.cz>
+ (c) 1997--2019 Martin Mares <mj@ucw.cz>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------------------------------------------
-WARNING: NSC has undergone significant changes between versions 2.3 and 2.99b.
-See NEWS for the summary of changes. Most importantly, the configuration files are
-NOT compatible with the old releases.
-------------------------------------------------------------------------------------
+-----------------------------------------------------------------------
+WARNING: There were several incompatible changes between major versions
+ See NEWS for the summary of changes.
+-----------------------------------------------------------------------
NSC is a set of shell and M4 scripts for easy maintenance of DNS zone files
-and name server daemon configuration (currently available only for BIND 8.X,
+and name server daemon configuration (currently available only for BIND 8.x/9.x,
but easily portable for other daemons). It has been designed to make administration
of a DNS server a piece of cake (unlike other utilities which resemble more
an English pudding :-) ), which includes automatic generation of reverse records
for all your hosts, handling of classless reverse delegations and support for IPv6
-(AAAA and PTR in in6.arpa, not A6 and DNAME which seem to be dying out).
+(AAAA and PTR in ip6.arpa, not A6 and DNAME which seem to be dying out).
- NSC requires GNU m4 and a POSIX-compatible shell, some of the extra utilities
-require Perl 5. I've tested everything on Linux (Debian Woody), 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
- Create a directory where all NSC files will reside (e.g., /etc/named)
and copy everything from the NSC distribution here.
- - Symlink /etc/bind/named.conf (or /etc/named.conf or where the config file
- of your installation of BIND resides) to /etc/named/named.conf
+ - Add an include directive to your BIND configuration file (usually
+ /etc/bind/named.conf), referring to /etc/named/named.conf.
- Change directory to /etc/named
- Create cf/<domain-name> for all domains (again, you can easily follow
the example domains).
+ - If you are using BIND 9.x, make the `bak' directory writable
+ by the bind user.
+
- Run bin/nsconfig (Makefile and named.conf will be generated).
- Run make.
- Enjoy your new DNS setup. If everything goes OK, be happy. Else
write a bug report :-)
- - Every time you modify the domain files
+ - Every time you modify the domain files, re-run make. If you have
+ 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.
+The Sleuth is available from http://mj.ucw.cz/sw/sleuth/. However, I haven't
+updated Sleuth for a long time, so it does not know about DNSSEC yet.
1. Directory structure
bak/ - backups of zones we serve as a secondary NS for
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
concatenated to produce a single configuration). See the next
section for a look inside these files.
+ When the zone name contains a slash (as happens in classless
+ reverse zones), it is replaced by "@" in the cf file name.
+
SECONDARY(zone, primary)
Define a zone we run a secondary name server for.
"primary" is an IP address of the primary name server.
You can also use the REV macro explicitly, which can be handy
for example in SECONDARY declarations.
+FORWARDED(zone, ip...)
+ Define a forwarding zone. All queries are forwarded to the
+ specified name servers.
+
+BLACKHOLE(zone)
+ Define an empty zone according to RFC 6303. This is usually done
+ for zones for which clients are known to erroneously ask queries
+ (e.g., reverse resolving of link-local addresses). The contents
+ served for these zones is taken from cf/blackhole.
+
ZONE_OPTIONS(`options;
more options;
')
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
~~~~~~~~~~~~~~~~~~~
All host or domain names are either names relative to the current domain
with no dots inside or absolute names (in this case, NSC automatically
-ensures that the trailing dot is present in the resource records). Relative
-names with dots are not supported, but they are rare and you can always write
-them as absolute anyway.
+ensures that the trailing dot is present in the resource records). If you
+really need a relative name with dots, escape all dots as "\.".
Your menu:
ADDR(addr...)
Specify addresses for the current host. In the normal mode, it
- creates A records, in the reverse mode, PTR records.
+ creates A/AAAA records, in the reverse mode, PTR records.
H(host, addr...)
A shortcut for H(host) ADDR(addr...) -- in many cases everything
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
Generates a series of CNAME records pointing from the aliases
to the current host/domain.
+TXT(text)
+ Specify a TXT record for the current host or domain.
+
+RP(mail, txt)
+ Specify a RP (responsible person) record for the current host or domain.
+ The first argument is a mail address in DNS notation (with `@' replaced
+ by `.' as in the SOA record), the second one is a name of a TXT record
+ with contact information.
+
+SRV(service, protocol, priority, weight, port, target)
+ Specify a SRV (service) record for the current host or domain.
+
CNAME(src, dest)
Generate a CNAME record -- "src" points to "dest".
The following variables are available:
NAMED_RESTART_CMD Shell command for restarting the name server daemon
- (default: ndc restart)
+ (default: rndc reload)
-ROOT Root directory of the whole package (default: /etc/named)
CFDIR Directory with config files (default: cf)
-ZONEDIR Directory with zone files (default: zone)
-BAKDIR Directory with backup files (default: bak)
-VERSDIR Directory with version files (default: var)
-ROOTCACHE File with the cache of root name servers
REFRESH SOA record parameters
RETRY
NSNAME Origin server (default: hostname of your machine)
MAINTNAME Domain maintainer name (default: root@NSNAME)
-BIND_OPTIONS Extra options to put to the options { ... } section of named.conf
+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:
MINUTES(n) Convert minutes to seconds
DAYS(n) Convert days to seconds
-For the BIND_OPTIONS, we offer:
-
-FORWARD(ip...) Try to ask the given name servers first to see if they
- have the reply cached.
-SLAVE(ip...) Pass all non-local requests to the given name servers.
-
5. Makefile targets
~~~~~~~~~~~~~~~~~~~
The Makefile generated by NSC offers the following targets:
all (default) - update all zone files and reload the daemon
- clean - clean all generated zone files and backups
+ clean - clean all generated zone files, backups, and hashes
clobber - clean + delete Makefile and named.conf
(wise to do after major reconfigurations)
distclean - clobber + delete all version files (use only
is not supported. All other syntaxes and quirks hopefully are.
-8. Interaction with M4
+8. DNSSEC support
+~~~~~~~~~~~~~~~~~
+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.
+
+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
~~~~~~~~~~~~~~~~~~~~~~
All config files are fully-fledged M4 scripts, so you can use any M4 features
you need, the most helpful one being definition of your own macros by
for the NSC itself and unless documented, messing with them can
bring surprising results. If you need to use such a name in your
zone file (maybe you like to shout in your host names :-) ),
- quote it with ` and '.
+ quote it like `this'.
o Don't use commas, quotes nor parentheses in your record names.
projects / nsc-5.git / blobdiff