wip finalise

[chiark-utils.git] / scripts / named-conf.8

diff --git a/scripts/named-conf.8 b/scripts/named-conf.8
index a14765cb9e4cb9b76aa05cea582498930ba860f0..0faae0ae7c0789b47b2f7b92db6013cf3c648db3 100644 (file)
--- a/scripts/named-conf.8
+++ b/scripts/named-conf.8
@@ -58,6 +58,12 @@ and store the results; \-\-mail\-final also sends a mail to the zone
 SOA MNAME or local administrator, if too many of the calls had errors
 or warnings (calls before the most recent \-\-mail\-first being
 ignored).
 SOA MNAME or local administrator, if too many of the calls had errors
 or warnings (calls before the most recent \-\-mail\-first being
 ignored).

+.TP
+.B \-mail\-final\-test
+just like \-\-mail\-final except that it always sends mail to the
+local server admin and never to remote zone contacts, adding
+.B (testing!)
+to the start of the To: field.

 .LP
 Alternatively, one or more zone names may be supplied as arguments, in
 which case their delegations will be checked, and compared with the
 .LP
 Alternatively, one or more zone names may be supplied as arguments, in
 which case their delegations will be checked, and compared with the


@@ -113,6 +119,10 @@ directive specifies the same group, they are all affected.
 directives which don't specify a group cannot be affected.  It is an
 error if the group does not appear in the config file.  See ZONE STYLE
 MODIFIERS, below.
 directives which don't specify a group cannot be affected.  It is an
 error if the group does not appear in the config file.  See ZONE STYLE
 MODIFIERS, below.

+.PP
+The special group
+.B foreign
+is used for zones which don't appear in the configuration file.

 .TP
 .BR \-q | \-\-quiet
 Suppress the usual report of the list of nameservers for each zone and
 .TP
 .BR \-q | \-\-quiet
 Suppress the usual report of the list of nameservers for each zone and


@@ -142,7 +152,9 @@ several physical lines.
 .SS GENERAL DIRECTIVES
 These directives specify general configuration details.  They should
 appear before directives specifying zones, as each will affect only
 .SS GENERAL DIRECTIVES
 These directives specify general configuration details.  They should
 appear before directives specifying zones, as each will affect only

-later zone directives.
+later zone directives.  Foreign zones (zones explicitly specified on
+the command line but not mentioned in the configuration) use the
+configuration settings prevailing at the end of the config file.

 .TP
 \fBadmin\fP \fIemail\-address\fP
 Specifies the email address of the local administrator.  This is used
 .TP
 \fBadmin\fP \fIemail\-address\fP
 Specifies the email address of the local administrator.  This is used


@@ -164,9 +176,15 @@ option is specified.
 Specifies the list of addresses that are forbidden as any nameserver
 for any zone.  The default is no such addresses.
 .TP
 Specifies the list of addresses that are forbidden as any nameserver
 for any zone.  The default is no such addresses.
 .TP

+\fBforbid\-addr\fP [\fIip-address ...\fP]
+Specifies the list of addresses that are forbidden as a nameserver
+for a zone for which we are the primary - ie, the list of our old or
+to-be-obsoleted slaves.  The default is no such addresses.
+.TP

 \fBserverless\-glueless\fP \fIdomain ...\fP
 Specifies a list of domains under which we do not expect to find any
 \fBserverless\-glueless\fP \fIdomain ...\fP
 Specifies a list of domains under which we do not expect to find any

-nameservers; for these zones it is OK to find glueless referrals.
+nameservers without glue; for these zones it is OK to find glueless
+referrals.

 Each domain listed names a complete subtree of the DNS, starting at
 the named point.  The default is
 .BR "in\-addr.arpa ip6.arpa ip6.int" .
 Each domain listed names a complete subtree of the DNS, starting at
 the named point.  The default is
 .BR "in\-addr.arpa ip6.arpa ip6.int" .


@@ -175,8 +193,30 @@ To avoid indefinitely long or even circularly glueless referrals
 (which delay or prevent lookups) it is necessary for all sites to
 effectively implement similar conventions; currently the author
 believes that only the reverse lookup namespaces are conventionally
 (which delay or prevent lookups) it is necessary for all sites to
 effectively implement similar conventions; currently the author
 believes that only the reverse lookup namespaces are conventionally

