iodine/man/iodine.8

.\" groff -man -Tascii iodine.8
.TH IODINE 8 "SEP 2009" "User Manuals"
.SH NAME
iodine, iodined \- tunnel IPv4 over DNS
.SH SYNOPSIS
.B iodine [-v]

.B iodine [-h]

.B iodine [-f] [-r] [-u
.I user
.B ] [-P
.I password
.B ] [-m
.I fragsize
.B ] [-t
.I chrootdir
.B ] [-d
.I device
.B ] [-m
.I fragsize
.B ] [-z
.I context
.B ] [-F
.I pidfile
.B ] [-T
.I dnstype
.B ] [-O
.I downenc
.B ] [-L
.I 0|1
.B ] [-I
.I interval
.B ]
.B [
.I nameserver
.B ]
.I topdomain

.B iodined [-v]

.B iodined [-h]

.B iodined [-c] [-s] [-f] [-D] [-u
.I user
.B ] [-t
.I chrootdir
.B ] [-d
.I device
.B ] [-m
.I mtu
.B ] [-l
.I listen_ip
.B ] [-p
.I port
.B ] [-n
.I external_ip
.B ] [-b
.I dnsport
.B ] [-P
.I password
.B ] [-z
.I context
.B ] [-F
.I pidfile
.B ]
.I tunnel_ip
.B [
.I /netmask
.B ]
.I topdomain
.SH DESCRIPTION
.B iodine
lets you tunnel IPv4 data through a DNS 
server. This can be useful in situations where Internet access is firewalled,
but DNS queries are allowed. It needs a TUN/TAP device to operate. The 
bandwidth is asymmetrical,
with a measured maximum of 680 kbit/s upstream and 2.3 Mbit/s
downstream in a wired LAN test network.
Realistic sustained throughput on a Wifi network using a carrier-grade
DNS cache has been measured at some 50 kbit/s upstream and over 200 kbit/s
downstream.
.B iodine
is the client application,
.B iodined
is the server.
.SH OPTIONS
.SS Common Options:
.TP
.B -v
Print version info and exit.
.TP
.B -h
Print usage info and exit.
.TP
.B -f
Keep running in foreground.
.TP
.B -u user
Drop privileges and run as user 'user' after setting up tunnel.
.TP
.B -t chrootdir
Chroot to 'chrootdir' after setting up tunnel.
.TP
.B -d device
Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
and otherwise tunX.
.TP
.B -P password
Use 'password' to authenticate. If not used, 
.B stdin
will be used as input. Only the first 32 characters will be used.
.TP
.B -z context
Apply SELinux 'context' after initialization.
.TP
.B -F pidfile
Create 'pidfile' and write process id in it.
.SS Client Options:
.TP
.B -r
Skip raw UDP mode. If not used, iodine will try getting the public IP address
of the iodined host and test if it is reachable directly. If it is, traffic
will be sent to the server instead of the DNS relay.
.TP
.B -m fragsize
Force maximum downstream fragment size. Not setting this will cause the
client to automatically probe the maximum accepted downstream fragment size.
.TP
.B -T dnstype
DNS request type.
.I NULL
is default. If this doesn't work, try
.I TXT
(some less bandwidth) or
.I CNAME
(much less bandwidth). Also supported are
.I A
(returning CNAME) and
.I MX
requests, but these may/will cause additional lookups by "smart" caching
nameservers to get an actual IP address, which may either slow down or fail
completely.
.TP
.B -O downenc
Downstream encoding for all query type responses except NULL.
.I Base32
is default and should always work.
.I Base64
provides more bandwidth, but may not work on all nameservers.
For TXT queries,
.I Raw
will provide maximum performance. This will only work if the nameserver
path is fully 8-bit-clean for responses that are assumed to be "legible text".
.TP
.B -L 0|1
Lazy-mode switch.
\-L1 (default): Use lazy mode if server supports it, for improved
performance and decreased latency.
Some DNS servers, notably the opendns.com network, appear unstable when
handling lazy mode DNS traffic and will re-order requests. If this occurs,
you will notice fluctuating response speed in interactive sessions.
The iodine client will eventually detect this and switch back to legacy
mode automatically. Use \-L0 to force running in legacy mode
(implies \-I1).
.TP
.B -I interval
Maximum interval between requests (pings) so that intermediate DNS
servers will not time out. Default is 4 in lazy mode, which will work
fine in almost all cases. Decrease if you get SERVFAIL errors in periods
without tunneled data traffic. To get absolute minimum DNS traffic,
increase well above 4 until SERVFAIL errors start to occur.
Maximum useful value is 59, since iodined will close a client's
connection after 60 seconds of inactivity.
.SS Server Options:
.TP
.B -c
Disable checking the client IP address on all incoming requests.
By default, requests originating from non-matching IP adresses will be
rejected, however this will cause problems when requests are routed
via a cluster of DNS servers.
.TP
.B -s
Don't try to configure IP address or MTU. 
This should only be used if you have already configured the device that will be
used.
.TP
.B -D
Increase debug level. Level 1 prints info about each RX/TX packet.
Implies the
.B -f
option.
.TP
.B -m mtu
Set 'mtu' as mtu size for the tun device. 
This will be sent to the client on login, and the client will use the same mtu
for its tun device.  Default 1200.  Note that the DNS traffic will be
automatically fragmented when needed.
.TP
.B -l listen_ip
Make the server listen only on 'listen_ip' for incoming requests.
By default, incoming requests are accepted from all interfaces.
.TP
.B -p port
Make the server listen on 'port' instead of 53 for traffic. 
.B Note:
You must make sure the dns requests are forwarded to this port yourself.
.TP
.B -n external_ip
The IP address to return in NS responses. Default is to return the address used
as destination in the query.
.TP
.B -b dnsport
If this port is specified, all incoming requests not inside the tunnel domain
will be forwarded to this port on localhost, to be handled by a real dns.
.B Note:
The forwarding is not fully transparent, and not advised for use
in production environments.
.SS Client Arguments:
.TP
.B nameserver
The nameserver to use to relay the dns traffic. This can be any relaying
nameserver  or the ip number of the server running iodined if reachable.
This argument is optional, and if not specified a nameserver will be read
from the
.I /etc/resolv.conf
file.
.TP
.B topdomain
The dns traffic will be sent as queries for subdomains under
\'topdomain'. This is normally a subdomain to a domain you own. Use a short
domain name to get better throughput. If 
.B nameserver
is the iodined server, then the topdomain can be chosen freely. This argument
must be the same on both the client and the server.
.SS Server Arguments:
.TP
.B tunnel_ip[/netmask]
+This is the server's ip address on the tun interface. The client will be
given the next ip number in the range. It is recommended to use the 
10.0.0.0 or 172.16.0.0 ranges. The default netmask is /27, can be overriden
by specifying it here. Using a smaller network will limit the number of
concurrent users.
.TP
.B topdomain
+The dns traffic is expected to arrive as queries for
subdomains under 'topdomain'. This is normally a subdomain to a domain you 
own. Use a short domain name to get better throughput. This argument must be 
the same on both the client and the server. Queries for domains other
than 'topdomain' will be forwarded when the \-b option is given, otherwise
they will be dropped.
.SH EXAMPLES
.SS Quickstart:
.TP
Try it out within your own LAN! Follow these simple steps:
.TP
- On your server, run: ./iodined \-f 10.0.0.1 test.asdf
(If you already use the 10.0.0.0 network, use another internal net like 
172.16.0.0)
.TP
- Enter a password
.TP
- On the client, run: ./iodine \-f 192.168.0.1 test.asdf
(Replace 192.168.0.1 with the server's ip address)
.TP
- Enter the same password
.TP
- Now the client has the tunnel ip 10.0.0.2 and the server has 10.0.0.1
.TP
- Try pinging each other through the tunnel
.TP
- Done! :)
.TP
To actually use it through a relaying nameserver, see below.
.SS Full setup:

