- Domain Name Server Configuration Utilities -- NSC 2.1
+ Domain Name Server Configuration Utilities -- NSC 3.0.2
- (c) 1998 Martin Mares <mj@ucw.cz>
+ (c) 1997--2008 Martin Mares <mj@ucw.cz>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- NSC is a set of shell and M4 scripts for easy maintenance of all domain name
-server files (including configuration and zone files). It requires BIND 8.X,
-GNU bash and GNU m4 to be installed on the system. All programs have been
-tested on Linux, but should work on all unices assuming the required packages
-are present.
- The whole program 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 :-]).
+------------------------------------------------------------------------------------
+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.
+------------------------------------------------------------------------------------
-1. Getting Started
-~~~~~~~~~~~~~~~~~~
+ 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,
+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).
- To use NSC, you need to perform the following steps:
+ 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.
+
+ 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 ;-)).
+
+
+0. Quick Howto for the Impatient
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(everything will be explained in more detail in the subsequent sections)
- Create a directory where all NSC files will reside (e.g., /etc/named)
and copy everything from the NSC distribution here.
- - Link /etc/named.conf to /etc/named/named.conf
+ - 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
- - CD to /etc/named
+ - Change directory to /etc/named
- - Edit cf/domains and add lines for all domains you want to use (see
- the next section for what configuration commands are available).
+ - Edit cf/domains to suit your needs -- replace the example domains
+ by your entries.
- - Define cf/<domain-name> for all domains (see section three).
+ - Create cf/<domain-name> for all domains (again, you can easily follow
+ the example domains).
- Run bin/nsconfig (Makefile and named.conf will be generated).
- Enjoy your new DNS setup. If everything goes OK, be happy. Else
write a bug report :-)
+ - Every time you modify the domain files
-2. The Domain List File
-~~~~~~~~~~~~~~~~~~~~~~~
-
- The domain list contains configuration commands describing all domains the
-server should act as primary or secondary for and also some other parameters
-which get inserted to named.conf and to the Makefile:
+ 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.
-OPTIONS(...) - set insert options to named.conf. This command _must_ be used
- at the start of cf/domains even if the list of supplied
- options is empty.
-CONFIG(...) - insert user data to named.conf (e.g., the logging options).
+1. Directory structure
+~~~~~~~~~~~~~~~~~~~~~~
+The NSC directory (/etc/named in the above example) contains the following
+files and subdirectories:
+
+ cf/ - user-defined configuration files
+ cf/domains - the domain list (see Section 2)
+ cf/config - global settings (see Section 3)
+ cf/<domain> - each domain has its own config file
+ bin/ - commands (e.g., nsconfig)
+ m4/ - M4 scripts (used by the commands)
+ zone/ - primary zone files
+ bak/ - backups of zones we serve as a secondary NS for
+ ver/ - version files where NSC remembers version
+ numbers of the primary zones
-FORWARD(f1,f2,...) - specify forwarders (name servers we ask first if we are
- behind a firewall or we try to do better caching). This must
- be included in the OPTIONS block.
+ How are different files created:
-SLAVE(f1,f2,...) - same as FORWARDers, but asks _only_ these.
+ - You create everything in cf/.
+ - Then you run bin/nsconfig.
+ - Makefile and named.conf gets created according to cf/domains.
+ - You run make.
+ - The Makefile creates primary zone files in zone/ and version files
+ in ver/ and tells BIND to reload its configuration.
+ - BIND downloads contents of secondary zones and puts them to bak/.
-MAKEFILE(...) - insert user data to the Makefile.
-PRIMARY(zone) - define zone we act as a primary name server for.
+2. The Domain List File
+~~~~~~~~~~~~~~~~~~~~~~~
+The domain list contains configuration commands describing all domains handled
+by your server and their parameters. In fact, it's a M4 script, but viewing it as
+a config file is a good approximation (however, see Section 8 for some caveats).
+Lines starting with a semicolon are treated as comments and ignored. Text outside
+declarations is silently ignored.
+
+You can specify:
+
+PRIMARY(zone, [extra-files...])
+ Define a zone (domain) we run a primary name server for.
+ The contents of the zone are described in cf/<zone>
+ and possibly in other specified cf files (all files are
+ concatenated to produce a single configuration). See the next
+ section for a look inside these files.
+
+SECONDARY(zone, primary)
+ Define a zone we run a secondary name server for.
+ "primary" is an IP address of the primary name server.
+
+REVERSE(network, primary-files...)
+ Define a reverse zone for the given network. The network name
+ consists of several numbers separated by dots, just like an IP
+ address does, but the network usually has only 3 components.
+ Each reverse zone has its own config file cf/<network> which
+ can of course specify the contents of the zone.
+
+ However, there is a more convenient method to generate the PTR
+ records directly from the A records: just specify the REVERSE
+ directive in cf/<network> and then include all the config files
+ for the primary zones containing hosts from this network. The
+ automatic concatenation of multiple primary-files comes very
+ handy for that.
+
+ In fact, REVERSE(network, p-f...) is almost an equivalent of
+ PRIMARY(REV(network), p-f...) where REV(network) is a macro
+ translating network numbers to names of the corresponding
+ reverse zones [e.g., REV(1.2.3) equals 3.2.1.in-addr.arpa].
+ The only difference is that although the domain name is translated
+ by REV, the config file is still named according to the network.
+ You can also use the REV macro explicitly, which can be handy
+ for example in SECONDARY declarations.
+
+ZONE_OPTIONS(`options;
+ more options;
+')
+ Define options to be inserted to all subsequent zone declarations
+ until the next ZONE_OPTIONS command. Please keep in mind that the
+ semicolon character act as M4 comment, so you need to put the
+ closing quote at a separate line. See our example cf/domains.
+
+CONFIG(...)
+ Insert user data to named.conf, again beware of semicolons.
+
+MAKEFILE(...)
+ Insert user data to Makefile.
-SECONDARY(zone, primary) - define zone we act as a secondary name server
- for. "primary" is an IP address of the primary NS for this
- zone.
-REVERSE(netprefix, zone1, zone2...) - define reverse zone containing all hosts
- from given zones starting with given netprefix. If you want
- to delegate some subrange of addresses to another name server
- (as defined by RFC XXXX), you need to use netprefix+count
- instead of zone name (e.g., 194.213.32.16+16) -- this
- generates correct CNAME glue records for the subrange.
- The list of name servers authoritative for the reverse zone
- is obtained from the _first_ zone specified as an argument,
- which must NOTbe a subrange specifier (you should use a dummy
- zone in case you want only subranges).
+3. The Domain Files
+~~~~~~~~~~~~~~~~~~~
+The domain files contain descriptions of all DNS records for the given
+domain, starting with the SOA record. Again, these are M4 scripts and the
+declarations are macro calls. Lines starting with a semicolon are treated
+as comments and just copied to the generated zone file. Text outside
+declarations is copied to the zone file as well, so you can spice up the NSC
+output with your own records.
+
+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.
+
+Your menu:
+
+SOA(domain-name)
+ Generate a SOA record for the domain. This must be the first
+ declaration in the config file. The parameters of the SOA
+ are taken from configuration variables (see below). The
+ serial number is calculated from the version number remembered
+ in the version file, following the usual practice of encoding
+ current date and a sequence number within the current day
+ in the serial number, which is guaranteed to be strictly
+ increasing unless you perform more than 99 updates in a single
+ day (in which case NSC stops and tells you to tweak the serial
+ number manually).
+
+ The SOA record otherwise acts like a sub-domain (D) declaration,
+ therefore it can be followed by other records like NS (mandatory)
+ or MX.
+
+H(host)
+ Start declaration of a host. Doesn't generate anything, only
+ remembers the host's name.
+
+ADDR(addr...)
+ Specify addresses for the current host. In the normal mode, it
+ creates A records, in the reverse mode, PTR records.
+
+H(host, addr...)
+ A shortcut for H(host) ADDR(addr...) -- in many cases everything
+ you need for a single host.
+
+DADDR(addr...)
+ Like ADDR, but suppresses PTR records. (This one is useful if you
+ have a single IP address used for zillions of names and you want
+ to avoid having zillions of PTR records for the same address.)
+
+DH(host, addr...)
+ A shortcut for H(host) DADDR(addr...)
+
+D(domain)
+ Start declaration of a sub-domain. Technically the same as H(domain),
+ but this one should be more intuitive.
+
+GLUE(ns, addr...)
+ Specify a glue record for a name server contained within a sub-domain
+ it's a primary for. Currently it's an equivalent of DH(ns, addr...).
+
+NS(ns...)
+ Specify a list of name server names for the current domain
+ (started by either a SOA or D declaration). Generates NS records.
+
+MX(mx...)
+ Specify a list of mail exchangers for the current host or domain.
+ Each mail exchanger should be preceded by a priority. Generates
+ MX records.
+
+HI(hw,os)
+ Specify a HINFO record for the current host. Very rare in the
+ today's Internet.
+
+ALIAS(alias...)
+ Specify a list of aliases for the current host or domain.
+ 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".
+
+PTR(src, dest)
+ Generate a PTR record -- "src" points to "dest". It's a common
+ record in reverse zones (and although it's legal in forward
+ zones as well, such use is very rare), however it's more convenient
+ to have your PTR's generated by the REVERSE directive. But if you
+ need anything special, here is the tool.
+
+REVBLOCK(subdomain, min, max)
+ Generate a series of CNAME records numbered from `min' to `max'
+ and pointing to the same name in the given sub-domain, finally
+ declaring the sub-domain as well, so you can continue with its
+ NS records.
+
+ Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields
-PARTIAL(netprefix, count, primary, sec1, sec2...) - define delegation of a
- reverse subzone (see REVERSE above) consisting of <count>
- addresses starting at <netprefix>. <primary> is a master
- server for that subzone, <sec1> ... <secn> are secondaries
- (except our name-server which is _always_ expected to be
- a secondary).
+ 16 CNAME 16.a
+ 17 CNAME 17.a
+ 18 CNAME 18.a
+ a NS ns.xyzzy.org.
-PREVERSE(netprefix, zone1, zone2...) - define reverse zone for a subrange
- -- used when we want to export a subzone (to be imported
- by the master server for the corresponding parent zone
- by a mechanism similar to that specified by the PARTIAL
- command).
+ This is a very common construct for classless reverse delegations,
+ see Section 6 for more details.
+REVERSE(network)
+ Switch to reverse mode. From this point on, all output is suppressed
+ except for ADDR declarations belonging to the specified network which
+ are automatically converted to PTR records.
-3. The Domain Files
-~~~~~~~~~~~~~~~~~~~
+ With help of this feature, defining reverse zones can be as easy as:
- The domain files contain descriptions of all DNS records for the given
-domain, starting with the SOA record. As these files are processed by the M4,
-you can simply insert plain RR data between the macro calls (such data are
-ignored if we're generating a reverse zone) and define your own macros at the
-beginning. The standard macros you can redefine are:
+ ; Reverse zone for 10.0.0.0/24 a.k.a. 0.0.10.in-addr.arpa.
+ SOA(REV(10.0.0))
+ NS(ns1.example.com, ns2.example.com)
+ REVERSE(10.0.0)
+ ; Include all primary zones containing ADDR's from this range,
+ ; which can be accomplished by a multi-file REVERSE declaration
+ ; in cf/domains.
- - refresh, retry, expire, minttl: standard SOA timing parameters (you
- can specify them as number of seconds or using predefined time macros
- as minutes(N), hours(N) and days(N).
- - nsname: our canonical name (defaults to result of `hostname -f`)
+4. Configuration variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+There is a fair amount of configuration variables (which are in reality normal
+M4 macros). Each variable has a hard-wired default value which can be overridden
+in cf/config by re-defining the variable. Also, all other config files can specify
+their local definitions, but you need to be careful to change the variable before
+it is used for the first time.
- - maintname: zone maintainer name (defaults to 'root@nsname')
+To change the setting, use
-SOA record:
+ define(`variable', `value')
- SOA(domainname) - generates the SOA itself (serial numbers are
- created automagically from current data and
- version counter stored in a separate file)
- NS(ns1,ns2,...) - generates list of authoritative NS's
- MX(pri1 mx1, ...) - [optional] - generates list of mail exchangers
- for mail addressed directly to the domain
- name. Each MX is preceeded by its priority.
+As usually, even this config file is a M4 script. Comments can be started by
+semicolons, text outside macros is ignored.
-Subdomains:
+The following variables are available:
- D(name) - remembers domain name for further macros
- NS(ns1,ns2,...) - generates list of authoritative NS's
- [you might need to insert glue A records
- manually]
+NAMED_RESTART_CMD Shell command for restarting the name server daemon
+ (default: ndc restart)
-Hosts:
+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
- H(name,list-of-ip-addrs) - define new host with given IP addresses
- HI(hw,os) - define HINFO record
- MX(pri1 mx1, ...) - define mail exchangers for that host
- ALIAS(al1, al2,...) - define aliases for that host
+REFRESH SOA record parameters
+RETRY
+EXPIRE
+MINTTL
+NSNAME Origin server (default: hostname of your machine)
+MAINTNAME Domain maintainer name (default: root@NSNAME)
- HH(name) - define dummy host without any addresses
- (e.g., only for mail)
- RH(name,list-of-ip-addrs) - define out-of-domain host appearing only
- in the reverse zone
+BIND_OPTIONS Extra options to put to the options { ... } section of named.conf
+For the timing parameters, the following shortcuts are available:
-4. Directory structure
-~~~~~~~~~~~~~~~~~~~~~~
+HOURS(n) Convert hours to seconds
+MINUTES(n) Convert minutes to seconds
+DAYS(n) Convert days to seconds
- The NSC directory hierarchy contains the following directories:
+For the BIND_OPTIONS, we offer:
- bak/ - backups of zones we act as a secondary for
- bin/ - scripts (e.g., nsconfig)
- cf/ - configuration files (domains etc.)
- m4/ - M4 scripts
- ver/ - version files where NSC remembers version
- numbers for the zones
- zone/ - primary zone files
+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 - update all files and restart named
- clean - clean all normal data files
- clobber - clean + delete Makefile and named.conf (should
- be done after major reconfiguration)
+ all (default) - update all zone files and reload the daemon
+ clean - clean all generated zone files and backups
+ clobber - clean + delete Makefile and named.conf
+ (wise to do after major reconfigurations)
distclean - clobber + delete all version files (use only
if you really know what you are doing as the
serial number information in newly generated
files might be inconsistent then).
-6. Other utilities
-~~~~~~~~~~~~~~~~~~
+6. Classless reverse delegations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+NSC also supports classless delegations for reverse zones using the mechanism
+described in RFC 2317, i.e. by putting CNAME records to the reverse zone which
+point to records of the same name in a sub-domain which you can delegate directly.
+
+For example if you want to delegate 64-127 in 0.0.10.in-addr.arpa to ns.example.net,
+you create a 64/26 sub-domain (26 is the network prefix length) and add the following
+records to 0.0.10.in-addr.arpa:
+
+ 64 CNAME 64.64/26.0.0.10.in-addr.arpa.
+ 65 CNAME 65.64/26.0.0.10.in-addr.arpa.
+ ...
+ 127 CNAME 127.64/26.0.0.10.in-addr.arpa.
+
+ 64/26 NS ns.example.net.
+
+Then you configure ns.example.net to be a primary name server for the zone
+64/26.0.0.10.in-addr.arpa and put the PTR records there:
+
+ 64 PTR sixty-four.example.net.
+ 65 PTR sixty-five.example.net.
+ ...
+ 127 PTR two-to-seven-minus-one.example.net.
-chkdom Checks domains for correctness using the 'host' utility
- (check ftp://ftp.nikhef.nl/pub/network for latest version).
- Use chkdom <domain> <NS> to check specific domain or no
- parameters to check all domains mentioned in cf/domains.
+NSC offers special primitives for configuring such delegations, but not limited
+to the sub-domain name syntax shown above (which is recommended by the RFC, but it's
+far from being the only one used in the real world, other possibilities being for
+example 64-127, 64+64 etc.).
+
+The CNAME block can be generated by the REVBLOCK(subdomain-name, low-addr, high-addr)
+directive in the configuration of the whole reverse zone. The example above would
+be written as:
+
+ REVBLOCK(64/26, 64, 127)
+
+The sub-zone can be created automatically like any another reverse zone, you only
+need to use the three-parameter form of the REVERSE directive to specify the
+address range in order to filter out possible hosts falling outside your range.
+
+CAVEAT: The slashes in zone names are automatically translated to @'s when forming
+file names.
+
+Again for the example above, you need to put the following to cf/domains:
+
+ REVERSE(10.0.0.64/26, <list-of-domains-to-gather-the-addresses-from>)
+
+And to cf/64@26.0.0.10:
+
+ SOA(REV(10.0.0.64/26))
+ NS(<list-of-name-servers>)
+ REVERSE(10.0.0, 64, 127)
+
+NOTE: It's usually helpful to configure the primary name server for the parent
+domain (i.e., the one where you configure the delegation and create the CNAME's)
+as a secondary for the sub-zone as well, so if it replies with the CNAME, it will
+include the PTR record pointed to by the CNAME in the additional section of its
+reply, eliminating the need for an extra query.
+
+
+7. Support for IPv6
+~~~~~~~~~~~~~~~~~~~
+NSC also supports IPv6 in a pretty straightforward form: wherever you can write
+an IPv4 address, you can use an IPv6 address as well. Incomplete IP addresses
+or ranges used for specifying address blocks for reverse delegations are replaced
+by network prefixes of the standard form <address>/<prefix-length>.
+
+Example:
+
+ H(ianus, 1.2.3.4, fec0::1234:5678:9abc:def0)
+
+specifies a dual-stack host with both an A record and an AAAA record.
+
+CAVEAT: The backward-compatible IPv6 address syntax with ":v.w.x.y" at the end
+is not supported. All other syntaxes and quirks hopefully are.
+
+
+8. 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
+
+ define(`macro_name', `expansion')
+
+However, there is a couple of things you need to care about:
+
+ o The comment character is redefined to `;'. I.e., wherever a semicolon
+ occurs, the rest of the line is a comment which is copied verbatim
+ to the output file (if the output is not suppressed like in case
+ of the cf/domains file).
+
+ o Names starting with 'nsc_' or spelled in all caps are reserved
+ 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 '.
+
+ o Don't use commas, quotes nor parentheses in your record names.
+
+
+9. Other utilities
+~~~~~~~~~~~~~~~~~~
+convert A simple Perl script for conversion of zone files to NSC
+ domain files. Requires the Net::DNS module (available from
+ CPAN at ftp.cpan.org; present in recent versions of Perl).
+ Keep in mind that the script is very simple and its craft
+ is of a very limited kind, so check its output carefully.
+
+chkdel A simple Perl script for checking of domain delegations --
+ it checks all PRIMARY and SECONDARY records in cf/domains
+ against NS records. Requires the Net::DNS module and also
+ some tweaking of parameters at the top of the script.
projects / nsc-5.git / blobdiff