#75, update docs

README

@@ -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:
+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
 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:
 

man/iodine.8

@@ -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
+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:
 .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
+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
 .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
+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
 .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
 .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