dnscache(8)

💖 dnscache — bestie's own DNS cache 💖

okay so. the manual name is dnscache(8) and honestly? it's giving backbone of the internet, but make it cozy. it's a DNS cache, periodt.

---

✨ NAME ✨

dnscache — a DNS cache. that's it, that's the whole name. iconic.

---

🌸 DESCRIPTION 🌸

bestie, real talk: this is a reference page. it's not the tutorial. if you want the walk-you-through-it version, go read the instructions for

• workstations (http://cr.yp.to/djbdns/run-cache.html)
• home computers (http://cr.yp.to/djbdns/run-cache-home.html)
• external caches (http://cr.yp.to/djbdns/run-cache-x.html)
• or upgrading from BIND (http://cr.yp.to/djbdns/run-cache-bind-1.html)

so what does dnscache actually do? it takes recursive DNS queries from local clients — think web browsers, mail transfer agents, the whole crew — goes out and collects the responses from remote DNS servers, and then caches those responses so future lookups are basically instant. it's the friend who already knows the answer and doesn't make you wait. 👑

🎀 Configuration 🎀

normally you don't hand-roll this — dnscache gets set up by the dnscache-conf(8) program. let it cook.

dnscache runs chrooted in the directory specified by the $ROOT environment variable, under the uid and gid specified by the $UID and $GID environment variables.

it listens for incoming UDP packets and TCP connections addressed to port 53 of $IP. typically $IP is 127.0.0.1, but it can also be an externally accessible IP address. live your truth.

here's the vibe: dnscache accepts a packet or connection from IP address 1.2.3.4 if it sees a file named ip/1.2.3.4 or ip/1.2.3 or ip/1.2 or ip/1. yes, it walks the prefixes like a little detective. 🕵️

outgoing packets? those go from high ports of $IPSEND. typically $IPSEND is 0.0.0.0, meaning the machine's primary IP address.

it also reads a seed, up to 128 bytes, from standard input, and passes that seed to dns_random_init. keep it secret, keep it safe. 🙈

then it reads a list of dotted-decimal root server IP addresses, one address per line, from servers/@. it also scans the servers directory for server IP addresses for other domains. example time: if there are addresses listed in servers/moon.af.mil, then dnscache will send queries for anything.moon.af.mil to those addresses, and will not cache records for anything.moon.af.mil from outside servers such as the root servers.

Versions 1.03 and above: if $FORWARDONLY is set, dnscache treats servers/@ as a list of IP addresses for other caches, not root servers. it forwards queries to those caches the same way that a client does, rather than contacting a chain of servers according to NS records. glow up.

🧚 Memory use 🧚

dnscache uses a fixed-size table, under 256K, to keep track of as many as 200 simultaneous UDP queries and 20 simultaneous TCP connections. it also dynamically allocates memory — usually just a few bytes, but occasionally much more — for each active query. and if it runs out of memory handling a query? it discards that query. no drama, just dropped. 💀

it asks the operating system to reserve a 128K buffer for bursts of incoming UDP queries.

in versions 1.03 and above:

• if a new UDP query arrives when dnscache is already handling 200 simultaneous UDP queries, dnscache drops the oldest query.
• if a new TCP connection arrives when dnscache is already handling 20 simultaneous TCP connections, dnscache drops the oldest connection.

oldest out, bestie. sorry not sorry.

dnscache uses a fixed-size cache, as controlled by the $CACHESIZE environment variable. roughly 5% of the cache is used for a hash table. the rest is used for cache entries — and yes, that includes 8-byte Y2038-compliant expiration times. future-proof queen. 👑

here's the size breakdown, per entry type:

• A sets. 22 bytes plus 4 bytes per address plus the length of the owner name.
• NS sets or PTR sets or CNAME sets. 22 bytes plus the length of the owner name and all the data names.
• MX sets. 22 bytes plus 2 bytes per MX plus the length of all the names.
• Other record sets. 22 bytes plus 2 bytes per record plus the length of all the data strings plus the length of the owner name.
• Nonexistent domain or server failure. 22 bytes plus the length of the owner name.

sets larger than 8192 bytes are not cached. know your limits, babe.

and here's the reassuring part: dnscache does not exit when it runs out of space in its cache; it simply removes the oldest entries to make more space. it's unbothered. it's thriving. it's making room. ✨

🌈 Resolution and caching policies 🌈

dnscache relies on a configured list of root name servers. in contrast, BIND starts from a ``hint file'' listing name servers, and asks those name servers where the root name servers are. we don't do that here. we already know. 💅

dnscache does not cache (or pass along) records outside the server's bailiwick — those records could be poisoned. 💀 records for foo.dom, for example, are accepted only from the root servers, the dom servers, and the foo.dom servers.

it also does not bypass its cache to obtain glue from the additional section of a response. in particular, it will not use:

• glue outside the server's bailiwick
• glue with TTL 0
• glue that violates other caching policies

dnscache caches records for at most a week. it interprets TTLs above 2147483647 as 0.

and no, it does not cache SOA records. however, it does use SOA TTLs to determine cache times (up to an hour) for zero-record responses and nonexistent domains. sneaky, but in a smart way.

🦋 Responses to DNS clients 🦋

dnscache's responses are generally much smaller than BIND's responses. they do not include:

• authority records (NS records of the source name servers and SOA records for negative answers)
• additional records (A records relevant to NS or MX records)

and when the answer section is truncated by UDP length limits, it is eliminated entirely. gone. bye. 🫶

dnscache tries to prevent local users from snooping on other local users. so it:

• discards non-recursive queries
• discards inverse queries
• discards zone-transfer requests

if $HIDETTL is set, dnscache always uses a TTL of 0 in its responses. and heads up: in versions before 1.03, dnscache always uses a TTL of 0 in its responses.

according to RFC 1035, the AA bit ``specifies that the responding name server is an authority for the domain name in question section.''

dnscache is not an authority for any domain names. it's humble like that.

dnscache never sets the AA bit — except in NXDOMAIN responses, as required by RFC 2308, to work around a common client bug. in contrast, BIND often sets AA for positive responses even when it is not an authority for the domain name. (this appears to have been fixed in BIND 9.) not us though. we stay honest.

🍓 Repeated IP addresses 🍓

if a server sends dnscache a repeated IP address, dnscache passes the repeated IP address along to the client. the server's behavior violates RFC 2181, section 5.5, but there are reasonable uses of repeated IP addresses for load balancing, so dnscache does not go out of its way to remove repetitions when they occur. it's not the parent here. it's just delivering the mail. 📬

a widespread BIND server bug (apparently fixed in BIND 9.1) can unintentionally produce repeated IP addresses. here is an example from one of the BIND company's servers (now fixed):

% dnsq a ns-ext.vix.com ns-ext.vix.com
1 ns-ext.vix.com:
117 bytes, 1+1+2+2 records, response, authoritative, noerror
query: 1 ns-ext.vix.com
answer: ns-ext.vix.com 3600 A 204.152.184.64
authority: vix.com 3600 NS ns-ext.vix.com
authority: vix.com 3600 NS ns1.gnac.com
additional: ns-ext.vix.com 3600 A 204.152.184.64
additional: ns1.gnac.com 130768 A 209.182.195.77

this BIND bug is the most common reason for users to see repeated IP addresses from dnscache. so if you're seeing doubles, that's probably why. mystery solved. 🔍

💜 Special names 💜

dnscache handles some names all by itself, no upstream needed:

• it handles localhost internally, giving it an A record of 127.0.0.1.
• it handles 1.0.0.127.in-addr.arpa internally, giving it a PTR record of localhost.
• it handles dotted-decimal domain names internally, giving (e.g.) the domain name 192.48.96.2 an A record of 192.48.96.2.

---

⭐ SEE ALSO ⭐

• dnscache-conf(8)
• http://cr.yp.to/djbdns.html

---

okay bestie that's the whole page 💖 this one came from the System Manager's Manual, and it's dnscache(8) — so go set up your cache and slay, fr fr. 🌸🦋✨