Fix an example, loosen version bounds, and bump to v0.4.2.

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

diff --git a/doc/man1/haeredes.1 b/doc/man1/haeredes.1
index 2c8508ef36afb5a37a7f39b569064a0496f9787a..97c47b844e81c34598cfc88e690e4dd203425913 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,6 +81,38 @@ 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
 .SH OPTIONS
 
 .IP \fB\-\-no\-append\-root\fR,\ \fB-n\fR


@@ -88,6 +122,8 @@ probably just lead to false positives.
 .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


@@ -128,11 +164,20 @@ Domain \(dqorlitzky.com.\(dq delegates somewhere else: \
 .fi
 .IP \[bu]
 Check a nonexistent domain (we provide no delegates, since we
 .fi
 .IP \[bu]
 Check a nonexistent domain (we provide no delegates, since we

-know .invalid will not be delegated):
+know .bar will not be delegated):
+
+.nf
+.I $ haeredes <<< \(dqfoo.bar\(dq
+Domain \(dqfoo.bar.\(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
 
 .nf

-.I $ haeredes <<< \(dqexample.invalid\(dq
-Domain \(dqexample.invalid.\(dq not delegated.
+.I $ haeredes --timeout=1 --server 10.1.46.12 ns1.example.com \\\\
+.I "           <<< \(dqexample.com\(dq"

 .fi
 .SH BUGS
 .P
 .fi
 .SH BUGS
 .P