source: README @ 27e16d

Revision 27e16d, 17.1 KB checked in by Erik Ekman <yarrick@…>, 8 years ago (diff)

Add credits

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