Refresh existing patches.
[debian/iodine.git] / man / iodine.8
1 .\" groff -man -Tascii iodine.8
2 .TH IODINE 8 "JUN 2014" "User Manuals"
3 .SH NAME
4 iodine, iodined \- tunnel IPv4 over DNS
5 .SH SYNOPSIS
6 .B iodine [-v]
7
8 .B iodine [-h]
9
10 .B iodine [-4] [-6] [-f] [-r] [-u
11 .I user
12 .B ] [-P
13 .I password
14 .B ] [-m
15 .I fragsize
16 .B ] [-t
17 .I chrootdir
18 .B ] [-d
19 .I device
20 .B ] [-R
21 .I rdomain
22 .B ] [-m
23 .I fragsize
24 .B ] [-M
25 .I namelen
26 .B ] [-z
27 .I context
28 .B ] [-F
29 .I pidfile
30 .B ] [-T
31 .I dnstype
32 .B ] [-O
33 .I downenc
34 .B ] [-L
35 .I 0|1
36 .B ] [-I
37 .I interval
38 .B ]
39 .B [
40 .I nameserver
41 .B ]
42 .I topdomain
43
44 .B iodined [-v]
45
46 .B iodined [-h]
47
48 .B iodined [-c] [-s] [-f] [-D] [-u
49 .I user
50 .B ] [-t
51 .I chrootdir
52 .B ] [-d
53 .I device
54 .B ] [-m
55 .I mtu
56 .B ] [-l
57 .I listen_ip
58 .B ] [-p
59 .I port
60 .B ] [-n
61 (
62 .B auto
63 |
64 .I external_ip
65 )
66 .B ] [-b
67 .I dnsport
68 .B ] [-P
69 .I password
70 .B ] [-z
71 .I context
72 .B ] [-F
73 .I pidfile
74 .B ] [-i
75 .I max_idle_time
76 .B ]
77 .I tunnel_ip
78 .B [
79 .I /netmask
80 .B ]
81 .I topdomain
82 .SH DESCRIPTION
83 .B iodine
84 lets you tunnel IPv4 data through a DNS 
85 server. This can be useful in situations where Internet access is firewalled,
86 but DNS queries are allowed. It needs a TUN/TAP device to operate. The 
87 bandwidth is asymmetrical,
88 with a measured maximum of 680 kbit/s upstream and 2.3 Mbit/s
89 downstream in a wired LAN test network.
90 Realistic sustained throughput on a Wifi network using a carrier-grade
91 DNS cache has been measured at some 50 kbit/s upstream and over 200 kbit/s
92 downstream.
93 .B iodine
94 is the client application,
95 .B iodined
96 is the server.
97
98 Note: server and client are required to speak the exact same protocol. In most
99 cases, this means running the same iodine version. Unfortunately, implementing
100 backward and forward protocol compatibility is usually not feasible.
101 .SH OPTIONS
102 .SS Common Options:
103 .TP
104 .B -v
105 Print version info and exit.
106 .TP
107 .B -h
108 Print usage info and exit.
109 .TP
110 .B -f
111 Keep running in foreground.
112 .TP
113 .B -u user
114 Drop privileges and run as user 'user' after setting up tunnel.
115 .TP
116 .B -t chrootdir
117 Chroot to 'chrootdir' after setting up tunnel.
118 .TP
119 .B -d device
120 Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
121 and otherwise tunX.
122 .TP
123 .B -P password
124 Use 'password' to authenticate. If not used, 
125 .B stdin
126 will be used as input. Only the first 32 characters will be used.
127 .TP
128 .B -z context
129 Apply SELinux 'context' after initialization.
130 .TP
131 .B -F pidfile
132 Create 'pidfile' and write process id in it.
133 .SS Client Options:
134 .TP
135 .B -4
136 Force IPv4 DNS queries
137 .TP
138 .B -6
139 Force IPv6 DNS queries
140 .TP
141 .B -r
142 Skip raw UDP mode. If not used, iodine will try getting the public IP address
143 of the iodined host and test if it is reachable directly. If it is, traffic
144 will be sent to the server instead of the DNS relay.
145 .TP
146 .B -R rdomain
147 Use OpenBSD routing domain 'rdomain' for the DNS connection.
148 .TP
149 .B -m fragsize
150 Force maximum downstream fragment size. Not setting this will cause the
151 client to automatically probe the maximum accepted downstream fragment size.
152 .TP
153 .B -M namelen
154 Maximum length of upstream hostnames, default 255.
155 Usable range ca. 100 to 255.
156 Use this option to scale back upstream bandwidth in favor of downstream
157 bandwidth.
158 Also useful for DNS servers that perform unreliably when using full-length
159 hostnames, noticeable when fragment size autoprobe returns very
160 different results each time.
161 .TP
162 .B -T dnstype
163 DNS request type override.
164 By default, autodetection will probe for working DNS request types, and
165 will select the request type that is expected to provide the most bandwidth.
166 However, it may turn out that a DNS relay imposes limits that skew the
167 picture, which may lead to an "unexpected" DNS request type providing
168 more bandwidth.
169 In that case, use this option to override the autodetection.
170 In (expected) decreasing bandwidth order, the supported DNS request types are:
171 .IR NULL ,
172 .IR PRIVATE ,
173 .IR TXT ,
174 .IR SRV ,
175 .IR MX ,
176 .I CNAME
177 and
178 .I A
179 (returning CNAME).
180 Note that
181 .IR SRV ,
182 .I MX
183 and
184 .I A
185 may/will cause additional lookups by "smart" caching
186 nameservers to get an actual IP address, which may either slow down or fail
187 completely. The
188 .IR PRIVATE
189 type uses value 65399 (in the 'private use' range) and requires servers
190 implementing RFC 3597.
191 .TP
192 .B -O downenc
193 Force downstream encoding type for all query type responses except NULL.
194 Default is autodetected, but may not spot all problems for the more advanced
195 codecs.
196 Use this option to override the autodetection.
197 .I Base32
198 is the lowest-grade codec and should always work; this is used when
199 autodetection fails.
200 .I Base64
201 provides more bandwidth, but may not work on all nameservers.
202 .I Base64u
203 is equal to Base64 except in using underscore ('_')
204 instead of plus sign ('+'), possibly working where
205 .I Base64
206 does not.
207 .I Base128
208 uses high byte values (mostly accented letters in iso8859-1),
209 which might work with some nameservers.
210 For TXT queries,
211 .I Raw
212 will provide maximum performance, but this will only work if the nameserver
213 path is fully 8-bit-clean for responses that are assumed to be "legible text".
214 .TP
215 .B -L 0|1
216 Lazy-mode switch.
217 \-L1 (default): Use lazy mode for improved performance and decreased latency.
218 A very small minority of DNS relays appears to be unable to handle the
219 lazy mode traffic pattern, resulting in no or very little data coming through.
220 The iodine client will detect this and try to switch back to legacy mode,
221 but this may not always work.
222 In these situations use \-L0 to force running in legacy mode
223 (implies \-I1).
224 .TP
225 .B -I interval
226 Maximum interval between requests (pings) so that intermediate DNS
227 servers will not time out. Default is 4 in lazy mode, which will work
228 fine in most cases. When too many SERVFAIL errors occur, iodine
229 will automatically reduce this to 1.
230 To get absolute minimum DNS traffic,
231 increase well above 4, but not so high that SERVFAIL errors start to occur.
232 There are some DNS relays with very small timeouts,
233 notably dnsadvantage.com (ultradns), that will give
234 SERVFAIL errors even with \-I1; data will still get trough,
235 and these errors can be ignored.
236 Maximum useful value is 59, since iodined will close a client's
237 connection after 60 seconds of inactivity.
238 .SS Server Options:
239 .TP
240 .B -c
241 Disable checking the client IP address on all incoming requests.
242 By default, requests originating from non-matching IP addresses will be
243 rejected, however this will cause problems when requests are routed
244 via a cluster of DNS servers.
245 .TP
246 .B -s
247 Don't try to configure IP address or MTU. 
248 This should only be used if you have already configured the device that will be
249 used.
250 .TP
251 .B -D
252 Increase debug level. Level 1 prints info about each RX/TX packet.
253 Implies the
254 .B -f
255 option.
256 On level 2 (\-DD) or higher, DNS queries will be printed literally.
257 When using Base128 upstream encoding, this is best viewed as
258 ISO Latin-1 text instead of (illegal) UTF-8.
259 This is easily done with : "LC_ALL=C luit iodined \-DD ..."
260 (see luit(1)).
261 .TP
262 .B -m mtu
263 Set 'mtu' as mtu size for the tun device. 
264 This will be sent to the client on login, and the client will use the same mtu
265 for its tun device.  Default 1130.  Note that the DNS traffic will be
266 automatically fragmented when needed.
267 .TP
268 .B -l listen_ip
269 Make the server listen only on 'listen_ip' for incoming requests.
270 By default, incoming requests are accepted from all interfaces.
271 .TP
272 .B -p port
273 Make the server listen on 'port' instead of 53 for traffic. 
274 If 'listen_ip' does not include localhost, this 'port' can be the same
275 as 'dnsport'.
276 .B Note:
277 You must make sure the dns requests are forwarded to this port yourself.
278 .TP
279 .B -n auto|external_ip
280 The IP address to return in NS responses. Default is to return the address used
281 as destination in the query.
282 If external_ip is 'auto', iodined will use externalip.net web service to
283 retrieve the external IP of the host and use that for NS responses.
284 .TP
285 .B -b dnsport
286 If this port is specified, all incoming requests not inside the tunnel domain
287 will be forwarded to this port on localhost, to be handled by a real dns.
288 If 'listen_ip' does not include localhost, this 'dnsport' can be the
289 same as 'port'.
290 .B Note:
291 The forwarding is not fully transparent, and not advised for use
292 in production environments.
293 .TP
294 .B -i max_idle_time
295 Make the server stop itself after max_idle_time seconds if no traffic have been received.
296 This should be combined with systemd or upstart on demand activation for being effective.
297 .SS Client Arguments:
298 .TP
299 .B nameserver
300 The nameserver to use to relay the dns traffic. This can be any relaying
301 nameserver or the server running iodined if reachable. This field can be
302 given as an IPv4/IPv6 address or as a hostname. This argument is optional,
303 and if not specified a nameserver will be read from the
304 .I /etc/resolv.conf
305 file.
306 .TP
307 .B topdomain
308 The dns traffic will be sent as queries for subdomains under
309 \'topdomain'. This is normally a subdomain to a domain you own. Use a short
310 domain name to get better throughput. If 
311 .B nameserver
312 is the iodined server, then the topdomain can be chosen freely. This argument
313 must be the same on both the client and the server.
314 .SS Server Arguments:
315 .TP
316 .B tunnel_ip[/netmask]
317 This is the server's ip address on the tun interface. The client will be
318 given the next ip number in the range. It is recommended to use the 
319 10.0.0.0 or 172.16.0.0 ranges. The default netmask is /27, can be overridden
320 by specifying it here. Using a smaller network will limit the number of
321 concurrent users.
322 .TP
323 .B topdomain
324 The dns traffic is expected to arrive as queries for
325 subdomains under 'topdomain'. This is normally a subdomain to a domain you 
326 own. Use a short domain name to get better throughput. This argument must be 
327 the same on both the client and the server. Queries for domains other
328 than 'topdomain' will be forwarded when the \-b option is given, otherwise
329 they will be dropped.
330 .SH EXAMPLES
331 See the README file for both a quick test scenario, and a detailed description
332 of real-world deployment.
333 .SH SECURITY
334 Login is a relatively secure challenge-response MD5 hash, with the
335 password never passing the wire.
336 However, all other data is
337 .B NOT
338 encrypted in any way. The DNS traffic is also vulnerable to replay,
339 injection and man-in-the-middle attacks, especially when iodined is used
340 with the \-c option. Use of ssh or vpn tunneling is strongly recommended.
341 On both server and client, use
342 .IR iptables ,
343 .I pf
344 or other firewalls to block all traffic coming in from the tun interfaces,
345 except to the used ssh or vpn ports.
346 .SH ENVIRONMENT
347 .SS IODINE_PASS
348 If the environment variable
349 .B IODINE_PASS
350 is set, iodine will use the value it is set to as password instead of asking
351 for one. The 
352 .B -P
353 option still has precedence.
354 .SS IODINED_PASS
355 If the environment variable
356 .B IODINED_PASS
357 is set, iodined will use the value it is set to as password instead of asking
358 for one. The
359 .B -P
360 option still has precedence.
361 .SH SEE ALSO
362 The README file in the source distribution contains some more elaborate
363 information.
364 .SH BUGS
365 File bugs at http://dev.kryo.se/iodine/
366 .SH AUTHORS
367 Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
368 contributions by Anne Bezemer.