##
##    Distributed with: Doc - Version 2.0 (8/22/90)
##    USC Information Sciences Institute
##


DOC                  UNIX Programmer's Manual               DOC



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.

     The only required parameter is the valid domain name of an
     existing domain. Example:

           doc isi.edu.

     If the parent (delegating) domain can be determined simply
     by stripping off the first domain part and subsequent dot from
     the specified domain name, then there is no need to include
     the parent_domain_name parameter.  Examples:

           doc isi.edu. edu.               (this is correct)
           doc isi.edu.                    (this works too)
           doc 9.128.in-addr.arpa. arpa.   (this is correct)
           doc 9.128.in-addr.arpa.         (this will NOT work)

     In the last (incorrect) example, because there is no parent
     domain specified, 'doc' fills in the optional parent_domain
     parameter, and runs as if you specified:

           doc 9.128.in-addr.arpa. 128.in-addr.arpa.

     Since, the delegation information for 9.128.in-addr.arpa. is
     not at 128.in-addr.arpa. (rather at arpa.), this run will
     abort, and not report as expected.

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


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

     '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 distribution file INFO, for details of procedure.

BUGS
     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.
     Comments are very much welcome.

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

SEE ALSO
     dig(1),  bind operators guide,  RFCs: 1034,1035,xxxx