Consulting djbware Publications


dnscache is enabled to do the following:

Figure: Concept and layout of dnscache; IP addresses are samples


dnscache is a DNS none-authoritative cache server, forwarder, and recurser. It supports UDP and TCP queries over IPv4 and IPv6 both for the requesting client as well as for the receiving name servers (NS). EDNS0 support is provided for ingress DNS messages. It is able to encrypt DNS queries and decrypt DNS responses using the DNSCurve format in the 'streamline' as well as in the 'txt' format. dnscache however, does not support DNSSec neither for querying nor for validation. dnscache can simultaneously bind to IPv4 and IPv6 network addresses and supports 'reverse IPv6-anycasting'.


System Setup

It is preferrable to install D.J. Bernsteins's daemontools or Bruce Guenter's daemontools-encore. Further alternatives are Gerrit Pape's runit though in principal systemd and any of its derivates or the s6 toolbox to manage Unix services will do.

Given the first two, dnscache-conf can be successfully applied to setup dnscache.

dnscache runs chrooted under a particular user, typically dnscache. while located usually at /etc/dnscache.

The run script for dnscache looks like:

#!/bin/sh exec 2>&1 exec < seed exec envdir ./env sh -c ' exec envuidgid dnscache softlimit -d "$DATALIMIT" /usr/local/bin/dnscache '

Here, envdir is used to source dnscache's ./env directory and populating the required environment variables, while softlimit may be used to restrict the heap memory (used for TCP only).
Prior of calling dnscache some random seed needs to become available.

dnscache logs to STDOUT which shall be managed by multilog with a dedicated systems user and rotation capability.

A run script for multilog can be very generic:

#!/bin/sh exec setuidgid daemon multilog t s1677721 /var/log/dnscache

It should be noted, that dnscache writes condensed log lines without a timestamp while appending this to the current file. Thus, it is advisable to restrict the logfile size.

systemd Setup

systemd needs a little tweaking to make it work with dnscache. Here is a two tier approach:

[Unit] Description=dnscache daemon ConditionFileIsExecutable=/usr/local/bin/dnscache ConditionFileIsExecutable=/usr/local/bin/softlimit [Install] [Service] Type=simple Restart=always StandardOutput=syslog StandardError=inherit SyslogFacility=mail SyslogIdentifier=dnscache Environment=PATH=/usr/local/bin:/bin:/usr/sbin:/sbin ExecStart=/service/dnscache/run WorkingDirectory=/etc/dnscache

Certainly, some changes here are required (eg. SysLogFacility). This unit file has be placed into your systemd's configuration directory. Now, you can start dnscache by means of systemctl start dnscache.

Note: It is strongly adviced to disable systemd's own DNS cache service! Consider to include dnscache listing IP address into /etc/resolv.conf! However, entries in here are potentically subject of overwriting by DHCP services!

Service Configuration

dnscache can run in two different operational modes:

In both cases though, the DNS responses are cached. In recursion mode, encryption of the DNS messges is automatically facilitated in case the upstrean name server supports DNSCurve and the NS's name includes its public key.

The main dnscache configuration is provided in the directory ./env. Here one defines in particular files:

Client Qualification

Queries from clients are accepted by, dnscache if the sending IPv4 or IPv6 address is listed in the directory ./root/ip as file name given the most significant octetts. Exceptions are be defined by prepending a hash sign # for a given IP addresss here.

Name Server Qualification

Name Server (NS) qualification is achieved in two steps:

  1. Root servers or other DNS cache servers are given by their IP address in the 'hint file' ./root/servers/@. Any other domains can be listed here as file by name and including the IPs of their name servers. Reverse zones follow the same convention but now with the reverse IP name as file name.
  2. Given the content of the file ./env/FLAGEDSERVER equals one, particular NS can be 'blacklisted' providing their IP address in ./root/ip/ touching a file with their IP address as file name prepended with a percent sign %.

Content Configuration

dnscache uses the ./root/server directory to store information about the name servers to consult:

Invocation of dnscache-conf will look for a file /etc/ and will copy the content to @; otherwise it will complain and stop. An additional script is provided in djbdnscurve6's source ./scripts directory allowing to query the IPv4 and IPv6 addresses of the root name server (by different DNS tools) while setting up a tailored list for those.