X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=scripts%2Fnamed-conf.8;h=2316c9de9fe479189344ebe621902d343cea1d3b;hb=b3f3d259857a51c3df303c44276457cad8d99d07;hp=4b41c02255bf24109d3d5685c80766ff58d21913;hpb=550082aef29cc19cd6bdc3722da865e4b074c23e;p=chiark-utils.git diff --git a/scripts/named-conf.8 b/scripts/named-conf.8 index 4b41c02..2316c9d 100644 --- a/scripts/named-conf.8 +++ b/scripts/named-conf.8 @@ -45,34 +45,29 @@ no new configuration file for the nameserver will be made. .SS ADDITIONAL OPTIONS .TP -\fB\-C\fP|\-\-config \fIconfig\-file\fP +.BR \-A | \-\-all +Checks even zones known to be broken. Ie, ignores the +.B ? +zone style modifier in the configuration. +.TP +.BR \-C | \-\-config " \fIconfig\-file\fP" Use .I config\-file instead of .BR /etc/bind/chiark-conf-gen.zones . +Also changes the default directory. .TP -.BR \-q | \-\-quiet -Do not print any information about zone(s) which do not have warnings. -.TP -.BR \-l | \-\-local -Only checks for mistakes which are the responsibility of the local -administrator. This means that for secondary and stealth zones we -only check that we're slaving from the right place. For primary zones -all checks are still done, unless the -.B \-l -option is repeated. It is a mistake to specify -.B \-l -with foreign zones (zones supplied explictly on the command line but -not relevant to the local server), so this counts as a warning. -.TP -.BR \-v | \-\-verbose -Print additional information about each zone. +.BR \-D +Enables debugging. Useful for debugging chiark\-named\-conf, but +probably not useful for debugging your DNS configuration. Repeat to +increase the debugging level. (Maximum is +.BR -DD .) .TP -.BR \-g | \-\-glueless-ok +.BR \-g | \-\-glueless Do not warn about glueless referrals. Not recommended. Note that -glueless referrals usually causes extra delays looking up names, and -can cause lookups to fail even if in theory they could succeed. There -is no generally agreed convention or standard for avoiding circular +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 @@ -87,9 +82,25 @@ 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. .TP -.BR \-D -Enables debugging. Useful for debugging chiark\-named\-conf, but -probably not useful for debugging your DNS configuration. +.BR \-l | \-\-local +Only checks for mistakes which are the responsibility of the local +administrator (to fix or get fixed). This means that for published +and stealth zones we only check that we're slaving from the right +place and that any names and addresses for ourself are right. For +primary zones all checks are still done. It is a mistake to specify +.B \-l +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. +.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. .SH USAGE The file .B /etc/bind/chiark-conf-gen.zones @@ -99,36 +110,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 (secondary 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 @@ -140,6 +130,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. +.TP \fBoutput\fP \fIformat\fP \fIfilename\fP [\fIformat\fP \fIfilename ...\fP] Arranges that each .I filename @@ -161,38 +169,98 @@ 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 -\fBprimary\fP \fIzone\fP \fIfilename\fP +.BR primary [ * | ? "] \fIzone filename\fP" Specifies that this server is supposed to be the primary nameserver for .I zone and that the zone data is to be found in .IR filename . .TP -\fBprimary-dir\fP \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 -\fBsecondary\fP \fIzone\fP \fIorigin\-addr\fP -Specifies that this server is supposed to be a published secondary for -the zone in question. +.BR published [ * | ? "] \fIzone origin\-addr\fP" +Specifies that this server is supposed to be a published slave +nameserver for the zone in question. .TP -\fBstealth\fP \fIzone\fP \fIserver\-addr ...\fP +.BR stealth [ * | ? "] \fIzone server\-addr ...\fP" Specifies that this server is supposed to be an unpublished secondary (aka stealth secondary) for the zone in question. +.SS ZONE DIRECTIVE STYLE MODIFIERS +Each of the zone directives may optionally be followed by one of the +following characters: +.TP +.B * +Indicates that the zone is unofficial, ie that it is not delegated as +part of the global Internet DNS and that no attempt should be made to +find the superzone and check delegations. Note that unofficial, local +zones should be created with caution. They should be in parts of the +namespace which are reserved for private use, or belong to the actual +zone maintainer. +.TP +.B ? +Indicates that the zone is known to be broken and no checks should be +carried out on it, unless the +.B \-A +option is specified. .SS OTHER DIRECTIVES .TP \fBinclude\fP \fIfile\fP @@ -222,15 +290,32 @@ 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 secondary -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 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, +configuration file or environment. It is not supposed to read its +stdin, but is not guaranteed to be safe if stdin is dangerous. +.LP +Killing chiark-named-conf suddenly should be safe, even with +.BR -y " or " -f +(though of course it may not complete its task if killed), provided +that only one invocation is made at once. +.LP +Slow remote nameservers will cause chiark-named-conf to take +excessively long. +.SH EXIT STATUS +.TP +.B 0 +All went well and there were no warnings. +.TP +any other +There were warnings or errors. .SH FILES .TP .B /etc/bind/chiark-conf-gen.zones @@ -246,6 +331,18 @@ Default output file. .TP .B /var/cache/bind/chiark-slave Default location for slave zones. +.SH ENVIRONMENT +.LP +Setting variables used by +.BR dig (1) +and +.BR adnshost (1) +will affect the operation of chiark\-named\-conf. +Avoid messing with these if possible. +.LP +.B PATH +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 its nameservers, is done simply using the system default nameserver.