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