Initial commit

Signed-off-by: Laurent Bercot <ska@appnovation.com>
author: Laurent Bercot <ska-skaware@skarnet.org> 2023-12-10 11:48:01 +0000
committer: Laurent Bercot <ska@appnovation.com> 2023-12-10 11:48:01 +0000
commit: b8d0f83e6cea9640a7ee4402c163ad812237355d (patch)
tree: 57a64ac8aa0e98c40db8c36e96e7379490e44dbf /doc/shibari-server-udp.html
download: shibari-b8d0f83e6cea9640a7ee4402c163ad812237355d.tar.xz
1 files changed, 163 insertions, 0 deletions
diff --git a/doc/shibari-server-udp.html b/doc/shibari-server-udp.html
new file mode 100644
index 0000000..c8e46f8
--- /dev/null
+++ b/doc/shibari-server-udp.html
@@ -0,0 +1,163 @@
+<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>shibari: the shibari-server-udp program</title>
+    <meta name="Description" content="shibari: the shibari-server-udp program" />
+    <meta name="Keywords" content="shibari DNS s6-dns server database authoritative UDP s6-networking tinydns" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">shibari</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The shibari-server-udp program </h1>
+
+<p>
+  shibari-server-udp is a long-lived process. It binds to a UDP socket, then
+answers DNS queries it receives, until it is killed.
+</p>
+
+<div id="interface">
+<h2> Interface </h2>
+</div>
+
+<pre>
+     shibari-server-udp [ -v <em>verbosity</em> ] [ -d <em>notif</em> ] [ -f <em>tdbfile</em> ] [ -i <em>rulesdir</em> ] [ -x <em>rulesfile</em> ] [ -p <em>port</em> ] <em>ip</em>
+</pre>
+
+<ul>
+ <li> shibari-server-udp creates a UDP socket and binds it to address <em>ip</em>
+on port 53. <em>ip</em> can be IPv4 or IPv6. </li>
+ <li> It listens to non-recursive DNS queries, sent by DNS caches, and, if
+appropriate, answers with data it reads from its data file. </li>
+ <li> It reloads its data file on SIGHUP, and exits 0 on SIGTERM. </li>
+ <li> The data file is a
+<a href="https://en.wikipedia.org/wiki/Cdb_(software)">cdb</a> database; it
+must use the output format from
+<a href="https://cr.yp.to/djbdns/tinydns-data.html">tinydns-data</a>. </li>
+</ul>
+
+<div id="exitcodes">
+<h2> Exit codes </h2>
+</div>
+
+<dl>
+ <dt> 0 </dt> <dd> Clean exit. shibari-server-udp received a SIGTERM and exited. <dd>
+ <dt> 100 </dt> <dd> Bad usage. shibari-server-udp was run in an incorrect way:
+typically bad command line options. </dd>
+ <dt> 101 </dt> <dd> Cannot happen. This signals a bug in shibari-server-udp, and comes with an
+error message asking you to report the bug. Please do so, on the
+<a href="//skarnet.org/lists/#skaware">skaware mailing-list</a>. </dd>
+ <dt> 102 </dt> <dd> Misconfiguration. shibari-server-udp found something in its DNS data file
+that it does not like. </dd>
+ <dt> 111 </dt> <dd> System call failed. This usually signals an issue with the
+underlying operating system. </dd>
+</dl>
+
+<div id="options">
+<h2> Options </h2>
+</div>
+
+<dl>
+ <dt> -v <em>verbosity</em> </dt>
+ <dd> Be more or less verbose.
+A <em>verbosity</em> of 0 means no warnings, no logs, only error messages. 1
+means warnings and terse logs. 2 or more means more logs.
+Default is <strong>1</strong>. </dd>
+
+ <dt> -d <em>notif</em> </dt>
+ <dd> Write a newline to file descriptor <em>notif</em>, then close it, when
+shibari-server-udp has bound its socket, opened its file, and is ready to serve.
+This is the <a href="https://skarnet.org/software/s6/notifywhenup.html">s6
+readiness notification</a> mechanism. By default, when this option isn't given
+no readiness notification is sent. </dd>
+
+ <dt> -f <em>tdbfile</em> </dt>
+ <dd> Read DNS data from <em>tdbfile</em>.
+The default is <strong><tt>data.cdb</tt></strong>, in the current working
+directory of the shibari-server-udp process. </dd>
+
+ <dt> -i <em>rulesdir</em> </dt>
+ <dd> Use <em>rulesdir</em> as a filesystem-based
+<a href="//skarnet.org/software/s6/libs6/accessrules.html">access rules
+database</a>: ignore any message whose originating IP address isn't
+explicitly allowed. The access rules database is also used to get
+<a href="#clientlocation">client location information</a>.
+If something in <em>rulesdir</em> changes while shibari-server-udp is
+running, it will immediately pick up the change. </dd>
+
+ <dt> -x <em>rulesfile</em> </dt>
+ <dd> Use <em>rulesfile</em> as a cdb
+<a href="//skarnet.org/software/s6/libs6/accessrules.html">access rules
+database</a>, see description of <tt>-i</tt> above. <tt>-i</tt> and
+<tt>-x</tt> are equivalent; you can switch between <em>rulesdir</em>
+and <em>rulesfile</em> via the
+<a href="//skarnet.org/software/s6/s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> and
+<a href="//skarnet.org/software/s6/s6-accessrules-fs-from-cdb.html">s6-accessrules-fs-from-cdb</a>
+programs. The cdb format is more efficient but more static than the
+filesystem format. If <em>rulesfile</em> changes while shibari-server-udp
+is running, it will continue to use the old data until it receives a SIGHUP. </dd>
+
+ <dt> -p <em>port</em> </dt>
+ <dd> Binds to port <em>port</em>. Default is <strong>53</strong>. </dd>
+</dl>
+
+<div id="clientlocation">
+<h2> Client location </h2>
+</div>
+
+<p>
+ shibari-server-udp ignores client location information given as
+<tt>%lo:ipprefix</tt> lines in the file created by
+<a href="https://cr.yp.to/djbdns/tinydns-data.html">tinydns-data</a>.
+Instead, it reads client location information in LOC definitions
+present in the <em>rulesdir</em> or <em>rulesfile</em>
+access rules database. For instance,
+if you have a <tt>%lo:1.2.3</tt> line in your text data file, meaning
+that clients whose IP address is in the <tt>1.2.3.0/24</tt> IPv4
+range are identified with the <tt>lo</tt> location and that DNS data
+entries ending with <tt>:lo</tt> are visible to them, you need to
+translate this information into the accessrules format. Your
+<em>rulesdir</em> must contain the following files:
+</p>
+
+<ul>
+ <li> <tt>ip4/1.2.3.0_24/allow</tt> (may be empty) </li>
+ <li> <tt>ip4/1.2.3.0_24/env/LOC</tt> containing <tt>lo</tt> </li>
+</ul>
+
+<p>
+ (To use the <tt>-x</tt> option instead, you'd do the same, then run
+<tt>s6-accessrules-cdb-from-fs <em>rulesfile</em> <em>rulesdir</em></tt>
+to compile the information into <em>rulesfile</em>.)
+</p>
+
+<div id="notes">
+<h2> Notes </h2>
+</div>
+
+<ul>
+ <li> The DNS database can be changed at any time via an invocation of
+<a href="https://cr.yp.to/djbdns/tinydns-data.html">tinydns-data</a>.
+shibari-server-udp will keep using the old data until it receives a
+SIGHUP, at which point it will reopen its database. </li>
+ <li> shibari-server-udp is a drop-in replacement for
+<a href="https://cr.yp.to/djbdns/tinydns.html">tinydns</a>, with the
+caveat of the <a href="#clientlocation">client location mechanism</a>. </li>
+ <li> If you are using the <tt>-i<tt> or <tt>-x</tt> option, the
+access rules database can, and should, be the same one that is used by the
+<a href="//skarnet.org/software/s6-networking/s6-tcpserver-access.html">s6-tcpserver-access</a>
+program in your
+<a href="shibari-server-tcp.html">shibari-server-tcp</a> service. You
+don't want to give different permissions, or different location information,
+depending on whether a query is made over TCP or UDP. </li>
+</ul>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2023-12-10 11:48:01 +0000
committer	Laurent Bercot <ska@appnovation.com>	2023-12-10 11:48:01 +0000
commit	b8d0f83e6cea9640a7ee4402c163ad812237355d (patch)
tree	57a64ac8aa0e98c40db8c36e96e7379490e44dbf /doc/shibari-server-udp.html
download	shibari-b8d0f83e6cea9640a7ee4402c163ad812237355d.tar.xz