From fab29b78d87d0114ecbdfbcac3b0e7c0edb463ba Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 28 Dec 2020 22:09:00 +0000 Subject: Initial commit --- doc/dnsfunneld.html | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 doc/dnsfunneld.html (limited to 'doc/dnsfunneld.html') diff --git a/doc/dnsfunneld.html b/doc/dnsfunneld.html new file mode 100644 index 0000000..006a6d6 --- /dev/null +++ b/doc/dnsfunneld.html @@ -0,0 +1,160 @@ + + + + + + dnsfunnel: the dnsfunnel-daemon 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 ] [ -d notif ] [ -o ops ] cachelist
+

+ +

dnsfunneld reads the cachelist file, 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 have a bound UDP inet domain socket as +its standard input. It expects to receive packets no more than 512 +bytes long, only containing DNS normal queries (QUERY) for the IN +class.
Depending on ops, dnsfunneld may send additional queries +to the caches listed in cachelist. It handles the answers +internally: the additional queries are invisible to clients.
dnsfunneld is a long-lived process.

+ +

Signals

+ +

SIGHUP: read the cachelist 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.
-d notif : readiness notification. When +dnsfunneld is ready to process queries, write a newline to file descriptor +notif. notif must be 3 or greater. Default is no notification +at all.
-o ops : perform various operations on +queries. ops is a decimal integer that is treated as a bitfield. +Default is 0. Operations are listed below.

+ +

DNS forwarding behaviour

+ +

When it receives a query, dnsfunneld forwards it to the first DNS cache +in the list it has read from the cachelist 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

+ +

+ ops is an integer used as a bitfield. Depending on which bits are set, +various operations are performed on queries or answers, slightly modifying the +behaviour described above. +

+ +

bit 0: activate 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.
bit 1: activate workaround for some servers that incorrectly report +NXDOMAIN when they're asked for an AAAA record, and no such record exists +for the domain but an A record exists. When that bit is set in ops, +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.
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.

+ + + -- cgit v1.3.1

The dnsfunneld program