cachlogres
==========

Programs
--------

cachlogres
	PTR Lookup with cache.
	Does forward (AAAA/A) lookup to check PTR record.
	Reads from stdin. Writes to stdout.
	Format: IP-Address or Host name <Space> Some-string <Newline>
	Replaces IP Address by host name if found.

dumpdnscac
	Dump DNS cache to text files;
	hash0.txt, hash1.txt, etc. And lin.txt

gendnscac
	Generate new cache files or update existing files.
	Reads from stdin.
	Can be used to read analog's cache format.

dnscacstats
	Generate cache statistics.

chkdnslin
	Check lin file.

rmdnscacip
	Remove IP address from cache.

dnscac2ana
	Converts dumped dns cache to a file format suitable for analog.


Options
-------

cachlogres
  -c: Path to cache files; Default: /var/local/cache/dns
  -d: Enable debug.
  -h: Print help and exit.
  -l: Lock file; Default: /var/local/lock/dnscache.lock
  -n: Negative TTL; Default: 604800 s (One week)
  -p: Positive TTL; Default: 2419200 s (Four weeks)
  -r: Resolver / Name server.
  -v: Print version and exit.

gendnscac
  -a: Analog epoch (minutes); Multiply epoch by 60.
  -b: Nr of CRC bits. 16 - 24. Default: 22.
  -d: Enable debug.
  -f: Nr of hash files. 1 - 16. Default: 1.
  -h: Print help and exit.
  -t: 1st field is address; Use current time as epoch.
  -v: Print version and exit.

dnscacstats
  -c: Path to cache files; Default: /var/local/cache/dns
  -h: Print this help and exit.
  -n: Negative TTL; Default: 604800 s
  -p: Positive TTL; Default: 2419200 s
  -w: Generate HTML output.

chkdnslin
  -c: Path to cache files; Default: /var/local/cache/dns
  -h: Print this help and exit.
  -n: Negative TTL; Default: 604800 s
  -p: Positive TTL; Default: 2419200 s


Files
-----

Cache file format:

       0        1        2        3        4        5        6        7
     +--------+--------+--------+--------+--------+--------+--------+--------+
   0 | IP Address                                                            |
     +--------+--------+--------+--------+--------+--------+--------+--------+
   8 |                                                                       |
     +--------+--------+--------+--------+--------+--------+--------+--------+
  16 | Host name                                                             |
     +--------+--------+--------+--------+--------+--------+--------+--------+
     ~                                                                       ~
     +--------+--------+--------+--------+--------+--------+--------+--------+
 264 |                                                                  0    |
     +--------+--------+--------+--------+--------+--------+--------+--------+
 272 | Epoch                                                                 |
     +--------+--------+--------+--------+--------+--------+--------+--------+

  Each entry is 280 bytes:

   16 Byte IP address. IPv4 Addresses are stored as IPv4-mapped IPv6 address.
  256 Byte host name. NULL Terminated string (with zero padding). Max 255 bytes.
      The maximum allowed host name size is 253 bytes. So this adds a little
      margin.
    8 Byte epoch.


IPv4-mapped IPv6 address:

  Example: IPv4 address w.x.y.z becomes ::ff:w.x.y.z

       0        1        2        3        4        5        6        7
     +--------+--------+--------+--------+--------+--------+--------+--------+
   0 |   0    |   0    |   0    |   0    |   0    |   0    |   0    |  0     |
     +--------+--------+--------+--------+--------+--------+--------+--------+
   8 |   0    |   0    |  0xff  |  0xff  |   w    |   x    |   y    |  z     |
     +--------+--------+--------+--------+--------+--------+--------+--------+

  For instance: 192.168.1.1 becomes ::ff:192.168.1.1

       0        1        2        3        4        5        6        7
     +--------+--------+--------+--------+--------+--------+--------+--------+
   0 |   0    |   0    |   0    |   0    |   0    |   0    |   0    |  0     |
     +--------+--------+--------+--------+--------+--------+--------+--------+
   8 |   0    |   0    |  0xff  |  0xff  |  0xc0  |  0xa8  |  0x01  |  0x01  |
     +--------+--------+--------+--------+--------+--------+--------+--------+


