X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=README;h=57379a16960ace7077c20d19a769c017b9f5222f;hb=d3916f203c55db59c5f63f697d4c0c7cc7e004c1;hp=d87e7b5eb03b8937c76303de50d62d840c0abb9a;hpb=4a9bee75de382022678a271192f29bc2206435c4;p=nsc-5.git diff --git a/README b/README index d87e7b5..57379a1 100644 --- a/README +++ b/README @@ -1,37 +1,56 @@ - Domain Name Server Configuration Utilities -- NSC 2.1 + Domain Name Server Configuration Utilities -- NSC 5.0 - (c) 1998 Martin Mares + (c) 1997--2019 Martin Mares ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - NSC is a set of shell and M4 scripts for easy maintenance of all domain name -server files (including configuration and zone 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: There were several incompatible changes between major versions + See NEWS for the summary of changes. +----------------------------------------------------------------------- -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/9.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 ip6.arpa, not A6 and DNAME which seem to be dying out). + + NSC requires GNU m4, GNU Bash, the `md5sum' and `sha1sum' utilities (which +are present for example in GNU coreutils), and utilities distributed with BIND. +Some of the extra utilities require Perl 5. I've tested everything on Linux +(Debian Stretch), 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, version 2 or higher. See file COPYING in any of the +GNU utility archives (you should have one as you are expected to have at least +GNU M4 ;-)). - To use NSC, you need to perform the following steps: + +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 + - Add an include directive to your BIND configuration file (usually + /etc/bind/named.conf), referring to /etc/named/named.conf. + + - Change directory to /etc/named - - CD to /etc/named + - Edit cf/domains to suit your needs -- replace the example domains + by your entries. - - Edit cf/domains and add lines for all domains you want to use (see - the next section for what configuration commands are available). + - Create cf/ for all domains (again, you can easily follow + the example domains). - - Define cf/ for all domains (see section three). + - If you are using BIND 9.x, make the `bak' directory writable + by the bind user. - Run bin/nsconfig (Makefile and named.conf will be generated). @@ -40,137 +59,502 @@ 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, re-run make. If you have + added or removed domains or changed options which affect named.conf, + re-run bin/nsconfig before make. + +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. However, I haven't updated Sleuth +for a long time, so it does not know about DNSSEC yet. + + +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 + tmp/ - temporary files + hash/ - hashes of zone files used for detection of changes + dss/ - DNSSEC DS records + keys// - DNSSEC keys + khash/ - hashes of DNSSEC keys used for detection of changes + + How are different files created: + + - You create everything in cf/. + - Then you run bin/nsconfig. + - If you want to use DNSSEC, create keys (see section 8) + - 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/. + 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. + +DNSSEC(`declarations...') + Request DNSSEC signing for all zones declared within the block. + +DSFOR(zone) + Declare dependency of the previous PRIMARY/REVERSE domain on DS + records for the given zone configured in dss/*. - 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: -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. +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/AAAA 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. + +DS() +DS(dsset) + Include DS records for the current sub-domain. With no arguments, + they are loaded from dss/. If the name of the sub-domain + does not match the name of the DSset (as it frequently happens with + reverse zones), you can specify the DSset name explicitly. + +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 + + 16 CNAME 16.a + 17 CNAME 17.a + 18 CNAME 18.a + a NS ns.xyzzy.org. + + 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. -CONFIG(...) - insert user data to named.conf (e.g., the logging options). + With help of this feature, defining reverse zones can be as easy as: -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. + ; 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. -SLAVE(f1,f2,...) - same as FORWARDers, but asks _only_ these. -MAKEFILE(...) - insert user data to the Makefile. +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. -PRIMARY(zone) - define zone we act as a primary name server for. +To change the setting, use -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. + define(`variable', `value') -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). +As usually, even this config file is a M4 script. Comments can be started by +semicolons, text outside macros is ignored. -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). +The following variables are available: -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). +NAMED_RESTART_CMD Shell command for restarting the name server daemon + (default: rndc reload) +CFDIR Directory with config files (default: cf) -3. The Domain Files +REFRESH SOA record parameters +RETRY +EXPIRE +MINTTL +NSNAME Origin server (default: hostname of your machine) +MAINTNAME Domain maintainer name (default: root@NSNAME) + +KEYGEN_OPTIONS Extra options given to dnssec-keygen + (by default, it selects key type and key size). +SIGNZONE_OPTIONS Extra options given to dnssec-signzone + (by default, it specifies signature validity of 365 days). +DSFROMKEY_OPTIONS Extra options given to dnssec-dsfromkey + (by default, there are none). + +For the timing parameters, the following shortcuts are available: + +HOURS(n) Convert hours to seconds +MINUTES(n) Convert minutes to seconds +DAYS(n) Convert days to seconds + + +5. Makefile targets ~~~~~~~~~~~~~~~~~~~ +The Makefile generated by NSC offers the following targets: + + all (default) - update all zone files and reload the daemon + clean - clean all generated zone files, backups, and hashes + 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). - 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: - - 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). +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. - - nsname: our canonical name (defaults to result of `hostname -f`) +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: - - maintname: zone maintainer name (defaults to 'root@nsname') + 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. -SOA record: + 64/26 NS ns.example.net. - 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. +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: -Subdomains: + 64 PTR sixty-four.example.net. + 65 PTR sixty-five.example.net. + ... + 127 PTR two-to-seven-minus-one.example.net. - 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] +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.). -Hosts: +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: - 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 + REVBLOCK(64/26, 64, 127) - 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 +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. -4. Directory structure -~~~~~~~~~~~~~~~~~~~~~~ +Again for the example above, you need to put the following to cf/domains: - The NSC directory hierarchy contains the following directories: + REVERSE(10.0.0.64/26, ) - 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 +And to cf/64@26.0.0.10: + SOA(REV(10.0.0.64/26)) + NS() + REVERSE(10.0.0, 64, 127) -5. Makefile targets +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
/. - 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) - 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). +Example: + H(ianus, 1.2.3.4, fec0::1234:5678:9abc:def0) -6. Other utilities -~~~~~~~~~~~~~~~~~~ +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. DNSSEC support +~~~~~~~~~~~~~~~~~ +NSC knows the basics of DNSSEC. It does not handle key management (you need to +schedule generation and retirement of your keys by other means), but once the +keys are in place, it uses them for signing zones. + +=== Key management === + +Keys live in keys//*.(key|private) and they are stored in the usual BIND +format. To generate a zone-signing key, you can use the following command after +writing at least rudimentary cf/: + + bin/key-gen + +If you want a key-signing key, use: + + bin/key-gen -f KSK + +(Generally, you can add arbitrary arguments for BIND's dnssec-keygen. Default +keygen options can be set in cf/config, see section 4.) + +To detect key changes, NSC keeps a hash of all keys for each domain. +If you edit the keys manually (e.g., to delete a key), you need to recalculate +the hash by: + + bin/key-update + +(or without a zone to update all hashes). + +=== Domain signing === + +All domains whose declarations in cf/domains are wrapped by DNSSEC(`...') +are automatically signed using all set up keys. If you specify key validity +period when generating the key, it is respected, but the domains are not +re-signed automatically when a key becomes valid / ceases to be. If you +want to modify dnssec-signzone arguments, you can do so in cf/config. + +Beware that all signatures have a limited lifetime (even if the keys do not +expire). The default lifetime is 365 days, so you need to re-sign your zones +at least once in a year. The recommended solution is to set up a cron job, +which touches keys/resign-stamp. A change of timestamp of this file forces +a re-sign on the next run of make. -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. +=== Subdomains === + +If you want to delegate a signed sub-domain, you need to include DS records +in the parent zone. Add a DS() macro after declaration of the sub-domain +in the parent. It loads DS records from dss/. + +If the sub-domain is also maintained by NSC, you can generate the DS record +set automatically by: + + bin/key-delegate + +=== Reverse zones === + +Unlike primary/secondary zones, reverse zones have file names which differ +from the full domain name. In such cases, keys are named after the file name +and NSC constructs the full name whenever necessary. + +There is one exception where automatic construction is not available: +delegation of sub-domain keys. In such cases, you need to pass the file +name of the sub-zone to the DS macro. + + +9. 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 like `this'. + + 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.