README

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