dnsfunnel: the dnsfunneld program

The `dnsfunneld` program

dnsfunneld is a small DNS forwarder daemon. It receives DNS queries from clients, then forwards them to one or more DNS caches. It collects the responses and forwards them back to the clients. Depending on the options it is given, it may perform light processing on the queries, the responses, or both.

Interface

     dnsfunneld [ -v verbosity ] [ -1 ] [ -U | -u uid -g gid ] [ -i ip ] [ -p port ] [ -R root ] [ -b bufsize ] [ -t globaltimeout ] [ -X | -x ] [ -N | -n ]

dnsfunneld creates a UDP inet domain socket and binds it to IP (v4 or v6) address ip (by default 127.0.0.1) and port port (normally 53).
Depending on the options it has been given, it may chroot and lose privileges on its gid and uid.
It reads the caches file (relative to its current directory, which is either the directory it has been run from or, if requested, the one it has chrooted into), expecting to find a list of IP (v4 or v6) addresses, one per line. These addresses are the DNS caches it will forward the queries to.
dnsfunneld expects to receive packets no more than 512 bytes long, only containing DNS normal queries (QUERY) for the IN class, on its socket.
Depending on options, dnsfunneld may send additional queries to the caches listed in caches. It handles the answers internally: the additional queries are invisible to clients.
dnsfunneld is a long-lived process.

Signals

SIGHUP: read the caches file again, updating its in-memory cache list. In-flight queries are still handled by the old list; the new list will only apply for queries arriving after the SIGHUP.
SIGTERM: enter lame-duck mode, do not accept any more queries. When all in-flight queries have been answered, exit 0.

Exit codes

0: SIGTERM received and all in-flight queries have been answered
100: wrong usage
111: system call failed

Options

-v verbosity : verbosity. Default is 1. 0 suppresses warning messages. Higher values may give more informational messages in the future.
-1 : readiness notification. When dnsfunneld is ready to process queries, write a newline to stdout, then close it. Default is no notification at all.
-U : read an uid in the UID environment variable and a gid in the GID environment variable, and drop privileges to that uid/gid.
-u uid : drop privileges to numerical uid uid.
-g gid : drop privileges to numerical gid gid.
-i ip : bind the socket to IP address ip. Default is 127.0.0.1.
-p port : bind the socket to port port. Default is 53.
-R root : chroot to root. Default is /run/dnsfunnel/root. Note that chrooting only increases security if privileges are also dropped via the -U or -u and -g options. Chrooting is only supported on platforms that have the chroot() primitive. You can also disable it by passing an empty string as the argument to -R.
-b bufsize : try and reserve a kernel buffer size of bufsize bytes for the socket. The default is whatever the default is for your kernel.
-t globaltimeout : maximum resolution time. If a query takes more than globaltimeout milliseconds to resolve, abandon it and return a SERVFAIL to the client. Default is 0, meaning infinite: no global timeout is set.

The other options control the activation or deactivation of various features. See below for the detail of operations.

-X : Do not activate truncation of responses. This is the default.
-x : If a DNS response is bigger than 510 bytes, truncate its last resource records until it fits into 510 bytes and can be sent in a UDP packet.
-N : Do not activate NXDOMAIN workaround. This is the default.
-n : Activate NXDOMAIN workaround.
Other options may be added in the future.

DNS forwarding behaviour

When it receives a query, dnsfunneld forwards it to the first DNS cache in the list it has read from the caches file.
If it receives a response with the TC bit, it resends the query over TCP.
If it receives a suitable response within a given time frame, it forwards it to the client.
On SERVFAIL, or after a timeout of 1 second, it gives up and sends the query to the next DNS cache in its list. (If the first cache answers after the time frame, the answer is dropped.)
If dnsfunneld reaches the end of its cache list, it retries the whole procedure starting at the beginning of the list, but with a timeout of 3 seconds. Caches that returned a SERVFAIL are crossed off the list for that query.
If the second pass fails again, dnsfunneld tries again with a timeout of 11 seconds, then with a timeout of 45 seconds. If all of this fails, it returns a SERVFAIL to the client.
A machine should not use a DNS cache that is too far away. In normal operation, a timeout of 1 second should be more than enough for a cache to answer, if it already has the answer. If the answer is absent from all caches and it takes them more than 1 second to resolve the query, the answer will be obtained by dnsfunneld in the second pass. Realistically, the only cases when caches that are not at the top of the list are used are:
- obscure DNS queries, not likely to be in the caches, and that will take time to resolve;
- or the first cache has really gone to lunch.

dnsfunneld operations

Depending on the options it has been given, dnsfunneld may perform the following operations on the queries or responses it receives:

Truncation

If a DNS response is more than 510 bytes long, dnsfunneld will truncate the last resource records in the response, until it fits into 510 bytes and can be given to the client in a UDP packet. The structure of a DNS packet makes it so the RRs are listed in order of decreasing importance, so keeping as many RRs as will fit in 510 bytes without reordering them is the natural way of truncating a response.

NXDOMAIN workaround

Some DNS servers incorrectly answer NXDOMAIN when they should just answer NODATA, and querying for another, existing, record type for the same domain allows dnsfunneld to tell the difference between a real NXDOMAIN. When that operation is requested, for every A or AAAA query dnsfunneld receives and forwards, it also sends an additional AAAA or A query for the same domain. If the main query returns NXDOMAIN, dnsfunneld waits for the response to the auxiliary query: if this response is not NXDOMAIN, then dnsfunneld answers NODATA to the client instead of NXDOMAIN. Be aware that activating this workaround can practically double the number of queries sent to the DNS caches, and may cause additional delays before the clients get their answers.

Notes

The point of dnsfunneld is to work around ill-designed or unreliable client setups with several motley nameserver entries in /etc/resolv.conf. By converting those entries to a cache list instead (via the dnsfunnel-translate program), running dnsfunneld on 127.0.0.1, and enforcing a policy of one single nameserver 127.0.0.1 entry in /etc/resolv.conf, the setup can be made more reliable and more consistent.
Such a policy can be automated, for instance, by listening to changes on the /etc/resolv.conf file (via inotify or kqueue, depending on your system) and immediately calling dnsfunnel-translate, sending a SIGHUP to dnsfunneld, and forcefully overwriting /etc/resolv.conf.
dnsfunneld can also be used as a simple forwarder, for instance to transmit DNS queries arriving on an IPv6 address to a DNS cache that only listens to IPv4 addresses.
It is easy to send a SIGHUP to dnsfunneld even without knowing its pid, if it is run under a process supervision system such as s6.

The dnsfunneld program