~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#### 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
+ 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).
+
+ 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 :-]).
+(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:
+1. 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 :-)
- 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.
+ - Every time you modify the domain files
+ 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.
-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.
+2. 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 3)
+ cf/config - global settings (see Section XXX)
+ 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
-CONFIG(...) - insert user data to named.conf (e.g., the logging options).
+ How are different files created:
-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.
+ - 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/.
-SLAVE(f1,f2,...) - same as FORWARDers, but asks _only_ these.
-MAKEFILE(...) - insert user data to the Makefile.
+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 XXX 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.
+
+CONFIG(...) - insert user data to named.conf
+
+MAKEFILE(...) - insert user data to 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.
+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.
+
+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 subdomain (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 supresses 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 subdomain. 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 subdomain
+ 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.
+
+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 subdomain, finally
+ declaring the subdomain as well, so you can continue with its
+ NS records.
+
+ Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields
+
+ 16 CNAME 16.a
+ 17 CNAME 17.a
+ 18 CNAME 18.a
+ a NS ns.xyzzy.org.
+
+ This is a very common construct for classless reverse delegations,
+ see Section XXX for more details.
+
+REVERSE(network)
+ Switch to reverse mode. From this point on, all output is supressed
+ except for ADDR declarations belonging to the specified network which
+ are automatically converted to PTR records.
+
+ With help of this feature, defining reverse zones can be as easy as:
-REVERSE(netprefix, zone1, zone2...) - define reverse zone containing all hosts
- from given zones starting with given netprefix.
+ ; 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.
- 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).
+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 overriden
+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.
-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
- (don't list the local name-server, it's always expected to
- be a secondary).
+To change the setting, use
-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.
+ define(`variable', `value')
-You can also change several predefined macros:
+As usually, even this config file is a M4 script. Comments can be started by
+semicolons, text outside macros is ignored.
- - named_restart_cmd: command used to restart named (default: `ndc reload')
+The following variables are available:
+NAMED_RESTART_CMD Shell command for restarting the name server daemon
+ (default: ndc restart)
-3. The Domain Files
-~~~~~~~~~~~~~~~~~~~
+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 nameservers
- 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 SOA record parameters
+RETRY
+EXPIRE
+MINTTL
+NSNAME Origin server (default: hostname of your machine)
+MAINTNAME Domain maintainer name (default: root@NSNAME)
- - 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).
+BIND_OPTIONS Extra options to put to the options { ...} section of named.conf
- - nsname: our canonical name (defaults to result of `hostname -f`)
+For the timing parameters, the following shortcuts are avaiable:
- - maintname: zone maintainer name (defaults to 'root@nsname')
+HOURS(n) Convert hours to seconds
+MINUTES(n) Convert minutes to seconds
+DAYS(n) Convert days to seconds
-SOA record:
+For the BIND_OPTIONS, we offer:
- 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.
+FORWARD(ip...) Try to ask the given nameservers first to see if they
+ have the reply cached.
+SLAVE(ip...) Pass all non-local requests to the given nameservers.
-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]
+5. Makefile targets
+~~~~~~~~~~~~~~~~~~~
+The Makefile generated by NSC offers the following targets:
-Hosts:
+ 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).
- 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
+6. Classless reverse delegations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-4. Directory structure
-~~~~~~~~~~~~~~~~~~~~~~
+7. Support for IPv6
+~~~~~~~~~~~~~~~~~~~
- 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
+ in style of RFC 2317. The RFC recommends syntax `net/prefix-len'
+ for the subdomains (which is especially nasty for all systems
+ storing domains in files with the same name :) ; NSC avoids this
+ by automagically translating all slashes in domain names to @'s
+ when creating file names)
-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).
+8. Interaction with M4
+~~~~~~~~~~~~~~~~~~~~~~
-6. Other utilities
+9. Other utilities
~~~~~~~~~~~~~~~~~~
chkdom Checks domains for correctness using the 'host' utility
projects / nsc-5.git / commitdiff