doc/man1/djbdns-logparse.1

   1 .TH djbdns-logparse 1
   2
   3 .SH NAME
   4 djbdns-logparse \- make tinydns and dnscache logs human-readable
   5 .SH SYNOPSIS
   6 .SY djbdns-logparse
   7 .OP LOGFILE ...
   8 .YS
   9
  10 .SY djbdns-logparse
  11 .B \-h
  12 .SY djbdns-logparse
  13 .B \-\-help
  14 .YS
  15
  16 .SH INPUT
  17 .P
  18 Each \fILOGFILE\fR should be a tinydns or dnscache log file; if none
  19 are given, the program will read from stdin.
  20 .SH DESCRIPTION
  21 .P
  22 Tinydns and dnscache are two daemons in the djbdns suite. Both keep
  23 logs of their activity, but only in an undocumented machine-oriented
  24 format. The goal of djbdns-logparse is to parse those logs and make
  25 them human-readable with a minimal amount of interference.
  26 .SH EXAMPLES
  27 .P
  28 Read the current dnscache log from stdin:
  29
  30 .EX
  31 .I $ djbdns-logparse < /var/dnscache/log/main/current
  32 2022-09-19 10:47:12.953666500 starting
  33 2022-09-19 10:47:33.084125500 query #1 127.0.0.1:44339 (id 9929) a www.example.com.
  34 2022-09-19 10:47:33.084128500 tx g=0 a www.example.com. . 192.168.1.1
  35 2022-09-19 10:47:33.099298500 rr 192.168.1.1 TTL=40285 a www.example.com. 93.184.216.34
  36 2022-09-19 10:47:33.099300500 stats count=1 motion=43 udp-active=1 tcp-active=0
  37 2022-09-19 10:47:33.099377500 sent #1 49
  38 2022-09-19 10:47:37.913287500 query #2 127.0.0.1:47516 (id 14409) txt www.example.com.
  39 2022-09-19 10:47:37.913380500 tx g=0 txt www.example.com. . 192.168.1.1
  40 2022-09-19 10:47:37.931252500 rr 192.168.1.1 TTL=86400 txt www.example.com. 11:"v=spf1 -all"
  41 2022-09-19 10:47:37.931255500 rr 192.168.1.1 TTL=86400 txt www.example.com. 32:"wgyf8z8cgvm2qmxpnbnldrcltvk4xqf..."
  42 2022-09-19 10:47:37.931297500 stats count=2 motion=131 udp-active=1 tcp-active=0
  43 2022-09-19 10:47:37.931332500 sent #2 102
  44 .EE
  45
  46 Read all archived tinydns logs by filename:
  47
  48 .EX
  49 .I $ djbdns-logparse /var/tinydns/log/main/*.s | head -n 10
  50 2022-09-14 19:26:41.300364500 sent response to 192.168.0.46:53969 (id 35830): aaaa ipv6.example.com
  51 2022-09-14 19:26:41.487751500 sent response to 192.168.1.71:20039 (id 1659): a example.net
  52 2022-09-14 19:26:41.508978500 sent response to 192.168.1.71:48252 (id 21909): aaaa example.net
  53 2022-09-14 19:26:41.627669500 sent response to 192.168.0.139:30527 (id 43254): a dns3.example.com
  54 2022-09-14 19:26:41.668888500 sent response to 192.168.0.139:64880 (id 33302): a dns.example.com
  55 2022-09-14 19:26:41.882769500 sent response to 10.0.1.194:51020 (id 5411): aaaa example.org
  56 2022-09-14 19:26:42.135118500 dropped query (no authority) from 10.10.10.48:53220 (id 41583): a www.invalid
  57 2022-09-14 19:26:42.254312500 sent response to 172.17.29.1:3079 (id 54381): aaaa mail2.example.com
  58 2022-09-14 19:26:42.268802500 sent response to 172.17.30.135:38498 (id 57389): a dns2.example.com
  59 2022-09-14 19:26:42.686389500 dropped query (no authority) from 172.20.0.57:20491 (id 43936): any localhost
  60 .EE
  61
  62 .SH OPTIONS
  63
  64 .TP
  65 .B \-\-help, \-h
  66 Display detailed program usage.
  67 .SH TRANSFORMATIONS
  68
  69 A number of transformations are applied to the raw logs. Some are
  70 specific to tinydns, others are specific to dnscache, and some apply
  71 to both. In explaining these, we borrow terminology from the following:
  72
  73 .IP \(bu 2
  74 .UR https://www.dqd.com/~mayoff/notes/djbdns/tinydns-log.html
  75 Rob Mayoff's notes on the tinydns log file format
  76 .UE
  77 .IP \(bu
  78 .UR https://www.dqd.com/~mayoff/notes/djbdns/dnscache-log.html
  79 Rob Mayoff's notes on the dnscache log file format
  80 .UE
  81
  82 .P
  83 The following transformations are common to  both daemons' logs:
  84 .IP \(bu 2
  85 The leading timestamps are piped through the
  86 \fBtai64nlocal\fR program.
  87 .IP \(bu
  88 IPv4 addresses are converted from hexadecimal strings to decimal
  89 dotted-quads; for example \(dq7f000001\(dq becomes \(dq127.0.0.1\(dq.
  90 IPv6 addresses simply have colons interspersed, so that
  91 \(dq00000000000000000000ffff7f000001\(dq would become
  92 \(dq0000:0000:0000:0000:0000:ffff:7f00:0001\(dq.
  93 .IP \(bu
  94 Port numbers are converted from hexedecimal to decimal.
  95 .IP \(bu
  96 The query type id is converted to the corresponding RFC-defined type
  97 name, as in https://en.wikipedia.org/wiki/List_of_DNS_record_types.
  98 While dnscache logs the id in decimal, tinydns records it in
  99 hexadecimal (for example, \(dq001c\(dq) necessitating a hex->decimal
 100 conversion before we can look up its name.
 101
 102 .P
 103 The following transformations are specific to tinydns:
 104 .IP \(bu 2
 105 If a query was dropped, the symbol (\-, I, C, /) indicating the reason
 106 is converted to English and wrapped in parentheses:
 107 .RS
 108 .TP
 109 .B \-
 110 (no authority)
 111 .TP
 112 .B I
 113 (invalid query)
 114 .TP
 115 .B C
 116 (invalid class)
 117 .TP
 118 .B /
 119 (couldn't parse)
 120 .RE
 121 .IP \(bu
 122 The request id (which was chosen by the client and sent with its
 123 request) is split off the end of the \(dqip:port:id\(dq triplet and is
 124 placed in parentheses with the word \(dqid\(dq, like \(dq(id
 125 8675309)\(dq.
 126
 127 .P
 128 The following transformations are specific to dnscache:
 129 .IP \(bu 2
 130 In \(dqquery\(dq entries, the third component of the
 131 clientip:clientport:id triplet is a decimal packet identifier chosen
 132 and sent by the client. We separate it from the client ip:port, and
 133 put it in parentheses, like \(dq(id 8675309)\(dq.
 134 .IP \(bu
 135 We prefix each decimal TTL with \(dqTTL=\(dq so that you know what
 136 the magic number stands for.
 137 .IP \(bu
 138 All serial numbers are prefixed with a hash sign. This is the only
 139 field that we do this to, so if you see a number with a \(dq#\(dq in
 140 front of it, that's a serial number.
 141 .IP \(bu
 142 In a \(dqstats\(dq entry, the four decimal statistics are prefixed
 143 with what they represent. Specifically, the prefixes are
 144 \(dqcount=\(dq, \(dqmotion=\(dq, \(dqudp-active=\(dq, and
 145 \(dqtcp-active=\(dq. You may want to read
 146 .UR http://cr.yp.to/djbdns/cachesize.html
 147 DJB's explanation of the \(dqmotion\(dq field
 148 .UE
 149 .
 150 .IP \(bu
 151 The hex data logged from a TXT query response is decoded to ASCII.
 152 .IP \(bu
 153 The decimal \(dqgluelessness\(dq field is prefixed by \(dqg=\(dq.
 154 You may want to read
 155 .UR http://cr.yp.to/djbdns/notes.html#gluelessness
 156 DJB's explanation of gluelessness.
 157 .UE
 158
 159 .SH BUGS
 160
 161 Send bugs to
 162 .MT michael@orlitzky.com
 163 Michael Orlitzky
 164 .ME