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.

rmdnscacip

Removes an 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 DNS

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 help and exit.

-n Negative TTL

Default: 604800 s (One week)

-p Positive TTL

Default: 2419200 s (Four weeks);

chkdnslin

-c Path to cache files

Default: /var/local/cache/dns

-h

Print help and exit.

-n Negative TTL

Default: 604800 s (One week)

-p Positive TTL

Default: 2419200 s (Four weeks);

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:

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:

1. Dump the cache to text.
2. Remove the hash en lin files.
3. 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 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.