.\" groff -man -Tascii iodine.8 .TH IODINE 8 "OCT 2015" "User Manuals" .SH NAME iodine, iodined \- tunnel IPv4 over DNS .SH SYNOPSIS .B iodine [-v] .B iodine [-h] .B iodine [-4] [-6] [-f] [-D] [-r] [-V .I sec .B [-u .I user .B ] [-P .I password .B ] [-m .I fragsize .B ] [-t .I chrootdir .B ] [-d .I device .B ] [-R .I rdomain .B ] [-m .I fragsize .B ] [-w .I downfrags .B ] [-W .I upfrags .B ] [-i .I sec .B ] [-j .I sec .B ] [-c .I 0|1 .B ] [-C .I 0|1 .B ] [-s .I ms .B ] [-M .I maxlen .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 ] .I topdomain .B [ .I nameserver .B [ .I nameserver2 ... .B ] ] .B iodined [-v] .B iodined [-h] .B iodined [-4] [-6] [-f] [-D] [-c] [-s] [-u .I user .B ] [-t .I chrootdir .B ] [-d .I device .B ] [-m .I mtu .B ] [-l .I listen_ip4 .B ] [-L .I listen_ip6 .B ] [-p .I port .B ] [-n ( .B auto | .I external_ip ) .B ] [-b .I dnsport .B ] [-P .I password .B ] [-z .I context .B ] [-F .I pidfile .B ] [-i .I max_idle_time .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. .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 PERFORMANCE The bandwidth is asymmetrical, with a measured maximum of 13.7 Mbits/sec upstream and 53.4 Mbits/sec downstream with all data compression disabled in a wired LAN test network. In the same situation with compression enabled, the measured data throughput was approximately 46.1 Mbits/sec upstream and 37.4 Mbits/sec downstream. Compression is enabled by default, and can allow faster data transfer in both directions depending on the type of data being transferred. Realistic sustained throughput on a Wifi network using a carrier-grade DNS cache has been measured at some 600 Kbit/s upstream and over 2 Mbits/sec downstream once more with compression disabled, however that may be increased with compression enabled. All of the above test scenarios used lazy mode with upstream/downstream windowsizes of 8 fragments (default) and fixed fragment, DNS and server timeouts. These parameters were manually adjusted to best suit the environment, and can be specified using the .B iodine options described under .IR "Fine-tuning Options" . .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 -4 Force/allow only IPv4 DNS queries .TP .B -6 Force/allow only IPv6 DNS queries .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. On Mac OS X 10.6, this can also be utunX, which will attempt to use an utun device built into the OS. .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 -R rdomain Use OpenBSD routing domain 'rdomain' for the DNS connection. .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, noticeable 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 PRIVATE , .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. The .IR PRIVATE type uses value 65399 (in the 'private use' range) and requires servers implementing RFC 3597. .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 Target timeout for queries. This should be less than the smallest timeout for any intermediate DNS servers to reduce SERVFAILS. If this is specified, the server timeout will be adjusted automatically based on the round-trip time so that queries remain pending for as long as possible (only in lazy mode). This value will be used as the polling interval in immediate mode. When too many SERVFAIL errors occur, iodine will gradually reduce this until it reaches 0.5 seconds or below. If SERVFAILs continue to occur, lazy mode will be disabled and the server will respond to all queries immediately. To reduce DNS traffic, set this interval to something large and disable lazy mode, or set the upstream and downstream window sizes to 1. 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 through, 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 Fine-tuning Options (Client-side): .TP .B -s milliseconds Minimum query send interval. Increase this gradually if you notice that the nameserver(s) tend to fail more often with a high data load (and frequent queries) or drop excess DNS queries. This will affect throughput so use with caution. .B -w windowsize Size of downstream fragment sending window, or the number of fragments that can be in transit downstream at any point in time. The client will attempt to maintain at least this number of queries pending on the server in lazy mode, even when idle, so that the server can always send this number of fragments immediately if new data arrives on the tun device. The default value is 8 fragments. Increase this for high latency connections to improve throughput. The maximum usable value is probably around 128, however note that although higher values are possible there may be fragment overlaps and you may experience problems. .TP .B -W windowsize Number of fragments that can be in transit upstream at any point in time. The client will send a maximum of this number of queries immediately to the server when new data is received in addition to any already pending queries (such as those used to maintain the downstream windowsize). The server will respond to any excess queries using the oldest pending query first. The same limits apply as the downstream window size. .TP .B -i timeout The maximum amount of time in seconds the server should hold on to a pending query so as to not cause any intermediate DNS relays to time out. This should be less than the target timeout (set with .BR -I ) by at least the round-trip time for the connection. If not set, this will be calculated automatically based on the round-trip time and the target timeout. .TP .B -c 0|1 Enable or disable downstream data compression. Enabled by default. This may increase overall downstream throughput, or it may not depending on the type of data being transferred. .B -C 0|1 Enable/disable upstream data compression, also enabled by default. .SS Server Options: .TP .B -c Disable checking the client IP address on all incoming requests. By default, requests originating from non-matching IP addresses 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. Higher levels (>2) will spam the terminal with LOTS of debug messages. Recompile using `make debug` to enable extra debug output and debug timestamping. 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_ip4 Make the server listen only on 'listen_ip4' for incoming IPv4 requests. By default, incoming requests are accepted from all interfaces (0.0.0.0). .TP .B -L listen_ip6 Make the server listen only on 'listen_ip6' for incoming IPv6 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. If 'listen_ip4' does not include localhost, this 'port' can be the same as 'dnsport'. .B Note: You must make sure the dns requests are forwarded to this port yourself. .TP .B -n auto|external_ip The IP address to return in NS responses. Default is to return the address used as destination in the query. If external_ip is 'auto', iodined will use ipify.org web service to retrieve the external IP of the host and use that for NS responses. .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. If 'listen_ip' does not include localhost, this 'dnsport' can be the same as 'port'. .B Note: The forwarding is not fully transparent, and not advised for use in production environments. .TP .B -i max_idle_time Make the server stop itself after max_idle_time seconds if no traffic have been received. This should be combined with systemd or upstart on demand activation for being effective. .SS Client Arguments: .TP .B nameservers The nameservers 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 IPv4/IPv6 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. Multiple nameservers can be specified, separated by spaces. .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 address, 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/8, 172.16.0.0/12 or 192.168.0.0/16 ranges. The default netmask is /27, which can be overridden 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 ignored. .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. .SH SEE ALSO The README.md file in the source distribution contains some more elaborate information. .SH BUGS File bugs at http://dev.kryo.se/iodine/ .SH AUTHORS Erik Ekman , Bjorn Andersson and Frekky. Major contributions by Anne Bezemer.