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.  Exam-
     ples:

          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 informa-
     tion 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 addi-
          tionally  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 stan-
          dard output a summary of what is discovered.  In  addi-
          tion, 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 stan-
     dard query to discover  the  list  of  nameservers  for  the
     parent  domain.   Rather it queries the list of servers con-
     tained 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  confi-
     guration" 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.  How-
     ever, this version (2.0) is an initial attempt at automating
     this  task.   Further development is expected in identifying
     the appropriate queries, analysis,  and  subsequent  conclu-
     sions  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 offi-
     cial 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 han-
     dling 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
