Provided by: chiark-scripts_4.4.2build1_all bug

NAME

       chiark-named-conf - check and generate nameserver configuration

SYNOPSIS

       chiark-named-conf [options] -n|-y|-f
       chiark-named-conf [options] zone ...

DESCRIPTION

       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, that secondary zones are
       slaved from the right places, and to generate a configuration for 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 * after the serial number.

OPTIONS

   MODE OPTIONS
       If one of the options -n, -y, or -f is supplied then  chiark-named-conf
       will  read  its main configuration file for the list of relevant zones.
       It will then check the  configuration  and  delegation  for  each  zone
       and/or   generate   and  install  a  new  configuration  file  for  the
       nameserver:

       -y|--yes
              Generate and install new nameserver config, as well as  checking
              configuration, for all listed zones.

       -n|--no
              Check  configuration,  for all listed zones, but do not generate
              new nameserver config.

       -f|--force
              Generate and install new nameserver config,  without  doing  any
              configuration  cross-checking.   (Syntax  errors  in  our  input
              configuration will still abort this operation.)

       --nothing
              Do nothing: do no checks, and don't write a  new  config.   This
              can be used to get a list of the zones being processed.

       --mail-first | --mail-middle | --mail-final
              Send  mails  to  zone  SOA MNAMEs reporting zones with problems.
              You must  call  chiark-named-conf  at  least  twice,  once  with
              --mail-first,  and  later with --mail-final, and preferably with
              one or more  calls  to  --mail-middle  in  between.   All  three
              options  carry  out  a check 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).

       -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
              (testing!)  to the start of the To: field.

       Alternatively, one or more zone names may be supplied as arguments,  in
       which  case  their  delegations  will be checked, and compared with the
       data for that zone in the main configuration (if any).  In this case no
       new configuration file for the nameserver will be made.

   ADDITIONAL OPTIONS
       -A|--all
              Checks  even  zones known to be broken.  Ie, ignores the ?  zone
              style modifier in the configuration.

       -C|--config config-file
              Use  config-file  instead  of   /etc/bind/chiark-conf-gen.zones.
              Also changes the default directory.

       -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 -DD.)

       -g|--glueless
              Do  not  warn about glueless referrals (strictly, makes the zone
              style modifier ~  the  default).   Not  recommended  -  see  the
              section GLUELESSNESS, below.

       -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 -l with foreign zones (zones supplied
              explictly  on  the  command  line  but not relevant to the local
              server); doing so produces a warning.

       -mgroup!*$@~?
              Overrides a modifiers directive in the configuration file.   The
              modifiers  specified in the directive are completely replaced by
              those  specified  in  this  command  line  option.   (Note  that
              modifiers  specified in per-zone directives still override these
              per-group settings.)   If  more  than  one  modifiers  directive
              specifies  the  same  group,  they  are all affected.  modifiers
              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.

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

       -q|--quiet
              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.

       -r|--repeat
              When  a  problem  is  detected, warn for all sources of the same
              imperfect data, rather than only the first we come across

       -v|--verbose
              Print additional information about what is being checked, as  we
              go along.

