[web-team] NSD documentation

[Rick Moen]

We have stuff as ASCII files in the site-docs folder on www.svlug.org .
The overall intention is supposed to be:  Process documentation
_generally_ ought to live in our public Web space instead of in
site-docs, so that everyone can see it, not just people with shell
accounts.  Exceptions should be files with confidential inforamation
(e.g., passwords) and coverage of pass fsckups for core volunteers to
learn from without nagging the guilty parties in public for no reason.

What follows is site-docs/nsd-instructions, mostly for Josef's benefit.
I've subbed in '[redacted]' in part of the third section (one of those
'let's not fsck up this way again' sections) -- and again for some 
contact information in section two.



Contents:
I.   NSD Software
II.  How and with Whom SVLUG Has Its DNS
III. Domain administration



I.  NSD Software

NSD is an authoritative-only DNS nameserver written from scratch by the
people who run the .nl (Netherlands) top-level domain.  It does not
provide recursive service, so the machine on which it runs needs to have
access to a full-service nameserver somewhere, via reference in
/etc/resolv.conf.

NSD's advantages are high speed, small RAM footprint, and high security.
It does support IXFR/AXFR zone transfers, and thus is fully usable for
both master and slave DNS service.

Although it uses the same zonefile format that BIND8/BIND9 does (RFC
1034 zonefile format), it achieves much higher performance, in part by
using a hashed binary database.  Accordingly, whenever you modify one of
its zonefiles, you must "compile" it by doing "nsdc rebuild'.

Runtime control of NSD is best asserted using the "nsdc" utility, syntax
and features modeled on those of BIND's "rndc".


NSD's main configuration file is /etc/nsd3/nsd.conf, describing
one zone per "zone:" stanza (paragraph), with directives that differ
depending on whether ns1.svlug.org is a master or slave for that zone.
For master-role zones, keyword "notify:" specifies which (slave) IPs will
be sent NOTIFY data when the master zone changes.  Keyword "provide-xfr:"
specifies which (slave) IPs are permitted to pull zone AXFR/IXFR zone
transfers.  (Normally those will be the same IPs.)

For slave-role zones, keyword "allow-notify:" specifies which (master)
IP ns1.svlug.org will accept NOTIFY data from.  Keyword "request-xfr:"
specifies which (master) IP ns1.svlug.org will request AXFR/IXFR data
from.

Standard locations for zonefiles are subdirectories "/etc/nsd3/primary"
and "/etc/nsd3/secondary".

Your maintenance sequence will typically be like this:

1.  "cd /etc/nsd3/primary"
2.  Edit svlug.org.zone or whatever in your choice of text editor.  Don't
    forget to increment the S/N value!
3.  "cd .."  Check nsd.conf if you fooled with it.
4.  "nsdc rebuild"  This compiles the zone revision to binary file nsd.db .
    "nsd-patch" makes the on-disk ASCII zonefiles.
5.  "nsdc reload"  This makes NSD re-parse /etc/nsd3/nsd.conf and the
    compiled zone data.
6.  Check your work, by doing "dig -t a www.svlug.org @ns1.svlug.org".
    (Substitute an appropriate reference record for "-t a www.svlug.org"
    to reflect whatever you worked on.)  It's a good idea to at least
    run "dig -t soa svlug.org @ns1.svlug.org" to verify that your S/N
    update is reflected in actual DNS return values.

In fact:
To verify master nameserver functionality:
dig  svlug.org  @64.62.190.98 +short
dig  svlug.net  @64.62.190.98 +short
dig  svlug.com  @64.62.190.98 +short

To verify each volunteer secondary nameserver's functionality:
dig  svlug.org  @198.144.194.12 +short
dig  svlug.net  @198.144.194.12 +short
dig  svlug.com  @198.144.194.12 +short
dig  svlug.org  @198.144.195.186 +short
dig  svlug.net  @198.144.195.186 +short
dig  svlug.com  @198.144.195.186 +short
dig  svlug.org  @69.31.83.184 +short
dig  svlug.net  @69.31.83.184 +short
dig  svlug.com  @69.31.83.184 +short

