diff options
Diffstat (limited to 'jni/iodine/man/iodine.8')
| -rw-r--r-- | jni/iodine/man/iodine.8 | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/jni/iodine/man/iodine.8 b/jni/iodine/man/iodine.8 new file mode 100644 index 0000000..6eee603 --- /dev/null +++ b/jni/iodine/man/iodine.8 @@ -0,0 +1,338 @@ +.\" groff -man -Tascii iodine.8 +.TH IODINE 8 "DEC 2009" "User Manuals" +.SH NAME +iodine, iodined \- tunnel IPv4 over DNS +.SH SYNOPSIS +.B iodine [-v] + +.B iodine [-h] + +.B iodine [-f] [-r] [-u +.I user +.B ] [-P +.I password +.B ] [-m +.I fragsize +.B ] [-t +.I chrootdir +.B ] [-d +.I device +.B ] [-m +.I fragsize +.B ] [-M +.I namelen +.B ] [-z +.I context +.B ] [-F +.I pidfile +.B ] [-T +.I dnstype +.B ] [-O +.I downenc +.B ] [-L +.I 0|1 +.B ] [-I +.I interval +.B ] +.B [ +.I nameserver +.B ] +.I topdomain + +.B iodined [-v] + +.B iodined [-h] + +.B iodined [-c] [-s] [-f] [-D] [-u +.I user +.B ] [-t +.I chrootdir +.B ] [-d +.I device +.B ] [-m +.I mtu +.B ] [-l +.I listen_ip +.B ] [-p +.I port +.B ] [-n +.I external_ip +.B ] [-b +.I dnsport +.B ] [-P +.I password +.B ] [-z +.I context +.B ] [-F +.I pidfile +.B ] +.I tunnel_ip +.B [ +.I /netmask +.B ] +.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 a measured maximum of 680 kbit/s upstream and 2.3 Mbit/s +downstream in a wired LAN test network. +Realistic sustained throughput on a Wifi network using a carrier-grade +DNS cache has been measured at some 50 kbit/s upstream and over 200 kbit/s +downstream. +.B iodine +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 +.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 -d device +Use the TUN device 'device' instead of the normal one, which is dnsX on Linux +and otherwise tunX. +.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 -z context +Apply SELinux 'context' after initialization. +.TP +.B -F pidfile +Create 'pidfile' and write process id in it. +.SS Client Options: +.TP +.B -r +Skip raw UDP mode. If not used, iodine will try getting the public IP address +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 +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 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 +and +.I A +(returning CNAME). +Note that +.IR SRV , +.I MX +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 +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 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, 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 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 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: +.TP +.B -c +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. +.TP +.B -D +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 1130. Note that the DNS traffic will be +automatically fragmented when needed. +.TP +.B -l listen_ip +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 +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 +The nameserver to use to relay the dns traffic. This can be any relaying +nameserver or the server running iodined if reachable. This field can be +given as an IP address, or as a hostname. This argument is optional, and +if not specified a nameserver will be read from the +.I /etc/resolv.conf +file. +.TP +.B topdomain +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 +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[/netmask] +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 +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 +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. +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 +.IR iptables , +.I pf +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 +If the environment variable +.B IODINE_PASS +is set, iodine will use the value it is set to as password instead of asking +for one. The +.B -P +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 precedence. +.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 +Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major +contributions by Anne Bezemer. |