X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=chiark-utils.git;a=blobdiff_plain;f=scripts%2Fnamed-conf.8;h=a75dd7fb440cf445763c94d915ef92946330579f;hp=450c4c4142e9773f800630876aae49f2ea34936c;hb=f98e8767e057ec623069c0f12ba254ae17ab5ea3;hpb=02b64fd81edc8a7cd109eb9cdecc41eb48501735 diff --git a/scripts/named-conf.8 b/scripts/named-conf.8 index 450c4c4..a75dd7f 100644 --- a/scripts/named-conf.8 +++ b/scripts/named-conf.8 @@ -14,6 +14,13 @@ delegations are appropriate and working, and to generate a configuration for .BR BIND , from its own input file. + +By default, for each zone, in addition to any warnings, the output +lists the zone's configuration type. If the zone is checked, the +serial number at each of the nameservers is shown, with any +unpublished primary having +.B * +after the serial number. .SH OPTIONS .SS MODE OPTIONS @@ -50,7 +57,7 @@ Checks even zones known to be broken. Ie, ignores the .B ? zone style modifier in the configuration. .TP -\fB\-C\fP|\-\-config \fIconfig\-file\fP +.BR \-C | \-\-config " \fIconfig\-file\fP" Use .I config\-file instead of @@ -64,27 +71,8 @@ increase the debugging level. (Maximum is .BR -DD .) .TP .BR \-g | \-\-glueless -Warn only once about a glueless referral for each zone and server, -rather than once for each parent which gave out a referral without -glue. - -When repeated, do not warn about glueless referrals at all. Not -recommended. Note that glueless referrals usually cause extra delays -looking up names, and can make lookups fail even if in theory they -could succeed. There is no generally agreed convention or standard -for avoiding circular glueless situations such as -.br -.B example.com NS ns0.example.net.uk -.br -.B example.com NS ns1.example.net.uk -.br -.B example.net.uk NS ns0.example.com -.br -.B example.net.uk NS ns1.example.com -.br -where gluelessness would completely prevent lookups inside -example.net.uk and example.com. The best way to be sure to avoid this -is to avoid gluelessness. +Do not warn about glueless referrals. Not recommended - see +the section GLUELESSNESS, below. .TP .BR \-l | \-\-local Only checks for mistakes which are the responsibility of the local @@ -97,10 +85,17 @@ with foreign zones (zones supplied explictly on the command line but not relevant to the local server); doing so produces a warning. .TP .BR \-q | \-\-quiet -Do not print any information about zone(s) which do not have warnings. +Suppress the usual report of the list of nameservers for each zone and +the serial number from each. When specified twice, do not print any +information except warnings. +.TP +.BR \-r | \-\-repeat +When a problem is detected, warn for all sources of the same imperfect +data, rather than only the first we come across .TP .BR \-v | \-\-verbose -Print additional information about each zone. +Print additional information about what is being checked, as we go +along. .SH USAGE The file .B /etc/bind/chiark-conf-gen.zones @@ -110,36 +105,15 @@ option) contains a sequence of directives, one per line. Blank lines are permitted. Leading and trailing whitespace on each line is ignored. Comments are lines starting with .BR # . +Ending a line with a +.BR \\ +joins it to the next line, so that long directives can be split across +several physical lines. .SS GENERAL DIRECTIVES These directives specify general configuration details. They should appear before directives specifying zones, as each will affect only later zone directives. .TP -\fBself\-ns\fP \fIfqdn ...\fP -Specifies the list of names that this server may be known by in NS -records. There is no default. -.TP -\fBself\-soa\fP \fIfqdn ...\fP -Specifies the list of names that this server may be known by in -the ORIGIN field of SOA records. There is no default. -.TP -.BI self " fqdn ..." -Equivalent to both -.B self\-ns " and " self\-soa -with the same set of names. -.TP -\fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP] -Specifies the directory in which slave (published and stealth) -zonefiles should be placed. The default -.I directory -is -.BR /var/cache/bind/chiark-slave . -The default -.IR suffix " and " prefix -are empty; they also will be reset to these defaults by a -.B slave\-dir -directive which does not specify them. -.TP \fBdefault\-dir\fP \fIdirectory\fP Makes .I directory @@ -151,6 +125,24 @@ if no .B -C option is specified. .TP +\fBforbid\-addr\fP [\fIip-address ...\fP] +Specifies the list of addresses that are forbidden as any nameserver +for any zone. 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 +nameservers; 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" . + +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 +devoid of nameservers, and therefore fine to provide glueless +referrals for. See GLUELESSNESS below. +.TP \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP] Arranges that each .I filename @@ -172,6 +164,35 @@ otherwise it is an error for there to be any zones in the configuration before the first .B output directive. +.TP +\fBself\-addr\fP \fIip-address ...\fP +Specifies the list of addresses that this server may be known by in +A records. There is no default. +.TP +\fBself\-ns\fP \fIfqdn ...\fP +Specifies the list of names that this server may be known by in NS +records. There is no default. +.TP +\fBself\-soa\fP \fIfqdn ...\fP +Specifies the list of names that this server may be known by in +the ORIGIN field of SOA records. There is no default. +.TP +.BI self " fqdn ..." +Equivalent to both +.B self\-ns " and " self\-soa +with the same set of names. +.TP +\fBslave\-dir\fP \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP] +Specifies the directory in which slave (published and stealth) +zonefiles should be placed. The default +.I directory +is +.BR /var/cache/bind/chiark-slave . +The default +.IR suffix " and " prefix +are empty; they also will be reset to these defaults by a +.B slave\-dir +directive which does not specify them. .SS ZONE DIRECTIVES These directives specify one or more zones. .TP @@ -182,20 +203,34 @@ for and that the zone data is to be found in .IR filename . .TP -.BR primary\-dir [ * | ? "] \fIdirectory\fP [[\fIprefix\fP] \fIsuffix\fP]" +.BR primary\-dir [ * | ? "] \fIdirectory\fP[" / "\fIprefix\fP] [\fIsuffix\fP[" / \fIsubfile\fP]] Search .I directory -for files whose names match the glob pattern -.IR suffix * prefix . -Each such file is taken to represent a zone file for which this server -is supposed to be the primary. * is the name of the zone. The -default for -.I suffix -is -.BR _db ; -the default for +for files whose names start with .I prefix -is empty. +and end with +.IR suffix . +Each such file is taken to represent a zone file for which this server +is supposed to be the primary; the part of the filename between +.IR prefix " and " suffix +is the name of the zone. + +If +.BI / subfile +is specified, then instead of looking for files, we search for +directories containing +.IR subfile ; +directories which do not contain the subfile are simply skipped. + +If +.IR directory [\fB/\fP prefix ] +exists as specified and is a directory then it is interpreted as +.I directory +with an empty prefix; otherwise the final path component is assumed to +be the prefix. If no +.IB suffix / subfile +is specified then the default is +.BR _db . .TP .BR published [ * | ? "] \fIzone origin\-addr\fP" Specifies that this server is supposed to be a published slave @@ -250,15 +285,89 @@ always give the same addresses. Origin server's data: The set of nameservers in the origin server's version of the zone should be a superset of those in the delegations. -Our zone configuration: For -.B primary -zones, the SOA origin should be one of the names specified with -.BR self\-soa " (or " self ). For -.B published -zones, the address should be that of the SOA origin. For -.B stealth -zones, the address should be that of the SOA origin or one of the -published nameservers. +Our zone configuration: For primary zones, the SOA origin should be +one of the names specified with +.BR self\-soa " (or " self ). +For published zones, the address should be that of the SOA origin. +For stealth zones, the address should be that of the SOA origin or one +of the published nameservers. +.SH GLUELESSNESS +Glue is the name given for the addresses of nameservers which are +often supplied in a referral. In fact, it turns out that it is +important for the reliability and performance of the DNS that +referrals, in general, always come with glue. + +Firstly, glueless referrals usually cause extra delays looking up +names. BIND 8, when it receives a completely glueless referral and +does not have the nameservers' addresses in its cache, will start +queries for the nameserver addresses; but it will throw the original +client's question away, so that when these queries arrive, it won't +restart the query from where it left off. This means that the client +won't get its answer until it retries, typically at least 1 second +later - longer if you have more than one nameserver listed. Worse, if +the nameserver to which the glueless referral points is itself under +another glueless referral, another retry will be required. + +Even for better resolvers than BIND 8, long chains of glueless +referrals can cause performance and reliability problems, turning a +simple two or three query exchange into something needing more than a +dozen queries. + +Even worse, one might accidentally create a set of circularly glueless +referrals such as +.br +.B example.com NS ns0.example.net.uk +.br +.B example.com NS ns1.example.net.uk +.br +.B example.net.uk NS ns0.example.com +.br +.B example.net.uk NS ns1.example.com +.br +Here it is impossible to look up anything in either example.com or +example.net.uk. + +There are, as far as the author is aware, no generally agreed +conventions or standards for avoiding unreasonably long glueless +chains, or even circular glueless situations. The only way to +guarantee that things will work properly is therefore to always supply +glue. + +However, the situation is further complicated by the fact that many +implementations (including BIND 8.2.3, and many registry systems), +will refuse to accept glue RRs for delegations in a parent zonefile +unless they are under the parent's zone apex. In these cases it can +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. + +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. + +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 +in-addr.arpa zones (ie, no NS RRs seem to point into in-addr.arpa, +even those for in-addr.arpa zones). Current practice seems to be to +always use nameservers for in-addr.arpa which are in the normal, +forward, address space. If everyone sticks to the rule of always +publishing nameservers names in the `main' part of the namespace, and +publishing glue for them, there is no chance of anything longer than a +1-step glueless chain might occur for a in-addr.arpa zone. It is +probably best to maintain this as the status quo, despite the +performance problem this implies for BIND 8 caches. This is what the +serverless\-glueless directive is for. + +Dan Bernstein has some information and examples about this at +.UR http://cr.yp.to/djbdns/notes.html#gluelessness +http://cr.yp.to/djbdns/notes.html#gluelessness +.UE +but be warned that it is rather opinionated. .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, @@ -304,7 +413,7 @@ will affect the operation of chiark\-named\-conf. Avoid messing with these if possible. .LP .B PATH -Used to find subprograms such as +is used to find subprograms such as .BR dig " and " adnshost . .SH BUGS The determination of the parent zone for each zone to be checked, and