7.  If you ever wish to force an immediate notify, do "nsdc notify".
    Incoming NOTIFYs are processed daily by cronjob /etc/cron.d/nsd3 ,
    which implemtents import to ASCII zonefiles using "nsdc patch".
8.  "nsdc update" will make nsd pull down zone transfer data for all
    slave-role zones from their various masters.
9.  If all else fails, "nsdc restart" will relaunch nsd completely.
    (At this writing, you need to do "nsdc stop", then "nsdc start".)


Further info:
https://calomel.org/nsd_dns.html

Beware: many NSD articles are obsolete and misleading,
having been written for pre-3.0 NSD versions, e.g.
http://www.linux.com/archive/feature/46016





II.  How and with Whom SVLUG Has Its DNS

SVLUG owns domains svlug.org, svlug.net, and svlug.com.  (To date,
svlug.org is the only one advertised, and the others point to its
contents.)

Primary (master) DNS for the three domains is run at this Linode host,
using FQDN ns1.svlug.org (IP 64.62.190.98).  Slave nameservers are
offered by members Rick Moen (ns1.linuxmafia.com, IP 198.144.195.186),
and Aaron T. Porter (ns.primate.net, IP 198.144.194.12)

We formerly had slave nameservice from New York Linux User Group's
ns1.nylug.org, IP 66.114.81.152.  It was decommissioned May 2013.

Contact information:
Aaron T. Porter [e-mail and telephone number redacted]
Rick Moen <rick at linuxmafia.com>, 650-283-7902
Tony Marchesano (of NYLUG) [e-mail and telephone number redacted]

SVLUG's master nameserver ns1.svlug.org (Linode host) also does
secondary (slave) DNS for five domains owned by two of Rick Moen's
friends, as a favour.  Any questions, ask Rick (650-283-7902 cell).
(There's no reason we shouldn't do this to be nice to people.  It's
incredibly easy and costs very little traffic, processing time, etc.
E.g., we did nameservice for two of Paul Reiber's personal domains for a
very long time, until in 2010 he moved his authoritative service
elsewhere without bothering to tell us.)





III.  Domain administration

All three domains are currently (still) registered at joker.com.
Credentials for the domains are stored in /root on the Linode box.
Do not abuse that credential, or the wrath of SVLUG's volunteers will
be upon you, and we're not kidding.

(2015 update:  svlug.net expired on Dec. 28, 2014.  Fortunately, we
weren't actually using it for content.  It should become available
again, to the first comer, around March 13, 2015.)

It's really vital that all domain contact information (Registrant,
Technical Contact, Administrative Contact, Billing Contact) be valid,
deliverable e-mail addresses of real people who read their mail.
This should be checked occasionally.  Seriously.  We nearly lost
svlug.org because one-time domain holder [redacted] chose to ignore
Rick Moen's warnings about single points of failure (SPoFs) and declared
_all_ the domain contacts to be aliases on her starshine.org machine,
and then screwed up its aliases database during a machine rebuild without
realising it.  The consequence was that all of Joker.com's renewal
notices were undeliverable.

Fortunately, Rick Moen anticipated this debacle and was independently
monitoring pending domain expirations.  He paid the renewal out of
pocket just before the domain would have expired.  You can and should
consider _also_ using his preferred tool for such monitoring, the
domain-check Perl script.  See:
http://linuxmafia.com/~rick/preventing-expiration.html
http://linuxmafia.com/pub/linux/network/

Making sure _somebody_ pays the renewal money continues to be a problem.
Lately, Andrew Fife and Rick Moen have been picking up the expense.  In
past years, it's been at different times VA Research Corporation / VA
Linux Systems Inc., Drew Bertola, Ian Kluft, Heather Stern, and Don
Marti.

Important:  Any nameserver we use for our authoritative DNS has to be
cited _both_ in the domain zonefile's NS lines _and_ in the registry's
authoritative list for that domain.  Don't make the common error or
having stealth or lame nameservers by omitting one or the other!
The zonefile 'NS' roster should be cross-checked against the whois
nameserver roster periodically to verify that they match as they should.
And basically, if you're inexperienced with domain administration (or
with DNS), ask for a helping hand from our other volunteers.