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=2316c9de9fe479189344ebe621902d343cea1d3b;hp=0ba18b946f05797db64b0f3bf3eb6a4b1deb76d1;hb=c4441d680a870752e80ad0dfd839c9fa1d24c062;hpb=d8b6b8cd878568df71395443fab7a2d93259aaa6 diff --git a/scripts/named-conf.8 b/scripts/named-conf.8 index 0ba18b9..2316c9d 100644 --- a/scripts/named-conf.8 +++ b/scripts/named-conf.8 @@ -2,22 +2,20 @@ .TH CHIARK\-NAMED\-CONF 8 "30th December 2001" "Greenend" "chiark utilities" .SH NAME chiark\-named\-conf \- check and generate nameserver configuration - .SH SYNOPSIS -.B chiark\-named\-conf [\fIoptions\fP] \-n|\-y|\-f +.BR chiark\-named\-conf " [\fIoptions\fP] " \-n | \-y | \-f .br -.B chiark\-named\-conf [\fIoptions\fP] \fIzone ...\fP - +\fBchiark\-named\-conf\fP [\fIoptions\fP] \fIzone ...\fP .SH DESCRIPTION .B chiark\-named\-conf is a tool for managing nameserver configurations and checking for suspected DNS problems. Its main functions are to check that -delegations are appropriate and working, optionally from the root zone -down, and to generate a configuration for +delegations are appropriate and working, and to generate a +configuration for .BR BIND , from its own input file. - .SH OPTIONS + .SS MODE OPTIONS If one of the options .BR -n ", " -y ", or " -f @@ -47,23 +45,63 @@ 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 \-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 +Do not warn about glueless referrals. 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. +.TP +.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. -.TP -.BR \-r | \-\-root -Check the delegation all the way to the root zone. By default, -checks are only carried out on the delegations supplied by (all) the -nameservers for the immediate superzone. -.SH CONFIGURATION +.SH USAGE The file .B /etc/bind/chiark-conf-gen.zones (or other file specified with the @@ -72,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 -\fBself\fP \fIfqdn ...\fP -Equivalent to both -.BR 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 @@ -113,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 @@ -134,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 @@ -186,26 +281,41 @@ and agree with the local default nameserver. Delegated servers: Each server mentioned in the delegation should have the same SOA record (and obviously, should be authoritative). -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. -(The addresses of any additional servers will be acquired from the -local default nameserver at this point.) - All published nameservers - including delegated servers and servers named in the zone's nameserver set: All nameservers for the zone -should supply the same list of nameservers for the zone as the origin -server does, and none of this authority information should be -glueless. All the glue should always give the same addresses. +should supply the same list of nameservers for the zone, and none of +this authority information should be glueless. All the glue should +always give the same addresses. -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. +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 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 @@ -221,6 +331,27 @@ 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. + +The processing of output from +.B dig +is not very reliable or robust, but this is mainly the fault of dig. +This can lead to somewhat unhelpful error reporting for lookup +failures. .SH AUTHOR .B chiark\-named\-conf and this manpage were written by Ian Jackson .