/[debian]/iodine/trunk/README
ViewVC logotype

Contents of /iodine/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.26