Files

  hash0, hash1, hash2, ... hashe, hashf
	Sparse files.
	(The lower bits of) a 24-Bit CRC of the IP address is used as a hash.
	The hash is multiplied by the record size (280 bytes) and this is used as
	a file offset (number of bytes from start of file).
	hash0 is tried first. In case of a hash clash (an other IP address having
	the same hash) the next hash file is used.
	If all of the hash files clash the lin file is used.

  lin
	Regular file.
	Used for hash clashes in the above files.
	File size: 0 or more times 280 bytes.


cachlogres
----------

Default cache dir: /var/local/cache/dns
Default lock file: /var/local/lock/dnscache.lock

Default negative cache time:  604800 s (One week)
Default positive cache time: 2419200 s (Four weeks)

Negative caching applies to IP Addresses without a host name.
Positive caching applies to IP Addresses with a host name.
Stale entries are removed when read.

Besides in seconds, the TTLs can also be specied in Hours, Days, Weeks,
Months or Years.


gendnscac
---------

Uses the default directory.
Files are created when they do not exist.
Use the '-f' option to set the number of hash files.
Use the '-b' option to set the hash file size:

  Hash file size
     
  Bits   Entries   Max CRC    Hash file size 
     
   16      64k     0x00FFFF    17920 kB  
   17     128k     0x01FFFF       35 MB
   18     256k     0x03FFFF       70 MB
   19     512k     0x07FFFF      140 MB
   20       1M     0x0FFFFF      280 MB
   21       2M     0x1FFFFF      560 MB
   22       4M     0x3FFFFF     1120 MB  <-- Default
   23       8M     0x7FFFFF     2240 MB
   24      16M     0xFFFFFF     4480 MB

The '-b' and '-f' options can only be used when no cache files exist.
'gendnscac' can be also used to update existing files. For instance add or
change a host name. Stale entries are not removed by gendnscac.

Input format:

  Epoch <Space or Tab> IP Address <Space or Tab> Optional host name <Line Feed>

With '-t' option:

 IP Address <Space or Tab> Optional host name <Line Feed>

Use the '-a' option for analog's cache format.


dumpdnscac
----------

Uses the default directory.
The script 'gen-cache-txt.sh' can be used the combine the text versions of the
cache files into one file.


Changing the cache lay-out
--------------------------

A big lin file slows things down.
When the lin file gets to big you may need to increase the number of hash
files.

To change the cache lay-out:

- Dump the cache to text.
- Remove the hash en lin files.
- Generate a new cache.

You can use gendnscac to read the text files one by one.
Or merge the text files into one file and convert this file to a new cache.
The script 'gen-cache-txt.sh' merges the text files for you. It sorts by
epoch and IP address. Output is cache.txt.


dnscacstats
-----------

Generates cache statistics.
Example output below:


CRC                hash0   hash1   Total

 000000 - 01FFFF    3502      39    3541
 020000 - 03FFFF    2915      27    2942
 040000 - 05FFFF    2515      22    2537
 060000 - 07FFFF    2729      24    2753
 080000 - 09FFFF    3920      38    3958
 0A0000 - 0BFFFF    3431      51    3482
 0C0000 - 0DFFFF    3688      32    3720
 0E0000 - 0FFFFF    2829      20    2849
 100000 - 11FFFF    2366      18    2384
 120000 - 13FFFF    2363      16    2379
 140000 - 15FFFF    4047      63    4110
 160000 - 17FFFF    5049      66    5115
 180000 - 19FFFF    2906      20    2926
 1A0000 - 1BFFFF    3545      26    3571
 1C0000 - 1DFFFF    3567      37    3604
 1E0000 - 1FFFFF    3095      37    3132

In hash files:   53003     IPv4:   46861 88%  Name   14812 32%  Old   16617 35%
In lin file:         4     IPv6:    6146 12%  Name     442  7%  Old       0  0%
Total cache:     53007     From 2026-08-01 11:41:00 to 2026-08-17 08:32:15 UTC


'Name' means entries with a host name.
Note that stale entries are only removed when read by cachlogres. So the
above overview includes stale (Old) entries.

Besides in seconds, the TTLs can also be specied in Hours, Days, Weeks,
Months or Years.


chkdnslin
---------

The lin file is searched linear. So a large lin file slows things down.
chkdnslin shows which records are empty and which records are stale.
You need to change the cache lay-out when the lin gets too big.

Besides in seconds, the TTLs can also be specied in Hours, Days, Weeks,
Months or Years.

rmdnscacip
----------
Removes an IP address from cache.
The IP address is specified on the command line.
Uses the default directory.