-devoid of nameservers, and therefore fine to provide glueless
-referrals for.  See GLUELESSNESS below.
+devoid of (glueless) nameservers, and therefore fine to provide
+glueless referrals for.  See GLUELESSNESS below.
+.TP
+\fBallow-\-indirect\-glue\fP \fInameserver-superdomain ...\fP
+Specifies a list of domains under which we expect to find glueless
+nameservers, with up to one layer of indirection.
+For nameservers under these domains it is OK to to find glueless
+referrals, but only when listed as a nameserver for a zone which is
+not itself a subdomain of an \fBallow-indirect-glue\fR
+\fInameserver-superdomain\fR.
+
+This supports to common configuration style where DNS operator(s) set
+up all of their nameservers with names within a small subsection of
+the DNS (the portions under \fInameserver-superdomain\fRs), and
+provide glueless referrals naming these nameservers for all other
+zones.  This provides at most one level of missing glue.
+
+Note that if the DNS administrators collectively able to influence the
+service for some zone (including the admins for its superzones, the
+zones containing its nameservers, and their superzones and so forth)
+are not in sufficiently close communication do not all agree on the
+proper set of \fInameserver-superdomain\fR then they might still set
+up circular glue and \fBchiark-named-conf\fR would not necessarily be
+able to detect this even if it was run on every relevant nameserver.

 .TP
 \fBmail\-state\-dir\fP \fIdirectory\fP
 Uses
 .TP
 \fBmail\-state\-dir\fP \fIdirectory\fP
 Uses


@@ -338,7 +378,7 @@ zone maintainer.
 .B $
 Indicates that any mails should be sent about the zone to the
 nameserver admin rather than to the zone SOA MNAME.  This is the
 .B $
 Indicates that any mails should be sent about the zone to the
 nameserver admin rather than to the zone SOA MNAME.  This is the

-default for stealth zones.
+default unless we are supposedly a published server for the zone.

 .TP
 .B !@
 Indicates that no mails should be sent about the zone to anyone.
 .TP
 .B !@
 Indicates that no mails should be sent about the zone to anyone.


@@ -438,14 +478,13 @@ be necessary to create names for the child's nameservers which are
 underneath the child's apex, so that the glue records are both in the
 parent's bailiwick and obviously necessary.
 
 underneath the child's apex, so that the glue records are both in the
 parent's bailiwick and obviously necessary.
 

-Even worse, the horrid `shared registry system' managing .com, .net
-and .org does not allow a single IPv4 address to be used for more than
-one nameserver name!  It does, however, give out glue for any
-nameserver properly registered in the system.  I therefore recommend
-that you create a single name for your nameserver somewhere
-in .com, .net or .org, and use that for all the delegations
-from .com, .net and .org.  At the time of writing (January 2002) this
-seems to produce correct and glueful referrals.
+In the past, the `shared registry system' managing .com, .net and .org
+did not allow a single IPv4 address to be used for more than one
+nameserver name.  However, at the time of writing (October 2002) this
+problem seems to have been fixed, and the workaround I previously
+recommended (creating a single name for your nameserver somewhere
+in .com, .net or .org, and using that for all the delegations
+from .com, .net and .org) should now be avoided.

 
 Finally, a note about `reverse' zones, such as those in in-addr.arpa:
 It does not seem at all common practice to create nameservers in
 
 Finally, a note about `reverse' zones, such as those in in-addr.arpa:
 It does not seem at all common practice to create nameservers in


@@ -465,6 +504,22 @@ Dan Bernstein has some information and examples about this at
 http://cr.yp.to/djbdns/notes.html#gluelessness
 .UE
 but be warned that it is rather opinionated.
 http://cr.yp.to/djbdns/notes.html#gluelessness
 .UE
 but be warned that it is rather opinionated.

+.SS GLUELESSNESS SUMMARY
+
+I recommend that every nameserver should have its own name in every
+forward zone that it serves.  For example:
+.br
+.B zone.example.com NS servus.ns.example.com
+.br
+.B servus.ns.example.com A 127.0.0.2
+.br
+.B 2.0.0.127.in-addr.arpa PTR servus.example.net
+.br
+.B servus.example.net A 127.0.0.2
+.LP
+Domain names in
+.B in-addr.arpa
+should not be used in the right hand side of NS records.

 .SH SECURITY
 chiark\-named\-conf is supposed to be resistant to malicious data in
 the DNS.  It is not resistant to malicious data in its own options,
 .SH SECURITY
 chiark\-named\-conf is supposed to be resistant to malicious data in
 the DNS.  It is not resistant to malicious data in its own options,


@@ -537,5 +592,5 @@ FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 details.
 
 You should have received a copy of the GNU General Public License along
 details.
 
 You should have received a copy of the GNU General Public License along

-with this program; if not, write to the Free Software Foundation, Inc.,
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+with this program; if not, consult the Free Software Foundation's
+website at www.fsf.org, or the GNU Project website at www.gnu.org.