Applied patch from #88, thanks a lot!

man/iodine.8

@@ -1,5 +1,5 @@
 .\" groff -man -Tascii iodine.8
-.TH IODINE 8 "SEP 2009" "User Manuals"
+.TH IODINE 8 "DEC 2009" "User Manuals"
 .SH NAME
 iodine, iodined \- tunnel IPv4 over DNS
 .SH SYNOPSIS
@@ -19,6 +19,8 @@ iodine, iodined \- tunnel IPv4 over DNS
 .I device
 .B ] [-m
 .I fragsize
+.B ] [-M
+.I namelen
 .B ] [-z
 .I context
 .B ] [-F
@@ -84,6 +86,10 @@ downstream.
 is the client application,
 .B iodined
 is the server.
+
+Note: server and client are required to speak the exact same protocol. In most
+cases, this means running the same iodine version. Unfortunately, implementing
+backward and forward protocol compatibility is usually not feasible.
 .SH OPTIONS
 .SS Common Options:
 .TP
@@ -127,49 +133,85 @@ will be sent to the server instead of the DNS relay.
 Force maximum downstream fragment size. Not setting this will cause the
 client to automatically probe the maximum accepted downstream fragment size.
 .TP
+.B -M namelen
+Maximum length of upstream hostnames, default 255.
+Usable range ca. 100 to 255.
+Use this option to scale back upstream bandwidth in favor of downstream
+bandwidth.
+Also useful for DNS servers that perform unreliably when using full-length
+hostnames, noticable when fragment size autoprobe returns very
+different results each time.
+.TP
 .B -T dnstype
-DNS request type.
-.I NULL
-is default. If this doesn't work, try
-.I TXT
-(some less bandwidth) or
+DNS request type override.
+By default, autodetection will probe for working DNS request types, and
+will select the request type that is expected to provide the most bandwidth.
+However, it may turn out that a DNS relay imposes limits that skew the
+picture, which may lead to an "unexpected" DNS request type providing
+more bandwidth.
+In that case, use this option to override the autodetection.
+In (expected) decreasing bandwidth order, the supported DNS request types are:
+.IR NULL ,
+.IR TXT ,
+.IR SRV ,
+.IR MX ,
 .I CNAME
-(much less bandwidth). Also supported are
+and
 .I A
-(returning CNAME) and
+(returning CNAME).
+Note that
+.IR SRV ,
 .I MX
-requests, but these may/will cause additional lookups by "smart" caching
+and
+.I A
+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.
+Force downstream encoding type for all query type responses except NULL.
+Default is autodetected, but may not spot all problems for the more advanced
+codecs.
+Use this option to override the autodetection.
 .I Base32
-is default and should always work.
+is the lowest-grade codec and should always work; this is used when
+autodetection fails.
 .I Base64
 provides more bandwidth, but may not work on all nameservers.
+.I Base64u
+is equal to Base64 except in using underscore ('_')
+instead of plus sign ('+'), possibly working where
+.I Base64
+does not.
+.I Base128
+uses high byte values (mostly accented letters in iso8859-1),
+which might work with some nameservers.
 For TXT queries,
 .I Raw
-will provide maximum performance. This will only work if the nameserver
+will provide maximum performance, but this will only work if the nameserver
 path is fully 8-bit-clean for responses that are assumed to be "legible text".
 .TP
 .B -L 0|1
 Lazy-mode switch.
-\-L1 (default): Use lazy mode if server supports it, for improved
-performance and decreased latency.
-Some DNS servers, notably the opendns.com network, appear unstable when
-handling lazy mode DNS traffic and will re-order requests. If this occurs,
-you will notice fluctuating response speed in interactive sessions.
-The iodine client will eventually detect this and switch back to legacy
-mode automatically. Use \-L0 to force running in legacy mode
+\-L1 (default): Use lazy mode for improved performance and decreased latency.
+A very small minority of DNS relays appears to be unable to handle the
+lazy mode traffic pattern, resulting in no or very little data coming through.
+The iodine client will detect this and try to switch back to legacy mode,
+but this may not always work.
+In these situations use \-L0 to force running in legacy mode
 (implies \-I1).
 .TP
 .B -I interval
 Maximum interval between requests (pings) so that intermediate DNS
 servers will not time out. Default is 4 in lazy mode, which will work
-fine in almost all cases. Decrease if you get SERVFAIL errors in periods
-without tunneled data traffic. To get absolute minimum DNS traffic,
-increase well above 4 until SERVFAIL errors start to occur.
+fine in most cases. When too many SERVFAIL errors occur, iodine
+will automatically reduce this to 1.
+To get absolute minimum DNS traffic,
+increase well above 4, but not so high that SERVFAIL errors start to occur.
+There are some DNS relays with very small timeouts,
+notably dnsadvantage.com (ultradns), that will give
+SERVFAIL errors even with \-I1; data will still get trough,
+and these errors can be ignored.
 Maximum useful value is 59, since iodined will close a client's
 connection after 60 seconds of inactivity.
 .SS Server Options:
@@ -190,11 +232,16 @@ Increase debug level. Level 1 prints info about each RX/TX packet.
 Implies the
 .B -f
 option.
+On level 2 (-DD) or higher, DNS queries will be printed literally.
+When using Base128 upstream encoding, this is best viewed as
+ISO Latin-1 text instead of (illegal) UTF-8.
+This is easily done with : "LC_ALL=C luit iodined -DD ..."
+(see luit(1)).
 .TP
 .B -m 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
+for its tun device.  Default 1130.  Note that the DNS traffic will be
 automatically fragmented when needed.
 .TP
 .B -l listen_ip
@@ -236,97 +283,22 @@ must be the same on both the client and the server.
 .SS Server Arguments:
 .TP
 .B tunnel_ip[/netmask]
-+This is the server's ip address on the tun 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 is expected to arrive as queries 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. 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
-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.
+See the README file for both a quick test scenario, and a detailed description
+of real-world deployment.
 .SH SECURITY
 Login is a relatively secure challenge-response MD5 hash, with the
 password never passing the wire.
@@ -336,10 +308,9 @@ 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
-,
+.IR iptables ,
 .I pf
-or other firewlls to block all traffic coming in from the tun interfaces,
+or other firewalls to block all traffic coming in from the tun interfaces,
 except to the used ssh or vpn ports.
 .SH ENVIRONMENT
 .SS IODINE_PASS
@@ -348,14 +319,14 @@ If the environment variable
 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.
+option still has precedence.
 .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.
+option still has precedence.
 .El
 .SH SEE ALSO
 The README file in the source distribution contains some more elaborate