205 lines
6.1 KiB
Groff
205 lines
6.1 KiB
Groff
.\" groff -man -Tascii iodine.8
|
|
.TH IODINE 8 "JUL 2008" "User Manuals"
|
|
.SH NAME
|
|
iodine, iodined \- tunnel IPv4 over DNS
|
|
.SH SYNOPSIS
|
|
.B iodine [-v]
|
|
|
|
.B iodine [-h]
|
|
|
|
.B iodine [-f] [-u
|
|
.I user
|
|
.B ] [-P
|
|
.I password
|
|
.B ] [-t
|
|
.I chrootdir
|
|
.B ] [-d
|
|
.I device
|
|
.B ]
|
|
.B [
|
|
.I nameserver
|
|
.B ]
|
|
.I topdomain
|
|
|
|
.B iodined [-v]
|
|
|
|
.B iodined [-h]
|
|
|
|
.B iodined [-c] [-s] [-f] [-D] [-u
|
|
.I user
|
|
.B ] [-P
|
|
.I password
|
|
.B ] [-t
|
|
.I chrootdir
|
|
.B ] [-m
|
|
.I mtu
|
|
.B ] [-l
|
|
.I listen_ip
|
|
.B ] [-d
|
|
.I device
|
|
.B ]
|
|
.I tunnel_ip
|
|
.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 limited upstream and up to 1 Mbit/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 -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 -d device
|
|
Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
|
|
and otherwise tunX.
|
|
.SS Server Options:
|
|
.TP
|
|
.B -c
|
|
Disable checks on client IP on all incoming requests.
|
|
.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.
|
|
.TP
|
|
.B -m mtu
|
|
Set 'mtu' as mtu size for the tunnel device. This will be sent to the client
|
|
on connect, and the client will use the same mtu.
|
|
.TP
|
|
.B -l listen_ip
|
|
Make the server listen only on 'listen_ip' instead of on 0.0.0.0 for incoming
|
|
connections.
|
|
.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.
|
|
.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 querys of type NULL 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
|
|
This is the servers ip address on the tunnel interface. The client will be
|
|
given the next ip number in the range. It is recommended to use the
|
|
10.0.0.0/8 or 172.16.0.0/12 ranges.
|
|
.TP
|
|
.B topdomain
|
|
The dns traffic will is expected to be sent as querys of type NULL 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.
|
|
.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 static public IP number that does not yet run a DNS
|
|
server. 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 MTU issues:
|
|
Some relaying DNS servers enforce a 512 byte packet limit. All larger packets are
|
|
simply dropped. If you can ping through the tunnel but not login via SSH, this is
|
|
most likely the case. Set the MTU on the server to 220 to ensure that all packets
|
|
are less than 512 bytes. This will however greatly affect performance.
|
|
.SH BUGS
|
|
File bugs at http://dev.kryo.se/iodine/
|
|
.SH AUTHORS
|
|
Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>
|