X-Git-Url: http://gitweb.michael.orlitzky.com/?p=haeredes.git;a=blobdiff_plain;f=doc%2Fman1%2Fhaeredes.1;h=31eeff72981584441d4d998a2ebc6cfb25f0d75f;hp=facf5cc1f3d076bd1df3bd5f6a4d6816dcfae692;hb=7cc26ab4bfa90c4abe0c741d5a3eaf575544466a;hpb=e8fe3d4c76b719d256a3c04d462819cd98218111

diff --git a/doc/man1/haeredes.1 b/doc/man1/haeredes.1
index facf5cc..31eeff7 100644
--- a/doc/man1/haeredes.1
+++ b/doc/man1/haeredes.1
@@ -32,11 +32,64 @@ important to remove domains from the old mail host as soon as the MX
 record is changed.
 .P
 Haeredes can alert administrators when NS/MX records are changed.
+.SH NORMALIZATION
+.P
+By default, domain/hostnames given will be normalized in two ways:
+.IP \[bu] 2
+All names will be lowercased.
+
+.IP \[bu]
+All names will have a trailing dot (the DNS root) appended if one is
+not present. This can be controlled with the
+\fB\-\-no\-append\-root\fR flag.
+.SH QUERY RESULTS
+.P
+When Haeredes makes a query for an MX record, the result is parsed
+from the \(dqanswer\(dq section of the response. This is
+straightforward.
+.P
+For NS records, however, there are two sections that may contain
+results. If you query the authoritative nameservers for example.com,
+they will return the response in the \(dqanswer\(dq section, as with
+MX records:
+
+.nf
+.I $ dig +short @a.iana-servers.net example.com NS
+b.iana-servers.net.
+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:
+
+.nf
+.I $ dig +short @a.gtld-servers.net example.com NS
+.fi
+.P
+We have to request the \(dqauthority\(dq section explicitly:
+
+.nf
+.I $ dig +noall +authority @a.gtld-servers.net example.com NS
+example.com.		172800	IN	NS	a.iana-servers.net.
+example.com.		172800	IN	NS	b.iana-servers.net.
+.fi
+.P
+Given Haeredes' use case, it is useful to combine the two. You can
+query a root server to check the registrar data, or a recursive
+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.
 .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.
+/etc/resolv.conf. Either an IP address or a hostname will work.
 .SH EXAMPLES
 
 .IP \[bu] 2
@@ -48,10 +101,10 @@ Make sure example.com has the expected name servers,
 .fi
 .IP \[bu]
 Check orlitzky.com against the expected name servers, using
-d.gtld-servers.net:
+a root nameserver (this checks the registrar configuration):
 
 .nf
-.I $ haeredes --server 199.7.91.13 dns1.viabit.com dns2.viabit.com \\\\
+.I $ haeredes --server d.gtld-servers.net dns1.viabit.com dns2.viabit.com \\\\
 .I "           <<< \(dqorlitzky.com\(dq"
 .fi
 .IP \[bu]