Sort output to fix random breakage in the test suite.

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

diff --git a/doc/man1/haeredes.1 b/doc/man1/haeredes.1
index 2c8508ef36afb5a37a7f39b569064a0496f9787a..6ea57eb067d63a9831075b93c7297579b3ecd752 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


@@ -95,7 +131,7 @@ Make sure example.com has the expected name servers,
 [ab].iana-servers.net:
 
 .nf
 [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
 .fi
 
 .IP \[bu] 2


@@ -104,35 +140,44 @@ must remember to supply the trailing dot yourself. Otherwise, you'll
 get false positives.
 
 .nf
 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:
 Domain \(dqexample.com\(dq delegates somewhere else:

-\(dqb.iana-servers.net.\(dq \(dqa.iana-servers.net.\(dq
+\(dqa.iana-servers.net.\(dq \(dqb.iana-servers.net.\(dq

 .fi
 .IP \[bu]
 Check orlitzky.com against the expected name servers, using
 a root nameserver (this checks the registrar configuration):
 
 .nf
 .fi
 .IP \[bu]
 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
 .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
 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
 
 .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
 .fi
 .SH BUGS
 .P