freebsd-dev/contrib/bind/doc/misc/style.txt

Path: vixie!vixie
From: vixie@vix.com (Paul A Vixie)
Newsgroups: comp.protocols.tcp-ip.domains
Subject: Re: Format of DNS files (style question)
Date: 28 Aug 94 03:17:08
Organization: Vixie Enterprises
Lines: 159
Distribution: inet
Message-ID: <VIXIE.94Aug28031708@office.home.vix.com>
References: <33onnr$i4u@zombie.ncsc.mil>
NNTP-Posting-Host: office.home.vix.com
In-reply-to: sjr@zombie.ncsc.mil's message of 27 Aug 1994 21:02:51 -0400

> (Style) Suggestions for how to layout DNS configuration files (both
> forward and reverse)?

I've gone back and forth on the question of whether the BOG should include a
section on this topic.  I know what I myself prefer, but I'm wary of ramming
my own stylistic preferences down the throat of every BOG reader.  But since
you ask :-)...

Create /var/named.  If your system is too old to have a /var, either create
one or use /usr/local/adm/named instead.  Put your named.boot in it, and make
/etc/named.boot a symlink to it.  If your system doesn't have symlinks, you're
S-O-L (but you knew that).  In named.boot, put a "directory" directive that
specifies your actual BIND working directory:

	directory	/var/named

All relative pathnames used in "primary", "secondary", and "cache" directives
will be evaluated relative to this directory.  Create two subdirectories,
/var/named/pri and /var/named/sec.  Whenever you add a "primary" directive
to your named.boot, use "pri/WHATEVER" as the path name.  And then put the
primary zone file into "pri/WHATEVER".  Likewise when you add "secondary"
directives, use "sec/WHATEVER" and BIND (really named-xfer) will create the
files in that subdirectory.

(Variations: (1) make a midlevel directory "zones" and put "pri" and "sec"
into it; (2) if you tend to pick up a lot of secondaries from a few hosts,
group them together in their own subdirectories -- something like
/var/named/zones/uucp if you're a UUCP Project name server.)

For your forward files, name them after the zone.  dec.com becomes
"/var/named/zones/pri/dec.com".  For your reverse files, name them after the
network number.  0.1.16.in-addr.arpa becomes "/var/named/zones/pri/16.1.0".

When creating or maintaining primary zone files, try to use the same SOA
values everywhere, except for the serial number which varies per zone.  Put
a $ORIGIN directive at the top of the primary zone file, not because it's
needed (it's not since the default origin is the zone named in the "primary"
directive) but because it make it easier to remember what you're working on
when you have a lot of primary zones.  Put some comments up there indicating
contact information for the real owner if you're proxying.  Use RCS and put
the "$Id: style.txt,v 8.1 1995/12/22 21:59:52 vixie Exp $" in a ";" comment near the top of the zone file.

The SOA and other top level information should all be listed together.  But
don't put IN on every line, it defaults nicely.  For example:

==============
@	IN	SOA	gw.home.vix.com. postmaster.vix.com. (
			1994082501      ; serial
                        3600    ; refresh (1 hour)
                        1800    ; retry (30 mins)
                        604800  ; expire (7 days)
                        3600 )  ; minimum (1 hour)

		NS	gw.home.vix.com.
		NS	ns.uu.net.
		NS	uucp-gw-1.pa.dec.com.
		NS	uucp-gw-2.pa.dec.com.

		MX	10 gw.home.vix.com.
		MX	20 uucp-gw-1.pa.dec.com.
		MX	20 uucp-gw-1.pa.dec.com.
==============

I don't necessarily recommend those SOA values.  Not every zone is as volatile
as the example shown.  I do recommend that serial number format; it's in date
format with a 2-digit per-day revision number.  This format will last us until
2147 A.D. at which point I expect a better solution will have been found :-).
(Note that it would last until 4294 A.D. except that there are some old BINDs
out there that use a signed quantity for representing serial number interally;
I suppose that as long as none of these are still running after 2047 A.D.,
that we can use the above serial number format until 4294 A.D., at which point
a better solution will HAVE to be found.)

You'll note that I use a tab stop for "IN" even though I never again specify
it.  This leaves room for names longer than 7 bytes without messing up the
columns.  You might also note that I've put the MX priority and destination
in the same tab stop; this is because both are part of the RRdata and both 
are very different from MX which is an RRtype.  Some folks seem to prefer to
group "MX" and the priority together in one tab stop.  While this looks neat
it's very confusing to newcomers and for them it violates the law of least
astonishment.

If you have a multi-level zone (one which contains names that have dots in
them), you can use additional $ORIGIN statements but I recommend against it
since there is no "back" operator.  That is, given the above example you can
add:

=============
$ORIGIN home
gw		A	192.5.5.1
=============

The problem with this is that subsequent RR's had better be somewhere under
the "home.vix.com" name or else the $ORIGIN that introduces them will have
to use a fully qualified name.  FQDN $ORIGIN's aren't bad and I won't be mad
if you use them.  Unqualified ones as shown above are real trouble.  I usually
stay away from them and just put the whole name in:

=============
gw.home		A	192.5.5.1
=============

In your reverse zones, you're usually in some good luck because the owner name
is usually a single short token or sometimes two.

=============
$ORIGIN 5.5.192.in-addr.arpa.
@	IN	SOA	...
		NS	...
1		PTR	gw.home.vix.com.
-------------
$ORIGIN 1.16.in-addr.arpa.
@	IN	SOA	...
		NS	...
2.0		PTR	gatekeeper.dec.com.
=============

It is usually pretty hard to keep your forward and reverse zones in synch.
You can avoid that whole problem by just using "h2n" (see the ORA book, DNS
and BIND, and its sample toolkit, included in the BIND distribution or on
ftp.uu.net (use the QUOTE SITE EXEC INDEX command there to find this -- I
never can remember where it's at).  "h2n" and many tools like it can just
read your old /etc/hosts file and churn it into DNS zone files.  (May I
recommend contrib/decwrl/mkdb.pl from the BIND distribution?)  However, if
you (like me) prefer to edit these things by hand, you need to follow the
simple convention of making all of your holes consistent.  If you use
192.5.5.1 and 192.5.5.3 but not (yet) 192.5.5.2, then in your forward file
you will have something like

=============
...
gw.home		A	192.5.5.1
;avail		A	192.5.5.2
pc.home		A	192.5.5.3
=============

and in your reverse file you will have something like

=============
...
1		PTR	gw.home.vix.com.
;2		PTR	avail
3		PTR	pc.home.vix.com.
=============

This convention will allow you to keep your sanity and make fewer errors.
Any kind of automation (h2n, mkdb, or your own perl/tcl/awk/python tools)
will help you maintain a consistent universe even if it's also a complex
one.  Editing by hand doesn't have to be deadly but you MUST take care.

Anyone who wants to know how to maintain nonleaf zones, i.e., zones which
have few or no hosts in them but have hundreds or thousands of delegations,
should attend Usenix LISA in San Diego and be there for the SENDS talk.
Contact office@usenix.org for conference information.
--
Paul Vixie
Redwood City, CA
decwrl!vixie!paul
<paul@vix.com>