BIND max-cache-size: sizing the resolver cache without triggering the OOM killer

named disappears from the process table. dmesg shows the OOM killer selected it. systemd restarts it, the cache is cold, every query triggers recursion, upstream load spikes, and RSS climbs again. Within hours the cycle repeats. The root cause is often not a memory leak. It is the default max-cache-size.

Since BIND 9.11, the default max-cache-size for views with recursion yes is 90% of physical memory. On a dedicated resolver with 16 GB of RAM, that is 14.4 GB for the cache alone. On a shared box or a mixed-role server that also serves authoritative zones, that default guarantees the OOM killer will eventually visit.

Set it too high and BIND becomes the OOM killer’s favorite target. Set it too low and the cache evicts entries faster than it can build hit ratio, driving up outbound recursive queries and downstream latency. The goal is an explicit bound large enough for your working set but small enough to leave room for everything else on the host.

What max-cache-size actually bounds

max-cache-size bounds an individual cache database and its metadata; current BIND also sizes the ADB at one-eighth of that cache limit. It does not bound zone data, per-query state, RPZ datasets, DNSSEC key material, or any other internal allocation. Setting it to 90% of physical memory means 90% of RAM is available to the cache while everything else BIND uses, plus the OS and co-located processes, competes for the remaining 10%. Setting it to 100% guarantees OOM.

BIND does not return memory to the OS efficiently. The internal allocator fragments, so RSS climbs during peak traffic and never fully recedes when cache entries expire. On BIND 9.18+, jemalloc is used by default when available, which mitigates this, but RSS can still run significantly higher than BIND’s internal InUse counter suggests. Budget for fragmentation overhead.

Per-view multiplication compounds the problem. Each view with recursion yes gets its own cache with its own max-cache-size. Four recursive views with the default setting means four caches each allowed to grow to 90% of physical memory. That is a guaranteed OOM.

flowchart LR
  A["max-cache-size"] -->|90% default or too high| B["RSS reaches system limit"]
  B --> C["OOM kill"]
  C --> D["Cold restart cycle"]
  D --> B
  A -->|Too small| E["LRU eviction thrash"]
  E --> F["Hit ratio collapses"]
  F --> G["Recursive load spikes"]

Common causes

Quick checks

# Current max-cache-size setting (absent means default is in effect)
named-checkconf -p /etc/named.conf | grep -i "max-cache-size"

# named process RSS, %mem, and uptime
ps -o pid,rss,vsz,%mem,etime -p $(pgrep -x named)

# OOM kills of named (use journalctl if dmesg ring buffer has rotated)
dmesg | grep -i "oom" | grep -i "named"
journalctl -k --since "7 days ago" | grep -i oom | grep -i named

# Restart count (systemd)
systemctl show named --property=NRestarts

# BIND version
named -V | head -1

# Available system memory
free -m

# Cache stats per view from the statistics channel
# (adjust port to match your statistics-channels config)
curl -s http://localhost:8653/json/v1/server | \
  python3 -c "import sys,json; d=json.load(sys.stdin); \
  [print(f'{v}: Hits={cs.get(\"CacheHits\",0)} Misses={cs.get(\"CacheMisses\",0)} ' \
  f'DeleteLRU={cs.get(\"DeleteLRU\",\"N/A\")} TreeMemInUse={cs.get(\"TreeMemInUse\",\"N/A\")} ' \
  f'CacheNodes={cs.get(\"CacheNodes\",\"N/A\")}') \
  for v,vd in d.get('views',{}).items() if (cs:=vd.get('resolver',{}).get('cachestats',{}))]"

Diagnosis

1. Confirm whether named was OOM killed. Run dmesg | grep -i oom | grep -i named or journalctl -k | grep -i oom. If the OOM killer targeted named, memory pressure is the root cause. Check systemctl show named --property=NRestarts for a climbing restart count.

2. Check the configured max-cache-size. If named-checkconf does not show it, the default is in effect: 90% of physical memory for views with recursion yes, and 2 MB for views with recursion no.

3. Count recursive views. Each view with recursion yes gets its own 90% default. Three recursive views means the total default allocation is 270% of physical memory.

4. Measure RSS trend over time. A single snapshot is not enough. Track RSS at intervals and look for steady growth after cache warmup (30-60 minutes post-restart). Growth that continues past warmup and never plateaus indicates cache filling to max or a version-specific issue.

5. Check cache eviction rate. DeleteLRU in cachestats counts entries evicted due to memory pressure. If it is climbing rapidly, the cache is at capacity and thrashing. If it is zero, the cache has not reached max and memory is being consumed elsewhere.

6. Distinguish cache memory from other BIND memory. Compare TreeMemInUse and HeapMemInUse from cachestats against total process RSS. If RSS is much higher than cache memory, zone data, RPZ datasets, or allocator fragmentation are the consumers, and reducing max-cache-size alone will not fix the problem.

