1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<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>
<p>
The goal of shibari-server-udp, at the moment, is to be a drop-in replacement
for the <a href="https://cr.yp.to/djbdns/tinydns.html">tinydns</a> program,
while being more maintainable.
</p>
<div id="interface">
<h2> Interface </h2>
</div>
<pre>
shibari-server-udp [ -U ] [ -v <em>verbosity</em> ] [ -d <em>notif</em> ] [ -f <em>tdbfile</em> ] [ -w <em>wtimeout</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> -U </dt>
<dd> Drop privileges. shibari-server-udp will expect the UID and GID
environment variables to contain a suitable uid and gid, and will change
to this uid and gid after binding its socket. </dd>
<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> -w <em>wtimeout</em> </dt>
<dd> Write timeout. If shibari-server-udp is unable
to send its answer in <em>wtimeout</em> milliseconds, which means the network is
congested, give up and go back to listening to other queries.
The default is <strong>0</strong>, which means infinite: shibari-server-udp will
wait forever until the network decongests in order to send its answer (which
may prevent it from servicing other queries). </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>
|
