New upstream release.
[debian/iodine.git] / README
1
2 iodine - http://code.kryo.se/iodine
3
4 ***********************************
5
6 This is a piece of software that lets you tunnel IPv4 data through a DNS
7 server. This can be usable in different situations where internet access is
8 firewalled, but DNS queries are allowed.
9
10
11 COMPILING:
12
13 Iodine has no configure script. There are two optional features for Linux
14 (SELinux and systemd support) that will be enabled automatically if the
15 relevant header files are found in /usr/include. (See script at ./src/osflags)
16
17 Run 'make' to compile the server and client binaries.
18 Run 'make install' to copy binaries and manpage to the destination directory.
19 Run 'make test' to compile and run the unit tests. (Requires the check library)
20
21
22 QUICKSTART:
23
24 Try it out within your own LAN! Follow these simple steps:
25 - On your server, run: ./iodined -f 10.0.0.1 test.com
26   (If you already use the 10.0.0.0 network, use another internal net like 
27   172.16.0.0)
28 - Enter a password
29 - On the client, run: ./iodine -f -r 192.168.0.1 test.com
30   (Replace 192.168.0.1 with your server's ip address)
31 - Enter the same password
32 - Now the client has the tunnel ip 10.0.0.2 and the server has 10.0.0.1
33 - Try pinging each other through the tunnel
34 - Done! :)
35 To actually use it through a relaying nameserver, see below.
36
37
38 HOW TO USE:
39
40 Note: server and client are required to speak the exact same protocol. In most
41 cases, this means running the same iodine version. Unfortunately, implementing
42 backward and forward protocol compatibility is usually not feasible.
43
44 Server side:
45 To use this tunnel, you need control over a real domain (like mydomain.com),
46 and a server with a public IP address to run iodined on. If this server
47 already runs a DNS program, change its listening port and then use iodined's
48 -b option to let iodined forward the DNS requests. (Note that this procedure
49 is not advised in production environments, because iodined's DNS forwarding
50 is not completely transparent.)
51
52 Then, delegate a subdomain (say, t1.mydomain.com) to the iodined server.
53 If you use BIND for your domain, add two lines like these to the zone file:
54
55 t1              IN      NS      t1ns.mydomain.com.              ; note the dot!
56 t1ns            IN      A       10.15.213.99
57
58 The "NS" line is all that's needed to route queries for the "t1" subdomain
59 to the "t1ns" server. We use a short name for the subdomain, to keep as much
60 space as possible available for the data traffic. At the end of the "NS" line
61 is the name of your iodined server. This can be any name, pointing anywhere,
62 but in this case it's easily kept in the same zone file. It must be a name
63 (not an IP address), and that name itself must have an A record (not a CNAME).
64
65 If your iodined server has a dynamic IP, use a dynamic dns provider. Simply
66 point the "NS" line to it, and leave the "A" line out:
67
68 t1              IN      NS      myname.mydyndnsprovider.com.    ; note the dot!
69
70 Then reload or restart your nameserver program. Now any DNS queries for
71 domains ending in t1.mydomain.com will be sent to your iodined server.
72
73 Finally start iodined on your server. The first argument is the IP address
74 inside the tunnel, which can be from any range that you don't use yet (for
75 example 192.168.99.1), and the second argument is the assigned domain (in this
76 case t1.mydomain.com). Using the -f option will keep iodined running in the
77 foreground, which helps when testing. iodined will open a virtual interface
78 ("tun device"), and will also start listening for DNS queries on UDP port 53.
79 Either enter a password on the commandline (-P pass) or after the server has
80 started. Now everything is ready for the client.
81
82 If there is a chance you'll be using an iodine tunnel from unexpected
83 environments, start iodined with a -c option.
84
85 Resulting commandline in this example situation:
86 ./iodined -f -c -P secretpassword 192.168.99.1 t1.mydomain.com
87
88 Client side: 
89 All the setup is done, just start iodine. It takes one or two arguments, the
90 first is the local relaying DNS server (optional) and the second is the domain
91 you used (t1.mydomain.com). If you don't specify the first argument, the
92 system's current DNS setting will be consulted.
93
94 If DNS queries are allowed to any computer, you can directly give the iodined
95 server's address as first argument (in the example: t1ns.mydomain.com or
96 10.15.213.99). In that case, it may also happen that _any_ traffic is allowed
97 to the DNS port (53 UDP) of any computer. Iodine will detect this, and switch
98 to raw UDP tunneling if possible. To force DNS tunneling in any case, use the
99 -r option (especially useful when testing within your own network).
100
101 The client's tunnel interface will get an IP close to the server's (in this
102 case 192.168.99.2 or .3 etc.) and a suitable MTU. Enter the same password as
103 on the server either as commandline option or after the client has started.
104 Using the -f option will keep the iodine client running in the foreground.
105
106 Resulting commandline in this example situation:
107 ./iodine -f -P secretpassword t1.mydomain.com
108 (add -r to force DNS tunneling even if raw UDP tunneling would be possible)
109
110 From either side, you should now be able to ping the IP address on the other
111 end of the tunnel. In this case, ping 192.168.99.1 from the iodine client, and
112 192.168.99.2 or .3 etc. from the iodine server.
113
114
115 MISC. INFO:
116
117 IPv6:
118 At the moment the iodined server only supports IPv4. The data inside the tunnel
119 is IPv4 only.
120
121 The client can use IPv4 or IPv6 nameservers to connect to iodined. The relay
122 nameservers will translate between protocols automatically if needed. Use
123 options -4 or -6 to force the client to use a specific IP version for its DNS
124 queries. The client has to force IPv4 if it has dual-stack connectivity and
125 the hostname handling the tunnel domain has both A and AAAA records.
126
127 Routing:
128 It is possible to route all traffic through the DNS tunnel. To do this, first
129 add a host route to the nameserver used by iodine over the wired/wireless
130 interface with the default gateway as gateway. Then replace the default
131 gateway with the iodined server's IP address inside the DNS tunnel, and
132 configure the server to do NAT.
133
134 However, note that the tunneled data traffic is not encrypted at all, and can
135 be read and changed by external parties relatively easily. For maximum
136 security, run a VPN through the DNS tunnel (=double tunneling), or use secure
137 shell (SSH) access, possibly with port forwarding. The latter can also be used
138 for web browsing, when you run a web proxy (for example Privoxy) on your
139 server.
140
141 Testing:
142 The iodined server replies to NS requests sent for subdomains of the tunnel
143 domain. If your iodined subdomain is t1.mydomain.com, send a NS request for
144 foo123.t1.mydomain.com to see if the delegation works. dig is a good tool
145 for this:
146 dig -t NS foo123.t1.mydomain.com
147
148 Also, the iodined server will answer requests starting with 'z' for any of the
149 supported request types, for example:
150 dig -t TXT z456.t1.mydomain.com
151 dig -t SRV z456.t1.mydomain.com
152 dig -t CNAME z456.t1.mydomain.com
153 The reply should look like garbled text in all these cases.
154
155 Operational info:
156 The DNS-response fragment size is normally autoprobed to get maximum bandwidth.
157 To force a specific value (and speed things up), use the -m option.
158
159 The DNS hostnames are normally used up to their maximum length, 255 characters.
160 Some DNS relays have been found that answer full-length queries rather
161 unreliably, giving widely varying (and mostly very bad) results of the
162 fragment size autoprobe on repeated tries. In these cases, use the -M switch
163 to reduce the DNS hostname length to for example 200 characters, which makes
164 these DNS relays much more stable. This is also useful on some "de-optimizing"
165 DNS relays that stuff the response with two full copies of the query, leaving
166 very little space for downstream data (also not capable of EDNS0). The -M
167 switch can trade some upstream bandwidth for downstream bandwidth. Note that
168 the minimum -M value is about 100, since the protocol can split packets (1200
169 bytes max) in only 16 fragments, requiring at least 75 real data bytes per
170 fragment.
171
172 The upstream data is sent gzipped encoded with Base32; or Base64 if the relay
173 server supports mixed case and '+' in domain names; or Base64u if '_' is
174 supported instead; or Base128 if high-byte-value characters are supported.
175 This upstream encoding is autodetected. The DNS protocol allows one query per
176 packet, and one query can be max 256 chars. Each domain name part can be max
177 63 chars. So your domain name and subdomain should be as short as possible to
178 allow maximum upstream throughput.
179
180 Several DNS request types are supported, with the NULL and PRIVATE types
181 expected to provide the largest downstream bandwidth. The PRIVATE type uses
182 value 65399 in the private-use range. Other available types are TXT, SRV, MX,
183 CNAME and A (returning CNAME), in decreasing bandwidth order.  Normally the
184 "best" request type is autodetected and used. However, DNS relays may impose
185 limits on for example NULL and TXT, making SRV or MX actually the best choice.
186 This is not autodetected, but can be forced using the -T option.  It is
187 advisable to try various alternatives especially when the autodetected request
188 type provides a downstream fragment size of less than 200 bytes.
189
190 Note that SRV, MX and A (returning CNAME) queries may/will cause additional
191 lookups by "smart" caching nameservers to get an actual IP address, which may
192 either slow down or fail completely.
193
194 DNS responses for non-NULL/PRIVATE queries can be encoded with the same set of
195 codecs as upstream data. This is normally also autodetected, but no fully
196 exhaustive tests are done, so some problems may not be noticed when selecting
197 more advanced codecs. In that case, you'll see failures/corruption in the
198 fragment size autoprobe. In particular, several DNS relays have been found that
199 change replies returning hostnames (SRV, MX, CNAME, A) to lowercase only when
200 that hostname exceeds ca. 180 characters. In these and similar cases, use the
201 -O option to try other downstream codecs; Base32 should always work.
202
203 Normal operation now is for the server to _not_ answer a DNS request until
204 the next DNS request has come in, a.k.a. being "lazy". This way, the server
205 will always have a DNS request handy when new downstream data has to be sent.
206 This greatly improves (interactive) performance and latency, and allows to
207 slow down the quiescent ping requests to 4 second intervals by default, and
208 possibly much slower. In fact, the main purpose of the pings now is to force
209 a reply to the previous ping, and prevent DNS server timeouts (usually at
210 least 5-10 seconds per RFC1035). Some DNS servers are more impatient and will
211 give SERVFAIL errors (timeouts) in periods without tunneled data traffic. All
212 data should still get through in these cases, but iodine will reduce the ping
213 interval to 1 second anyway (-I1) to reduce the number of error messages. This
214 may not help for very impatient DNS relays like dnsadvantage.com (ultradns),
215 which time out in 1 second or even less. Yet data will still get trough, and
216 you can ignore the SERVFAIL errors.
217
218 If you are running on a local network without any DNS server in-between, try
219 -I 50 (iodine and iodined close the connection after 60 seconds of silence).
220 The only time you'll notice a slowdown, is when DNS reply packets go missing;
221 the iodined server then has to wait for a new ping to re-send the data. You can
222 speed this up by generating some upstream traffic (keypress, ping). If this
223 happens often, check your network for bottlenecks and/or run with -I1.
224
225 The delayed answering in lazy mode will cause some "carrier grade" commercial
226 DNS relays to repeatedly re-send the same DNS query to the iodined server.
227 If the DNS relay is actually implemented as a pool of parallel servers,
228 duplicate requests may even arrive from multiple sources. This effect will
229 only be visible in the network traffic at the iodined server, and will not
230 affect the client's connection. Iodined will notice these duplicates, and send
231 the same answer (when its time has come) to both the original query and the
232 latest duplicate. After that, the full answer is cached for a short while.
233 Delayed duplicates that arrive at the server even later, get a reply that the
234 iodine client will ignore (if it ever arrives there).
235
236 If you have problems, try inspecting the traffic with network monitoring tools
237 like tcpdump or ethereal/wireshark, and make sure that the relaying DNS server
238 has not cached the response. A cached error message could mean that you
239 started the client before the server. The -D (and -DD) option on the server
240 can also show received and sent queries.
241
242
243 TIPS & TRICKS:
244
245 If your port 53 is taken on a specific interface by an application that does 
246 not use it, use -p on iodined to specify an alternate port (like -p 5353) and 
247 use for instance iptables (on Linux) to forward the traffic:
248 iptables -t nat -A PREROUTING -i eth0 -p udp --dport 53 -j DNAT --to :5353
249 (Sent in by Tom Schouten)
250
251 Iodined will reject data from clients that have not been active (data/pings)
252 for more than 60 seconds. Similarly, iodine will exit when no downstream
253 data has been received for 60 seconds. In case of a long network outage or
254 similar, just restart iodine (re-login), possibly multiple times until you get
255 your old IP address back. Once that's done, just wait a while, and you'll
256 eventually see the tunneled TCP traffic continue to flow from where it left
257 off before the outage.
258
259 With the introduction of the downstream packet queue in the server, its memory
260 usage has increased with several megabytes in the default configuration.
261 For use in low-memory environments (e.g. running on your DSL router), you can
262 decrease USERS and undefine OUTPACKETQ_LEN in user.h without any ill conse-
263 quence, assuming at most one client will be connected at any time. A small
264 DNSCACHE_LEN is still advised, preferably 2 or higher, however you can also
265 undefine it to save a few more kilobytes.
266
267
268 PERFORMANCE:
269
270 This section tabulates some performance measurements. To view properly, use
271 a fixed-width font like Courier.
272
273 Measurements were done in protocol 00000502 in lazy mode; upstream encoding
274 always Base128; iodine -M255; iodined -m1130. Network conditions were not
275 extremely favorable; results are not benchmarks but a realistic indication of
276 real-world performance that can be expected in similar situations.
277
278 Upstream/downstream throughput was measured by scp'ing a file previously
279 read from /dev/urandom (i.e. incompressible), and measuring size with
280 "ls -l ; sleep 30 ; ls -l" on a separate non-tunneled connection. Given the
281 large scp block size of 16 kB, this gives a resolution of 4.3 kbit/s, which
282 explains why some values are exactly equal.
283 Ping round-trip times measured with "ping -c100", presented are average rtt
284 and mean deviation (indicating spread around the average), in milliseconds.
285
286
287 Situation 1:
288 Laptop  ->   Wifi AP   ->  Home server  ->  DSL provider  ->  Datacenter
289  iodine    DNS "relay"        bind9           DNS cache        iodined
290
291                         downstr.  upstream downstr.  ping-up       ping-down
292                         fragsize   kbit/s   kbit/s  avg +/-mdev   avg +/-mdev
293 ------------------------------------------------------------------------------
294
295 iodine -> Wifi AP :53
296   -Tnull (= -Oraw)           982    43.6    131.0   28.0    4.6   26.8    3.4
297
298 iodine -> Home server :53
299   -Tnull (= -Oraw)          1174    48.0    305.8   26.6    5.0   26.9    8.4
300
301 iodine -> DSL provider :53  
302   -Tnull (= -Oraw)          1174    56.7    367.0   20.6    3.1   21.2    4.4
303   -Ttxt -Obase32             730    56.7    174.7*
304   -Ttxt -Obase64             874    56.7    174.7
305   -Ttxt -Obase128           1018    56.7    174.7
306   -Ttxt -Oraw               1162    56.7    358.2
307   -Tsrv -Obase128            910    56.7    174.7
308   -Tcname -Obase32           151    56.7     43.6
309   -Tcname -Obase128          212    56.7     52.4
310
311 iodine -> DSL provider :53  
312   wired (no Wifi) -Tnull    1174    74.2    585.4   20.2    5.6   19.6    3.4
313
314  [174.7* : these all have 2frag/packet]
315
316
317 Situation 2:
318 Laptop  ->  Wifi+vpn / wired  ->  Home server
319  iodine                            iodined
320
321                         downstr.  upstream downstr.  ping-up       ping-down
322                         fragsize   kbit/s   kbit/s  avg +/-mdev   avg +/-mdev
323 ------------------------------------------------------------------------------
324
325 wifi + openvpn  -Tnull      1186   166.0   1022.3    6.3    1.3    6.6    1.6
326
327 wired  -Tnull               1186   677.2   2464.1    1.3    0.2    1.3    0.1
328
329
330 Performance is strongly coupled to low ping times, as iodine requires
331 confirmation for every data fragment before moving on to the next. Allowing
332 multiple fragments in-flight like TCP could possibly increase performance,
333 but it would likely cause serious overload for the intermediary DNS servers.
334 The current protocol scales performance with DNS responsivity, since the
335 DNS servers are on average handling at most one DNS request per client.
336
337
338 PORTABILITY:
339
340 iodine has been tested on Linux (arm, ia64, x86, AMD64 and SPARC64), FreeBSD
341 (ia64, x86), OpenBSD (x86), NetBSD (x86), MacOS X (ppc and x86, with
342 http://tuntaposx.sourceforge.net/). and Windows (with OpenVPN TAP32 driver, see
343 win32 readme file).  It should be easy to port to other unix-like systems that
344 has TUN/TAP tunneling support. Let us know if you get it to run on other
345 platforms. 
346
347
348 THE NAME:
349
350 The name iodine was chosen since it starts with IOD (IP Over DNS) and since
351 iodine has atomic number 53, which happens to be the DNS port number.
352
353
354 THANKS:
355
356 - To kuxien for FreeBSD and OS X testing
357 - To poplix for code audit
358
359
360 AUTHORS & LICENSE:
361
362 Copyright (c) 2006-2014 Erik Ekman <yarrick@kryo.se>, 2006-2009 Bjorn
363 Andersson <flex@kryo.se>. Also major contributions by Anne Bezemer.
364
365 Permission to use, copy, modify, and distribute this software for any purpose
366 with or without fee is hereby granted, provided that the above copyright notice
367 and this permission notice appear in all copies.
368
369 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
370 REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
371 FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
372 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
373 LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
374 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
375 PERFORMANCE OF THIS SOFTWARE.
376
377
378 MD5 implementation by L. Peter Deutsch (license and source in src/md5.[ch])
379 Copyright (C) 1999, 2000, 2002 Aladdin Enterprises.  All rights reserved.