#8 added manpage
This commit is contained in:
Erik Ekman
parent
71e9359ed0
commit
cf3734c70e
|
|
@ -0,0 +1,185 @@
|
|||
.\" groff -man -Tascii iodine.8
|
||||
.TH IODINE 8 "FEB 2007" "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 ]
|
||||
.I nameserver
|
||||
.I topdomain
|
||||
|
||||
.B iodined [-v]
|
||||
|
||||
.B iodined [-h]
|
||||
|
||||
.B iodined [-f] [-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 -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.
|
||||
Normally, you should specify a nameserver from your
|
||||
.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.
|
||||
.SH BUGS
|
||||
File bugs at http://dev.kryo.se/iodine/
|
||||
.SH AUTHORS
|
||||
Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>
|
||||
Loading…
Reference in New Issue