This package contains the DNS Sleuth, version 1.4.4.

Copyright (c) 1999--2008 Martin Mares <mj@ucw.cz>

All files in this package can be freely distributed and used according
to the terms of the GNU General Public License, either version 2 or
(at your opinion) any newer version. The exact text of the license can
be found in file COPYING in any of GNU packages or at FSF Web pages
at URL http://www.gnu.org/copyleft/


   Sleuth is a Perl script designed for easy checking of DNS zones
for common errors and also for processing of secondary name service
requests. I wrote it after I've examined at least a dozen of utilities
claiming to do this job and found that all of them are either unable
to discover most zone bugs or too ugly for me to maintain. Sleuth also
lists the corresponding RFC references with most of its error messages,
so that the people upset with their zones being buggy can simply look
up what exactly is going wrong and how to fix it.

   Sleuth requires the Perl DNS module which can be found at
ftp://ftp.cpan.org/pub/CPAN/modules/by-category/05_Networking_Devices_IPC/Net/Net-DNS-0.12.tar.gz.
If you want to install it locally in your home directory, just modify
the @INC path in sleuth.conf. Sleuth has been developed under Perl
5.004_03 and it's probable that bugs in earlier Perl releases may
prevent it from working properly.

   You can download the current version from ftp://atrey.karlin.mff.cuni.cz/pub/local/mj/net/
or try the online version at http://atrey.karlin.mff.cuni.cz/~mj/sleuth/ .

   Please send me all bug reports and suggestions to <mj@ucw.cz>. This
will help me with making Sleuth even more useful.

   If you're tired of manually editing all the zone files and syncing the
reverse records by hand, look at NSC -- a suite of M4 scripts for easy
maintenance of DNS zones, you can download it from the same directory
where Sleuth lives, look for "nsc-*.tar.gz".

   The rest of this file tries to provide at least few bits of documentation.

					Have fun
							Martin


Usage
~~~~~
To check a zone for consistency, just run "sleuth <domain>".

To check a zone on specified name server, use "sleuth <domain> <server>"
where <server> is the _name_ of the server. If the server itself is not
yet registered, just add its IP address: "sleuth <domain> <server> <server-ip>".

Also, Sleuth can be used for checks of secondary name service requests
(this includes all of the usual zone checks plus several special ones,
see below for a full list). To turn this mode on, just add two more
parameters: the name of your secondary server and its IP address:
"sleuth <domain> <server> <server-ip> <secondary-server> <secondary-ip>".

By default, Sleuth lists only resource records defined in the zone being
checked. By specifying a "-v" switch, Sleuth switches to verbose mode
and includes all records it looks at during the checks (e.g., all the
reverse records).

If you want to check a private zone (i.e., skip all the tests regarding
connection to the worldwide DNS and stop warning about private addresses
occuring), add a "-p" switch.

You can also switch formatting of output by specifying either "-m"
(plain output -- just lines with their categories, useful for feeding
to an external formatting engine) or "-h" (HTML fragment output,
used by the WWW interface).


WWW Interface
~~~~~~~~~~~~~
This package also includes a simple CGI script which allows Sleuth to be
used interactively from any form-capable Web browser. The CGI interface
(check.cgi) requires the CGI Perl module (standard part of recent Perl
distributions or look at CPAN if you don't have it).

The script needs some bits of customization, so please look at the
check.conf file and follow the comments.

The script expects Sleuth and check.conf to be in the same directory
as it's run from.


Configuration
~~~~~~~~~~~~~
You can customize Sleuth by editing the configuration file sleuth.conf
(just follow the comments) which should be placed either in /etc or in
the same directory as the sleuth script itself.


Errors checked
~~~~~~~~~~~~~~
Here is a table of all the checks we do together with their identifiers.
You can set severity of any of the checks (ignore/warning/error/fatal error)
in the configuration file.

dnserr	Fatal DNS error (truncated errors and some other nasties)
reserr	Resolver error
selfa	Server unable to resolve its own name
badname	Malformed domain name
badrn	Malformed domain name in reverse zones
zcname	Zone is a CNAME
znexist	Zone doesn't exist
nonsa	Unable to find IP address of the DNS server
pcname	DNS record pointing to CNAME
rcname	CNAME pointing to CNAME
badrev	Invalid reverse mapping
norev	Missing reverse mapping
inexrev	Inexact reverse mapping (name -> ip -> different names only)
soamail	"@ instead of ." and other syntactic errors in SOA zone master address
soammx	Missing MX record for zone master address
soammxa	Missing A record for that MX record
soaamx	A record used instead of MX record
soaorg	Missing A record for origin server
recchk	The nameserver should be able to answer trivial queries
nolocal	No localhost records
badloc	Bad localhost records
revloc	No reverse record for 127.0.0.1
unkrevz	Unable to find network number in zone name
badrevn	Illegal name in reverse zone
badrevr	Illegal record type in reverse zone
arev	A records in reverse zones are considered bad practice
revcn	Illegal CNAME in reverse zone
ptrnoa	No A for PTR record
ptrbada	Mismatched A for PTR record
outzone	Out of zone records
wildac	Wildcard A's and CNAME's are strongly deprecated
wild	Wildcard records considered bad practice
reccn	CNAME recursion
suspcn	Suspicious overlapping CNAME
dangcn	Dangling CNAME
dangcnr	Dangling CNAME in reverse zone
missrev	Missing PTR for A
missa	Missing A for MX/NS/... destination
obsrec	Obsolete records (MD, MF, MB, MG, MR)
supsoa	Superfluous SOAs
ptrfwd	PTR records in forward zones are considered bad practice
mxpref	Invalid preference in MX record
cnclash	CNAME together with other records or two CNAME's for same name
twons	A zone has to have at least two nameservers
lamer	Lame delegations [check mode only]
oodsec	Authoritative servers don't agree on domain versions [check mode only]
nosecns	Our secondary not listed between NS records [submit mode only]
utoplev	Unknown top-level domain [submit mode only]
xtoplev	Name of top-level domain used as zone name [submit mode only]
rtoplev	Registration of top-level domain attempted [submit mode only]
alknown	Already known at our secondary [submit mode only]
snauth	Selected nameserver is not zone source [submit mode only]
missns	No NS records present [submit mode only]
suspttl	Suspicious TTL
suspmtl	Suspicious minttl in SOA
suspexp	Suspicious expire in SOA
wks	WKS record is obsolete
ornotns	Origin server not listed in domain's NS records
unxtype	Unexpected record in reply packet
axfer	Zone transfer failed
alldig	All-digit names are not allowed
noserv	No name server available for checking
diffns	Different name servers report different set of NS records
duprec	Duplicate record in zone
srvnam	Invalid name of SRV record
srvpar	Invalid parameters of SRV record
srvdest	Destination of SRV has no A
iapname	IP address found instead of name
needaa	Answer is not authoritative
