Man Linux: Main Page and Category List


       chiark-named-conf - check and generate nameserver configuration


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


       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.


       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

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

              Check  configuration,  for all listed zones, but do not generate
              new nameserver config.

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

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

              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.

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

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

              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.

              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.

              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.

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

              Print additional information about what is being checked, as  we
              go along.


       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
       joins  it to the next line, so that long directives can be split across
       several physical lines.

       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

              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-

              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

       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

       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 would mean to expect us to
              be listed as 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

       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.

       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

       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.

       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

       $      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

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

       include file
              Reads file as if it were included here.

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


       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


       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 NS NS NS NS
       Here it is impossible to look up  anything  in  either  or

       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

       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
       It does not seem at all common practice to create  nameservers  in  in-  zones  (ie,  no NS RRs seem to point into, even
       those for zones).  Current practice seems to be to  always
       use  nameservers  for  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 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 but be warned that it is
       rather opinionated.

       I recommend that every nameserver should have its  own  name  in  every
       forward zone that it serves.  For example: NS A PTR A

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


       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.


       0      All went well and there were no warnings.

       any other
              There were warnings or errors.


              Default input configuration file.  (Override with -C.)

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

              Default output file.

              Default location for slave zones.


       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.


       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.


       chiark-named-conf   and  this  manpage  were  written  by  Ian  Jackson
       <>.  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, or the GNU Project website at