#75, update docs

This commit is contained in:
Erik Ekman 2009-09-20 15:11:10 +00:00
parent a02f7d776f
commit 3703485c9c
2 changed files with 101 additions and 24 deletions

32
README
View File

@ -70,14 +70,8 @@ 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.
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.
If you have problems, try inspecting the traffic with network monitoring tools
and make sure that the relaying DNS server has not cached the response. A
cached error message could mean that you started the client before the server.
The -D option on the server can also show received and sent queries.
The DNS-response fragment size is normally autoprobed to get maximum bandwidth.
To force a specific value (and speed things up), use the -m option.
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
@ -90,6 +84,21 @@ and one query can be max 256 chars. Each domain name part can be max 63 chars.
So your domain name and subdomain should be as short as possible to allow
maximum upstream throughput.
The default is to use DNS NULL-type queries, as this provides the largest
downstream bandwidth. If your DNS server blocks NULL requests, try TXT or
CNAME queries via the -T option. Also supported are A (returning CNAME) and
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. DNS responses for non-NULL are Base32 encoded by default, which
should always work. For more bandwidth, try Base64 or Raw (TXT only) via the
-O option. If Base64/Raw doesn't work, you'll see many failures in the
fragment size autoprobe.
If you have problems, try inspecting the traffic with network monitoring tools
and make sure that the relaying DNS server has not cached the response. A
cached error message could mean that you started the client before the server.
The -D (and -DD) option on the server can also show received and sent queries.
TIPS & TRICKS:
@ -99,6 +108,13 @@ use for instance iptables (on Linux) to forward the traffic:
iptables -t nat -A PREROUTING -i eth0 -p udp --dport 53 -j DNAT --to :5353
(Sent in by Tom Schouten)
Iodined will reject data from clients that have not been active (data/pings)
for more than 60 seconds. In case of a long network outage or similar, just
stop iodine and restart (re-login), possibly multiple times until you get
your old IP address back. Once that's done, just wait a while, and you'll
eventually see the tunneled TCP traffic continue to flow from where it left
off before the outage.
PORTABILITY:

View File

@ -1,5 +1,5 @@
.\" groff -man -Tascii iodine.8
.TH IODINE 8 "JUL 2008" "User Manuals"
.TH IODINE 8 "SEP 2009" "User Manuals"
.SH NAME
iodine, iodined \- tunnel IPv4 over DNS
.SH SYNOPSIS
@ -23,6 +23,10 @@ iodine, iodined \- tunnel IPv4 over DNS
.I context
.B ] [-F
.I pidfile
.B ] [-T
.I dnstype
.B ] [-O
.I downenc
.B ]
.B [
.I nameserver
@ -46,7 +50,7 @@ iodine, iodined \- tunnel IPv4 over DNS
.B ] [-p
.I port
.B ] [-n
.I external ip
.I external_ip
.B ] [-b
.I dnsport
.B ] [-P
@ -111,40 +115,78 @@ 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.
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".
.SS Server Options:
.TP
.B -c
Disable checks on client IP on all incoming requests.
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.
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 tunnel device. This will be sent to the client
on connect, and the client will use the same 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' instead of on 0.0.0.0 for incoming
connections.
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
.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
@ -156,7 +198,7 @@ from the
file.
.TP
.B topdomain
The dns traffic will be sent as querys of type NULL for subdomains under
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
@ -165,17 +207,19 @@ 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
+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 will is expected to be sent as querys of type NULL for
+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.
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
@ -254,6 +298,20 @@ dig \-t NS foo123.tunnel.com
.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
@ -270,6 +328,9 @@ 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