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