|
1 | 1 | # DNS - Cache Info |
2 | 2 |
|
3 | | -## Obtain information about Pi-hole's DNS cache |
| 3 | +`pihole-FTL` offers an efficient DNS cache that helps speed up your Internet experience. This DNS cache is part of the embedded `dnsmasq` server. Setting the cache size to zero disables caching. The DNS TTL value is used for determining the caching period. `pihole-FTL` clears its cache on receiving `SIGHUP`. |
| 4 | + |
| 5 | +<!-- markdownlint-disable code-block-style --> |
| 6 | +!!! warning Some warning about the DNS cache size |
| 7 | + **There is no benefit in increasing this number *unless* the number of DNS cache evictions is greater than zero.** |
| 8 | + |
| 9 | + A larger cache *will* consume more memory on your node, leaving less memory available for other caches of your Pi-hole. If you push this number to the extremes, it may even be that your Pi-hole gets short on memory and does not operate as expected. |
| 10 | + |
| 11 | + You can not reduce the cache size below `150` when DNSSEC is enabled because the DNSSEC validation process uses the cache. |
| 12 | +<!-- markdownlint-enable code-block-style --> |
| 13 | + |
| 14 | +### Cache metrics |
| 15 | + |
| 16 | +The Settings page (System panel, FTL table) gives live information about the cache usage. |
| 17 | + |
| 18 | +#### DNS cache size |
| 19 | + |
| 20 | +Size of the DNS domain cache, defaulting to 10,000 entries. It is the number of entries that can be actively cached at the same time. |
| 21 | +This information may also be queried using `dig +short chaos txt cachesize.bind` |
| 22 | + |
| 23 | +The cache size is set in `/etc/dnsmasq.d/01-pihole.conf`. However, note that this setting does not survive Pi-hole updates. If you want to change the cache size permanently, add a setting |
| 24 | + |
| 25 | +``` plain |
| 26 | +CACHE_SIZE=12345 |
| 27 | +``` |
| 28 | + |
| 29 | +in `/etc/pihole/setupVars.conf` and run `pihole -r` (Repair) to get the cache size changed for you automatically. |
| 30 | + |
| 31 | +#### DNS cache insertions |
| 32 | + |
| 33 | +Number of total insertions into the cache. This number can be substantially larger than DNS cache size as expiring cache entries naturally make room for new insertions over time. Each lookup with a non-zero TTL will be cached. |
| 34 | + |
| 35 | +This information may also be queried using `dig +short chaos txt insertions.bind` |
| 36 | + |
| 37 | +#### DNS cache evictions |
| 38 | + |
| 39 | +The number of cache entries that had to be removed although the corresponding entries were **not** expired. Old cache entries get removed if the cache is full to make space for more recent domains. The cache size should be increased when this number is larger than zero. |
| 40 | + |
| 41 | +This information may also be queried using `dig +short chaos txt evictions.bind` |
| 42 | + |
| 43 | + |
| 44 | +## Obtain information about Pi-hole's DNS cache through the API |
4 | 45 |
|
5 | 46 | - `GET /api/dns/cache` |
6 | 47 |
|
|
19 | 60 | ``` python |
20 | 61 | import requests |
21 | 62 |
|
22 | | - url = 'http://pi.hole/api/dns/cacheinfo' |
| 63 | + url = 'http://pi.hole:8080/api/dns/cacheinfo' |
23 | 64 | sid = '<valid session id>' |
24 | 65 | data = {"sid": sid} |
25 | 66 |
|
|
39 | 80 | ``` json |
40 | 81 | { |
41 | 82 | "cache_size": 10000, |
42 | | - "cache_inserted": 509, |
| 83 | + "cache_inserted": 2616, |
43 | 84 | "cache_evicted": 0 |
44 | 85 | } |
45 | 86 | ``` |
|
51 | 92 | **Fields** |
52 | 93 |
|
53 | 94 | ??? info "DNS cache size (`"cache_size": number`)" |
54 | | - Size of the DNS domain cache, defaulting to 10,000 entries. You typically specify this number directly in `/etc/dnsmasq.d/01-pihole.conf`. It is the number of entries that can be actively cached at the same time. There is no benefit in enlarging this number *except* if the DNS cache evictions count is larger than zero. |
55 | | - |
56 | | - This information may also be queried using `#!bash dig +short chaos txt cachesize.bind` |
| 95 | + See above. |
57 | 96 |
|
58 | 97 | ??? info "DNS cache insertions (`"cache_inserted": number`)" |
59 | 98 |
|
60 | | - Number of total insertions into the cache. This number can be substantially larger than DNS cache size as expiring cache entries naturally make room for new insertions over time. Each lookup with a non-zero TTL will be cached. |
61 | | - |
62 | | - This information may also be queried using `#!bash dig +short chaos txt insertions.bind` |
| 99 | + See above. |
63 | 100 |
|
64 | 101 | ??? info "DNS cache evictions (`"cache_evicted": number`)" |
65 | 102 |
|
66 | | - The number of cache entries that had to be removed although the corresponding entries were **not** expired. Old cache entries get removed if the cache is full to make space for more recent domains. |
67 | | - |
68 | | - The cache size should be increased when the number of evicted cache entries is larger than zero. |
69 | | - |
70 | | - This information may also be queried using `#!bash dig +short chaos txt evictions.bind` |
| 103 | + See above. |
71 | 104 |
|
72 | 105 | <!-- markdownlint-enable code-block-style --> |
73 | 106 |
|
|
0 commit comments