1IODINE(8) System Manager's Manual IODINE(8)
2
6 iodine, iodined - tunnel IPv4 over DNS
7
9 iodine [-v]
10 iodine [-h]
12 iodine [-f] [-r] [-u user ] [-P password ] [-m fragsize ] [-t chrootdir
14 ] [-d device ] [-m fragsize ] [-M namelen ] [-z context ] [-F pidfile ]
15 [-T dnstype ] [-O downenc ] [-L 0|1 ] [-I interval ] [ nameserver ]
16 topdomain
17 iodined [-v]
19 iodined [-h]
21 iodined [-c] [-s] [-f] [-D] [-u user ] [-t chrootdir ] [-d device ] [-m
23 mtu ] [-l listen_ip ] [-p port ] [-n external_ip ] [-b dnsport ] [-P
24 password ] [-z context ] [-F pidfile ] tunnel_ip [ /netmask ] topdomain
25
27 iodine lets you tunnel IPv4 data through a DNS server. This can be use‐
28 ful in situations where Internet access is firewalled, but DNS queries
29 are allowed. It needs a TUN/TAP device to operate. The bandwidth is
30 asymmetrical, with a measured maximum of 680 kbit/s upstream and 2.3
31 Mbit/s downstream in a wired LAN test network. Realistic sustained
32 throughput on a Wifi network using a carrier-grade DNS cache has been
33 measured at some 50 kbit/s upstream and over 200 kbit/s downstream.
34 iodine is the client application, iodined is the server.
35 Note: server and client are required to speak the exact same protocol.
37 In most cases, this means running the same iodine version. Unfortu‐
38 nately, implementing backward and forward protocol compatibility is
39 usually not feasible.
40
42 Common Options:
43 -v Print version info and exit.
44 -h Print usage info and exit.
46 -f Keep running in foreground.
48 -u user
50 Drop privileges and run as user 'user' after setting up tunnel.
51 -t chrootdir
53 Chroot to 'chrootdir' after setting up tunnel.
54 -d device
56 Use the TUN device 'device' instead of the normal one, which is
57 dnsX on Linux and otherwise tunX.
58 -P password
60 Use 'password' to authenticate. If not used, stdin will be used
61 as input. Only the first 32 characters will be used.
62 -z context
64 Apply SELinux 'context' after initialization.
65 -F pidfile
67 Create 'pidfile' and write process id in it.
68 Client Options:
70 -r Skip raw UDP mode. If not used, iodine will try getting the pub‐
71 lic IP address of the iodined host and test if it is reachable
72 directly. If it is, traffic will be sent to the server instead
73 of the DNS relay.
74 -m fragsize
76 Force maximum downstream fragment size. Not setting this will
77 cause the client to automatically probe the maximum accepted
78 downstream fragment size.
79 -M namelen
81 Maximum length of upstream hostnames, default 255. Usable range
82 ca. 100 to 255. Use this option to scale back upstream band‐
83 width in favor of downstream bandwidth. Also useful for DNS
84 servers that perform unreliably when using full-length host‐
85 names, noticable when fragment size autoprobe returns very dif‐
86 ferent results each time.
87 -T dnstype
89 DNS request type override. By default, autodetection will probe
90 for working DNS request types, and will select the request type
91 that is expected to provide the most bandwidth. However, it may
92 turn out that a DNS relay imposes limits that skew the picture,
93 which may lead to an "unexpected" DNS request type providing
94 more bandwidth. In that case, use this option to override the
95 autodetection. In (expected) decreasing bandwidth order, the
96 supported DNS request types are: NULL, TXT, SRV, MX, CNAME and A
97 (returning CNAME). Note that SRV, MX and A may/will cause addi‐
98 tional lookups by "smart" caching nameservers to get an actual
99 IP address, which may either slow down or fail completely.
100 -O downenc
102 Force downstream encoding type for all query type responses
103 except NULL. Default is autodetected, but may not spot all
104 problems for the more advanced codecs. Use this option to over‐
105 ride the autodetection. Base32 is the lowest-grade codec and
106 should always work; this is used when autodetection fails.
107 Base64 provides more bandwidth, but may not work on all name‐
108 servers. Base64u is equal to Base64 except in using underscore
109 ('_') instead of plus sign ('+'), possibly working where Base64
110 does not. Base128 uses high byte values (mostly accented let‐
111 ters in iso8859-1), which might work with some nameservers. For
112 TXT queries, Raw will provide maximum performance, but this will
113 only work if the nameserver path is fully 8-bit-clean for
114 responses that are assumed to be "legible text".
115 -L 0|1 Lazy-mode switch. -L1 (default): Use lazy mode for improved
117 performance and decreased latency. A very small minority of DNS
118 relays appears to be unable to handle the lazy mode traffic pat‐
119 tern, resulting in no or very little data coming through. The
120 iodine client will detect this and try to switch back to legacy
121 mode, but this may not always work. In these situations use -L0
122 to force running in legacy mode (implies -I1).
123 -I interval
125 Maximum interval between requests (pings) so that intermediate
126 DNS servers will not time out. Default is 4 in lazy mode, which
127 will work fine in most cases. When too many SERVFAIL errors
128 occur, iodine will automatically reduce this to 1. To get abso‐
129 lute minimum DNS traffic, increase well above 4, but not so high
130 that SERVFAIL errors start to occur. There are some DNS relays
131 with very small timeouts, notably dnsadvantage.com (ultradns),
132 that will give SERVFAIL errors even with -I1; data will still
133 get trough, and these errors can be ignored. Maximum useful
134 value is 59, since iodined will close a client's connection
135 after 60 seconds of inactivity.
136 Server Options:
138 -c Disable checking the client IP address on all incoming requests.
139 By default, requests originating from non-matching IP adresses
140 will be rejected, however this will cause problems when requests
141 are routed via a cluster of DNS servers.
142 -s Don't try to configure IP address or MTU. This should only be
144 used if you have already configured the device that will be
145 used.
146 -D Increase debug level. Level 1 prints info about each RX/TX
148 packet. Implies the -f option. On level 2 (-DD) or higher, DNS
149 queries will be printed literally. When using Base128 upstream
150 encoding, this is best viewed as ISO Latin-1 text instead of
151 (illegal) UTF-8. This is easily done with : "LC_ALL=C luit
152 iodined -DD ..." (see luit(1)).
153 -m mtu Set 'mtu' as mtu size for the tun device. This will be sent to
155 the client on login, and the client will use the same mtu for
156 its tun device. Default 1130. Note that the DNS traffic will
157 be automatically fragmented when needed.
158 -l listen_ip
160 Make the server listen only on 'listen_ip' for incoming
161 requests. By default, incoming requests are accepted from all
162 interfaces.
163 -p port
165 Make the server listen on 'port' instead of 53 for traffic.
166 Note: You must make sure the dns requests are forwarded to this
167 port yourself.
168 -n external_ip
170 The IP address to return in NS responses. Default is to return
171 the address used as destination in the query.
172 -b dnsport
174 If this port is specified, all incoming requests not inside the
175 tunnel domain will be forwarded to this port on localhost, to be
176 handled by a real dns. Note: The forwarding is not fully trans‐
177 parent, and not advised for use in production environments.
178 Client Arguments:
180 nameserver
181 The nameserver to use to relay the dns traffic. This can be any
182 relaying nameserver or the server running iodined if reachable.
183 This field can be given as an IP address, or as a hostname. This
184 argument is optional, and if not specified a nameserver will be
185 read from the /etc/resolv.conf file.
186 topdomain
188 The dns traffic will be sent as queries for subdomains under
189 ´topdomain'. This is normally a subdomain to a domain you own.
190 Use a short domain name to get better throughput. If nameserver
191 is the iodined server, then the topdomain can be chosen freely.
192 This argument must be the same on both the client and the
193 server.
194 Server Arguments:
196 tunnel_ip[/netmask]
197 This is the server's ip address on the tun interface. The client
198 will be given the next ip number in the range. It is recommended
199 to use the 10.0.0.0 or 172.16.0.0 ranges. The default netmask is
200 /27, can be overriden by specifying it here. Using a smaller
201 network will limit the number of concurrent users.
202 topdomain
204 The dns traffic is expected to arrive as queries for subdomains
205 under 'topdomain'. This is normally a subdomain to a domain you
206 own. Use a short domain name to get better throughput. This
207 argument must be the same on both the client and the server.
208 Queries for domains other than 'topdomain' will be forwarded
209 when the -b option is given, otherwise they will be dropped.
210
212 See the README file for both a quick test scenario, and a detailed
213 description of real-world deployment.
214
216 Login is a relatively secure challenge-response MD5 hash, with the
217 password never passing the wire. However, all other data is NOT
218 encrypted in any way. The DNS traffic is also vulnerable to replay,
219 injection and man-in-the-middle attacks, especially when iodined is
220 used with the -c option. Use of ssh or vpn tunneling is strongly recom‐
221 mended. On both server and client, use iptables, pf or other firewalls
222 to block all traffic coming in from the tun interfaces, except to the
223 used ssh or vpn ports.
224
226 IODINE_PASS
227 If the environment variable IODINE_PASS is set, iodine will use the
228 value it is set to as password instead of asking for one. The -P option
229 still has precedence.
230 IODINED_PASS
232 If the environment variable IODINED_PASS is set, iodined will use the
233 value it is set to as password instead of asking for one. The -P option
234 still has precedence.
235
237 The README file in the source distribution contains some more elaborate
238 information.
239
241 File bugs at http://dev.kryo.se/iodine/
242
244 Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
245 contributions by Anne Bezemer.
246User Manuals DEC 2009 IODINE(8)