USAGE

       The  file /etc/bind/chiark-conf-gen.zones (or other file specified with
       the -C 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 #.  Ending a line with a .ft
       R  joins  it  to  the  next  line, so that long directives can be split
       across several physical lines.

   GENERAL DIRECTIVES
       These directives specify general configuration  details.   They  should
       appear  before  directives  specifying  zones, as each will affect only
       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.

       admin email-address
              Specifies the email address of the local administrator.  This is
              used  in the From: line of mails sent out, and will also receive
              copies of the reports.  There is no default.

       default-dir directory
              Makes directory be the  default  directory  (which  affects  the
              interpretation  of  relative  filenames).   The  default  is the
              directory containing the main configuration file,  ie  /etc/bind
              if no -C option is specified.

       forbid-addr [ip-address ...]
              Specifies  the  list  of  addresses  that  are  forbidden as any
              nameserver for any zone.  The default is no such addresses.

       forbid-addr [ip-address ...]
              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.

       serverless-glueless domain ...
              Specifies a list of domains under which we do not expect to find
              any 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
              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 (glueless) nameservers, and therefore
              fine to provide glueless referrals for.  See GLUELESSNESS below.

       allow--indirect-glue nameserver-superdomain ...
              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 allow-indirect-glue  nameserver-
              superdomain.

              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 nameserver-
              superdomains),  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  nameserver-
              superdomain  then  they  might  still  set  up circular glue and
              chiark-named-conf would not necessarily be able to  detect  this
              even if it was run on every relevant nameserver.

       mail-state-dir directory
              Uses directory for storing information about recent failures for
              mailing to zone admins.  See --mail-first et al.  Old  files  in
              here should be cleaned up periodically out of cron.  There is no
              default.

       mail-max-warnfreq percentage
              When --mail-final is used, a mail will  be  sent  to  all  zones
              which  had warnings or errors more than percentage% of the times
              --mail-* was used (since the last --mail-first).  The default is
              50%.

       modifiers !*$@~?] [group]
              Applies  the  specified  zone  style  modifiers  (see  below) to
              subsequently  declared   zones   (until   the   next   modifiers
              directive),  as  if the modifiers specified were written out for
              each zone.  You must specify at  least  one  character  for  the
              modifiers;  if you want to reset everything to the default, just
              say !.  If style  modifiers  specified  in  the  zone  directive
              conflict  with  the  modifiers directive, those specified in the
              zone directive take effect.  group may contain alphanumerics and
              underscores, and is used for the -m command-line option.

       self-addr ip-address ...
              Specifies the list of addresses that this server may be known by
              in A records.  There is no default.

       output format filename [format filename ...]
              Arranges that each filename will be overwritten when  -y  or  -f
              are  used; its new contents will be configuration directives for
              the  zones  which  follow  for  the  nameserver   in   question.
              Currently  the  only  format  supported is bind8 which indicates
              new-style BIND 8.  If no zones follow, then each file will still
              be overwritten, by an effectively empty file.  Default: if there
              is no output directive in the configuration then the default  is
              to use bind8 chiark-conf-gen.bind8; otherwise it is an error for
              there to be any zones in  the  configuration  before  the  first
              output directive.

       self-ns fqdn ...
              Specifies  the list of names that this server may be known by in
              NS records.  There is no default.  Any trailing * is replaced by
              the  name  of  the  zone  being  checked, so for example self-ns
              isp.ns.*  before the zone example.com would mean to expect us to
              be listed as isp.ns.example.com in the NS RRset.

       self-soa fqdn ...
              Specifies  the list of names that this server may be known by in
              the ORIGIN field of SOA records.   There  is  no  default.   Any
              trailing * is replaced by the name of the zone, as for self-ns.

       self fqdn ...
              Equivalent  to  both self-ns  and  self-soa with the same set of
              names.

       slave-dir directory [[prefix] suffix]
              Specifies the directory in which slave (published  and  stealth)
              zonefiles   should   be   placed.    The  default  directory  is
              /var/cache/bind/chiark-slave.  The default suffix and prefix are
              empty;  they also will be reset to these defaults by a slave-dir
              directive which does not specify them.

   ZONE DIRECTIVES
       These directives specify one or more zones.

       primary[!*$@~?] zone filename
              Specifies that  this  server  is  supposed  to  be  the  primary
              nameserver  for  zone  and  that the zone data is to be found in
              filename.

       primary-dir[!*$@~?] directory[/prefix] [suffix[/subfile]]
              Search directory for files whose names start with prefix and end
              with  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 prefix and suffix is the name of the zone.

              If  /subfile is specified, then instead of looking for files, we
              search for directories containing subfile; directories which  do
              not contain the subfile are simply skipped.

              If  directory[/prefix]  exists  as  specified and is a directory
              then it is  interpreted  as  directory  with  an  empty  prefix;
              otherwise  the final path component is assumed to be the prefix.
              If no suffix/subfile is specified then the default is _db.

       published[!*$@~?] zone origin-addr
              Specifies that this server is supposed to be a  published  slave
              nameserver for the zone in question.

       stealth[!*$@~?] zone server-addr ...
              Specifies  that  this  server  is  supposed to be an unpublished
              secondary (aka stealth secondary) for the zone in question.

   ZONE STYLE MODIFIERS
       Each of the zone directives may optionally be followed by one  or  more
       of the following characters (each at most once):

       !      Reverses  the  meaning of all style modifiers after the !.  Only
              one !  must appear in the modifier list.  In  this  list,  other
              modifiers which default to `enabled' are described by describing
              the effect of their inverse - see the description for !@ below.

       *      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.

       $      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 unless we are supposedly  a  published  server  for  the
              zone.

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

       ~      Indicates  that  the  zone's delegation is known to be glueless,
              and that lack of glue should not be flagged.  Not recommended  -
              see the section GLUELESSNESS, below.

       ?      Indicates  that  the  zone  is  known to be broken and no checks
              should be carried out on it, unless the -A option is specified.

   OTHER DIRECTIVES
       include file
              Reads file as if it were included here.

       end    Ends processing of this file; any  data  beyond  this  point  is
              ignored.

CHECKS

       chiark-named-conf makes the following checks:

       Delegations:  Each  delegation  from  a server for the superzone should
       contain the same set of nameservers.  None of  the  delegations  should
       lack  glue.   The glue addresses should be the same in each delegation,
       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).

       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, and none of this
       authority information should be glueless.  All the glue  should  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 primary zones, the SOA origin should be one
       of  the  names specified with 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.

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
       example.com NS ns0.example.net.uk
       example.com NS ns1.example.net.uk
       example.net.uk NS ns0.example.com
       example.net.uk NS ns1.example.com
       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.

       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  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
       http://cr.yp.to/djbdns/notes.html#gluelessness
       ⟨http://cr.yp.to/djbdns/notes.html#gluelessness⟩ but be warned that  it
       is rather opinionated.

   GLUELESSNESS SUMMARY
       I  recommend  that  every  nameserver should have its own name in every
       forward zone that it serves.  For example:
       zone.example.com NS servus.ns.example.com
       servus.ns.example.com A 127.0.0.2
       2.0.0.127.in-addr.arpa PTR servus.example.net
       servus.example.net A 127.0.0.2

       Domain names in in-addr.arpa should not be used in the right hand  side
       of NS records.

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.

       Killing chiark-named-conf suddenly should be safe, even with -y  or  -f
       (though  of  course  it  may not complete its task if killed), provided
       that only one invocation is made at once.

       Slow  remote  nameservers  will   cause   chiark-named-conf   to   take
       excessively long.

EXIT STATUS

       0      All went well and there were no warnings.

       any other
              There were warnings or errors.

FILES

       /etc/bind/chiark-conf-gen.zones
              Default input configuration file.  (Override with -C.)

       /etc/bind
              Default directory.  (Override with -C or default-dir.)

       dir/chiark-conf-gen.bind8
              Default output file.

       /var/cache/bind/chiark-slave
              Default location for slave zones.

ENVIRONMENT

       Setting  variables  used  by  dig(1)  and  adnshost(1)  will affect the
       operation of chiark-named-conf.  Avoid messing with these if possible.

       PATH is used to find subprograms such as dig and adnshost.

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 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.

AUTHOR

       chiark-named-conf   and  this  manpage  were  written  by  Ian  Jackson
       <ian@chiark.greenend.org.uk>.  They are Copyright 2002 Ian Jackson.

       chiark-named-conf  and  this  manpage  are  free  software;   you   can
       redistribute  it  and/or  modify  it under the terms of the GNU General
       Public License as published by the  Free  Software  Foundation;  either
       version 2, or (at your option) any later version.

       This is distributed in the hope that it will be useful, but WITHOUT ANY
       WARRANTY; without even  the  implied  warranty  of  MERCHANTABILITY  or
       FITNESS  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
       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.