7. Check your BIND version for known bugs. In BIND 9.19.16 through 9.19.17, cache over-memory detection was a no-op after isc_mem_setwater() was removed (ISC GitLab issue #4340), so the cache could exceed a finite limit without eviction. The fix landed in BIND 9.16.45, 9.18.20, and 9.19.18.

Metrics and signals

Fixes

Set an explicit bound on multi-purpose servers

Set max-cache-size to a value that leaves room for everything else on the host.

options {
    max-cache-size 2G;
};

For dedicated resolver servers, a practical starting range is often 2-5 GB on 64-bit systems; for shared or mixed-role boxes, 50% of RAM or a fixed value such as 2 GB is a reasonable place to start. Validate with the cache working set. The exact number depends on your working set: a resolver handling diverse end-user traffic needs more cache than one serving a controlled datacenter with predictable query patterns.

max-cache-size is not the maximum memory BIND will use. It directly bounds the cache and sizes the ADB; other BIND allocations remain outside it. Total BIND memory equals cache plus zone data plus RPZ data plus per-query state plus allocator overhead. Budget for all of it.

Size per-view when running multiple views

Each view needs its own explicit max-cache-size. Without it, the 90% default applies independently to each view.

view "internal" {
    recursion yes;
    max-cache-size 1G;
};
view "external" {
    recursion yes;
    max-cache-size 2G;
};

Calculate the total across all views and verify it fits within your memory budget with headroom for non-cache BIND memory and co-located processes.

Account for fragmentation overhead

BIND’s memory allocator does not return small blocks to the OS efficiently. Even with jemalloc on 9.18+, RSS can exceed the configured max-cache-size by a significant margin. Budget up to 50% fragmentation overhead: a configured 2 GB cache may consume 3 GB of RSS.

Use pmap -x $(pgrep -x named) (Dirty column) or smem (USS column) for a more accurate picture of actual memory consumption than RSS alone.

Version-specific considerations

If you are running BIND 9.19.16 through 9.19.17, setting max-cache-size may not trigger over-memory eviction. Use 9.18.20, 9.19.18, or a later release on the corresponding branch.

Before BIND 9.20.23, cache cleanup near the memory limit could cause CPU spikes and query-throughput drops. BIND 9.20.23 spreads cleanup probabilistically; upgrade if you see this pattern.

Since BIND 9.17.4, setting max-cache-size preallocates fixed-size RBT hash tables at startup. Current BIND documents this as less than 1% of the configured limit, not a full allocation of the cache limit; verify startup memory on large configurations.

Prevention

• Track RSS as a trend, not a snapshot. After cache warmup (30-60 minutes), RSS should stabilize. Continued growth indicates cache filling to max, a version-specific issue, or a genuine memory leak. Plot RSS over days and weeks to catch gradual drift.

• Watch DeleteLRU as an early warning signal. If evictions start climbing, the cache is at capacity. Either increase max-cache-size (if memory headroom allows) or accept the hit-ratio cost and plan additional resolver capacity.

• Set a memory headroom rule. Keep named RSS below 70% of available system memory. The remaining 30% covers the OS page cache, co-located processes, and burst absorption. On cgroup-limited deployments (containers, systemd slices), use the lesser of system RAM and the cgroup limit.

• Validate configuration before deployment. Run named-checkconf before every reload. An explicit max-cache-size on every recursive view prevents the silent 90% default from creeping back in after config changes.

• Monitor restart count. A climbing NRestarts counter is often the first visible evidence of a repeated OOM cycle, especially if alerts fire on process liveness but not on memory trends.

How Netdata helps

• Per-second RSS tracking for the named process catches gradual memory growth that hourly sampling misses. The trend line after cache warmup should be flat; any upward slope is actionable.

• Cache eviction correlation. Netdata surfaces DeleteLRU and DeleteTTL alongside CacheHits/CacheMisses. When eviction rate rises while hit ratio drops, the cache is undersized. When eviction rate is zero and RSS is still climbing, the problem is not the cache.

• Internal cache memory visibility. TreeMemInUse, HeapMemInUse, and CacheNodes from cachestats are collected per view, letting you see which view’s cache is consuming memory and whether it is approaching the configured limit.

• OOM cascade correlation. Correlating RSS trend, system available memory, restart count, and post-restart cache hit ratio (dropping to near zero) identifies the OOM kill cycle before it repeats.

• Per-view isolation. In split-horizon setups, per-view cache stats prevent one view’s memory consumption from hiding behind aggregate numbers.

Related guides

• BIND clients-per-query and max-clients-per-query: duplicate recursion for popular names
• BIND forwarding loops: recursion that never terminates and burns recursive slots
• How BIND actually works in production: a mental model for operators
• BIND monitoring checklist: the signals every production resolver and authoritative server needs
• BIND monitoring maturity model: from survival to expert
• BIND ’no more recursive clients: quota reached’: the recursive-clients circuit breaker
• named not responding on port 53: total outage versus UDP-works-TCP-fails
• BIND resolver NumFetch per view: per-view recursive pressure in split-horizon setups
• BIND NXDOMAIN spike: DGA malware, water torture, and Windows suffix search lists
• BIND recursive resolution cascade: one slow upstream taking down all resolution
• BIND RecursClients climbing toward the limit: reading the recursive saturation gauge
• BIND REFUSED responses: ACL denials, recursion policy, and clients that get locked out