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