Imported Debian patch 1:1.05-8

[hcoop/zz_old/debian/djbdns.git] / debian / djbdns-man / dnscache.8

.TH dnscache 8

.SH NAME
dnscache \- a DNS cache.

.SH DESCRIPTION
This is a reference page.
For tutorial information, see the instructions for
.br
.B workstations
(http://cr.yp.to/djbdns/run-cache.html),
.br
.B home computers
(http://cr.yp.to/djbdns/run-cache-home.html),
.br
.B external caches
(http://cr.yp.to/djbdns/run-cache-x.html),
or
.br
.B upgrading from BIND
(http://cr.yp.to/djbdns/run-cache-bind-1.html).

.B 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.

.SH Configuration
Normally 
.B dnscache
is set up by the
.BR dnscache-conf (8)
program.

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

.B dnscache
listens for incoming UDP packets and TCP connections
addressed to port 53 of 
.IR $IP .
Typically 
.I $IP
is 
.IR 127.0.0.1 ,
but it can also be an externally accessible IP address.

.B dnscache
accepts a packet or connection
from IP address 
.I 1.2.3.4
if it sees a file named 
.I ip/1.2.3.4
or 
.I ip/1.2.3
or 
.I ip/1.2
or 
.IR ip/1 .

.B dnscache
sends outgoing packets from high ports of 
.IR $IPSEND .
Typically 
.I $IPSEND
is 
.IR 0.0.0.0 ,
meaning the machine's primary IP address.

.B dnscache
reads a seed, up to 128 bytes,
from standard input,
and passes the seed to
dns_random_init.

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

Versions 1.03 and above:
If
.I $FORWARDONLY
is set,
.B dnscache
treats
.I 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.

.SH Memory use

.B 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.

.B 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
.B dnscache
is already handling 200 simultaneous UDP queries,
.B dnscache
drops the oldest query.
If a new TCP connection arrives
when
.B dnscache
is already handling 20 simultaneous TCP connections,
.B dnscache
drops the oldest connection.

.B dnscache
uses a fixed-size cache,
as controlled by the 
.I $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):

.TP
o
A sets.
22 bytes plus 4 bytes per address plus the length of the owner name.
.TP
o
NS sets or PTR sets or CNAME sets.
22 bytes plus the length of the owner name and all the data names.
.TP
o
MX sets.
22 bytes plus 2 bytes per MX plus the length of all the names.
.TP
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.
.TP
o
Nonexistent domain or server failure.
22 bytes plus the length of the owner name.

.P
Sets larger than 8192 bytes are not cached.

.B dnscache
does not exit when it runs out of space in its cache;
it simply removes the oldest entries to make more space.

.SH Resolution and caching policies

.B 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.

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

.B 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.

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

.B 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.

.SH Responses to DNS clients

.BR 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.

.B 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
.I $HIDETTL
is set,
.B dnscache
always uses a TTL of 0 in its responses.
In versions before 1.03,
.B 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.''

.B dnscache
is not an authority for any domain names.

.B 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.)

.SH Repeated IP addresses
If a server
sends
.B dnscache
a repeated IP address,
.B 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
.B 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
.BR dnscache .

.SH Special names

.B dnscache
handles 
.I localhost
internally,
giving it an A record of 127.0.0.1.

.B dnscache
handles 
.I 1.0.0.127.in-addr.arpa
internally,
giving it a PTR record of
.IR localhost .

.B dnscache
handles dotted-decimal domain names internally,
giving (e.g.) the domain name 
.I 192.48.96.2
an A record of 
.IR 192.48.96.2 .

.SH SEE ALSO
dnscache-conf(8)

http://cr.yp.to/djbdns.html