Provided by: bind_8.4.6-1_i386 bug

NAME

       doc - diagnose unhealthy DNS domains

SYNOPSIS

       doc [-p] [-e][-w][-v][-d] domain_name [parent_domain_name]

DESCRIPTION

       Doc  is an automated tool for verifying (to an extent) that a domain is
       configured and functioning correctly.  It makes no attempt to  validate
       the  data  inside  a  domain,  only  the  structure.  The only required
       parameter is the valid domain name of an existing domain.  Example:

                 doc isi.edu.

       Previous  versions  of  doc  required  that  you  specify  the   parent
       (delegating)  domain  if  it  was  not  precisely one level up from the
       domain  being  checked  (or  specify  the  parent  nameservers  in   an
       appropriately named file).  Although the option still exists to do that
       (and it  may  be  required  with  some  complex  configurations),  some
       heuristics  have  been  added  that  make some attempt to handle parent
       domains that are more than  one  level  up  from  the  current  domain.
       Examples:

            doc isi.edu. edu.             (correct, but not required)
            doc isi.edu.                  (this works too)
            doc 9.128.in-addr.arpa. arpa. (correct, but not required)
            doc 9.128.in-addr.arpa.       (this works too)

       If  you  have  problems,  giving  the  parent  information  information
       explicitly may help.

OPTIONS

       -p     Skip  testing  the  information  held  at  delegating   domain’s
              servers.

              The  default  operation  of doc includes testing that all of the
              servers for the  delegating  (parent)  domain  agree  about  the
              delegation  information  held for the domain in question.  Since
              inconsistencies discovered at this level may or may not indicate
              serious problems, one can choose to skip the parent testing.  If
              so, doc uses the first non-authoritative list of NS records from
              a  parent  domain server as those to direct further queries.  If
              all of the parent domain servers are additionally  authoritative
              for  the  domain,  the answer from the last one queried is used.
              This may be a useful timesaver if you are regularly checking  up
              on  a large number of domains.  [See also section FILES USED for
              a similar functionality.]

       -[e][w][v][d]  Specify the level of verbosity to standard output.

              The default mode of operation  is  to  only  print  to  standard
              output  a  summary  of  what is discovered.  In addition, errors
              made in the  process  of  testing  (i.e.  query  errors,  errors
              causing doc to abort, etc) are noted.

                  -e    Output comments about errors discovered.
                  -w    Output comments about warnings issued.
                  -v    Verbose output. Include misc. comments and output
                        confirming correct behavior.
                  -d    Debug output. Checkpoint current (last)
                        nameserver query.

              These  output options are cumulative (i.e. -v implies -v -w -e).

              NOTE: Parsing is very simple.  All option flags must come before
              the domain names.

FILES CREATED

       In  addition  to  the  standard  output,  doc produces a log file named
       log.<domain_name>, which it places in the current directory.  This file
       includes  all  "verbose"  level  comments,  followed  by the nameserver
       responses to the queries (in a slightly masticated form).

       While running, doc creates  several  temporary  files  in  the  current
       directory.  These files have names of the form:

            <domain_name>.*

FILES USED

       Doc  expects  the  auxiliary files: doc1.awk, doc3.awk, and doc4.awk to
       reside in the current working directory.  This  can  be  overridden  by
       changing  the  program  to  look for them in a directory indicated in a
       shell variable intended for this purpose.  If your System Administrator
       installed doc, they’ll need to make the necessary modification.

       Doc  looks  for  the  file  DNsrv.<parent_domain_name>  in  the working
       directory.  If it exists,  doc  does  not  make  a  standard  query  to
       discover  the  list  of  nameservers  for the parent domain.  Rather it
       queries the list of servers contained in this file to obtain delegation
       information  for  the  domain  being tested.  This may be useful if one
       regularly tests a series of domains, all with the same delegating zone,
       where one of the servers in known to be foul.  This server would simply
       be omitted from the the DNsrv.* file.

       awk, sed & dig (version 2.0 or higher) are expected to be found in your
       normal  path.  If not, you may want to alias to the full path inside of
       doc itself.

DETAILS

       See  file  INFO  (included  with  distribution  tar)  for  details   of
       procedure.

BUGS

       The  exit code returned via the shell is only 8 bits.  This could cause
       a problem in the value returned by the auxiliary file  doc3.awk.   This
       hasn’t  been  seen yet (a "poison configuration" is not likely to occur
       yet), and hopefully will be corrected  if/when  doc  is  re-implemented
       (see below).

       The  current implementation is fairly simple (albeit not pretty), so it
       is not expected to abort unexpectedly.  However, this version (2.0)  is
       an  initial  attempt  at  automating this task.  Further development is
       expected  in  identifying  the  appropriate  queries,   analysis,   and
       subsequent conclusions that are made.  Hopefully once the design of the
       test suite has  become  more  stable,  a  less  "patchwork"  production
       version of doc will be done.

COMMENTS

       The  previous  authors  effectively  stopped  further  development  and
       support in 1990.  Starting with version 2.1, the official anonymous FTP
       site  for  doc is ftp.vix.com as part of the the latest distribution of
       BIND (see the BIND Home  Page  at  <URL:http://www.isc.org/isc/>).   It
       will  likely  also  be  made  available  in  the DNS Resource Directory
       <URL:http://www.is.co.za/andras/computer/dnsrd/> in the near future.

       Relatively minor modifications have been made with version 2.1,  mostly
       to  make  the program a bit more robust in handling parent (delegating)
       domains for the use of Defense Information Systems Agency personnel.

       This program is being shared  with  the  rest  of  the  Internet  on  a
       unsupported  basis.   If  you have any enhancements or changes you have
       made, please let us know.  We’d love to see them, with an  eye  towards
       integrating them into our version (and also into the publicly available
       version).  However, keep in mind that I’m not getting paid  (nor  do  I
       have the time) to support the whole Internet on this tool.

       With  the  previous  authors  no  longer  providing support for doc, it
       becomes far less likely that a "less  ’patchwork’  production  version"
       will ever become available.

INFO

       The  name doc comes from Domain Obscenity Control, in that the kinds of
       problems it looks for are considered "obscene" from the perspective  of
       a well-managed DNS.

TO DO

       RFC 1537 SOA value conformance checking (warnings only).

PREVIOUS AUTHORS

       Steve Hotz (hotz@isi.edu) Paul Mockapetris (pvm@isi.edu)

MODIFICATIONS BY

       Brad Knowles (brad@birch.ims.disa.mil)

SEE ALSO

       dig(1),        bind       operators       guide      (BOG),       RFCs:
       1034,1035,1535-1537,1713,xxxx

                                    5/27/95                             DOC(8)