From 2478b6d707ffb78e796271036090a15623d48e72 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Fri, 20 Feb 2026 20:48:59 -0500 Subject: [PATCH] doc/README.rst: add reStructuredText README This is like, half of the man page. But it will be nice to have something human-readable for Codeberg. --- doc/README.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 doc/README.rst diff --git a/doc/README.rst b/doc/README.rst new file mode 100644 index 0000000..d4d5df0 --- /dev/null +++ b/doc/README.rst @@ -0,0 +1,83 @@ +Introduction +============ + +*This is only a brief introduction, see the man page for a detailed +overview.* + +Haeredes alerts you when NS/MX records are changed. + +This is primarily useful for hosting providers. Customers will +occasionally switch hosts without alerting the current one, leading to +two problems: + +* NS records: the previous host keeps hosting a DNS zone that does + nothing. If that host uses their authoritative nameserver as a + caching lookup server as well, it may return incorrect results to + queries about the domain in question. + +* MX records: most mail servers will immediately accept mail for which + the server thinks it is the destination. If a mail server is + configured as the destination for a domain, but it is not the MX for + that domain, mail submitted to that server can be "lost." It is + therefore important to remove domains from the old mail host as soon + as the MX record is changed. + +Haeredes can alert you when these NS/MX records are changed. + + +Usage +===== + +.. code-block:: console + + $ haeredes [OPTIONS] [DELEGATES] + + +Examples +======== + +Make sure example.com has the expected name servers, [ab].iana-servers.net: + +.. code-block:: console + + $ echo "example.com" | haeredes a.iana-servers.net b.iana-servers.net + +Check orlitzky.com using a root nameserver (this checks the registrar +configuration): + +.. code-block:: console + + $ echo "orlitzky.com" | haeredes --server d.gtld-servers.net dns1.viabit.com + Domain "orlitzky.com." delegates somewhere else: "dns2.viabit.com." + +In this case, we are correctly warned about the second nameserver that +we forgot to mention. + + +Requirements +============ + +All of the software dependencies are listed in the ``haeredes.cabal`` +file. Just use cabal to build it. + + +Installation +============ + +Cabal handles the build, so do whatever you normally do to install +cabal packages. If you just want to install it for your user, + +.. code-block:: console + + $ runghc Setup.hs configure --user + $ runghc Setup.hs build + $ runghc Setup.hs install + +should do it. + + +Bugs +==== + +Email them to me at michael@orlitzky.com, or report them on `Codeberg +`_. -- 2.51.0