README

   1
   2              Domain Name Server Configuration Utilities -- NSC 2.2
   3
   4                     (c) 1997--1999 Martin Mares <mj@ucw.cz>
   5
   6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7
   8    NSC is a set of shell and M4 scripts for easy maintenance of all domain name
   9 server files (including configuration and zone files). It requires BIND 8.X,
  10 GNU bash and GNU m4 to be installed on the system. All programs have been
  11 tested on Linux, but should work on all unices assuming the required packages
  12 are present.
  13
  14    The whole program can be used and distributed according to the terms of the
  15 GNU General Public License. See file COPYING in any of the GNU utility archives
  16 (you should have one as you are expected to have at least GNU M4 :-]).
  17
  18
  19 1. Getting Started
  20 ~~~~~~~~~~~~~~~~~~
  21
  22    To use NSC, you need to perform the following steps:
  23
  24         - Create a directory where all NSC files will reside (e.g., /etc/named)
  25           and copy everything from the NSC distribution here.
  26
  27         - Link /etc/named.conf to /etc/named/named.conf
  28
  29         - CD to /etc/named
  30
  31         - Edit cf/domains and add lines for all domains you want to use (see
  32           the next section for what configuration commands are available).
  33
  34         - Define cf/<domain-name> for all domains (see section three).
  35
  36         - Run bin/nsconfig (Makefile and named.conf will be generated).
  37
  38         - Run make.
  39
  40         - Enjoy your new DNS setup. If everything goes OK, be happy. Else
  41           write a bug report :-)
  42
  43    An interesting companion to this program is the Sleuth utility which checks
  44 consistency of DNS zones. It's written in perl with help of the DNS module,
  45 knows of more errors than other checkers and it's freely available at
  46 ftp://atrey.karlin.mff.cuni.cz/pub/local/mj/net/sleuth-1.0.tar.gz.
  47
  48
  49 2. The Domain List File
  50 ~~~~~~~~~~~~~~~~~~~~~~~
  51
  52    The domain list contains configuration commands describing all domains the
  53 server should act as primary or secondary for and also some other parameters
  54 which get inserted to named.conf and to the Makefile:
  55
  56 OPTIONS(...)    - set insert options to named.conf. This command _must_ be used
  57                   at the start of cf/domains even if the list of supplied
  58                   options is empty.
  59
  60 CONFIG(...)     - insert user data to named.conf (e.g., the logging options).
  61
  62 FORWARD(f1,f2,...) - specify forwarders (name servers we ask first if we are
  63                   behind a firewall or we try to do better caching). This must
  64                   be included in the OPTIONS block.
  65
  66 SLAVE(f1,f2,...) - same as FORWARDers, but asks _only_ these.
  67
  68 MAKEFILE(...)   - insert user data to the Makefile.
  69
  70 PRIMARY(zone)   - define zone we act as a primary name server for.
  71
  72 SECONDARY(zone, primary) - define zone we act as a secondary name server
  73                   for. "primary" is an IP address of the primary NS for this
  74                   zone.
  75
  76 REVERSE(netprefix, zone1, zone2...) - define reverse zone containing all hosts
  77                   from given zones starting with given netprefix. If you want
  78                   to delegate some subrange of addresses to another name server
  79                   (as defined by RFC XXXX), you need to use netprefix+count
  80                   instead of zone name (e.g., 194.213.32.16+16) -- this
  81                   generates correct CNAME glue records for the subrange.
  82                   The list of name servers authoritative for the reverse zone
  83                   is obtained from the _first_ zone specified as an argument,
  84                   which must NOTbe a subrange specifier (you should use a dummy
  85                   zone in case you want only subranges).
  86
  87 PARTIAL(netprefix, count, primary, sec1, sec2...) - define delegation of a
  88                   reverse subzone (see REVERSE above) consisting of <count>
  89                   addresses starting at <netprefix>. <primary> is a master
  90                   server for that subzone, <sec1> ... <secn> are secondaries
  91                   (except our name-server which is _always_ expected to be
  92                   a secondary).
  93
  94 PREVERSE(netprefix, zone1, zone2...) - define reverse zone for a subrange
  95                   -- used when we want to export a subzone (to be imported
  96                   by the master server for the corresponding parent zone
  97                   by a mechanism similar to that specified by the PARTIAL
  98                   command).
  99
 100
 101 3. The Domain Files
 102 ~~~~~~~~~~~~~~~~~~~
 103
 104    The domain files contain descriptions of all DNS records for the given
 105 domain, starting with the SOA record. As these files are processed by the M4,
 106 you can simply insert plain RR data between the macro calls (such data are
 107 ignored if we're generating a reverse zone) and define your own macros at the
 108 beginning. The standard macros you can redefine are:
 109
 110         - refresh, retry, expire, minttl: standard SOA timing parameters (you
 111           can specify them as number of seconds or using predefined time macros
 112           as minutes(N), hours(N) and days(N).
 113
 114         - nsname: our canonical name (defaults to result of `hostname -f`)
 115
 116         - maintname: zone maintainer name (defaults to 'root@nsname')
 117
 118 SOA record:
 119
 120         SOA(domainname)         - generates the SOA itself (serial numbers are
 121                                   created automagically from current data and
 122                                   version counter stored in a separate file)
 123         NS(ns1,ns2,...)         - generates list of authoritative NS's
 124         MX(pri1 mx1, ...)       - [optional] - generates list of mail exchangers
 125                                   for mail addressed directly to the domain
 126                                   name. Each MX is preceeded by its priority.
 127
 128 Subdomains:
 129
 130         D(name)                 - remembers domain name for further macros
 131         NS(ns1,ns2,...)         - generates list of authoritative NS's
 132                                   [you might need to insert glue A records
 133                                    manually]
 134
 135 Hosts:
 136
 137         H(name,list-of-ip-addrs) - define new host with given IP addresses
 138         HI(hw,os)               - define HINFO record
 139         MX(pri1 mx1, ...)       - define mail exchangers for that host
 140         ALIAS(al1, al2,...)     - define aliases for that host
 141
 142         HH(name)                - define dummy host without any addresses
 143                                   (e.g., only for mail)
 144         RH(name,list-of-ip-addrs) - define out-of-domain host appearing only
 145                                   in the reverse zone
 146
 147
 148 4. Directory structure
 149 ~~~~~~~~~~~~~~~~~~~~~~
 150
 151    The NSC directory hierarchy contains the following directories:
 152
 153         bak/                    - backups of zones we act as a secondary for
 154         bin/                    - scripts (e.g., nsconfig)
 155         cf/                     - configuration files (domains etc.)
 156         m4/                     - M4 scripts
 157         ver/                    - version files where NSC remembers version
 158                                   numbers for the zones
 159         zone/                   - primary zone files
 160
 161
 162 5. Makefile targets
 163 ~~~~~~~~~~~~~~~~~~~
 164
 165         all                     - update all files and restart named
 166         clean                   - clean all normal data files
 167         clobber                 - clean + delete Makefile and named.conf (should
 168                                   be done after major reconfiguration)
 169         distclean               - clobber + delete all version files (use only
 170                                   if you really know what you are doing as the
 171                                   serial number information in newly generated
 172                                   files might be inconsistent then).
 173
 174
 175 6. Other utilities
 176 ~~~~~~~~~~~~~~~~~~
 177
 178 chkdom          Checks domains for correctness using the 'host' utility
 179                 (check ftp://ftp.nikhef.nl/pub/network for latest version).
 180                 Use chkdom <domain> <NS> to check specific domain or no
 181                 parameters to check all domains mentioned in cf/domains.
 182                 It's even better to use the Sleuth script mentioned in
 183                 the introduction.
 184
 185 convert         A simple perl script for conversion of zone files to NSC
 186                 domain files. Requires the DNS module (available from CPAN at
 187                 ftp.cpan.org).