277 lines
8.0 KiB
Groff
277 lines
8.0 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] [-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 ]
|
|
.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 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 -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
|
|
Maximum downstream fragsize. Not setting this will cause the client to probe
|
|
the maximum accepted downstream packet size.
|
|
.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.
|
|
.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.
|
|
.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[/netmask]
|
|
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 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 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 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 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 BUGS
|
|
File bugs at http://dev.kryo.se/iodine/
|
|
.SH AUTHORS
|
|
Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>
|