


 DOC(8)                                                               DOC(8)
                                   7/12/95



 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.
      Additional "short-cut" heuristics have been added in the "in-
      addr.arpa" case.  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.]






                                    - 1 -          Formatted:  July 12, 1995






 DOC(8)                                                               DOC(8)
                                   7/12/95



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




                                    - 2 -          Formatted:  July 12, 1995






 DOC(8)                                                               DOC(8)
                                   7/12/95



 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 also be separately available in the DNS Resources Directory
      <URL:http://www.is.co.za/andras/computer/dnsrd/>.

      Relatively minor modifications have been made with version 2.1, mostly
      to make the program a bit more robust in handling parent (delegating)
      domains.

      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 me know.  I'd love to see them, with an eye towards
      integrating them into my 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.

      Now that I have changed employers, and I am going to be involved in
      writing all sorts of administrative tools for our internal use, I
      intend to use doc and some other programs as "excuses" to learn Perl
      and Tcl/Tk.  I hope to make these updated version publicly available,
      but I have yet to get formal approval for that.  I will make available
      whatever I can, likely through the URLs provided above, and through
      related URLs that will be widely publicized.

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



                                    - 3 -          Formatted:  July 12, 1995






 DOC(8)                                                               DOC(8)
                                   7/12/95



 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 (BKnowles@aol.net)

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










































                                    - 4 -          Formatted:  July 12, 1995



