X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;ds=sidebyside;f=README;h=776108e27e072117b7cbadd9f2c82edf486800f7;hb=41302bf2517bf92a9d402a01f1265744f6d646a8;hp=4f6aeb03428f8ad271937c049fbf073ba29fb239;hpb=ded4fe1add43222e47f4105aac673428c60c4f2e;p=nsc-5.git diff --git a/README b/README index 4f6aeb0..776108e 100644 --- a/README +++ b/README @@ -1,36 +1,52 @@ - Domain Name Server Configuration Utilities -- NSC 2.1 + Domain Name Server Configuration Utilities -- NSC 3.1 - (c) 1998 Martin Mares + (c) 1997--2008 Martin Mares ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - NSC is a set of shell and M4 scripts for easy maintenance of all domain name -server 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 -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 :-]). +------------------------------------------------------------------------------------ +WARNING: NSC has undergone significant changes between versions 2.3 and 2.99b. +See NEWS for the summary of changes. Most importantly, the configuration files are +NOT compatible with the old releases. +------------------------------------------------------------------------------------ -1. Getting Started -~~~~~~~~~~~~~~~~~~ + 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). - To use NSC, you need to perform the following steps: + 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 ;-)). + + +0. 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/ for all domains (see section three). + - Create cf/ for all domains (again, you can easily follow + the example domains). - Run bin/nsconfig (Makefile and named.conf will be generated). @@ -39,137 +55,420 @@ GNU General Public License. See file COPYING in any of the GNU utility archives - Enjoy your new DNS setup. If everything goes OK, be happy. Else write a bug report :-) + - Every time you modify the domain files -2. The Domain List File -~~~~~~~~~~~~~~~~~~~~~~~ - - The domain list contains configuration commands describing all domains the -server should act as primary or secondary for and also some other parameters -which get inserted to named.conf and to the Makefile: + 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. -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. -CONFIG(...) - insert user data to named.conf (e.g., the logging options). +1. 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 2) + cf/config - global settings (see Section 3) + cf/ - 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 -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. + How are different files created: -SLAVE(f1,f2,...) - same as FORWARDers, but asks _only_ these. + - 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/. -MAKEFILE(...) - insert user data to the Makefile. -PRIMARY(zone) - define zone we act as a primary name server for. +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 8 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/ + 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. + + When the zone name contains a slash (as happens in classless + reverse zones), it is replaced by "@" in the cf file name. + +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/ 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/ 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. + +FORWARDED(zone, ip...) + Define a forwarding zone. All queries are forwarded to the + specified name servers. + +BLACKHOLE(zone) + Define an empty zone according to RFC 6303. This is usually done + for zones for which clients are known to erroneously ask queries + (e.g., reverse resolving of link-local addresses). The contents + served for these zones is taken from cf/blackhole. + +ZONE_OPTIONS(`options; + more options; +') + Define options to be inserted to all subsequent zone declarations + until the next ZONE_OPTIONS command. Please keep in mind that the + semicolon character act as M4 comment, so you need to put the + closing quote at a separate line. See our example cf/domains. + +CONFIG(...) + Insert user data to named.conf, again beware of semicolons. + +MAKEFILE(...) + Insert user data to Makefile. -SECONDARY(zone, primary) - define zone we act as a secondary name server - for. "primary" is an IP address of the primary NS for this - zone. -REVERSE(netprefix, zone1, zone2...) - define reverse zone containing all hosts - from given zones starting with given netprefix. If you want - to delegate some subrange of addresses to another name server - (as defined by RFC XXXX), you need to use netprefix+count - instead of zone name (e.g., 194.213.32.16+16) -- this - generates correct CNAME glue records for the subrange. - The list of name servers authoritative for the reverse zone - is obtained from the _first_ zone specified as an argument, - which must NOTbe a subrange specifier (you should use a dummy - zone in case you want only subranges). +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. + +All host or domain names are either names relative to the current domain +with no dots inside or absolute names (in this case, NSC automatically +ensures that the trailing dot is present in the resource records). Relative +names with dots are not supported, but they are rare and you can always write +them as absolute anyway. + +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 sub-domain (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 suppresses 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 sub-domain. 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 sub-domain + 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. + +TXT(text) + Specify a TXT record for the current host or domain. + +RP(mail, txt) + Specify a RP (responsible person) record for the current host or domain. + The first argument is a mail address in DNS notation (with `@' replaced + by `.' as in the SOA record), the second one is a name of a TXT record + with contact information. + +SRV(service, protocol, priority, weight, port, target) + Specify a SRV (service) record for the current host or 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 sub-domain, finally + declaring the sub-domain as well, so you can continue with its + NS records. + + Example: REVBLOCK(a, 16, 18) NS(ns.xyzzy.org) yields -PARTIAL(netprefix, count, primary, sec1, sec2...) - define delegation of a - reverse subzone (see REVERSE above) consisting of - addresses starting at . is a master - server for that subzone, ... are secondaries - (except our name-server which is _always_ expected to be - a secondary). + 16 CNAME 16.a + 17 CNAME 17.a + 18 CNAME 18.a + a NS ns.xyzzy.org. -PREVERSE(netprefix, zone1, zone2...) - define reverse zone for a subrange - -- used when we want to export a subzone (to be imported - by the master server for the corresponding parent zone - by a mechanism similar to that specified by the PARTIAL - command). + This is a very common construct for classless reverse delegations, + see Section 6 for more details. +REVERSE(network) + Switch to reverse mode. From this point on, all output is suppressed + except for ADDR declarations belonging to the specified network which + are automatically converted to PTR records. -3. The Domain Files -~~~~~~~~~~~~~~~~~~~ + With help of this feature, defining reverse zones can be as easy as: - 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: + ; 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. - - 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). - - nsname: our canonical name (defaults to result of `hostname -f`) +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 overridden +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. - - maintname: zone maintainer name (defaults to 'root@nsname') +To change the setting, use -SOA record: + define(`variable', `value') - 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. +As usually, even this config file is a M4 script. Comments can be started by +semicolons, text outside macros is ignored. -Subdomains: +The following variables are available: - 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] +NAMED_RESTART_CMD Shell command for restarting the name server daemon + (default: ndc restart) -Hosts: +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 name servers - 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 +REFRESH SOA record parameters +RETRY +EXPIRE +MINTTL +NSNAME Origin server (default: hostname of your machine) +MAINTNAME Domain maintainer name (default: root@NSNAME) - 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 +BIND_OPTIONS Extra options to put to the options { ... } section of named.conf +For the timing parameters, the following shortcuts are available: -4. Directory structure -~~~~~~~~~~~~~~~~~~~~~~ +HOURS(n) Convert hours to seconds +MINUTES(n) Convert minutes to seconds +DAYS(n) Convert days to seconds - The NSC directory hierarchy contains the following directories: +For the BIND_OPTIONS, we offer: - bak/ - backups of zones we act as 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 +FORWARD(ip...) Try to ask the given name servers first to see if they + have the reply cached. +SLAVE(ip...) Pass all non-local requests to the given name servers. 5. Makefile targets ~~~~~~~~~~~~~~~~~~~ +The Makefile generated by NSC offers the following 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) + 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). -6. Other utilities -~~~~~~~~~~~~~~~~~~ +6. Classless reverse delegations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +NSC also supports classless delegations for reverse zones using the mechanism +described in RFC 2317, i.e. by putting CNAME records to the reverse zone which +point to records of the same name in a sub-domain which you can delegate directly. + +For example if you want to delegate 64-127 in 0.0.10.in-addr.arpa to ns.example.net, +you create a 64/26 sub-domain (26 is the network prefix length) and add the following +records to 0.0.10.in-addr.arpa: + + 64 CNAME 64.64/26.0.0.10.in-addr.arpa. + 65 CNAME 65.64/26.0.0.10.in-addr.arpa. + ... + 127 CNAME 127.64/26.0.0.10.in-addr.arpa. + + 64/26 NS ns.example.net. + +Then you configure ns.example.net to be a primary name server for the zone +64/26.0.0.10.in-addr.arpa and put the PTR records there: + + 64 PTR sixty-four.example.net. + 65 PTR sixty-five.example.net. + ... + 127 PTR two-to-seven-minus-one.example.net. -chkdom Checks domains for correctness using the 'host' utility - (check ftp://ftp.nikhef.nl/pub/network for latest version). - Use chkdom to check specific domain or no - parameters to check all domains mentioned in cf/domains. +NSC offers special primitives for configuring such delegations, but not limited +to the sub-domain name syntax shown above (which is recommended by the RFC, but it's +far from being the only one used in the real world, other possibilities being for +example 64-127, 64+64 etc.). + +The CNAME block can be generated by the REVBLOCK(subdomain-name, low-addr, high-addr) +directive in the configuration of the whole reverse zone. The example above would +be written as: + + REVBLOCK(64/26, 64, 127) + +The sub-zone can be created automatically like any another reverse zone, you only +need to use the three-parameter form of the REVERSE directive to specify the +address range in order to filter out possible hosts falling outside your range. + +CAVEAT: The slashes in zone names are automatically translated to @'s when forming +file names. + +Again for the example above, you need to put the following to cf/domains: + + REVERSE(10.0.0.64/26, ) + +And to cf/64@26.0.0.10: + + SOA(REV(10.0.0.64/26)) + NS() + REVERSE(10.0.0, 64, 127) + +NOTE: It's usually helpful to configure the primary name server for the parent +domain (i.e., the one where you configure the delegation and create the CNAME's) +as a secondary for the sub-zone as well, so if it replies with the CNAME, it will +include the PTR record pointed to by the CNAME in the additional section of its +reply, eliminating the need for an extra query. + + +7. Support for IPv6 +~~~~~~~~~~~~~~~~~~~ +NSC also supports IPv6 in a pretty straightforward form: wherever you can write +an IPv4 address, you can use an IPv6 address as well. Incomplete IP addresses +or ranges used for specifying address blocks for reverse delegations are replaced +by network prefixes of the standard form
/. + +Example: + + H(ianus, 1.2.3.4, fec0::1234:5678:9abc:def0) + +specifies a dual-stack host with both an A record and an AAAA record. + +CAVEAT: The backward-compatible IPv6 address syntax with ":v.w.x.y" at the end +is not supported. All other syntaxes and quirks hopefully are. + + +8. Interaction with M4 +~~~~~~~~~~~~~~~~~~~~~~ +All config files are fully-fledged M4 scripts, so you can use any M4 features +you need, the most helpful one being definition of your own macros by + + define(`macro_name', `expansion') + +However, there is a couple of things you need to care about: + + o The comment character is redefined to `;'. I.e., wherever a semicolon + occurs, the rest of the line is a comment which is copied verbatim + to the output file (if the output is not suppressed like in case + of the cf/domains file). + + o Names starting with 'nsc_' or spelled in all caps are reserved + for the NSC itself and unless documented, messing with them can + bring surprising results. If you need to use such a name in your + zone file (maybe you like to shout in your host names :-) ), + quote it with ` and '. + + o Don't use commas, quotes nor parentheses in your record names. + + +9. Other utilities +~~~~~~~~~~~~~~~~~~ +convert A simple Perl script for conversion of zone files to NSC + domain files. Requires the Net::DNS module (available from + CPAN at ftp.cpan.org; present in recent versions of Perl). + Keep in mind that the script is very simple and its craft + is of a very limited kind, so check its output carefully. + +chkdel A simple Perl script for checking of domain delegations -- + it checks all PRIMARY and SECONDARY records in cf/domains + against NS records. Requires the Net::DNS module and also + some tweaking of parameters at the top of the script.