--- /dev/null
+.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
HCoop / hcoop / zz_old / debian / djbdns.git / blobdiff