dnswalk.1   [plain text]


.TH DNSWALK 1
.SH NAME
dnswalk \- A DNS database debugger
.SH SYNOPSIS
.B dnswalk
[
.BR \- adilrfFm
]
.I domain.
.SH "DESCRIPTION"
.B dnswalk
is a DNS debugger.  It performs zone transfers of specified domains,
and checks the database in numerous ways for internal consistency, as
well as for correctness according to accepted practices with the Domain
Name System.
.PP
The
.I domain
name specified on the command line MUST end with a '.'.
You can specify a forward domain, such as
.B dnswalk pop.psu.edu.
or a reverse domain, such as
.B dnswalk 155.118.128.in-addr.arpa.
.SH OPTIONS
.PD 0
.TP
.BI \-f
Force a zone transfer from an authoritative nameserver.
dnswalk normally will look in its saved 'axfr' file
for each domain and use that. (if it exists, and the serial
number has not increased)
.TP
.BI \-r
Recursively descend sub-domains of the specified
domain.  Use with care.
.TP
.BI \-a
Turn on warning of duplicate A records.  (see below)
.TP
.BI \-d
Print debugging and 'status' information to stderr.
(Use only if redirecting stdout)  See DIAGNOSTICS section.
.TP
.BI \-m
Perform checks only if the zone has been modified since the previous run.
.TP
.BI \-F
perform "fascist" checking.  When checking an A record,
compare the PTR name for each IP address with the forward
name and report mismatches.  (see below)  I recommend
you try this option at least once to see what sorts of
errors pop up - you might be surprised!.
.TP
.BI \-i
Suppress check for invalid characters in a domain name.  (see below)
.TP
.BI \-l
Perform "lame delegation" checking.  For every NS record,
check to see that the listed host is indeed returning
authoritative answers for this domain.
.TP
.BI \-D\ dir
Use
.BI dir
as the directory to use for saved zone transfer files.  Default is '.'.
.SH ERRORS
The following the list of error messages that dnswalk will return
if it sees a potential problem with the database.  Duplicate messages
will be suppressed automatically for each zone.
.TP
.PD 0
.BI "X PTR Y: unknown host"
X is a PTR record to Y, but Y is not a valid host (no A record).
These are often left over from when someone deleted a host from
the DNS and forgot to delete the PTR record.
.TP
.BI "X PTR Y: A record not found"
X is a PTR record to Y, but the IP address associated with the PTR
record is not listed as an address for Y.  There should be an A
record for every valid IP address for a host.  Many Internet services
will not talk to you if you have mismatched PTR records.
.TP
.BI "X PTR Y: CNAME (to Z)"
X is a PTR record to Y, but Y is a CNAME to Z.  PTR records MUST point
to the canonical name of a host, not an alias.
.TP
.BI "X CNAME Y: unknown host"
X is aliased to Y, but Y is not a valid host (no A record).
.TP
.BI "X CNAME Y: CNAME (to Z)"
X is aliased to Y, but Y is aliased to Z.  CNAMEs should not be chained.
.TP
.BI "X MX Y: unknown host"
X is an MX to Y, but Y is not a valid host (no A record).
.TP
.BI "X MX Y: CNAME (to Z)"
X is an MX to Y, but Y is an alias for Z.  MX records must point to
the canonical name, not an alias.
.TP
.BI "X A Y: no PTR record"
X has an IP address Y, but there is no PTR record to map the IP address
Y back to a hostname (usually X). Many Internet servers (such as anonymous
FTP servers) will not talk to addresses that don't have PTR records.
.TP
.BI ";; packet size error (found xxx, dlen was yyy)"
These are error messages from dig.  They indicate a format error
in the DNS response.  Most often they are caused by records which have
an incorrect number of fields.  For example, HINFO records require
exactly two fields.
.TP
.BI "warning: X has only one authoritative nameserver"
Zones must have at least one authoritative nameserver, in case
one is down or unreachable.  Make sure the parent and child domains
list all authoritative nameservers for a zone.
.TP
.BI "Cannot check X: no available nameservers!"
The  X  zone  was delegated with NS records but all the nameservers
for the zone are either unavailable or say that they have no data for
the zone (are lame).  Verify that  the X zone isn't a typo, and if so
make sure that all the listed nameservers are configured to answer
with data for the zone.
.TP
.BI "X: invalid character(s) in name"
Allowable characters in a domain name are the ASCII letters a through Z
the digits 0 through 9,
and the "-" character.  A "." may be used only as a domain separator.
(checking can be suppressed with
.B \-i
)
.TP
.BI "X: domain occurred twice, forgot trailing '.'?"
A sanity check which looks for "dom.ain.dom.ain." in a name.  This
is often caused by forgetting to put a trailing '.' on the end of
a name.
.TP
(with -a switch)
.TP
.BI "X: possible duplicate A record (glue of Z?)"
A duplicate A records is listed for X.  NOTE: this is most
often caused by the practice of always putting A records for all
secondaries after NS glue records.  While this is not an error, it is
usually redundant and makes changing IP addresses later more difficult,
since they occur more than one time in the file (and in multiple
files).  You may get spurious errors, mostly because of a quirk in
BIND releases before 4.9.x that reports cached glue A records in a zone
transfer even though they don't exist in the original zone file.
.TP
(with -F switch)
.TP
.BI "X A Y: points to Z"
X has Y for an IP address, but the PTR record associated with Y
returns "Z" as the name associated with that host.  This is not
necessarily an error (for example if you have an A record for your
domain name), but can be useful to check for A records which point
to the wrong host, or PTR records that point to the wrong host.
.TP
(with -l switch)
.TP
.BI "X NS Y: lame NS delegation"
Y is a listed nameserver for zone X, but Y is not returning
authoritative data for zone X.  This is usually the result of a
lack of communication on the part of the respective hostmasters.  Lame
delegations are not fatal problems except in severe cases, they just
tend to create significant increases in DNS traffic.  NS records for
the parent and child domains should be consistent, and each server
listed in the NS record MUST be able to answer with authoritative data,
either by being a primary or secondary for the zone.
.TP
.BI "X NS Y: nameserver error (lame?)"
Any errors returned from dig while contacting other nameservers
(like connection refused or timeout) will be reported.  This could
mean a lame delegation, or simply that the host is temporarily
unreachable.
.SH FILES
.br
.nf
.\" set tabstop to longest possible filename, plus a wee bit
.ta \w'xxxxxxxxxxxxxxxxxxxxxxxx   'u
\fIbar/foo/axfr\fR  saved zone transfer information for "foo.bar"
.SH "SEE ALSO"
.nf
RFC 1034 - "DOMAIN NAMES - CONCEPTS AND FACILITIES"
RFC 1035 - "DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION"
RFC 1123 - "Requirements for Internet Hosts -- Application and Support"
Paul Albitz, Cricket Liu: "DNS and BIND" O'Reilly & Associates.
.SH NOTES
This package was tested under Perl 4.036, dig 2.0, as well as the dig
shipped with BIND 4.9.x.
.SH CAVEATS
If a domain "foo.edu" lists "ns.bar.foo.edu" as authoritative for
a zone "bar.foo.edu", but "ns.bar.foo.edu" isn't, then the the dig of
the zone transfer will hang.  (This was the case here for a subdomain
that moved into a new set of IP addresses, but the parent nameserver still
had the old authority records pointing to their nameservers which weren't
answering to the old reverse domain anymore.)  If this happens, you can
hit ^C while the transfer is going on and dnswalk will abort that server.
(It will also remove the partial axfr file)  Hopefully I can figure a
more elegant way around this.  (or fix dig so that it doesn't hang)
.SH DIAGNOSTICS
When invoked with the
.B \-d
option,
.B dnswalk
will print status information to stderr.  It consists of information
about what zone is being checked, and a single letter corresponding
to the resource record checked, and any errors.
.TP
.BI a
A record
.TP
.BI c
CNAME record
.TP
.BI p
PTR record
.TP
.BI m
MX record
.TP
.BI s
SOA record
.TP
.BI !
An error occurred
.TP
.BI .
A previous error in the zone was repeated, but suppressed.
.PP
.SH BUGS
dnswalk will make the directory tree before it has a chance to
find out that you gave it a bogus domain name.
.PP
When checking lots of hosts and lots of options, it is very
slow.  Running dnswalk on a machine with a local nameserver helps
considerably.
.PP
Perl's gethostby{name,addr}() routine doesn't seem to
consistently return an error whenever it is unable to resolve an
address.  Argh.  This will mean lots of "no PTR record" and "host unknown"
errors if a server is unavailable, or for some reason the lookup fails.
You may get strange error messages if your perl was compiled without
support for herror().
.PP
I really need to rewrite this all to not rely on dig, and use
bind.pl instead.
.SH AUTHOR
David Barr <barr@pop.psu.edu>