DOC(8)DOC(8)NAMEdoc - diagnose unhealthy DNS domains
SYNOPSISdoc [-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 parame‐
ter. 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 dele‐
gation 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 out‐
put 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 direc‐
tory. 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 proce‐
dure.
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 subse‐
quent 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 are very much welcome.
AUTHOR
Steve Hotz (hotz@isi.edu) Paul Mockapetris (pvm@isi.edu)
SEE ALSOdig(1), bind operators guide, RFCs: 1034,1035,xxxx
August 22, 1990 DOC(8)