diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2014-12-10 03:05:47 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2014-12-10 03:05:47 +0000 |
| commit | 416ef5e2bf59bb2e45066a1d5d91ac677c0f48e5 (patch) | |
| tree | 1c746d673dcec7a8488c6ac51db8245411034376 /doc/skadns/skadnsd.html | |
| download | s6-dns-416ef5e2bf59bb2e45066a1d5d91ac677c0f48e5.tar.xz | |
Initial commit
Diffstat (limited to 'doc/skadns/skadnsd.html')
| -rw-r--r-- | doc/skadns/skadnsd.html | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/doc/skadns/skadnsd.html b/doc/skadns/skadnsd.html new file mode 100644 index 0000000..e8316b8 --- /dev/null +++ b/doc/skadns/skadnsd.html @@ -0,0 +1,120 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-dns: the skadnsd internal program</title> + <meta name="Description" content="s6-dns: the skadnsd internal program" /> + <meta name="Keywords" content="s6-dns skadnsd asynchronous dns daemon" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<a href="index.html">libskadns</a><br /> +<a href="../index.html">s6-dns</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a><p /> + +<h1> The <tt>skadnsd</tt> program </h1> + +<p> +<tt>skadnsd</tt> is the skadns daemon. It reads a series of +queries from the client on stdin, resolves them asynchronously, +and writes +the answers to the client as soon as it gets them. It exits 0 +when its stdin closes. It exits 111 on any serious error, +writing the error message to stderr. +</p> + +<p> +<tt>skadnsd</tt> is a stub resolver. It reads <tt>/etc/resolv.conf</tt> +at start looking for a "nameserver" line containing +the address of a DNS cache (aka full resolver). It will exit 111 if it cannot +find any valid cache address in <tt>/etc/resolv.conf</tt>. If the +<tt>DNSCACHEIP</tt> environment variable is set, its value overrides +what <tt>/etc/resolv.conf</tt> says. +</p> + +<h2> Interface </h2> + +<p> +skadnsd does not fork, does not background itself automatically, +and does not use syslog. It is not meant to be run directly by the +user: it will be invoked and spawned by the skadns library calls. +</p> + +<p> + There are 2 ways to use skadnsd: +</p> +<ol> +<li> (preferred) Use the <tt>skadns_startf()</tt> library call. +A <tt>skadnsd</tt> child will then be spawned from your +calling process, and automatically reaped when you call +<tt>skadns_end()</tt>. It requires care with applications that +trap SIGCHLD. </li> +<li> Use the <tt>skadns_start()</tt> library call, together with +a <em>skadnsd service</em>. </li> +</ol> + +<h3> Running skadnsd as a child process </h3> + +<p> + This is the simplest and safest way of using <em>skadns</em>. Forget +about <tt>skadnsd</tt>: just start your library calls with +<tt>skadns_startf()</tt> and end them with <tt>skadns_end()</tt>. +Be careful though: if you're using SIGCHLD handlers, make sure they do +not interfere with the child processes your application has without +knowing. This is a general Unix programming rule. +</p> + +<h3> Running a skadnsd as a daemon: the skadnsd service </h3> + +<p> + In this mode, you set up a daemon listening on a Unix domain socket, +and clients connect to this socket to access the service. The +advantage of this setup is that it works even with badly written +clients that have trouble handling a child process; the drawback is +that it requires support from the system administrator. +</p> + +<p> +skadnsd has no "standalone" mode: it is designed to work with a Unix +domain superserver, like +<a href="http://skarnet.org/software/s6-networking/s6-ipcserver.html">s6-ipcserver</a>. +skadnsd follows the <a href="http://cr.yp.to/proto/ucspi.txt">UCSPI"</a> +interface, it can be directly executed from the superserver. +</p> + +<p> +You should run skadnsd (and its Unix superserver) under a specific user +and group, for elementary security reasons; and you should run its +dedicated logger as another specific user. Do NOT run skadnsd as root; +check your super-server documentation to find how +to run it under a specific account. +</p> + +<h2> Notes </h2> + +<ul> + <li> Users should never invoke <tt>skadnsd</tt> directly. It's an +internal program designed to be spawned by the skadns library. </li> + <li> If a poorly designed client sends a lot of queries and never reads the +answers, those will indefinitely queue up in the daemon, eating up +memory. You should run your process (or your Unix superserver, if you're +using a skadnsd service) under a program like +<a href="http://skarnet.org/software/s6/s6-softlimit.html">s6-softlimit</a> to +set a memory limit to every skadnsd instance. If skadnsd runs out of +allowed memory, it will simply die. </li> + <li> If you're using a skadnsd service: you should configure your +Unix superserver to set a maximum +number of concurrent skadnsd instances; most +Unix superserver implementations provide the +<tt>-c</tt> option for this. The s6-ipcserver program also +allows you to specify a maximum number of concurrent daemon +instances per client. </li> +<li> The only way to ensure absolute reliability of the skadnsd process is +to run it as a child, not as a daemon: use <tt>skadnsd_startf()</tt> when +possible. </li> +</ul> + +</body> +</html> |