update docs #75

This commit is contained in:
J. A. Bezemer 2009-09-20 15:11:10 +00:00 committed by Erik Ekman
parent c2bc500cba
commit 6b78b3a9bd
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, replace the default gateway with the servers IP address within the DNS tunnel,
and configure the server to do NAT. and configure the server to do NAT.
MTU issues: The DNS-response fragment size is normally autoprobed to get maximum bandwidth.
These issues should be solved now, with automatic fragmentation of downstream To force a specific value (and speed things up), use the -m option.
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 iodined server replies to NS requests sent for subdomains of the tunnel 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 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 So your domain name and subdomain should be as short as possible to allow
maximum upstream throughput. 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: 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 iptables -t nat -A PREROUTING -i eth0 -p udp --dport 53 -j DNAT --to :5353
(Sent in by Tom Schouten) (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: PORTABILITY:

View file

@ -1,5 +1,5 @@
.\" groff -man -Tascii iodine.8 .\" groff -man -Tascii iodine.8
.TH IODINE 8 "JUL 2008" "User Manuals" .TH IODINE 8 "SEP 2009" "User Manuals"
.SH NAME .SH NAME
iodine, iodined \- tunnel IPv4 over DNS iodine, iodined \- tunnel IPv4 over DNS
.SH SYNOPSIS .SH SYNOPSIS
@ -23,6 +23,10 @@ iodine, iodined \- tunnel IPv4 over DNS
.I context .I context
.B ] [-F .B ] [-F
.I pidfile .I pidfile
.B ] [-T
.I dnstype
.B ] [-O
.I downenc
.B ] .B ]
.B [ .B [
.I nameserver .I nameserver
@ -46,7 +50,7 @@ iodine, iodined \- tunnel IPv4 over DNS
.B ] [-p .B ] [-p
.I port .I port
.B ] [-n .B ] [-n
.I external ip .I external_ip
.B ] [-b .B ] [-b
.I dnsport .I dnsport
.B ] [-P .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. will be sent to the server instead of the DNS relay.
.TP .TP
.B -m fragsize .B -m fragsize
Maximum downstream fragsize. Not setting this will cause the client to probe Force maximum downstream fragment size. Not setting this will cause the
the maximum accepted downstream packet size. 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: .SS Server Options:
.TP .TP
.B -c .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 .TP
.B -s .B -s
Don't try to configure IP address or MTU. This should only be used if Don't try to configure IP address or MTU.
you have already configured the device that will be used. This should only be used if you have already configured the device that will be
used.
.TP .TP
.B -D .B -D
Increase debug level. Level 1 prints info about each RX/TX packet. Increase debug level. Level 1 prints info about each RX/TX packet.
Implies the
.B -f
option.
.TP .TP
.B -m mtu .B -m mtu
Set 'mtu' as mtu size for the tunnel device. This will be sent to the client Set 'mtu' as mtu size for the tun device.
on connect, and the client will use the same mtu. 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 .TP
.B -l listen_ip .B -l listen_ip
Make the server listen only on 'listen_ip' instead of on 0.0.0.0 for incoming Make the server listen only on 'listen_ip' for incoming requests.
connections. By default, incoming requests are accepted from all interfaces.
.TP .TP
.B -p port .B -p port
Make the server listen on 'port' instead of 53 for traffic. Make the server listen on 'port' instead of 53 for traffic.
.B Note: .B Note:
You must make sure the dns requests are forwarded to this port yourself. You must make sure the dns requests are forwarded to this port yourself.
.TP .TP
.B -n external ip .B -n external_ip
The IP address to return in NS responses. Default is to return the address used The IP address to return in NS responses. Default is to return the address used
as destination in the query. as destination in the query.
.TP .TP
.B -b dnsport .B -b dnsport
If this port is specified, all incoming requests not inside the tunnel domain 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. 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: .SS Client Arguments:
.TP .TP
.B nameserver .B nameserver
@ -156,7 +198,7 @@ from the
file. file.
.TP .TP
.B topdomain .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 \'topdomain'. This is normally a subdomain to a domain you own. Use a short
domain name to get better throughput. If domain name to get better throughput. If
.B nameserver .B nameserver
@ -165,17 +207,19 @@ must be the same on both the client and the server.
.SS Server Arguments: .SS Server Arguments:
.TP .TP
.B tunnel_ip[/netmask] .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 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 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 by specifying it here. Using a smaller network will limit the number of
concurrent users. concurrent users.
.TP .TP
.B topdomain .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 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 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 .SH EXAMPLES
.SS Quickstart: .SS Quickstart:
.TP .TP
@ -254,6 +298,20 @@ dig \-t NS foo123.tunnel.com
.B MTU issues: .B MTU issues:
These issues should be solved now, with automatic fragmentation of downstream 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. 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 .SH ENVIRONMENT
.SS IODINE_PASS .SS IODINE_PASS
If the environment variable If the environment variable
@ -270,6 +328,9 @@ for one. The
.B -P .B -P
option still has preference. option still has preference.
.El .El
.SH SEE ALSO
The README file in the source distribution contains some more elaborate
information.
.SH BUGS .SH BUGS
File bugs at http://dev.kryo.se/iodine/ File bugs at http://dev.kryo.se/iodine/
.SH AUTHORS .SH AUTHORS