Provided by: djbdns_1.05-8ubuntu1_i386 bug

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