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/dnsfunnel-daemon.html | 112 ++++++++++++++++++++++++++++++ doc/dnsfunnel-translate.html | 70 +++++++++++++++++++ doc/dnsfunneld.html | 160 +++++++++++++++++++++++++++++++++++++++++++ doc/index.html | 116 +++++++++++++++++++++++++++++++ doc/upgrade.html | 28 ++++++++ 5 files changed, 486 insertions(+) create mode 100644 doc/dnsfunnel-daemon.html create mode 100644 doc/dnsfunnel-translate.html create mode 100644 doc/dnsfunneld.html create mode 100644 doc/index.html create mode 100644 doc/upgrade.html (limited to 'doc') diff --git a/doc/dnsfunnel-daemon.html b/doc/dnsfunnel-daemon.html new file mode 100644 index 0000000..d93d463 --- /dev/null +++ b/doc/dnsfunnel-daemon.html @@ -0,0 +1,112 @@ + + + + + + dnsfunnel: the dnsfunnel-daemon program + + + + + + +

+ +

The `dnsfunnel-daemon` program

+ +

+dnsfunnel-daemon binds to a local UDP socket, drops its +privileges, then executes into dnsfunneld. +

+ +

Interface

+ +

+     dnsfunnel-daemon [ -v verbosity ] [ -d notif ] [ -U | -u uid -g gid ] [ -i ip:port ] [ -R root ] [ -b bufsize ] [ -f cachelist ] [ -T | -t ] [ -N | -n ]
+

+ +

