1IODINE(8) System Manager's Manual IODINE(8)
2
6 iodine - tunnel IPv4 over DNS
7
9 iodine [-v]
10 iodine [-h]
12 iodine [-4] [-6] [-f] [-r] [-u user ] [-P password ] [-m fragsize ] [-t
14 chrootdir ] [-d device ] [-R rdomain ] [-m fragsize ] [-M namelen ] [-z
15 context ] [-F pidfile ] [-T dnstype ] [-O downenc ] [-L 0|1 ] [-I
16 interval ] [ nameserver ] topdomain
17
21 iodine lets you tunnel IPv4 data through a DNS server. This can be use‐
22 ful in situations where Internet access is firewalled, but DNS queries
23 are allowed. It needs a TUN/TAP device to operate. The bandwidth is
24 asymmetrical, with a measured maximum of 680 kbit/s upstream and 2.3
25 Mbit/s downstream in a wired LAN test network. Realistic sustained
26 throughput on a Wifi network using a carrier-grade DNS cache has been
27 measured at some 50 kbit/s upstream and over 200 kbit/s downstream.
28 iodine is the client application, iodined is the server.
29 Note: server and client are required to speak the exact same protocol.
31 In most cases, this means running the same iodine version. Unfortu‐
32 nately, implementing backward and forward protocol compatibility is
33 usually not feasible.
34
36 Common Options:
37 -v Print version info and exit.
38 -h Print usage info and exit.
40 -f Keep running in foreground.
42 -u user
44 Drop privileges and run as user 'user' after setting up tunnel.
45 -t chrootdir
47 Chroot to 'chrootdir' after setting up tunnel.
48 -d device
50 Use the TUN device 'device' instead of the normal one, which is
51 dnsX on Linux and otherwise tunX.
52 -P password
54 Use 'password' to authenticate. If not used, stdin will be used
55 as input. Only the first 32 characters will be used.
56 -z context
58 Apply SELinux 'context' after initialization.
59 -F pidfile
61 Create 'pidfile' and write process id in it.
62 Client Options:
64 -4 Force IPv4 DNS queries
65 -6 Force IPv6 DNS queries
67 -r Skip raw UDP mode. If not used, iodine will try getting the pub‐
69 lic IP address of the iodined host and test if it is reachable
70 directly. If it is, traffic will be sent to the server instead
71 of the DNS relay.
72 -R rdomain
74 Use OpenBSD routing domain 'rdomain' for the DNS connection.
75 -m fragsize
77 Force maximum downstream fragment size. Not setting this will
78 cause the client to automatically probe the maximum accepted
79 downstream fragment size.
80 -M namelen
82 Maximum length of upstream hostnames, default 255. Usable range
83 ca. 100 to 255. Use this option to scale back upstream band‐
84 width in favor of downstream bandwidth. Also useful for DNS
85 servers that perform unreliably when using full-length host‐
86 names, noticeable when fragment size autoprobe returns very dif‐
87 ferent results each time.
88 -T dnstype
90 DNS request type override. By default, autodetection will probe
91 for working DNS request types, and will select the request type
92 that is expected to provide the most bandwidth. However, it may
93 turn out that a DNS relay imposes limits that skew the picture,
94 which may lead to an "unexpected" DNS request type providing
95 more bandwidth. In that case, use this option to override the
96 autodetection. In (expected) decreasing bandwidth order, the
97 supported DNS request types are: NULL, PRIVATE, TXT, SRV, MX,
98 CNAME and A (returning CNAME). Note that SRV, MX and A may/will
99 cause additional lookups by "smart" caching nameservers to get
100 an actual IP address, which may either slow down or fail com‐
101 pletely. The PRIVATE type uses value 65399 (in the 'private use'
102 range) and requires servers implementing RFC 3597.
103 -O downenc
105 Force downstream encoding type for all query type responses
106 except NULL. Default is autodetected, but may not spot all
107 problems for the more advanced codecs. Use this option to over‐
108 ride the autodetection. Base32 is the lowest-grade codec and
109 should always work; this is used when autodetection fails.
110 Base64 provides more bandwidth, but may not work on all name‐
111 servers. Base64u is equal to Base64 except in using underscore
112 ('_') instead of plus sign ('+'), possibly working where Base64
113 does not. Base128 uses high byte values (mostly accented let‐
114 ters in iso8859-1), which might work with some nameservers. For
115 TXT queries, Raw will provide maximum performance, but this will
116 only work if the nameserver path is fully 8-bit-clean for
117 responses that are assumed to be "legible text".
118 -L 0|1 Lazy-mode switch. -L1 (default): Use lazy mode for improved
120 performance and decreased latency. A very small minority of DNS
121 relays appears to be unable to handle the lazy mode traffic pat‐
122 tern, resulting in no or very little data coming through. The
123 iodine client will detect this and try to switch back to legacy
124 mode, but this may not always work. In these situations use -L0
125 to force running in legacy mode (implies -I1).
126 -I interval
128 Maximum interval between requests (pings) so that intermediate
129 DNS servers will not time out. Default is 4 in lazy mode, which
130 will work fine in most cases. When too many SERVFAIL errors
131 occur, iodine will automatically reduce this to 1. To get abso‐
132 lute minimum DNS traffic, increase well above 4, but not so high
133 that SERVFAIL errors start to occur. There are some DNS relays
134 with very small timeouts, notably dnsadvantage.com (ultradns),
135 that will give SERVFAIL errors even with -I1; data will still
136 get trough, and these errors can be ignored. Maximum useful
137 value is 59, since iodined will close a client's connection
138 after 60 seconds of inactivity.
139
141 IODINE_PASS
142 If the environment variable IODINE_PASS is set, iodine will use the
143 value it is set to as password instead of asking for one. The -P option
144 still has precedence.
145
147 The README file in the source distribution contains some more elaborate
148 information.
149
151 File bugs at http://dev.kryo.se/iodine/
152
154 Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
155 contributions by Anne Bezemer.
156User Manuals JUN 2014 IODINE(8)