Domain Name Server Configuration Utilities -- NSC 3.0 (c) 1997--2003 Martin Mares ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #### BIG FAT WARNING #### NSC 3.0 is close to having been rewritten from scratch. However, the documentation has not been updated yet, only the example configs in cf/* were. #### BIG FAT END OF WARNING #### 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 :-]). 1. Getting Started ~~~~~~~~~~~~~~~~~~ To use NSC, you need to perform the following steps: - 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 - CD 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). - Define cf/ for all domains (see section three). - 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 :-) An interesting companion to this program is the Sleuth utility which checks consistency of DNS zones. It's written in perl with help of the DNS module, knows of more errors than other checkers and it's freely available at ftp://atrey.karlin.mff.cuni.cz/pub/local/mj/net/sleuth-1.3.tar.gz. 2. The Domain List File ~~~~~~~~~~~~~~~~~~~~~~~ The domain list contains configuration commands describing all domains the server is either primary or secondary for and also some other parameters which get inserted to named.conf and to the Makefile: 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). 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. SLAVE(f1,f2,...) - same as FORWARDers, but asks _only_ these. MAKEFILE(...) - insert user data to the Makefile. PRIMARY(zone) - define zone we're a primary name server for. SECONDARY(zone, primary) - define zone we're 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 a part of your C range to another name server, use the PARTIAL directive to configure a partial reverse domain and mention a subzone (e.g., 194.213.32.16+16) in the main REVERSE directive. The list of name servers authoritative for the reverse zone is obtained from the _first_ zone specified as an argument, which must NOT be a subrange specifier (you should use a dummy zone in case you want only subranges). PARTIAL(netprefix, count, primary, sec1, sec2...) - define delegation of a reverse subzone (see REVERSE above) consisting of addresses starting at . is a master server for that subzone, ... are secondaries (don't list the local name-server, it's always expected to be a secondary). PREVERSE(netprefix, zone1, zone2...) - analogon of REVERSE for partial zones (to be used when you want to export a subzone to another server which is configured by PARTIAL). Just use a 4-component netprefix. You can also change several predefined macros: - named_restart_cmd: command used to restart named (default: `ndc reload') 3. The Domain Files ~~~~~~~~~~~~~~~~~~~ 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: - 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`) - maintname: zone maintainer name (defaults to 'root@nsname') SOA record: 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. Subdomains: 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] Hosts: 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 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 4. Directory structure ~~~~~~~~~~~~~~~~~~~~~~ The NSC directory hierarchy contains the following directories: bak/ - backups of zones we're 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 5. Makefile 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) 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 ~~~~~~~~~~~~~~~~~~ chkdom Checks domains for correctness using the 'host' utility (check ftp://ftp.nikhef.nl/pub/network for latest version). Use chkdom to check specific domain or no parameters to check all domains mentioned in cf/domains. It's even better to use the Sleuth script mentioned in the introduction. convert A simple perl script for conversion of zone files to NSC domain files. Requires the DNS module (available from CPAN at ftp.cpan.org). 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 DNS Perl module and also some tweaking of parameters at the top of the script.