X-Git-Url: http://gitweb.michael.orlitzky.com/?p=haeredes.git;a=blobdiff_plain;f=doc%2Fman1%2Fhaeredes.1;h=197b7e8eadd7f62a0b4c2397a9dc7a2acd2396a2;hp=900b4c64e195bc044fc68c149b6b178dc3afb778;hb=7b1f25b5a8f60c2f388eff66a4532f424820e1d6;hpb=f9610a6d357f2ed79f2f18baa477244970f8b40f

diff --git a/doc/man1/haeredes.1 b/doc/man1/haeredes.1
index 900b4c6..197b7e8 100644
--- a/doc/man1/haeredes.1
+++ b/doc/man1/haeredes.1
@@ -91,6 +91,28 @@ example, to use 10 threads,
 .nf
 $ haeredes [OPTIONS] [DELEGATES] \fI+RTS -N10\fR
 .fi
+.SH DNS ERRORS
+.P
+There are three types of DNS errors that can occur:
+.nr step 1 1
+.IP \n[step] 2
+Timeouts. If the query times out, we don't get an answer back. The
+timeout can be adjusted with the \fB\-\-timeout\fR flag.
+.IP \n+[step]
+Sequence number mismatches. Every DNS query is sent with a sequence
+number; if the response has a different sequence number than the one
+we sent, something is wrong (foul play, or a bug somewhere in the
+stack).
+.IP \n+[step]
+Unexpected RDATA. If we ask for an \fIA\fR record, we expect to get a
+response for an \fIA\fR record. If we get something else -- well,
+something went wrong.
+.P
+Haeredes is designed to ignore these errors. A timeout or bad response
+to a query is not an indication that something is wrong with the DNS
+for the supplied domains. There might be something else wrong with
+your (caching/recursive) DNS infrastructure, but it isn't one of the
+problems that Haeredes is designed to detect.
 .SH OPTIONS
 
 .IP \fB\-\-no\-append\-root\fR,\ \fB-n\fR
@@ -109,7 +131,7 @@ Make sure example.com has the expected name servers,
 [ab].iana-servers.net:
 
 .nf
-.I $ haeredes a.iana-servers.net b.iana-servers.net <<< \(dqexample.com\(dq
+.I $ echo \(dqexample.com\(dq | haeredes a.iana-servers.net b.iana-servers.net
 .fi
 
 .IP \[bu] 2
@@ -118,9 +140,8 @@ must remember to supply the trailing dot yourself. Otherwise, you'll
 get false positives.
 
 .nf
-.I $ haeredes \-\-no\-append\-root \\\\
-.I "          a.iana-servers.net b.iana-servers.net" \\\\
-.I "          <<< \(dqexample.com\(dq"
+.I $ echo \(dqexample.com\(dq | \\\\
+.I "    haeredes \-\-no\-append\-root a.iana-servers.net b.iana-servers.net"
 Domain \(dqexample.com\(dq delegates somewhere else:
 \(dqb.iana-servers.net.\(dq \(dqa.iana-servers.net.\(dq
 .fi
@@ -129,24 +150,34 @@ Check orlitzky.com against the expected name servers, using
 a root nameserver (this checks the registrar configuration):
 
 .nf
-.I $ haeredes --server d.gtld-servers.net dns1.viabit.com dns2.viabit.com \\\\
-.I "           <<< \(dqorlitzky.com\(dq"
+.I $ echo \(dqorlitzky.com\(dq | \\\\
+.I "    haeredes --server d.gtld-servers.net" \\\\
+.I "    dns1.viabit.com dns2.viabit.com"
 .fi
 .IP \[bu]
 Check orlitzky.com against only one of the expected two nameservers:
 
 .nf
-.I $ haeredes dns1.viabit.com <<< \(dqorlitzky.com\(dq
+.I $ echo \(dqorlitzky.com\(dq | haeredes dns1.viabit.com
 Domain \(dqorlitzky.com.\(dq delegates somewhere else: \
 \(dqdns2.viabit.com.\(dq
 .fi
 .IP \[bu]
 Check a nonexistent domain (we provide no delegates, since we
-know .invalid will not be delegated):
+know .doesnt-exist will not be delegated):
+
+.nf
+.I $ echo \(dqfoo.doesnt-exist\(dq | haeredes
+Domain \(dqfoo.doesnt-exist.\(dq not delegated.
+.fi
+.IP \[bu]
+Set the timeout to one second, and query a nonexistent
+nameserver. This should result in a timeout, which will be ignored per
+the discussion in \fBDNS ERRORS\fR:
 
 .nf
-.I $ haeredes <<< \(dqexample.invalid\(dq
-Domain \(dqexample.invalid.\(dq not delegated.
+.I $ echo \(dqexample.com\(dq | \\\\
+.I "    haeredes --timeout=1 --server 10.1.46.12 ns1.example.com"
 .fi
 .SH BUGS
 .P