man/iodine.8

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