]> mj.ucw.cz Git - nsc-5.git/blob - README
8922bf872a2b77cb586d2c24eb34120e014cdc11
[nsc-5.git] / 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 is either 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're a primary name server for.
71
72 SECONDARY(zone, primary) - define zone we're a secondary name server for.
73                   "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.
78
79                   If you want to delegate a part of your C range to another
80                   name server, use the PARTIAL directive to configure a partial
81                   reverse domain and mention a subzone (e.g., 194.213.32.16+16)
82                   in the main REVERSE directive.
83
84                   The list of name servers authoritative for the reverse zone
85                   is obtained from the _first_ zone specified as an argument,
86                   which must NOT be a subrange specifier (you should use a dummy
87                   zone in case you want only subranges).
88
89 PARTIAL(netprefix, count, primary, sec1, sec2...) - define delegation of a
90                   reverse subzone (see REVERSE above) consisting of <count>
91                   addresses starting at <netprefix>. <primary> is a master
92                   server for that subzone, <sec1> ... <secn> are secondaries
93                   (don't list the local name-server, it's always expected to
94                   be a secondary).
95
96 PREVERSE(netprefix, zone1, zone2...) - analogon of REVERSE for partial zones
97                   (to be used when you want to export a subzone to another
98                   server which is configured by PARTIAL). Just use a 4-component
99                   netprefix.
100
101 You can also change several predefined macros:
102
103         - named_restart_cmd: command used to restart named (default: `ndc reload')
104
105
106 3. The Domain Files
107 ~~~~~~~~~~~~~~~~~~~
108
109    The domain files contain descriptions of all DNS records for the given
110 domain, starting with the SOA record. As these files are processed by the M4,
111 you can simply insert plain RR data between the macro calls (such data are
112 ignored if we're generating a reverse zone) and define your own macros at the
113 beginning. The standard macros you can redefine are:
114
115         - refresh, retry, expire, minttl: standard SOA timing parameters (you
116           can specify them as number of seconds or using predefined time macros
117           as minutes(N), hours(N) and days(N).
118
119         - nsname: our canonical name (defaults to result of `hostname -f`)
120
121         - maintname: zone maintainer name (defaults to 'root@nsname')
122
123 SOA record:
124
125         SOA(domainname)         - generates the SOA itself (serial numbers are
126                                   created automagically from current data and
127                                   version counter stored in a separate file)
128         NS(ns1,ns2,...)         - generates list of authoritative NS's
129         MX(pri1 mx1, ...)       - [optional] - generates list of mail exchangers
130                                   for mail addressed directly to the domain
131                                   name. Each MX is preceeded by its priority.
132
133 Subdomains:
134
135         D(name)                 - remembers domain name for further macros
136         NS(ns1,ns2,...)         - generates list of authoritative NS's
137                                   [you might need to insert glue A records
138                                    manually]
139
140 Hosts:
141
142         H(name,list-of-ip-addrs) - define new host with given IP addresses
143         HI(hw,os)               - define HINFO record
144         MX(pri1 mx1, ...)       - define mail exchangers for that host
145         ALIAS(al1, al2,...)     - define aliases for that host
146
147         HH(name)                - define dummy host without any addresses
148                                   (e.g., only for mail)
149         RH(name,list-of-ip-addrs) - define out-of-domain host appearing only
150                                   in the reverse zone
151
152
153 4. Directory structure
154 ~~~~~~~~~~~~~~~~~~~~~~
155
156    The NSC directory hierarchy contains the following directories:
157
158         bak/                    - backups of zones we're a secondary for
159         bin/                    - scripts (e.g., nsconfig)
160         cf/                     - configuration files (domains etc.)
161         m4/                     - M4 scripts
162         ver/                    - version files where NSC remembers version
163                                   numbers for the zones
164         zone/                   - primary zone files
165
166
167 5. Makefile targets
168 ~~~~~~~~~~~~~~~~~~~
169
170         all                     - update all files and restart named
171         clean                   - clean all normal data files
172         clobber                 - clean + delete Makefile and named.conf (should
173                                   be done after major reconfiguration)
174         distclean               - clobber + delete all version files (use only
175                                   if you really know what you are doing as the
176                                   serial number information in newly generated
177                                   files might be inconsistent then).
178
179
180 6. Other utilities
181 ~~~~~~~~~~~~~~~~~~
182
183 chkdom          Checks domains for correctness using the 'host' utility
184                 (check ftp://ftp.nikhef.nl/pub/network for latest version).
185                 Use chkdom <domain> <NS> to check specific domain or no
186                 parameters to check all domains mentioned in cf/domains.
187                 It's even better to use the Sleuth script mentioned in
188                 the introduction.
189
190 convert         A simple perl script for conversion of zone files to NSC
191                 domain files. Requires the DNS module (available from CPAN at
192                 ftp.cpan.org).