diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dnsfunnel-daemon.html | 115 | ||||
| -rw-r--r-- | doc/dnsfunnel-translate.html | 6 | ||||
| -rw-r--r-- | doc/dnsfunneld.html | 107 | ||||
| -rw-r--r-- | doc/index.html | 8 |
4 files changed, 81 insertions, 155 deletions
diff --git a/doc/dnsfunnel-daemon.html b/doc/dnsfunnel-daemon.html deleted file mode 100644 index b779635..0000000 --- a/doc/dnsfunnel-daemon.html +++ /dev/null @@ -1,115 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>dnsfunnel: the dnsfunnel-daemon program</title> - <meta name="Description" content="dnsfunnel: the dnsfunnel-daemon program" /> - <meta name="Keywords" content="dnsfunnel daemon /etc/resolv.conf local cache resolver 127.0.0.1" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">dnsfunnel</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>dnsfunnel-daemon</tt> program </h1> - -<p> -<tt>dnsfunnel-daemon</tt> binds to a local UDP socket, drops its -privileges, then executes into <a href="dnsfunneld.html">dnsfunneld</a>. -It is the high-level entry point to invoke in scripts that want to launch -<a href="dnsfunneld.html">dnsfunneld</a>. - -</p> - -<h2> Interface </h2> - -<pre> - dnsfunnel-daemon [ -v verbosity ] [ -d notif ] [ -U | -u uid -g gid ] [ -i ip:port ] [ -R root ] [ -b bufsize ] [ -f cachelist ] [ -T | -t ] [ -N | -n ] -</pre> - -<ul> - <li> dnsfunnel-daemon creates a UDP inet domain socket and binds it -to IPv4 address <em>ip</em> (normally 127.0.0.1) and port <em>port</em> -(normally 53). </li> - <li> Depending on the options it has been given, it may chroot and lose -privileges on its gid and uid. </li> - <li> It execs into <a href="dnsfunneld.html">dnsfunneld</a> with the -UDP socket as its standard input. </li> -</ul> - -<p> - The point of <tt>dnsfunnel-daemon</tt> is to separate the administrative -operations of starting a daemon from the actual serving part, which is -handled by <a href="dnsfunneld.html">dnsfunneld</a>. -</p> - -<h2> Exit codes </h2> - -<ul> - <li> 100: wrong usage </li> - <li> 111: system call failed </li> - <li> 126: failed to exec <a href="dnsfunneld.html">dnsfunneld</a> </li> - <li> 127: could not find the <a href="dnsfunneld.html">dnsfunneld</a> executable </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-v <em>verbosity</em></tt> : verbosity of the -<a href="dnsfunneld.html">dnsfunneld</a> program. This option is passed as is -to <a href="dnsfunneld.html">dnsfunneld</a>. Default is 1. 0 suppresses warning -messages. Higher values may give more informational messages. </li> - <li> <tt>-d <em>notif</em></tt> : readiness notification. This option -is passed as is to <a href="dnsfunneld.html">dnsfunneld</a>, which will print a -newline to descriptor <em>notif</em> when it is ready. Default is no readiness -notification. </li> - <li> <tt>-U</tt> : read an uid in the UID environment variable and a gid -in the GID environment variable, and drop privileges to that uid/gid. </li> - <li> <tt>-u <em>uid</em></tt> : drop privileges to numerical uid -<em>uid</em>. </li> - <li> <tt>-g <em>gid</em></tt> : drop privileges to numerical gid -<em>gid</em>. </li> - <li> <tt>-i <em>ip</em>:<em>port</em></tt> : bind the socket to -IPv4 <em>ip</em> and port <em>port</em>. Default for <em>ip</em> is -<tt>127.0.0.1</tt>; default for <em>port</em> is 53. </li> - <li> <tt>-R <em>root</em></tt> : chroot to <em>root</em>. Note that -this option only increases security if you also drop privileges. </li> - <li> <tt>-b <em>bufsize</em></tt> : try and reserve a kernel buffer -size of <em>bufsize</em> bytes for the socket. Default is 131072. If the given -<em>bufsize</em> is 0, then <tt>dnsfunnel-daemon</tt> will use whatever the -default is for your kernel. </li> - <li> <tt>-f <em>cachelist</em></tt> : Use <em>cachelist</em> as the -file that <a href="dnsfunneld.html">dnsfunneld</a> reads its cache addresses -from. Default is <tt>/run/dnsfunnel-caches</tt>, or <em>file</em> -if the <tt>--with-cachelist=<em>file</em></tt> option has been given to the -configure script at build time. </li> -</ul> - -<p> - The other options control the activation or deactivation of various -<a href="dnsfunneld.html">dnsfunneld</a> features: -</p> - <li> <tt>-T</tt> : Do not activate truncation of responses. This is -the default. </li> - <li> <tt>-t</tt> : 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. </li> - <li> <tt>-N</tt> : Do not activate nxdomain workaround. This is the -default. </li> - <li> <tt>-n</tt> : 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). </li> - <li> Other options may be added in the future. </li> -</ul> - -</body> -</html> diff --git a/doc/dnsfunnel-translate.html b/doc/dnsfunnel-translate.html index 9dde27d..112a615 100644 --- a/doc/dnsfunnel-translate.html +++ b/doc/dnsfunnel-translate.html @@ -56,14 +56,12 @@ get printed to <tt>outputfile</tt> <li> <tt>-i <em>inputfile</em></tt> : process <em>inputfile</em>. Default is <tt>/etc/resolv.conf</tt>. </li> <li> <tt>-o <em>outputfile</em></tt> : write the result to -<em>outputfile</em>. Default is <tt>/run/dnsfunnel-caches</tt>, or <em>file</em> -if the <tt>--with-cachelist=<em>file</em></tt> option has been given to the -configure script at build time. </li> +<em>outputfile</em>. Default is <tt>/run/dnsfunnel/root/caches</tt>. </li> <li> <tt>-x <em>ignoredip</em></tt> : ignore the <em>ignoredip</em> IPv4 address if it shows up as a <tt>nameserver</tt> in <em>inputfile</em>. Default is <tt>127.0.0.1</tt>. The point of this option is to avoid copying to <tt>outputfile</tt> the IPv4 address that the -<a href="dnsfunnel-daemon.html">dnsfunnel-daemon</a> daemon will be bound to. </li> +<a href="dnsfunneld.html">dnsfunneld</a> daemon will be bound to. </li> </ul> </body> diff --git a/doc/dnsfunneld.html b/doc/dnsfunneld.html index 006a6d6..5181db1 100644 --- a/doc/dnsfunneld.html +++ b/doc/dnsfunneld.html @@ -3,9 +3,9 @@ <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <meta http-equiv="Content-Language" content="en" /> - <title>dnsfunnel: the dnsfunnel-daemon program</title> - <meta name="Description" content="dnsfunnel: the dnsfunnel-daemon program" /> - <meta name="Keywords" content="dnsfunnel daemon /etc/resolv.conf local cache resolver 127.0.0.1" /> + <title>dnsfunnel: the dnsfunneld program</title> + <meta name="Description" content="dnsfunnel: the dnsfunneld program" /> + <meta name="Keywords" content="dnsfunnel daemon dnsfunneld /etc/resolv.conf local cache resolver 127.0.0.1" /> <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> </head> <body> @@ -29,19 +29,25 @@ queries, the responses, or both. <h2> Interface </h2> <pre> - dnsfunneld [ -v verbosity ] [ -d notif ] [ -o ops ] cachelist + dnsfunneld [ -v <em>verbosity</em> ] [ -1 ] [ -U | -u <em>uid</em> -g <em>gid</em> ] [ -i <em>ip</em>:<em>port</em> ] [ -R <em>root</em> ] [ -b <em>bufsize</em> ] [ -T | -t ] [ -N | -n ] </pre> <ul> - <li> dnsfunneld reads the <em>cachelist</em> file, expecting to find + <li> dnsfunneld creates a UDP inet domain socket and binds it +to IPv4 address <em>ip</em> (normally 127.0.0.1) and port <em>port</em> +(normally 53). </li> + <li> Depending on the options it has been given, it may chroot and lose +privileges on its gid and uid. </li> + <li> It reads the <tt>caches</tt> 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. </li> - <li> dnsfunneld expects to have a bound UDP inet domain socket as -its standard input. It expects to receive packets no more than 512 + <li> dnsfunneld expects to receive packets no more than 512 bytes long, only containing DNS normal queries (QUERY) for the IN -class. </li> - <li> Depending on <em>ops</em>, dnsfunneld may send additional queries -to the caches listed in <em>cachelist</em>. It handles the answers +class, on its socket. </li> + <li> Depending on options, dnsfunneld may send additional queries +to the caches listed in <tt>caches</tt>. It handles the answers internally: the additional queries are invisible to clients. </li> <li> dnsfunneld is a long-lived process. </li> </ul> @@ -49,7 +55,7 @@ internally: the additional queries are invisible to clients. </li> <h2> Signals </h2> <ul> - <li> SIGHUP: read the <em>cachelist</em> file again, updating its + <li> SIGHUP: read the <tt>caches</tt> 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. </li> <li> SIGTERM: enter lame-duck mode, do not accept any more queries. When @@ -70,20 +76,51 @@ all in-flight queries have been answered, exit 0. <li> <tt>-v <em>verbosity</em></tt> : verbosity. Default is 1. 0 suppresses warning messages. Higher values may give more informational messages in the future. </li> - <li> <tt>-d <em>notif</em></tt> : readiness notification. When -dnsfunneld is ready to process queries, write a newline to file descriptor -<em>notif</em>. <em>notif</em> must be 3 or greater. Default is no notification -at all. </li> - <li> <tt>-o <em>ops</em></tt> : perform various operations on -queries. <em>ops</em> is a decimal integer that is treated as a bitfield. -Default is 0. Operations are listed below. </li> + <li> <tt>-1</tt> : readiness notification. When +dnsfunneld is ready to process queries, write a newline to stdout, then +close it. Default is no notification at all. </li> + <li> <tt>-U</tt> : read an uid in the UID environment variable and a gid +in the GID environment variable, and drop privileges to that uid/gid. </li> + <li> <tt>-u <em>uid</em></tt> : drop privileges to numerical uid +<em>uid</em>. </li> + <li> <tt>-g <em>gid</em></tt> : drop privileges to numerical gid +<em>gid</em>. </li> + <li> <tt>-i <em>ip</em>:<em>port</em></tt> : bind the socket to +IPv4 <em>ip</em> and port <em>port</em>. Default for <em>ip</em> is +<tt>127.0.0.1</tt>; default for <em>port</em> is 53. </li> + <li> <tt>-R <em>root</em></tt> : chroot to <em>root</em>. Default +is <tt>/run/dnsfunnel/root</tt>. Note that chrooting only increases security +if privileges are also dropped via the <tt>-U</tt> or <tt>-u</tt> and <tt>-g</tt> +options. Chrooting is only supported on platforms that have the <tt>chroot()</tt> +primitive. You can also disable it by passing an empty string as the argument +to <tt>-R</tt>. </li> + <li> <tt>-b <em>bufsize</em></tt> : try and reserve a kernel buffer +size of <em>bufsize</em> bytes for the socket. The default is whatever the +default is for your kernel. </li> +</ul> + +<p> + The other options control the activation or deactivation of various +features. See below for the detail of operations. +</p> + +<ul> + <li> <tt>-T</tt> : Do not activate truncation of responses. This is +the default. </li> + <li> <tt>-t</tt> : 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. </li> + <li> <tt>-N</tt> : Do not activate NXDOMAIN workaround. This is the +default. </li> + <li> <tt>-n</tt> : Activate NXDOMAIN workaround. </li> + <li> Other options may be added in the future. </li> </ul> <h2> DNS forwarding behaviour </h2> <ul> <li> When it receives a query, dnsfunneld forwards it to the first DNS cache -in the list it has read from the <em>cachelist</em> file. </li> +in the list it has read from the <tt>caches</tt> file. </li> <li> If it receives a response with the TC bit, it resends the query over TCP. </li> <li> If it receives a suitable response within a given time frame, it forwards it to the client. </li> @@ -112,29 +149,37 @@ time to resolve; </li> <h2> dnsfunneld operations </h2> <p> - <em>ops</em> 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. + Depending on the options it has been given, dnsfunneld may perform the +following operations on the queries or responses it receives: </p> -<ul> - <li> bit 0: activate truncation. If a DNS response is more than 510 bytes +<h3> Truncation </h3> + +<p> + If a DNS response is more than 510 bytes long, dnsfunneld will truncate the <em>last</em> 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. </li> - <li> 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 <em>ops</em>, -for every A or AAAA query dnsfunneld receives and forwards, it also sends +without reordering them is the natural way of truncating a response. +</p> + +<h3> NXDOMAIN workaround </h3> + +<p> + 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. </li> -</ul> +before the clients get their answers. +</p> <h2> Notes </h2> diff --git a/doc/index.html b/doc/index.html index fe8e8d4..b52f70a 100644 --- a/doc/index.html +++ b/doc/index.html @@ -42,15 +42,14 @@ TCP DNS transport. It was originally written to be used in the <h3> Requirements </h3> <ul> - <li> A POSIX-compliant system with a standard C development environment. -The system must also support <tt>chroot()</tt> </li> + <li> A POSIX-compliant system with a standard C development environment. </li> <li> GNU make, version 3.81 or later </li> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> 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. </li> <li> <a href="//skarnet.org/software/s6-dns/">s6-dns</a> version -2.3.3.0 or later. It's a build-time requirement. It's also a run-time +2.3.4.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. </li> @@ -67,7 +66,7 @@ library. </li> <ul> <li> The current released version of dnsfunnel is -<a href="dnsfunnel-0.0.1.0.tar.gz">0.0.1.0</a>. +<!--<a href="dnsfunnel-0.0.1.0.tar.gz">-->0.0.1.0<!--</a>-->. (This is a lie. dnsfunnel is in alpha development at the moment, and only available through git.) </li> @@ -100,7 +99,6 @@ the previous versions of dnsfunnel and the current one. </li> <h3> Commands </h3> <ul> -<li><a href="dnsfunnel-daemon.html">The <tt>dnsfunnel-daemon</tt> program</a></li> <li><a href="dnsfunneld.html">The <tt>dnsfunneld</tt> program</a></li> <li><a href="dnsfunnel-translate.html">The <tt>dnsfunnel-translate</tt> program</a></li> </ul> |