Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DOC(8)			    System Manager's Manual			DOC(8)

       doc - diagnose unhealthy	DNS domains

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

       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	param-
       eter is the valid domain	name of	an existing domain.  Example:


       Previous	versions of doc	required that you specify the parent (delegat-
       ing)  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 re-
       quired 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 ""	case.  Examples:

	    doc edu.		  (correct, but	not required)
	    doc		  (this	works too)
	    doc arpa. (correct, but	not required)
	    doc	  (this	works too)

       If you have problems, giving the	parent information information explic-
       itly may	help.

       -p     Skip  testing  the  information  held  at	 delegating   domain's

	      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 in-
	      consistencies 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.

       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  re-
       sponses to the queries (in a slightly masticated	form).

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


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

       See  file  INFO	(included with distribution tar) for details of	proce-

       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 ex-
       pected 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.

       The previous authors effectively	stopped	further	development  and  sup-
       port  in	 1990.	 Starting with version 2.1, the	official anonymous FTP
       site for	doc is as part of the the latest  distribution  of
       BIND  (see  the	BIND  Home Page	at <URL:>).  It
       will also be  separately	 available  in	the  DNS  Resources  Directory

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

       This  program is	being shared with the rest of the Internet on a	unsup-
       ported 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 inte-
       grating them into my version (and also into the publicly	available ver-
       sion).	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 in-
       tend 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	 what-
       ever I can, likely through the URLs provided above, and through related
       URLs that will be widely	publicized.

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

       RFC 1537	SOA value conformance checking (warnings only).

       Steve Hotz ( Paul Mockapetris (

       Brad Knowles (

       dig(1),	     bind      operators       guide	   (BOG),	 RFCs:

				    7/12/95				DOC(8)


Want to link to this manual page? Use this URL:

home | help