[svn-inject] Installing original source of iodine
[debian/iodine.git] / README
1
2 iodine - IP over DNS is now easy
3
4    http://code.kryo.se/iodine
5
6 ********************************
7
8 This is a piece of software that lets you tunnel IPv4 data through a DNS
9 server. This can be usable in different situations where internet access is
10 firewalled, but DNS queries are allowed.
11
12
13 QUICKSTART:
14
15 Try it out within your own LAN! Follow these simple steps:
16 - On your server, run: ./iodined -f 10.0.0.1 test.asdf
17   (If you already use the 10.0.0.0 network, use another internal net like 
18   172.16.0.0)
19 - On the client, run: ./iodine -f 192.168.0.1 test.asdf
20   (Replace 192.168.0.1 with the server's ip address)
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! :)
24 To actually use it through a relaying nameserver, see below.
25
26
27 HOW TO USE:
28
29 Server side:
30 To use this tunnel, you need control over a real domain (like mytunnel.com),
31 and a server with a static public IP number that does not yet run a DNS
32 server. Then, delegate a subdomain (say, tunnel1.mytunnel.com) to the server.
33 If you use BIND for the domain, add these lines to the zone file:
34
35 tunnel1host     IN      A       10.15.213.99
36 tunnel1         IN      NS      tunnel1host.mytunnel.com.
37
38 Now any DNS querys for domains ending with tunnel1.mytunnnel.com will be sent
39 to your server. Start iodined on the server. The first argument is the tunnel
40 IP address (like 192.168.99.1) and the second is the assigned domain (in this
41 case tunnel1.mytunnel.com). The -f argument will keep iodined running in the
42 foreground, which helps when testing. iodined will start a virtual interface,
43 and also start listening for DNS queries on UDP port 53. Now everything is
44 ready for the client.
45
46 Client side: 
47 All the setup is done, just start iodine. It also takes two
48 arguments, the first is the local relaying DNS server and the second is the
49 domain used (tunnel1.mytunnnel.com). If DNS queries are allowed to any
50 computer, you can use the tunnel endpoint (example: 10.15.213.99 or
51 tunnel1host.mytunnel.com) as the first argument. The tunnel interface will get
52 an IP close to the servers (in this case 192.168.99.2) and a suitable MTU. Now
53 you should be able to ping the other end of the tunnel from either side.  
54
55
56 MISC. INFO:
57
58 Note that you can have only one client per server at the same time. This is
59 because of the fragmentation of big packets going upstream, and will be fixed
60 in future versions. 
61
62 Try experimenting with the MTU size (-m option) to get maximum bandwidth. It is
63 set to 1024 by default, which seems to work with most DNS servers. If you have
64 problems, try setting it to below 512.
65
66 If you have problems, try inspecting the traffic with network monitoring tools
67 and make sure that the relaying DNS server has not cached the response. A
68 cached error message could mean that you started the client before the server.
69
70 The upstream data is sent gzipped encoded with Base32. DNS protocol allows
71 one query per packet, and one query can be max 256 chars. Each domain name part
72 can be max 63 chars. So your domain name and subdomain should be as short as
73 possible to allow maximum throughput.
74
75
76 TIPS & TRICKS:
77
78 If your port 53 is taken on a specific interface by an application that does 
79 not use it, use -p on iodined to specify an alternate port (like -p 5353) and 
80 use for instance iptables (on Linux) to forward the traffic:
81 iptables -t nat -A PREROUTING -i eth0 -p udp --dport 53 -j DNAT --to :5353
82 (Sent in by Tom Schouten)
83
84
85 PORTABILITY:
86
87 iodine has been tested on Linux (x86, AMD64 and SPARC64), FreeBSD (x86), 
88 OpenBSD (x86), NetBSD (x86) and MacOS X (10.3, ppc, with 
89 http://www-user.rhrk.uni-kl.de/~nissler/tuntap/). It should work on other 
90 unix-like systems as well that has TUN/TAP tunneling support (after some 
91 patching). Let us know if you get it to run on other platforms. 
92
93
94 THE NAME:
95
96 The name iodine was chosen since it starts with IOD (IP Over DNS) and since
97 iodine has atomic number 53, which happens to be the DNS port number.
98
99
100 THANKS:
101
102 - To kuxien for FreeBSD and OS X testing
103 - To poplix for code audit
104
105
106 AUTHORS & LICENSE:
107
108 Copyright (c) 2006 Bjorn Andersson <flex@kryo.se>, Erik Ekman <yarrick@kryo.se>
109
110 Permission to use, copy, modify, and distribute this software for any purpose
111 with or without fee is hereby granted, provided that the above copyright notice
112 and this permission notice appear in all copies.
113
114 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
115 REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
116 FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
117 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
118 LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
119 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
120 PERFORMANCE OF THIS SOFTWARE.