1IODINE(8) System Manager's Manual IODINE(8)
2
6 iodined - tunnel IPv4 over DNS
7
9 iodined [-v]
10 iodined [-h]
12 iodined [-4] [-6] [-c] [-s] [-f] [-D] [-u user ] [-t chrootdir ] [-d
14 device ] [-m mtu ] [-l listen_ip4 ] [-L listen_ip6 ] [-p port ] [-n (
15 auto | external_ip ) ] [-b dnsport ] [-P password ] [-z context ] [-F
16 pidfile ] [-i max_idle_time ] tunnel_ip [ /netmask ] topdomain
17
19 iodine lets you tunnel IPv4 data through a DNS server. This can be use‐
20 ful in situations where Internet access is firewalled, but DNS queries
21 are allowed. It needs a TUN/TAP device to operate. The bandwidth is
22 asymmetrical, with a measured maximum of 680 kbit/s upstream and 2.3
23 Mbit/s downstream in a wired LAN test network. Realistic sustained
24 throughput on a Wifi network using a carrier-grade DNS cache has been
25 measured at some 50 kbit/s upstream and over 200 kbit/s downstream.
26 iodine is the client application, iodined is the server.
27 Note: server and client are required to speak the exact same protocol.
29 In most cases, this means running the same iodine version. Unfortu‐
30 nately, implementing backward and forward protocol compatibility is
31 usually not feasible.
32
34 Common Options:
35 -v Print version info and exit.
36 -h Print usage info and exit.
38 -f Keep running in foreground.
40 -4 Force/allow only IPv4 DNS queries
42 -6 Force/allow only IPv6 DNS queries
44 -u user
46 Drop privileges and run as user 'user' after setting up tunnel.
47 -t chrootdir
49 Chroot to 'chrootdir' after setting up tunnel.
50 -d device
52 Use the TUN device 'device' instead of the normal one, which is
53 dnsX on Linux and otherwise tunX. On Mac OS X 10.6, this can
54 also be utunX, which will attempt to use an utun device built
55 into the OS.
56 -P password
58 Use 'password' to authenticate. If not used, stdin will be used
59 as input. Only the first 32 characters will be used.
60 -z context
62 Apply SELinux 'context' after initialization.
63 -F pidfile
65 Create 'pidfile' and write process id in it.
66 Server Options:
68 -c Disable checking the client IP address on all incoming requests.
69 By default, requests originating from non-matching IP addresses
70 will be rejected, however this will cause problems when requests
71 are routed via a cluster of DNS servers.
72 -s Don't try to configure IP address or MTU. This should only be
74 used if you have already configured the device that will be
75 used.
76 -D Increase debug level. Level 1 prints info about each RX/TX
78 packet. Implies the -f option. On level 2 (-DD) or higher, DNS
79 queries will be printed literally. When using Base128 upstream
80 encoding, this is best viewed as ISO Latin-1 text instead of
81 (illegal) UTF-8. This is easily done with : "LC_ALL=C luit
82 iodined -DD ..." (see luit(1)).
83 -m mtu Set 'mtu' as mtu size for the tun device. This will be sent to
85 the client on login, and the client will use the same mtu for
86 its tun device. Default 1130. Note that the DNS traffic will
87 be automatically fragmented when needed.
88 -l external|listen_ip4
90 Make the server listen only on 'listen_ip4' for incoming IPv4
91 requests. By default, incoming requests are accepted from all
92 interfaces (0.0.0.0). A domain name can be used as argument -
93 use one with only one A record. If listen_ip4 is 'external',
94 iodined will use the opendns.com DNS service to retrieve the ex‐
95 ternal IP of the host and use that as listen address.
96 -L listen_ip6
98 Make the server listen only on 'listen_ip6' for incoming IPv6
99 requests. By default, incoming requests are accepted from all
100 interfaces (::). A domain name can be used as argument - use
101 one with only one AAAA record.
102 -p port
104 Make the server listen on 'port' instead of 53 for traffic. If
105 'listen_ip4' does not include localhost, this 'port' can be the
106 same as 'dnsport'. Note: You must make sure the dns requests
107 are forwarded to this port yourself.
108 -n auto|external_ip
110 The IP address to return in NS responses. Default is to return
111 the address used as destination in the query. If external_ip is
112 'auto', iodined will use the opendns.com DNS service to retrieve
113 the external IP of the host and use that for NS responses.
114 -b dnsport
116 If this port is specified, all incoming requests not inside the
117 tunnel domain will be forwarded to this port on localhost, to be
118 handled by a real dns. If 'listen_ip' does not include local‐
119 host, this 'dnsport' can be the same as 'port'. Note: The for‐
120 warding is not fully transparent, and not advised for use in
121 production environments.
122 -i max_idle_time
124 Make the server stop itself after max_idle_time seconds if no
125 traffic have been received. This should be combined with sys‐
126 temd or upstart on demand activation for being effective.
127 Server Arguments:
129 tunnel_ip[/netmask]
130 This is the server's ip address on the tun interface. The client
131 will be given the next ip number in the range. It is recommended
132 to use the 10.0.0.0 or 172.16.0.0 ranges. The default netmask is
133 /27, can be overridden by specifying it here. Using a smaller
134 network will limit the number of concurrent users.
135 topdomain
137 The dns traffic is expected to arrive as queries for subdomains
138 under 'topdomain'. This is normally a subdomain to a domain you
139 own. Use a short domain name to get better throughput. This ar‐
140 gument must be the same on both the client and the server.
141 Queries for domains other than 'topdomain' will be forwarded
142 when the -b option is given, otherwise they will be dropped. The
143 topdomain can start with '*' which will allow all domains ending
144 with the same suffix.
145
147 See the README file for both a quick test scenario, and a detailed de‐
148 scription of real-world deployment.
149
151 Login is a relatively secure challenge-response MD5 hash, with the
152 password never passing the wire. However, all other data is NOT en‐
153 crypted in any way. The DNS traffic is also vulnerable to replay, in‐
154 jection and man-in-the-middle attacks, especially when iodined is used
155 with the -c option. Use of ssh or vpn tunneling is strongly recom‐
156 mended. On both server and client, use iptables, pf or other firewalls
157 to block all traffic coming in from the tun interfaces, except to the
158 used ssh or vpn ports.
159
161 IODINE_PASS
162 If the environment variable IODINE_PASS is set, iodine will use the
163 value it is set to as password instead of asking for one. The -P option
164 still has precedence.
165 IODINED_PASS
167 If the environment variable IODINED_PASS is set, iodined will use the
168 value it is set to as password instead of asking for one. The -P option
169 still has precedence.
170
172 The README file in the source distribution contains some more elaborate
173 information.
174
176 File bugs at https://github.com/yarrick/iodine
177
179 Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
180 contributions by Anne Bezemer.
181User Manuals APR 2023 IODINE(8)