.TH djbdns-logparse 1
.SH NAME
-djbdns-logparse \- Convert tinydns and dnscache logs to human-readable form
+djbdns-logparse \- make tinydns and dnscache logs human-readable
.SH SYNOPSIS
+.SY djbdns-logparse
+.OP LOGFILE ...
+.YS
+
+.SY djbdns-logparse
+.B \-h
+.SY djbdns-logparse
+.B \-\-help
+.YS
-\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
+Tinydns and dnscache are two daemons in the djbdns suite. Both 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:
+Read the current dnscache log from stdin:
-.nf
+.EX
.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: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
+.EE
+
+Read all archived tinydns logs by filename:
+
+.EX
+.I $ djbdns-logparse /var/tinydns/log/main/*.s | head -n 10
+2022-09-14 19:26:41.300364500 sent response to 192.168.0.46:53969 (id 35830): aaaa ipv6.example.com
+2022-09-14 19:26:41.487751500 sent response to 192.168.1.71:20039 (id 1659): a example.net
+2022-09-14 19:26:41.508978500 sent response to 192.168.1.71:48252 (id 21909): aaaa example.net
+2022-09-14 19:26:41.627669500 sent response to 192.168.0.139:30527 (id 43254): a dns3.example.com
+2022-09-14 19:26:41.668888500 sent response to 192.168.0.139:64880 (id 33302): a dns.example.com
+2022-09-14 19:26:41.882769500 sent response to 10.0.1.194:51020 (id 5411): aaaa example.org
+2022-09-14 19:26:42.135118500 dropped query (no authority) from 10.10.10.48:53220 (id 41583): a www.invalid
+2022-09-14 19:26:42.254312500 sent response to 172.17.29.1:3079 (id 54381): aaaa mail2.example.com
+2022-09-14 19:26:42.268802500 sent response to 172.17.30.135:38498 (id 57389): a dns2.example.com
+2022-09-14 19:26:42.686389500 dropped query (no authority) from 172.20.0.57:20491 (id 43936): any localhost
+.EE
+
.SH OPTIONS
-.IP \fB\-\-help\fR,\ \fB\-h\fR
+.TP
+.B \-\-help, \-h
Display detailed program usage.
.SH TRANSFORMATIONS
+A number of transformations are applied to the raw logs. Some are
+specific to tinydns, others are specific to dnscache, and some apply
+to both. In explaining these, we borrow terminology from the following:
+
+.IP \(bu 2
+.UR https://www.dqd.com/~mayoff/notes/djbdns/tinydns-log.html
+Rob Mayoff's notes on the tinydns log file format
+.UE
+.IP \(bu
+.UR https://www.dqd.com/~mayoff/notes/djbdns/dnscache-log.html
+Rob Mayoff's notes on the dnscache log file format
+.UE
+
+.P
The following transformations are common to both daemons' logs:
.IP \(bu 2
The leading timestamps are piped through the
-\fBtai64nlocal\fR program.
+\fBtai64nlocal\fR program from DJB's daemontools.
.IP \(bu
IPv4 addresses are converted from hexadecimal strings to decimal
dotted-quads; for example \(dq7f000001\(dq becomes \(dq127.0.0.1\(dq.
\(dq0000:0000:0000:0000:0000:ffff:7f00:0001\(dq.
.IP \(bu
Port numbers are converted from hexedecimal to decimal.
+.IP \(bu
+The query type id is converted to the corresponding RFC-defined type
+name, as in https://en.wikipedia.org/wiki/List_of_DNS_record_types.
+While dnscache logs the id in decimal, tinydns records it in
+hexadecimal (for example, \(dq001c\(dq) necessitating a hex->decimal
+conversion before we can look up its name.
+
.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
+If a query was dropped, the symbol (\-, I, C, /) indicating the reason
+is converted to English and wrapped in parentheses:
+.RS
+.TP
+.B \-
+(no authority)
+.TP
+.B I
+(invalid query)
+.TP
+.B C
+(invalid class)
+.TP
+.B /
+(couldn't parse)
+.RE
+.IP \(bu
+The request id (which was chosen by the client and sent with its
+request) is split off the end of the \(dqip:port:id\(dq triplet and is
+placed in parentheses with the word \(dqid\(dq, like \(dq(id
+8675309)\(dq.
+.P
+The following transformations are specific to dnscache:
+.IP \(bu 2
+In \(dqquery\(dq entries, the third component of the
+clientip:clientport:id triplet is a decimal packet identifier chosen
+and sent by the client. We separate it from the client ip:port, and
+put it in parentheses, like \(dq(id 8675309)\(dq.
+.IP \(bu
+We prefix each decimal TTL with \(dqTTL=\(dq so that you know what
+the magic number stands for.
+.IP \(bu
+All serial numbers are prefixed with a hash sign. This is the only
+field that we do this to, so if you see a number with a \(dq#\(dq in
+front of it, that's a serial number.
+.IP \(bu
+In a \(dqstats\(dq entry, the four decimal statistics are prefixed
+with what they represent. Specifically, the prefixes are
+\(dqcount=\(dq, \(dqmotion=\(dq, \(dqudp-active=\(dq, and
+\(dqtcp-active=\(dq. You may want to read
+.UR http://cr.yp.to/djbdns/cachesize.html
+DJB's explanation of the \(dqmotion\(dq field
+.UE
+.
+.IP \(bu
+The hex data logged from a TXT query response is decoded to ASCII.
+.IP \(bu
+The decimal \(dqgluelessness\(dq field is prefixed by \(dqg=\(dq.
+You may want to read
+.UR http://cr.yp.to/djbdns/notes.html#gluelessness
+DJB's explanation of gluelessness.
+.UE
.SH BUGS
-Send bugs to michael@orlitzky.com.
+Send bugs to
+.MT michael@orlitzky.com
+Michael Orlitzky
+.ME
projects / djbdns-logparse.git / blobdiff