NAME

       dnscache - DNS cache server and iterative resolver

DESCRIPTON

       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 for faster client lookup.

       Upon sending iterative queries dnscache will use the received FQDN of
       authoritive name servers to evalute their potential usage for
       encryption in case the hostname starts with uz5.  Subsequently dnscache
       will automatically encrypt queries to those servers identified to be
       CurveDNS capable.  Now, both queries and responses are encrypted using
       either the propriatory CurveDNS stream format, or if the environment
       variable $USETEXTFORMAT is set, the less performant TXT format to cope
       with deep packet inspecting Firewalls analysing DNS traffic and
       expecting a standard DNS header.

       In case the name server does not respond to encrypted UDP queries,
       dnscache may fall back to unencrypted queries after $UZ5FALLBACK
       trials, which usually defaults 2 and can be modified setting this
       environment variable.

       dnscache maybe used in a forward only mode.


CONFIGURATION

       Normally dnscache is set up by the dnscache-conf 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.  In case $USETEXTFORMAT is set, dnscache
       will send queries even for CurveDNS enabled name servers in with
       standard DNS TXT headers.

       dnscache can be adviced to go to unencrypted fallback mode, if hostname
       of the name server starts with uz5 but don't respond to encrypted UDP
       queries for this lookup.  This behavior can be changed using the
       environment variable $UZ5FALLBACK=n.  The value n=2 is the default
       value initally set-up be dnscache-conf.  A value like n=1 might impact
       correctly behaving CurveDNS name servers which do not respond to the
       initial query, while larger values like n=3 delays name resolution for
       those name servers significantly.  Setting $UZ5FALLBACK=0 disables
       fallback mode; which is the default.


BINDING

       dnscache listens for incoming UDP packets and TCP connections addressed
       to port 53 for $IP, which could be either an IPv4 or IPv6 scoped
       addresss, supporting both public or internal access.

       Given a host scope, one typically uses the addresses 127.0.0.1, ::1, or
       fe80::1%lo0.  In those cases, dnscache serves the own host only.

       Setting up dnscache on a private network requires private IPv4
       addresses; while for IPv6 ULA and LLU addresses can be used. Examples:
       10.10.10.53, fd00::53, fe80::53%eth0.
       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.  It does not contact the root servers, or any other DNS
       servers, directly.


CLIENT QUALIFICATION

       dnscache accepts a packet or connection from the IPv4 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.  For
       IPv6 addresses dnscache can be instructed in a similar way:
       ip/2001::fefe, ip/2001:a:b:c:d, ip/2001, ip/fe80 (all LLU), ip/fd00
       (all ULA).

       dnscache will silently reject packets or connections from IP addresses
       marked as 'commented out': ip/#2001::fec, ip/#192.168.1.  Rejections
       have precedence over acceptance.
        Note: In any case, the delimiter (either '.' or ':') shall not be used
       as last character.


SERVER QUALIFICATION

       If dnscache recognizes the environment variable $FLAGEDSERVER, name
       server listed under ip/ are treated in the following way: Servers
       included as ip/%1.2.3.4 or ip/%2001::a:b:c:d and given their dotted-
       decimal IPv4 or compactified IPv6 addresses are omitted for name
       resolution in case the IP address is prepended with a %.  If the IP
       addresses is prepended with a -, rather instead of a CurveDNS query a
       standard query will be used, irrespectively if the server's FQDN starts
       with the magic uz5.  Example: ip/-131.193.32.108.


ROOT SERVERS

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

       dnscache reads a list of root server given as dotted-decimal IPv4
       and/or compactified IPv6 addresses one per line from the file
       servers/@.

       A total of 32 names servers is handled, which are specified in dotted-
       decimal IPv4 or compactified IPv6 format.  Name severs specified by
       their IPv6 LLU addresses need to include the interface name via those
       are reachable.

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


MEMORY USE

       dnscache uses a fixed-size table, under 512K, to keep track of as many
       as 400 simultaneous UDP queries and 40 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

       o      A sets.  22 bytes plus 4 bytes per address plus the length of
              the owner name.

       o      AAAA sets.  22 bytes plus 16 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.


MESSAGE SIZES

       dnscache is expecting to be used on IPv6 capabable networks supporting
       a 'minimum length' MLMTU size of 1280 byte (RFC 8200) allowing larger
       UPD packet sizes than for IPv4 only.  Upon start, dnscache shows the
       UDP message size supported by default.  In addition, dnscache
       understands EDNS(0) extensions in DNS messages (RFC 6891), typically
       used by DNSSEC.


RESOLUTION AND CACHING POLICIES

       dnscache relies on a configured list of root name servers.  However,
       the IP addresses of the Internet root servers are subject of change.

       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

       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.


SPECIAL NAMES

       dnscache handles localhost internally, giving it an A record of
       127.0.0.1.  In addition, for the IPv6 address ::1 it considers those as
       ipv6-localhost together with the respective AAAA record.  dnscache
       handles 1.0.0.127.in-addr.arpa and 1.0.0...0.ip6.arpa internally,
       giving it a PTR record of 127.0.0.1 and ::1 respectively.

       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), dnscache-log(5)


REFERENCE

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



                                       8               djbdnscurve6:(dnscache)

Man(1) output converted with man2html