dnscache 1 user commands djbwares dnscache a caching proxy DNS server dnscache dnscache is a proxy DNS server that speaks the DNS/UDP and DNS/TCP protocols. It accepts DNS queries from local programs (clients such as web browsers and mail transfer agents with DNS client libraries in them), sends queries of its own to hosts around the Internet, takes the responses that it receives and combines them into answers that it then sends back to the local clients. It caches the responses that it receieves, to save time later when it is asked the same or related questions again. When it starts dnscache changes its root to the directory specified by the ROOT environment variable, and drops privileges to run as the user ID and group ID specified by the UID and GID environment variables. The latter can be set up with envuidgid1. Normally dnscache is run via server programs such as udp-socket-listen and tcp-socket-listen to listen for DNS/UDP and DNS/TCP queries on an appropriate IP address. It understands the LISTEN_PID and LISTEN_FDS environment variable convention for having already-listening sockets passed to it by such programs, and uses the last open file descriptors in the list that refer to a UDP/IPv4 socket and a TCP/IPv4 socket. If no such open file descriptors are provided it falls back to opening its own UDP/IPv4 and TCP/IPv4 sockets, bound to port 53 of the IP address given by the value of the IP environment variable. If just one is provided, it falls back for the other. Typically the IP address is a non-routable machine-local or link-local one such as 127.0.0.1. It can also be a public IP address, providing this service to other machines. To control what other machines that is, there is an access control mechanism. dnscache discards UDP packets or TCP connections from IP address 203.0.113.4 unless it sees a file named ip/203.0.113.4 or ip/203.0.113 or ip/203.0 or ip/203. A proper firewall is a more efficient mechanism for preventing client access, especially for DNS/TCP, however. This access control mechanism will change in a non-backwards compatible way when dnscache becomes capable of listening to IPv6 clients in a future release. 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) or additional records (A records relevant to NS or MX records). When the answer section is truncated by UDP length limits, it is eliminated entirely. dnscache tries to prevent local users from snooping on other local users. It discards non-recursive queries; it discards inverse queries; and it discards zone-transfer requests. It responds to ANY and OPT queries with a single synthesized HINFO resource record set. If the HIDETTL environment variable is set, dnscache always uses a TTL of 0 in its responses. Normally, it preserves the (current remaining) TTL, so that other proxies can use it as an upstream server. 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. dnscache never sets the AA bit (except in NXDOMAIN responses, as required by RFC 2308, to work around a common client bug). 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. If it runs out of memory handling a query, it discards that query. dnscache asks the operating system to reserve a 128K buffer for bursts of incoming UDP queries. 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. dnscache uses a fixed-size cache, as controlled by the value of the CACHESIZE environment variable. Roughly 5% of the cache is used for a hash table. The rest is used for cache entries (including 8-byte Y2038-compliant expiration times): A sets.22 bytes plus 4 bytes per address plus the length of the owner name. AAAA sets.22 bytes plus 16 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. SOA sets.22 bytes plus 20 bytes per SOA 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. dnscache does not exit when it runs out of space in its cache; it simply removes the oldest entries to make more space. dnscache relies on a configured list of root name servers. In contrast, some other servers start from a "hint file" listing (not necessarily root) name servers, and perform an intermediate extra step of asking those name servers where the root name servers are. 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. dnscache 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, or glue with TTL 0, or glue that violates other caching policies. dnscache caches records for at most a fortnight. It interprets TTLs above 2147483647 as 0, on the grounds that such excessive values are the results of unsigned arithmetic underflow. dnscache does not cache SOA resource records when they are TTL carriers for the DNS protocol, although it will cache them if they are actual answers to queries. It instead uses the TTL-carrying SOA record records to determine cache times (up to an hour) for zero-record responses and nonexistent domains. A server that returns a delegation response that (directly or indirectly) delegates back to itself is considered "lame". Responses from "lame" servers are logged, and what useful information they may contain, aside from the delegation, is cached (subject to the caching policies). dnscache handles several things internally, synthesizing data for them directly instead of issuing back-end transactions. walldns1 also synthesizes data for some of these domain names, and some domain names are handled internally by the DNS client library (see djbdns-client5). But what answers a proxy DNS server can synthesize are different to what answers a content DNS server can synthesize and different to what answers a DNS client library can synthesize. Many "special-use domain names" have different rules for all three. Several well-known domain names such as test. and home.arpa. and 10.in-addr.arpa. are not answered synthetically. These domain names are supposed to be prune-and-graft points handled by the the IP address selection mechanisms in the servers/test and servers/home.arpa and servers/10.in-addr.arpa files discussed later, switchable amongst walldns1, tinydns1, or a forwarded-to proxy DNS server. dnscache provides bare minima for loopback and link-local networking with fixed well-known and universal values, in line with RFC 6761 and RFC 6762. localhost. and its subdomains It gives localhost. itself an A record of 127.0.0.1 and an AAAA record of ::1. All other types of resource record set are empty sets. Its subdomains are treated likewise with the exception of subdomains of the form d.c.b.127.localhost.. It gives these an A record of 127.b.c.d, and an AAAA record of ::FFFF:127.b.c.d. 127.in-addr.arpa. subdomains To subdomains of the form d.c.b.127.in-addr.arpa. it gives a PTR record of d.c.b.127.localhost., with the exception of the 127.0.0.1 reverse mapping. It gives all other subdomains, including the 127.0.0.1 reverse mapping, a PTR record of localhost.. All other types of resource record set are empty sets. 254.169.in-addr.arpa., 8.e.f.ip6.arpa., and 9.e.f.ip6.arpa. subdomains To subdomains of the form c.b.254.169.in-addr.arpa., 29hexlabels.8.e.f.ip6.arpa., or 29hexlabels.9.e.f.ip6.arpa., which are the reverse lookup names used to map link-local IP addresses, it gives all query types empty resource record sets. 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. It gives this a PTR record of localhost.. All other types of resource record set are empty sets. dnscache handles a common error where an application expects a domain name but its user supplies it with a human-readable form of an IPv4 address, and this is not caught by a DNS client library and handled internally but a request has reached dnscache; or where a content DNS server has erroneously entered an IP address instead of a domain name in an NS resource record in a content DNS server's database. It gives dotted-decimal domain names an A record corresponding to the IP address whose human-readable form is the domain name (e.g. 192.48.96.2. is given an A record of 192.48.96.2) and an AAAA record corresponding to the IPv4-mapped IPv6 equivalent address. All other types of resource record set are empty sets. For opaque and bijective address-to-name-to-address mapping where, rather, the proper mechanisms are employed by applications, use the servers/in-addr.arpa and servers/ip6.arpa files to point to a content DNS server running walldns1. RFCs 6761, 7686, 8880, 9462, and 9476 specify that invalid., alt., onion., local., resolver.arpa., and their subdomains, should not query content DNS servers. They are either looked up via other mechanisms, if they are looked up at all, and queries for them should never have reached dnscache, or they are by their natures non-existent as far as the global DNS is concerned. For these, dnscache returns a "no such domain" error response. For empty resource record sets and "no such domain" errors, dnscache includes a synthetic SOA resource record that carries the TTL. As dnscache does not cache such SOA resource records when they are TTL carriers for the DNS protocol, properly operating caches in front of dnscache will not cache these records. dnscache sends outgoing requests from high ports of the IP address given by the value of the IPSEND environment variable. If IPSEND is not set then the default is either 0.0.0.0 or 0:0:0:0:0:0:0:0, allowing the operating system to pick an IP version 4 or version 6 address suitable for reaching the target servers. The ports are picked at random, as are the message IDs in the requests. The random number generator is seeded from a seed value, up to 128 bytes, that dnscache reads from its standard input at startup. The seed does not need to be preserved across successive incarnations of dnscache, and merely needs to be unknown and unpredictable outwith the dnscache process. It can just be a 128-byte snapshot of the system's random number generator read with the dd1 program. At startup, dnscache 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. If there are addresses listed in servers/moon.af.example, for example, then dnscache will send queries for anything.moon.af.example to those addresses, and will not cache records for anything.moon.af.example from outside servers such as the root servers. The list is capped at 16 IP addresses; the 17th and subsequent IP addresses being read, but discarded. If the servers/test and servers/home.arpa and servers/10.in-addr.arpa (and similar) files are missing, and it is not in forward-first or forward-only mode (more on which later) or those prune-and-graft points are not in turn handled by the forwarded-to proxy DNS servers either, dnscache is not correctly configured. This is not a condition that is detectable by the software unaided. If the FORWARDONLY environment variable is set, dnscache treats servers/@ as a list of IP addresses for other caching proxies, not for content 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. In this mode, it ignores referral responses, which it should never receive from a caching proxy in the first place and which the world at large has an unfortunate habit of making refer to IP addresses such as 127.0.0.1, which would cause a proxy loop if they were to be followed. It logs such occurrences. For similar reasons, for correct operation the list in a servers/* file should not include: the IP address on which dnscache is itself listening; the IP address on which another proxy DNS server is listening; or any IP addresses equivalent to those. If the FORWARDFIRST environment variable is set, dnscache permits back-end services that it contacts to be either caching proxies or content servers. It behaves exactly as in normal mode, except that back-end queries have the "recursion desired" bit set to on instead of to off. This causes caching proxies to respond with fully resolved responses, whilst still performing query resolution locally if they are content servers. Forward first mode is overridden by forward only mode. 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. A previously widespread server bug used to unintentionally produce repeated IP addresses. Here is an example (since 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 bug is the most common reason for users to see repeated IP addresses from dnscache. dnscache was originally part of Daniel J. Bernstein's djbdns toolset in 2000. Special handling of localhost., reverse lookup of 127.0.0.1, and dotted-decimal domain names were in the Bernstein original. This special handling was significantly expanded in 2025. dnscache ceased special-casing the ip6.int. superdomain in 2016. The ip6.int. superdomain was deprecated by RFC3152 in 2001 and obsoleted by RFC4159 in 2005. Original code and documentation by Daniel J. Bernstein. Documentation modernizations by Jonathan de Boyne Pollard.