README

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