doc/man1/djbdns-logparse.1: start a man page.

diff --git a/doc/man1/djbdns-logparse.1 b/doc/man1/djbdns-logparse.1
new file mode 100644 (file)
index 0000000..fbd4da0
--- /dev/null
+++ b/doc/man1/djbdns-logparse.1
@@ -0,0 +1,65 @@
+.TH djbdns-logparse 1
+
+.SH NAME
+djbdns-logparse \- Convert tinydns and dnscache logs to human-readable form
+.SH SYNOPSIS
+
+\fBdjbdns-logparse\fR [\fBLOGFILE\fR [\fBLOGFILE\fR...]]
+.SH INPUT
+.P
+Each \fILOGFILE\fR should be a tinydns or dnscache log file; if none
+are given, the program will read from stdin.
+.SH DESCRIPTION
+.P
+Both tinydns and dnscache (two daemons in the djbdns suite) keep logs
+of their activity, but only in an undocumented machine-oriented
+format. The goal of djbdns-logparse is to parse those logs and make
+them human-readable with a minimal amount of interference.
+.SH EXAMPLES
+.P
+Reading the current dnscache log from stdin:
+
+.nf
+.I $ djbdns-logparse < /var/dnscache/log/main/current
+2022-09-19 10:47:12.953666500 starting
+2022-09-19 10:47:33.084125500 query #1 127.0.0.1:44339 (id 9929) a www.example.com.
+2022-09-19 10:47:33.084128500 tx g=0 a www.example.com. . 192.168.1.1
+2022-09-19 10:47:33.099298500 rr 192.168.1.1 TTL=40285 a www.example.com. 93.184.216.34
+2022-09-19 10:47:33.099300500 stats count=1 motion=43 udp-active=1 tcp-active=0
+2022-09-19 10:47:33.099377500 sent #1 49
+2022-09-19 10:47:37.913287500 query #2 127.0.0.1:47516 (id 14409) txt www.example.com.
+2022-09-19 10:47:37.913380500 tx g=0 txt www.example.com. . 192.168.1.1
+2022-09-19 10:47:37.931252500 rr 192.168.1.1 TTL=86400 txt www.example.com. 11:"v=spf1 -all"
+2022-09-19 10:47:37.931255500 rr 192.168.1.1 TTL=86400 txt www.example.com. 32:"wgyf8z8cgvm2qmxpnbnldrcltvk4xqf..."
+2022-09-19 10:47:37.931297500 stats count=2 motion=131 udp-active=1 tcp-active=0
+2022-09-19 10:47:37.931332500 sent #2 102
+.fi
+.SH OPTIONS
+
+.IP \fB\-\-help\fR,\ \fB\-h\fR
+Display detailed program usage.
+.SH TRANSFORMATIONS
+
+The following transformations are common to  both daemons' logs:
+.IP \(bu 2
+The leading timestamps are piped through the
+\fBtai64nlocal\fR program.
+.IP \(bu
+IPv4 addresses are converted from hexadecimal strings to decimal
+dotted-quads; for example \(dq7f000001\(dq becomes \(dq127.0.0.1\(dq.
+IPv6 addresses simply have colons interspersed, so that
+\(dq00000000000000000000ffff7f000001\(dq would become
+\(dq0000:0000:0000:0000:0000:ffff:7f00:0001\(dq.
+.IP \(bu
+Port numbers are converted from hexedecimal to decimal.
+.P
+The following transformations are specific to tinydns:
+.IP \(bu 2
+The hexadecimal query type id (for example, \(dq001c\(dq) is converted
+first to decimal, and then to the corresponding RFC-defined type name,
+as in https://en.wikipedia.org/wiki/List_of_DNS_record_types
+
+
+.SH BUGS
+
+Send bugs to michael@orlitzky.com.