Sort output to fix random breakage in the test suite.
[haeredes.git] / doc / man1 / haeredes.1
1 .TH haeredes 1
2
3 .SH NAME
4 haeredes \- Confirm delegation of NS and MX records.
5 .SH SYNOPSIS
6
7 \fBhaeredes\fR [\fIOPTIONS\fR] [\fIDELEGATES\fR]
8 .SH INPUT
9 .P
10 A list of domains, separated by whitespace.
11 .SH OUTPUT
12 .P
13 A list of domains which don't have the supplied (expected) delegates
14 listed as their NS/MX records.
15 .SH DESCRIPTION
16 .P
17 Haeredes is primarily useful for ISP network administrators. Customers
18 will occasionally decide to switch hosts without alerting the current
19 host; this can cause two problems.
20 .P
21 With NS records, the previous host (at the very least) keeps hosting a
22 DNS zone that does nothing. If that host uses their authoritative
23 nameserver as a caching lookup server as well, it may return
24 incorrect results to queries about the domain in question.
25 .P
26 For MX records, the situation is slightly worse. Most mail servers
27 will immediately accept mail for which the server thinks it is the
28 ultimate destination. If a mail server is configured as the
29 destination for a domain, but it is not the MX for that domain, then
30 mail submitted to that server may possibly be lost. It is therefore
31 important to remove domains from the old mail host as soon as the MX
32 record is changed.
33 .P
34 Haeredes can alert administrators when NS/MX records are changed.
35 .SH NORMALIZATION
36 .P
37 By default, domain/hostnames given will be normalized in two ways:
38 .IP \[bu] 2
39 All names will be lowercased.
40
41 .IP \[bu]
42 All names will have a trailing dot (the DNS root) appended if one is
43 not present. This can be controlled with the
44 \fB\-\-no\-append\-root\fR flag.
45 .SH QUERY RESULTS
46 .P
47 When Haeredes makes a query for an MX record, the result is parsed
48 from the \(dqanswer\(dq section of the response. This is
49 straightforward.
50 .P
51 For NS records, however, there are two sections that may contain
52 results. If you query the authoritative nameservers for example.com,
53 they will return the response in the \(dqanswer\(dq section, as with
54 MX records:
55
56 .nf
57 .I $ dig +short @a.iana-servers.net example.com NS
58 b.iana-servers.net.
59 a.iana-servers.net.
60 .fi
61 .P
62 However, if you ask a root server, they will return the response in
63 another section, called \(dqauthority\(dq. The \(dqanswer\(dq section
64 is empty:
65
66 .nf
67 .I $ dig +short @a.gtld-servers.net example.com NS
68 .fi
69 .P
70 We have to request the \(dqauthority\(dq section explicitly:
71
72 .nf
73 .I $ dig +noall +authority @a.gtld-servers.net example.com NS
74 example.com. 172800 IN NS a.iana-servers.net.
75 example.com. 172800 IN NS b.iana-servers.net.
76 .fi
77 .P
78 Given Haeredes' use case, it is useful to combine the two. You can
79 query a root server to check the registrar data, or a recursive
80 resolver to check the data on the authoritative nameservers.
81 .P
82 So that's what we do. In NS mode, Haeredes will check both the
83 \(dqanswer\(dq and \(dqauthority\(dq sections for results.
84 .SH PARALLEL QUERIES
85 .P
86 Haeredes can use multiple threads to perform its queries. It will use
87 a number of threads equal to the number of processors available to the
88 GHC runtime. This can be changed with the \fI+RTS \-N\fR flag. For
89 example, to use 10 threads,
90
91 .nf
92 $ haeredes [OPTIONS] [DELEGATES] \fI+RTS -N10\fR
93 .fi
94 .SH DNS ERRORS
95 .P
96 There are three types of DNS errors that can occur:
97 .nr step 1 1
98 .IP \n[step] 2
99 Timeouts. If the query times out, we don't get an answer back. The
100 timeout can be adjusted with the \fB\-\-timeout\fR flag.
101 .IP \n+[step]
102 Sequence number mismatches. Every DNS query is sent with a sequence
103 number; if the response has a different sequence number than the one
104 we sent, something is wrong (foul play, or a bug somewhere in the
105 stack).
106 .IP \n+[step]
107 Unexpected RDATA. If we ask for an \fIA\fR record, we expect to get a
108 response for an \fIA\fR record. If we get something else -- well,
109 something went wrong.
110 .P
111 Haeredes is designed to ignore these errors. A timeout or bad response
112 to a query is not an indication that something is wrong with the DNS
113 for the supplied domains. There might be something else wrong with
114 your (caching/recursive) DNS infrastructure, but it isn't one of the
115 problems that Haeredes is designed to detect.
116 .SH OPTIONS
117
118 .IP \fB\-\-no\-append\-root\fR,\ \fB-n\fR
119 Don't append a trailing dot to any DNS names. If you know what you're
120 doing, this can be used to check relative results. Otherwise, it will
121 probably just lead to false positives.
122 .IP \fB\-\-server\fR,\ \fB-s\fR
123 Use the given DNS server rather than the resolvers listed in
124 /etc/resolv.conf. Either an IP address or a hostname will work.
125 .IP \fB\-\-timeout\fR,\ \fB-t\fR
126 The number of seconds to wait for an answer from DNS (default: 15).
127 .SH EXAMPLES
128
129 .IP \[bu] 2
130 Make sure example.com has the expected name servers,
131 [ab].iana-servers.net:
132
133 .nf
134 .I $ echo \(dqexample.com\(dq | haeredes a.iana-servers.net b.iana-servers.net
135 .fi
136
137 .IP \[bu] 2
138 If you use \-\-no\-append\-root and your nameservers are rooted, you
139 must remember to supply the trailing dot yourself. Otherwise, you'll
140 get false positives.
141
142 .nf
143 .I $ echo \(dqexample.com\(dq | \\\\
144 .I " haeredes \-\-no\-append\-root a.iana-servers.net b.iana-servers.net"
145 Domain \(dqexample.com\(dq delegates somewhere else:
146 \(dqa.iana-servers.net.\(dq \(dqb.iana-servers.net.\(dq
147 .fi
148 .IP \[bu]
149 Check orlitzky.com against the expected name servers, using
150 a root nameserver (this checks the registrar configuration):
151
152 .nf
153 .I $ echo \(dqorlitzky.com\(dq | \\\\
154 .I " haeredes --server d.gtld-servers.net" \\\\
155 .I " dns1.viabit.com dns2.viabit.com"
156 .fi
157 .IP \[bu]
158 Check orlitzky.com against only one of the expected two nameservers:
159
160 .nf
161 .I $ echo \(dqorlitzky.com\(dq | haeredes dns1.viabit.com
162 Domain \(dqorlitzky.com.\(dq delegates somewhere else: \
163 \(dqdns2.viabit.com.\(dq
164 .fi
165 .IP \[bu]
166 Check a nonexistent domain (we provide no delegates, since we
167 know .doesnt-exist will not be delegated):
168
169 .nf
170 .I $ echo \(dqfoo.doesnt-exist\(dq | haeredes
171 Domain \(dqfoo.doesnt-exist.\(dq not delegated.
172 .fi
173 .IP \[bu]
174 Set the timeout to one second, and query a nonexistent
175 nameserver. This should result in a timeout, which will be ignored per
176 the discussion in \fBDNS ERRORS\fR:
177
178 .nf
179 .I $ echo \(dqexample.com\(dq | \\\\
180 .I " haeredes --timeout=1 --server 10.1.46.12 ns1.example.com"
181 .fi
182 .SH BUGS
183 .P
184 Send bugs to michael@orlitzky.com.