djbdnscurve6:(dnscache)

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 DNSCurve capable. Now, both queries and responses are encrypted using either the propriatory DNSCurve stream format, or if the environment variable $USETXTFORMAT 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 falls back to unencrypted queries. dnscache may be 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 DNSCurve enabled name servers using 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. A value like n=1 might impact correctly behaving DNSCurve 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. The value UZ5FALLBACK=2 is initally set-up by dnscache-conf.

BINDINGS
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. dnscache is able to serve all existing IP addresses on the host (multi-homing). For IPv4 specify 0.0.0.0 and for IPv6 set :: within env/IP. In case of :: dnscache additionally supports reverse anycasting for IPv6. Now, dnscache will accept IPv6 packets from every available interface, even if dynamically allocated. dnscache forces simultaneous bind to IPv4 and IPv6 addresses in case a 'pseudo' IP address is specified as :0. However, this will not trigger reverse anycasting support. dnscache sends outgoing packets from high ports of $IPSEND. Typically $IPSEND is 0.0.0.0 or :: meaning the machine's primary IP address covering both IPv4 and IPv6. However, a specific sending IP address can be used, which might be destinct from the receiving ones.

FOWARDING MODE
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 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 DNSCurve query a standard query will be used, irrespectively if the server's FQDN starts with the magic uz5. Example: In case $IP4 is set, dnscache will contact only nameserves given their IPv4 address.

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 they 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 memory handling a query, it discards that query. dnscache asks the operating system to reserve a 128K buffer for bursts of incoming UDP queries. If a new UDP query arrives when dnscache is already handling 400 simultaneous UDP queries, dnscache drops the oldest query. If a new TCP connection arrives when dnscache is already handling 40 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   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 UDP 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 determine cache times (up to an hour) for zero-record responses and nonexistent domains.

RESPONSES TO QUERIES
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. 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