[svn-upgrade] Integrating new upstream version, iodine (0.4.1)
[debian/iodine.git] / man / iodine.8
1 .\" groff -man -Tascii iodine.8
2 .TH IODINE 8 "JUN 2007" "User Manuals"
3 .SH NAME
4 iodine, iodined \- tunnel IPv4 over DNS
5 .SH SYNOPSIS
6 .B iodine [-v]
7
8 .B iodine [-h]
9
10 .B iodine [-f] [-u
11 .I user
12 .B ] [-P
13 .I password
14 .B ] [-t
15 .I chrootdir
16 .B ] [-d
17 .I device
18 .B ]
19 .B [
20 .I nameserver
21 .B ]
22 .I topdomain
23
24 .B iodined [-v]
25
26 .B iodined [-h]
27
28 .B iodined [-f] [-u
29 .I user
30 .B ] [-P
31 .I password
32 .B ] [-t
33 .I chrootdir
34 .B ] [-m
35 .I mtu
36 .B ] [-l
37 .I listen_ip
38 .B ] [-d
39 .I device
40 .B ]
41 .I tunnel_ip
42 .I topdomain
43 .SH DESCRIPTION
44 .B iodine
45 lets you tunnel IPv4 data through a DNS 
46 server. This can be useful in situations where Internet access is firewalled,
47 but DNS queries are allowed. It needs a TUN/TAP device to operate. The 
48 bandwidth is asymmetrical with limited upstream and up to 1 Mbit/s downstream.
49 .B iodine
50 is the client application,
51 .B iodined
52 is the server.
53 .SH OPTIONS
54 .SS Common Options:
55 .TP
56 .B -v
57 Print version info and exit.
58 .TP
59 .B -h
60 Print usage info and exit.
61 .TP
62 .B -f
63 Keep running in foreground.
64 .TP
65 .B -u user
66 Drop privileges and run as user 'user' after setting up tunnel.
67 .TP
68 .B -t chrootdir
69 Chroot to 'chrootdir' after setting up tunnel.
70 .TP
71 .B -P password
72 Use 'password' to authenticate. If not used, 
73 .B stdin
74 will be used as input. Only the first 32 characters will be used.
75 .TP
76 .B -d device
77 Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
78 and otherwise tunX.
79 .SS Server Options:
80 .TP
81 .B -m mtu
82 Set 'mtu' as mtu size for the tunnel device. This will be sent to the client
83 on connect, and the client will use the same mtu.
84 .TP
85 .B -l listen_ip
86 Make the server listen only on 'listen_ip' instead of on 0.0.0.0 for incoming
87 connections.
88 .TP
89 .B -p port
90 Make the server listen on 'port' instead of 53 for traffic. 
91 .B Note:
92 You must make sure the dns requests are forwarded to this port yourself.
93 .SS Client Arguments:
94 .TP
95 .B nameserver
96 The nameserver to use to relay the dns traffic. This can be any relaying
97 nameserver  or the ip number of the server running iodined if reachable.
98 This argument is optional, and if not specified a nameserver will be read
99 from the
100 .I /etc/resolv.conf
101 file.
102 .TP
103 .B topdomain
104 The dns traffic will be sent as querys of type NULL for subdomains under
105 \'topdomain'. This is normally a subdomain to a domain you own. Use a short
106 domain name to get better throughput. If 
107 .B nameserver
108 is the iodined server, then the topdomain can be chosen freely. This argument
109 must be the same on both the client and the server.
110 .SS Server Arguments:
111 .TP
112 .B tunnel_ip
113 This is the servers ip address on the tunnel interface. The client will be
114 given the next ip number in the range. It is recommended to use the 
115 10.0.0.0/8 or 172.16.0.0/12 ranges.
116 .TP
117 .B topdomain
118 The dns traffic will is expected to be sent as querys of type NULL for 
119 subdomains under 'topdomain'. This is normally a subdomain to a domain you 
120 own. Use a short domain name to get better throughput. This argument must be 
121 the same on both the client and the server.
122 .SH EXAMPLES
123 .SS Quickstart:
124 .TP
125 Try it out within your own LAN! Follow these simple steps:
126 .TP
127 - On your server, run: ./iodined -f 10.0.0.1 test.asdf
128 (If you already use the 10.0.0.0 network, use another internal net like 
129 172.16.0.0)
130 .TP
131 - Enter a password
132 .TP
133 - On the client, run: ./iodine -f 192.168.0.1 test.asdf
134 (Replace 192.168.0.1 with the server's ip address)
135 .TP
136 - Enter the same password
137 .TP
138 - Now the client has the tunnel ip 10.0.0.2 and the server has 10.0.0.1
139 .TP
140 - Try pinging each other through the tunnel
141 .TP
142 - Done! :)
143 .TP
144 To actually use it through a relaying nameserver, see below.
145 .SS Full setup:
146
147 .TP
148 .B Server side:
149 To use this tunnel, you need control over a real domain (like mytunnel.com),
150 and a server with a static public IP number that does not yet run a DNS
151 server. Then, delegate a subdomain (say, tunnel1.mytunnel.com) to the server.
152 If you use BIND for the domain, add these lines to the zone file (replace
153 10.15.213.99 with your server ip):
154
155 .nf
156 tunnel1host     IN      A       10.15.213.99
157 tunnel1         IN      NS      tunnel1host.mytunnel.com.
158 .fi
159
160 Now any DNS querys for domains ending with tunnel1.mytunnnel.com will be sent
161 to your server. Start iodined on the server. The first argument is the tunnel
162 IP address (like 192.168.99.1) and the second is the assigned domain (in this
163 case tunnel1.mytunnel.com). The -f argument will keep iodined running in the
164 foreground, which helps when testing. iodined will start a virtual interface,
165 and also start listening for DNS queries on UDP port 53. Either enter a
166 password on the commandline (-P pass) or after the server has started. Now 
167 everything is ready for the client.
168 .TP
169 .B Client side: 
170 All the setup is done, just start iodine. It also takes two
171 arguments, the first is the local relaying DNS server and the second is the
172 domain used (tunnel1.mytunnnel.com). If DNS queries are allowed to any
173 computer, you can use the tunnel endpoint (example: 10.15.213.99 or
174 tunnel1host.mytunnel.com) as the first argument. The tunnel interface will get
175 an IP close to the servers (in this case 192.168.99.2) and a suitable MTU. 
176 Enter the same password as on the server either by argument or after the client
177 has started. Now you should be able to ping the other end of the tunnel from 
178 either side.  
179 .TP
180 .B Routing:
181 The normal case is to route all traffic through the DNS tunnel. To do this, first
182 add a route to the nameserver you use with the default gateway as gateway. Then
183 replace the default gateway with the servers IP address within the DNS tunnel,
184 and configure the server to do NAT.
185 .TP
186 .B MTU issues:
187 Some relaying DNS servers enforce a 512 byte packet limit. All larger packets are
188 simply dropped. If you can ping through the tunnel but not login via SSH, this is
189 most likely the case. Set the MTU on the server to 220 to ensure that all packets
190 are less than 512 bytes. This will however greatly affect performance.
191 .SH BUGS
192 File bugs at http://dev.kryo.se/iodine/
193 .SH AUTHORS
194 Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>