dnsfunnel-daemon creates a UDP inet domain socket and binds it +to IPv4 address ip (normally 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 execs into dnsfunneld with the +UDP socket as its standard input.

+ +

+ The point of dnsfunnel-daemon is to separate the administrative +operations of starting a daemon from the actual serving part, which is +handled by dnsfunneld. +

+ +

Exit codes

+ +

100: wrong usage
111: system call failed
126: failed to exec dnsfunneld
127: could not find the dnsfunneld executable

+ +

Options

+ +

-v verbosity : verbosity of the +dnsfunneld program. This option is passed as is +to dnsfunneld. Default is 1. 0 suppresses warning +messages. Higher values may give more informational messages.
-d notif : readiness notification. This option +is passed as is to dnsfunneld, which will print a +newline to descriptor notif when it is ready. Default is no readiness +notification.
-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:port : bind the socket to +IPv4 ip and port port. Default for ip is +127.0.0.1; default for port is 53.
-R root : chroot to root. Note that +this option only increases security if you also drop privileges.
-b bufsize : try and reserve a kernel buffer +size of bufsize bytes for the socket. Default is 131072. If the given +bufsize is 0, then dnsfunnel-daemon will use whatever the +default is for your kernel.
-f cachelist : Use cachelist as the +file that dnsfunneld reads its cache addresses +from. Default is /run/dnsfunnel-caches, or file +if the --with-cachelist=file option has been given to the +configure script at build time.

+ +

+ The other options control the activation or deactivation of various +dnsfunneld features: +

-T : Do not activate truncation of responses. This is +the default.

-t : 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. When receiving an A +(resp. AAAA) query to forward, also make an AAAA (resp. A) query, and adjust +the response accordingly. 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 (in which case that response is forwarded to the client) and +an incorrect one (in which case NODATA is answered to the client instead).

Other options may be added in the future.

+ + + + diff --git a/doc/dnsfunnel-translate.html b/doc/dnsfunnel-translate.html new file mode 100644 index 0000000..9dde27d --- /dev/null +++ b/doc/dnsfunnel-translate.html @@ -0,0 +1,70 @@ + + + + + + dnsfunnel: the dnsfunnel-translate program + + + + + + +

+dnsfunnel
+Software
+skarnet.org +

+ +

The `dnsfunnel-translate` program

+ +

+dnsfunnel-translate translates a file in resolv.conf +format to a file in dnsfunneld format. +

+ +

Interface

+ +

+     dnsfunnel-translate [ -i inputfile ] [ -o outputfile ] [ -x ignoredip ]
+

+ +

dnsfunnel-translate opens inputfile and parses it. It reads +and processes lines beginning with nameserver followed by an IP +address (v4 or v6). It ignores other lines.
It writes the IP addresses, without the nameserver keyword, +to outputfile, one per line.
If a nameserver address is ignoredip, it does not +get printed to outputfile +
dnsfunnel-translate exits 0 when it has finished processing +inputfile.

+ +

Exit codes

+ +

0: success
1: no suitable IP found in the input file
100: wrong usage
111: system call failed

+ +

Options

+ +

-i inputfile : process inputfile. +Default is /etc/resolv.conf.
-o outputfile : write the result to +outputfile. Default is /run/dnsfunnel-caches, or file +if the --with-cachelist=file option has been given to the +configure script at build time.
-x ignoredip : ignore the ignoredip +IPv4 address if it shows up as a nameserver in inputfile. +Default is 127.0.0.1. The point of this option is to avoid copying +to outputfile the IPv4 address that the +dnsfunnel-daemon daemon will be bound to.

+ + + 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 + + + + + + +

+dnsfunnel
+Software
+skarnet.org +

+ +

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.

+ + + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..fe8e8d4 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,116 @@ + + + + + + dnsfunnel - A small local DNS cache daemon + + + + + + +

+Software
+skarnet.org +

+ +

dnsfunnel

+ +

What is it ?

+ +

+ dnsfunnel is a small daemon listening to DNS client requests over UDP +(typically from the libc's +getaddrinfo() +function) and forwards them to a list of DNS caches. It provides the +client with the first answer it gets, trimming the answer so it fits +in an UDP packet. +

+ +

+ dnsfunnel is especially useful for distributions using the +musl libc, which does not support +TCP DNS transport. It was originally written to be used in the +Alpine Linux distribution. +

+ +

Installation

+ +

Requirements

+ +

A POSIX-compliant system with a standard C development environment. +The system must also support chroot()
GNU make, version 3.81 or later
skalibs version +2.10.0.0 or later. It's a build-time requirement. It's also a run-time +requirement if you link against the shared version of the skalibs +library.
s6-dns version +2.3.3.0 or later. It's a build-time requirement. It's also a run-time +requirement if you link against the shared version of the s6dns +library.

+ +

Licensing

+ +

+ dnsfunnel is free software. It is available under the +ISC license. +

+ +

Download

+ +

The current released version of dnsfunnel is +0.0.1.0. + (This is a lie. +dnsfunnel is in alpha development at the moment, and only +available through git.)
Alternatively, you can checkout a copy of the +dnsfunnel +git repository: +
```
 git clone git://git.skarnet.org/dnsfunnel 
```
There's also a +GitHub mirror +of the dnsfunnel git repository.

+ +

Compilation

+ +

See the enclosed INSTALL file for installation details.

+ +

Upgrade notes

+ +

This page lists the differences to be aware of between +the previous versions of dnsfunnel and the current one.

+ +

Reference

+ +

Commands

+ +

Related resources

+ +

dnsfunnel is discussed on the +skaware mailing-list.

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..6b46bde --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,28 @@ + + + + + + dnsfunnel: how to upgrade + + + + + + +

+dnsfunnel
+Software
+skarnet.org +

+ +

What has changed in dnsfunnel

+ +

in 0.0.1.0

+ +

Initial release.

+ + + -- cgit v1.2.3

The dnsfunnel-daemon program

Interface

Exit codes

Options

The dnsfunnel-translate program

Interface

Exit codes

Options

The dnsfunneld program

Interface

Signals

Exit codes

Options

DNS forwarding behaviour

dnsfunneld operations

Notes

dnsfunnel

What is it ?

Installation

Requirements

Licensing

Download

Compilation

Upgrade notes

Reference

Commands

Related resources

What has changed in dnsfunnel

in 0.0.1.0

The `dnsfunnel-daemon` program

The `dnsfunnel-translate` program

The `dnsfunneld` program