.gitignore: Added khash

[nsc-5.git] / README

diff --git a/README b/README
index 09d178118f307a9e74322ea0fda1d0cceb74d563..24dfd7f90c8ba6af74fb335e96ea388b62b90ab4 100644 (file)
--- a/README
+++ b/README
@@ -1,29 +1,29 @@
 
 

-            Domain Name Server Configuration Utilities -- NSC 2.99b
+            Domain Name Server Configuration Utilities -- NSC 4.0

 
 

-                   (c) 1997--2003 Martin Mares <mj@ucw.cz>
+                   (c) 1997--2019 Martin Mares <mj@ucw.cz>

 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 ------------------------------------------------------------------------------------
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 ------------------------------------------------------------------------------------

-WARNING: This is a prerelease of the NSC 3.0. See NEWS for the list of changes.
-Most importantly, the configuration files are NOT compatible with the old releases.
-Also, it hasn't undergone much extensive testing yet, so there might be bugs around.
+WARNING: There were several incompatible changes between versions 3.1 and 4.0.
+         See NEWS for the summary of changes.

 ------------------------------------------------------------------------------------
 
 
    NSC is a set of shell and M4 scripts for easy maintenance of DNS zone files
 ------------------------------------------------------------------------------------
 
 
    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,
+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
 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).
+(AAAA and PTR in ip6.arpa, not A6 and DNAME which seem to be dying out).

 
 

-   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.
+   NSC requires GNU m4, a POSIX-compatible shell and the `md5sum' utility (which
+is present for examile in GNU coreutils). Some of the extra utilities require
+Perl 5. I've tested everything on Linux (Debian Squeeze), 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
 
    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


@@ -37,8 +37,8 @@ GNU General Public License. See file COPYING in any of the GNU utility archives
        - Create a directory where all NSC files will reside (e.g., /etc/named)
          and copy everything from the NSC distribution here.
 
        - Create a directory where all NSC files will reside (e.g., /etc/named)
          and copy everything from the NSC distribution here.
 

-       - 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
+       - 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
 
 
        - Change directory to /etc/named
 


@@ -48,6 +48,9 @@ GNU General Public License. See file COPYING in any of the GNU utility archives
        - Create cf/<domain-name> for all domains (again, you can easily follow
          the example domains).
 
        - Create cf/<domain-name> for all domains (again, you can easily follow
          the example domains).
 

+       - 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).
 
        - Run make.
        - Run bin/nsconfig (Makefile and named.conf will be generated).
 
        - Run make.


@@ -55,7 +58,9 @@ 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 :-)
 
        - Enjoy your new DNS setup. If everything goes OK, be happy. Else
          write a bug report :-)
 

-       - Every time you modify the domain files
+       - 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
 
    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


@@ -78,6 +83,7 @@ files and subdirectories:
        m4/                     - M4 scripts (used by the commands)
        zone/                   - primary zone files
        bak/                    - backups of zones we serve as a secondary NS for
        m4/                     - M4 scripts (used by the commands)
        zone/                   - primary zone files
        bak/                    - backups of zones we serve as a secondary NS for

+       hash/                   - hashes of zone files used for detection of changes

        ver/                    - version files where NSC remembers version
                                  numbers of the primary zones
 
        ver/                    - version files where NSC remembers version
                                  numbers of the primary zones
 


@@ -109,6 +115,9 @@ PRIMARY(zone, [extra-files...])
                concatenated to produce a single configuration). See the next
                section for a look inside these files.
 
                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.
 SECONDARY(zone, primary)
                Define a zone we run a secondary name server for.
                "primary" is an IP address of the primary name server.


@@ -136,9 +145,36 @@ REVERSE(network, primary-files...)
                You can also use the REV macro explicitly, which can be handy
                for example in SECONDARY declarations.
 
                You can also use the REV macro explicitly, which can be handy
                for example in SECONDARY declarations.
 

-CONFIG(...)    - insert user data to named.conf
+ROOTHINT()
+               Insert a definition of hints for reaching root servers into named.conf.
+               This is necessary if you want your DNS server to resolve foreign
+               domains; otherwise, it will only give out authoritative answers
+               for locally defined zones and forward queries. The location of the
+               file with the hints can be set by the ROOTCACHE directive (see below).
+
+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.

 
 

-MAKEFILE(...)  - insert user data to Makefile
+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.

 
 
 3. The Domain Files
 
 
 3. The Domain Files


@@ -180,7 +216,7 @@ H(host)
 
 ADDR(addr...)
                Specify addresses for the current host. In the normal mode, it
 
 ADDR(addr...)
                Specify addresses for the current host. In the normal mode, it

-               creates A records, in the reverse mode, PTR records.
+               creates A/AAAA records, in the reverse mode, PTR records.

 
 H(host, addr...)
                A shortcut for H(host) ADDR(addr...) -- in many cases everything
 
 H(host, addr...)
                A shortcut for H(host) ADDR(addr...) -- in many cases everything


@@ -220,6 +256,18 @@ ALIAS(alias...)
                Generates a series of CNAME records pointing from the aliases
                to the current host/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".
 
 CNAME(src, dest)
                Generate a CNAME record -- "src" points to "dest".
 


@@ -280,13 +328,9 @@ semicolons, text outside macros is ignored.
 The following variables are available:
 
 NAMED_RESTART_CMD      Shell command for restarting the name server daemon
 The following variables are available:
 
 NAMED_RESTART_CMD      Shell command for restarting the name server daemon

-                       (default: ndc restart)
+                       (default: rndc reload)

 
 

-ROOT                   Root directory of the whole package (default: /etc/named)

 CFDIR                  Directory with config files (default: cf)
 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
 
 REFRESH                        SOA record parameters
 ROOTCACHE              File with the cache of root name servers
 
 REFRESH                        SOA record parameters


@@ -296,27 +340,19 @@ MINTTL
 NSNAME                 Origin server (default: hostname of your machine)
 MAINTNAME              Domain maintainer name (default: root@NSNAME)
 
 NSNAME                 Origin server (default: hostname of your machine)
 MAINTNAME              Domain maintainer name (default: root@NSNAME)
 

-BIND_OPTIONS           Extra options to put to the options { ... } section of named.conf
-

 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
 
 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
 

-For the BIND_OPTIONS, we offer:
-
-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 (default)           - update all zone files and reload the daemon
 
 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 and backups
+       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
        clobber                 - clean + delete Makefile and named.conf
                                  (wise to do after major reconfigurations)
        distclean               - clobber + delete all version files (use only


@@ -402,7 +438,17 @@ 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.
 
 
 is not supported. All other syntaxes and quirks hopefully are.
 
 

-8. Interaction with M4
+8. DNSSEC support
+~~~~~~~~~~~~~~~~~
+FIXME: Write real docs!
+
+bin/key-gen example.com
+bin/key-gen -f KSK example.com
+bin/key-update
+keys/resign-stamp
+
+
+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
 ~~~~~~~~~~~~~~~~~~~~~~
 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


@@ -420,7 +466,7 @@ However, there is a couple of things you need to care about:
      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 :-) ),
      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 '.
+     quote it like `this'.

 
   o  Don't use commas, quotes nor parentheses in your record names.
 
 
   o  Don't use commas, quotes nor parentheses in your record names.
 


@@ -437,5 +483,3 @@ 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.
                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.

-
- LocalWords:  MINTTL NSNAME hostname MAINTNAME