doc/README: siphon the description and history from bin/djbdns-logparse.

[djbdns-logparse.git] / doc / README

diff --git a/doc/README b/doc/README
new file mode 100644 (file)
index 0000000..07e52b3
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,46 @@
+djbdns-logparse: convert tinydns and dnscache logs to human-readable form
+
+== What is it? ==
+
+djbdns is Daniel J. Bernstein's suite of DNS software from,
+
+  https://cr.yp.to/djbdns.html
+
+Two of its daemons, tinydns and dnscache, resolve DNS queries while
+simultaneously logging obscure gibberish to a file. For example, this
+is what tinydns logs if I request the 'A' record for www.example.com:
+
+  @4000000063227a320c4f3114 7f000001:9d61:be69 - 0001 www.example.com
+
+djbdns-logparse converts these into something that you can actually
+read. The line above gets turned into,
+
+  2022-09-14 21:04:40.206516500 dropped query (no authority) from
+  127.0.0.1:40289 (id 48745): a www.example.com
+
+and surely you agree that this is preferable.
+
+
+== Requirements ==
+
+There are only two:
+
+  a) python-3.6 or later, for f-strings support
+  b) the tai64nlocal program from djbdns in your PATH
+
+
+== History ==
+
+This is a modernish fork of Greg Ward's parse_djbdns_log program
+from,
+
+  https://www.gerg.ca/hacks/parse_djbdns_log
+
+The original was inspired by Faried Nawaz's dnscache log parser,
+
+      http://www.hungry.com/~fn/dnscache-log.pl.txt
+
+with heavy assistance from Rob Mayoff's documentation:
+
+  * https://www.dqd.com/~mayoff/notes/djbdns/tinydns-log.html
+  * https://www.dqd.com/~mayoff/notes/djbdns/dnscache-log.html