.TP
.B Server side:
To use this tunnel, you need control over a real domain (like mytunnel.com),
and a server with a public IP number. If the server already runs a DNS
server, change the listening port and then use the \-b option to let
iodined forward the DNS requests. Then, delegate a subdomain 
(say, tunnel1.mytunnel.com) to the server. If you use BIND for the domain, 
add these lines to the zone file (replace 10.15.213.99 with your server ip):

.nf
tunnel1host	IN	A	10.15.213.99
tunnel1		IN	NS	tunnel1host.mytunnel.com.
.fi

Now any DNS querys for domains ending with tunnel1.mytunnnel.com will be sent
to your server. Start iodined on the server. The first argument is the tunnel
IP address (like 192.168.99.1) and the second is the assigned domain (in this
case tunnel1.mytunnel.com). The \-f argument will keep iodined running in the
foreground, which helps when testing. iodined will start a virtual interface,
and also start listening for DNS queries on UDP port 53. Either enter a
password on the commandline (\-P pass) or after the server has started. Now 
everything is ready for the client.
.TP
.B Client side: 
All the setup is done, just start iodine. It also takes two
arguments, the first is the local relaying DNS server and the second is the
domain used (tunnel1.mytunnnel.com). If DNS queries are allowed to any
computer, you can use the tunnel endpoint (example: 10.15.213.99 or
tunnel1host.mytunnel.com) as the first argument. The tunnel interface will get
an IP close to the servers (in this case 192.168.99.2) and a suitable MTU. 
Enter the same password as on the server either by argument or after the client
has started. Now you should be able to ping the other end of the tunnel from 
either side.  
.TP
.B Routing:
The normal case is to route all traffic through the DNS tunnel. To do this, first
add a route to the nameserver you use with the default gateway as gateway. Then
replace the default gateway with the servers IP address within the DNS tunnel,
and configure the server to do NAT.
.TP
.B Troubleshooting:
Use the \-D option on the server to show received and sent queries, or use a 
tool like Wireshark/tcpdump. The iodined server replies to NS requests sent for
subdomains of the tunnel domain. If your domain is tunnel.com, send a NS
request for foo.tunnel.com to see if the delegation works. dig is a good tool
for this: 
.nf
dig \-t NS foo123.tunnel.com
.fi
.TP
.B MTU issues:
These issues should be solved now, with automatic fragmentation of downstream 
packets. There should be no need to set the MTU explicitly on the server.
.SH SECURITY
Login is a relatively secure challenge-response MD5 hash, with the
password never passing the wire.
However, all other data is
.B NOT
encrypted in any way. The DNS traffic is also vulnerable to replay,
injection and man-in-the-middle attacks, especially when iodined is used
with the \-c option. Use of ssh or vpn tunneling is strongly recommended.
On both server and client, use
.I iptables
,
.I pf
or other firewlls to block all traffic coming in from the tun interfaces,
except to the used ssh or vpn ports.
.SH ENVIRONMENT
.SS IODINE_PASS
If the environment variable
.B IODINE_PASS
is set, iodine will use the value it is set to as password instead of asking
for one. The 
.B -P
option still has preference.
.SS IODINED_PASS
If the environment variable
.B IODINED_PASS
is set, iodined will use the value it is set to as password instead of asking
for one. The
.B -P
option still has preference.
.El
.SH SEE ALSO
The README file in the source distribution contains some more elaborate
information.
.SH BUGS
File bugs at http://dev.kryo.se/iodine/
.SH AUTHORS
Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>