doc/README

   1 djbdns-logparse: make tinydns and dnscache logs human-readable
   2
   3 == What is it? ==
   4
   5 djbdns is Daniel J. Bernstein's suite of DNS software from,
   6
   7   https://cr.yp.to/djbdns.html
   8
   9 Two of its daemons, tinydns and dnscache, resolve DNS queries while
  10 simultaneously logging obscure gibberish to a file. For example, this
  11 is what tinydns logs if I request the 'A' record for www.example.com:
  12
  13   @4000000063227a320c4f3114 7f000001:9d61:be69 - 0001 www.example.com
  14
  15 djbdns-logparse converts these into something that you can actually
  16 read. The line above gets turned into,
  17
  18   2022-09-14 21:04:40.206516500 dropped query (no authority) from
  19   127.0.0.1:40289 (id 48745): a www.example.com
  20
  21 and surely you agree that this is preferable.
  22
  23
  24 == Usage ==
  25
  26 Either,
  27
  28   $ djbdns-logparse < logfile
  29
  30 or
  31
  32   $  djbdns-logparse log1 [log2 [log3 ...]]
  33
  34
  35 == Requirements ==
  36
  37 There are only two:
  38
  39   a) python-3.6 or later, for f-strings support
  40   b) the tai64nlocal program from DJB's daemontools on your PATH
  41
  42
  43 == History ==
  44
  45 This is a modernish fork of Greg Ward's parse_djbdns_log program
  46 from,
  47
  48   https://www.gerg.ca/hacks/parse_djbdns_log
  49
  50 The original was inspired by Faried Nawaz's dnscache log parser,
  51
  52       http://www.hungry.com/~fn/dnscache-log.pl.txt
  53
  54 with heavy assistance from Rob Mayoff's documentation:
  55
  56   * https://www.dqd.com/~mayoff/notes/djbdns/tinydns-log.html
  57   * https://www.dqd.com/~mayoff/notes/djbdns/dnscache-log.html
  58
  59
  60 == Tests ==
  61
  62 The (doctest) test suite can be run with either setuptools,
  63
  64   $ python setup.py test
  65
  66 or using tox,
  67
  68   $ tox
  69
  70 Or, you can just run them manually:
  71
  72   $ python -m doctest -v djbdns/*.py