Add the DNS ERRORS section to the man page, in preparation for the dns library bump.

[haeredes.git] / doc / man1 / haeredes.1

diff --git a/doc/man1/haeredes.1 b/doc/man1/haeredes.1
index 31eeff72981584441d4d998a2ebc6cfb25f0d75f..a614993342201c16d6da9e68baf227922d97b315 100644 (file)
--- a/doc/man1/haeredes.1
+++ b/doc/man1/haeredes.1
@@ -59,7 +59,9 @@ b.iana-servers.net.
 a.iana-servers.net.
 .fi
 .P
 a.iana-servers.net.
 .fi
 .P

-However, if you ask a root server, they will return the response in another section, called \(dqauthority\(dq. The \(dqanswer\(dq section is empty:
+However, if you ask a root server, they will return the response in
+another section, called \(dqauthority\(dq. The \(dqanswer\(dq section
+is empty:

 
 .nf
 .I $ dig +short @a.gtld-servers.net example.com NS
 
 .nf
 .I $ dig +short @a.gtld-servers.net example.com NS


@@ -79,17 +81,49 @@ resolver to check the data on the authoritative nameservers.
 .P
 So that's what we do. In NS mode, Haeredes will check both the
 \(dqanswer\(dq and \(dqauthority\(dq sections for results.
 .P
 So that's what we do. In NS mode, Haeredes will check both the
 \(dqanswer\(dq and \(dqauthority\(dq sections for results.

+.SH PARALLEL QUERIES
+.P
+Haeredes can use multiple threads to perform its queries. It will use
+a number of threads equal to the number of processors available to the
+GHC runtime. This can be changed with the \fI+RTS \-N\fR flag. For
+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
 Don't append a trailing dot to any DNS names. If you know what you're
 doing, this can be used to check relative results. Otherwise, it will
 probably just lead to false positives.
 .SH OPTIONS
 
 .IP \fB\-\-no\-append\-root\fR,\ \fB-n\fR
 Don't append a trailing dot to any DNS names. If you know what you're
 doing, this can be used to check relative results. Otherwise, it will
 probably just lead to false positives.

-.SH EXAMPLES
-

 .IP \fB\-\-server\fR,\ \fB-s\fR
 Use the given DNS server rather than the resolvers listed in
 /etc/resolv.conf. Either an IP address or a hostname will work.
 .IP \fB\-\-server\fR,\ \fB-s\fR
 Use the given DNS server rather than the resolvers listed in
 /etc/resolv.conf. Either an IP address or a hostname will work.

+.IP \fB\-\-timeout\fR,\ \fB-t\fR
+The number of seconds to wait for an answer from DNS (default: 15).

 .SH EXAMPLES
 
 .IP \[bu] 2
 .SH EXAMPLES
 
 .IP \[bu] 2


@@ -99,6 +133,19 @@ Make sure example.com has the expected name servers,
 .nf
 .I $ haeredes a.iana-servers.net b.iana-servers.net <<< \(dqexample.com\(dq
 .fi
 .nf
 .I $ haeredes a.iana-servers.net b.iana-servers.net <<< \(dqexample.com\(dq
 .fi

+
+.IP \[bu] 2
+If you use \-\-no\-append\-root and your nameservers are rooted, you
+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"
+Domain \(dqexample.com\(dq delegates somewhere else:
+\(dqb.iana-servers.net.\(dq \(dqa.iana-servers.net.\(dq
+.fi

 .IP \[bu]
 Check orlitzky.com against the expected name servers, using
 a root nameserver (this checks the registrar configuration):
 .IP \[bu]
 Check orlitzky.com against the expected name servers, using
 a root nameserver (this checks the registrar configuration):