From: Michael Orlitzky <michael@orlitzky.com>
Date: Thu, 22 Sep 2022 00:56:57 +0000 (-0400)
Subject: doc/man1/djbdns-logparse.1: document dnscache transformations.
X-Git-Tag: 0.0.1~14
X-Git-Url: http://gitweb.michael.orlitzky.com/?a=commitdiff_plain;ds=sidebyside;h=3e9a04d99eee9fc1e4bd28e85300770fa5f1168e;p=djbdns-logparse.git

doc/man1/djbdns-logparse.1: document dnscache transformations.
---

diff --git a/doc/man1/djbdns-logparse.1 b/doc/man1/djbdns-logparse.1
index 580f046..05e6c75 100644
--- a/doc/man1/djbdns-logparse.1
+++ b/doc/man1/djbdns-logparse.1
@@ -19,8 +19,8 @@ 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
@@ -97,7 +97,8 @@ 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.
+conversion before we can look up its name. Decimal numbers with
+no entry in the id->name mapping are output as-is.
 
 .P
 The following transformations are specific to tinydns:
@@ -124,6 +125,37 @@ 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