djbdnscurve6:
Section: Misc. Reference Manual Pages (dnscache)
Updated: 8
Index
Return to Main Contents
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.
CONFIGURATION
Normally
dnscache
is set up by the
dnscache-conf
program at directory
s.
Two main directories are common here:
s/env
used to provide persistent environment
variables and
s/root
which is given as
$ROOT
and containing the subdirectories
root/ip
used for DNS client qualification and
root/servers
providing information about the name servers
to be contacted for iterative DNS lookups or forwarding.
DNSCURVE
For iterative queries
dnscache
will evaluate the received FQDN of authoritive name servers to
to be potentially used as public key for DNSCurve
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
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.
EDNS(0)
dnscache
usually does not include additional,
RFC 6891 defined so-called EDNS(0)
DNS-T-OPT
Pseudo Resource Records
in the query announcing its
acceptable UDP response
message size.
Rather, setting
DNSOPTRR
in the environment will enable this behavior for all queries.
However, this might be inferior for the DNS resolution
in case of an upstream NS policy requiring
DNSSEC
if this optional section is recognized and the
D0
flag is not set here.
Given responses,
dnscache
understands EDNS(0) extensions in DNS messages
but ignores them silently.
PRINCIPLE OPERATION
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.
Usually,
dnscache
ats as caching server while performing
iterative queuries to nameservers.
Rather,
dnscache
may be used in a
forward only
mode providing caching service only.
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.
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.
accepts a packet or connection
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.
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.
In case
$IP4
is set,
dnscache
will contact only nameserves given their IPv4 address.
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.
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
https://cr.yp.to/djbdns.html
Index
- NAME
-
- DESCRIPTON
-
- CONFIGURATION
-
- DNSCURVE
-
- EDNS(0)
-
- PRINCIPLE OPERATION
-
- ROOT SERVERS
-
- FOWARDING MODE
-
- BINDINGS
-
- CLIENT QUALIFICATION
-
- SERVER QUALIFICATION
-
- MEMORY USE
-
- MESSAGE SIZES
-
- RESOLUTION AND CACHING POLICIES
-
- RESPONSES TO QUERIES
-
- SPECIAL NAMES
-
- SEE ALSO
-
- REFERENCE
-
This document was created by
man2html,
using the manual pages.
Time: 15:54:42 GMT, April 04, 2026