NAME
dnscache - a DNS cache.
DESCRIPTION
This is a reference page. For tutorial information, see 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.html).
dnscache accepts recursive DNS queries from local clients such as web
browsers and mail transfer agents. It collects responses from remote
DNS servers. It caches the responses to save time later.
Configuration
Normally dnscache is set up by the dnscache-conf(8) program.
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.
dnscache 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.
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.
dnscache sends outgoing packets from high ports of $IPSEND. Typically
$IPSEND is 0.0.0.0, meaning the machine’s primary IP address.
dnscache reads a seed, up to 128 bytes, from standard input, and passes
the seed to dns_random_init.
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.mil, for example, 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.
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. 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. 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.
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 (including 8-byte
Y2038-compliant expiration times):
o A sets. 22 bytes plus 4 bytes per address plus the length of
the owner name.
o NS sets or PTR sets or CNAME sets. 22 bytes plus the length of
the owner name and all the data names.
o MX sets. 22 bytes plus 2 bytes per MX plus the length of all
the names.
o 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.
o 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.
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.
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 week. It interprets TTLs above
2147483647 as 0.
dnscache 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.
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) 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. If $HIDETTL is set, dnscache
always uses a TTL of 0 in its responses. 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.
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.)
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.
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.
Special names
dnscache handles localhost internally, giving it an A record of
127.0.0.1.
dnscache handles 1.0.0.127.in-addr.arpa internally, giving it a PTR
record of localhost.
dnscache 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
dnscache(8)