1IODINE(8) System Manager's Manual IODINE(8)
2
6 iodined - tunnel IPv4 over DNS
7
9 iodined [-v]
10 iodined [-h]
12 iodined [-c] [-s] [-f] [-D] [-u user ] [-t chrootdir ] [-d device ] [-m
14 mtu ] [-l listen_ip ] [-p port ] [-n ( auto | external_ip ) ] [-b
15 dnsport ] [-P password ] [-z context ] [-F pidfile ] [-i max_idle_time
16 ] tunnel_ip [ /netmask ] topdomain
17
19 iodined lets you tunnel IPv4 data through a DNS server. This can be
20 useful in situations where Internet access is firewalled, but DNS
21 queries are allowed. It needs a TUN/TAP device to operate. The band‐
22 width is asymmetrical, with a measured maximum of 680 kbit/s upstream
23 and 2.3 Mbit/s downstream in a wired LAN test network. Realistic sus‐
24 tained throughput on a Wifi network using a carrier-grade DNS cache has
25 been measured at some 50 kbit/s upstream and over 200 kbit/s down‐
26 stream. 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[d] 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 -u user
42 Drop privileges and run as user 'user' after setting up tunnel.
43 -t chrootdir
45 Chroot to 'chrootdir' after setting up tunnel.
46 -d device
48 Use the TUN device 'device' instead of the normal one, which is
49 dnsX on Linux and otherwise tunX.
50 -P password
52 Use 'password' to authenticate. If not used, stdin will be used
53 as input. Only the first 32 characters will be used.
54 -z context
56 Apply SELinux 'context' after initialization.
57 -F pidfile
59 Create 'pidfile' and write process id in it.
60 Server Options:
62 -c Disable checking the client IP address on all incoming requests.
63 By default, requests originating from non-matching IP addresses
64 will be rejected, however this will cause problems when requests
65 are routed via a cluster of DNS servers.
66 -s Don't try to configure IP address or MTU. This should only be
68 used if you have already configured the device that will be
69 used.
70 -D Increase debug level. Level 1 prints info about each RX/TX
72 packet. Implies the -f option. On level 2 (-DD) or higher, DNS
73 queries will be printed literally. When using Base128 upstream
74 encoding, this is best viewed as ISO Latin-1 text instead of
75 (illegal) UTF-8. This is easily done with : "LC_ALL=C luit
76 iodined -DD ..." (see luit(1)).
77 -m mtu Set 'mtu' as mtu size for the tun device. This will be sent to
79 the client on login, and the client will use the same mtu for
80 its tun device. Default 1130. Note that the DNS traffic will
81 be automatically fragmented when needed.
82 -l listen_ip
84 Make the server listen only on 'listen_ip' for incoming
85 requests. By default, incoming requests are accepted from all
86 interfaces.
87 -p port
89 Make the server listen on 'port' instead of 53 for traffic. If
90 'listen_ip' does not include localhost, this 'port' can be the
91 same as 'dnsport'. Note: You must make sure the dns requests
92 are forwarded to this port yourself.
93 -n auto|external_ip
95 The IP address to return in NS responses. Default is to return
96 the address used as destination in the query. If external_ip is
97 'auto', iodined will use externalip.net web service to retrieve
98 the external IP of the host and use that for NS responses.
99 -b dnsport
101 If this port is specified, all incoming requests not inside the
102 tunnel domain will be forwarded to this port on localhost, to be
103 handled by a real dns. If 'listen_ip' does not include local‐
104 host, this 'dnsport' can be the same as 'port'. Note: The for‐
105 warding is not fully transparent, and not advised for use in
106 production environments.
107 -i max_idle_time
109 Make the server stop itself after max_idle_time seconds if no
110 traffic have been received. This should be combined with sys‐
111 temd or upstart on demand activation for being effective.
112 Client Arguments:
114 nameserver
115 The nameserver to use to relay the dns traffic. This can be any
116 relaying nameserver or the server running iodined if reachable.
117 This field can be given as an IPv4/IPv6 address or as a host‐
118 name. This argument is optional, and if not specified a name‐
119 server will be read from the /etc/resolv.conf file.
120 topdomain
122 The dns traffic will be sent as queries for subdomains under
123 ´topdomain'. This is normally a subdomain to a domain you own.
124 Use a short domain name to get better throughput. If nameserver
125 is the iodined server, then the topdomain can be chosen freely.
126 This argument must be the same on both the client and the
127 server.
128 Server Arguments:
130 tunnel_ip[/netmask]
131 This is the server's ip address on the tun interface. The client
132 will be given the next ip number in the range. It is recommended
133 to use the 10.0.0.0 or 172.16.0.0 ranges. The default netmask is
134 /27, can be overridden by specifying it here. Using a smaller
135 network will limit the number of concurrent users.
136 topdomain
138 The dns traffic is expected to arrive as queries for subdomains
139 under 'topdomain'. This is normally a subdomain to a domain you
140 own. Use a short domain name to get better throughput. This
141 argument must be the same on both the client and the server.
142 Queries for domains other than 'topdomain' will be forwarded
143 when the -b option is given, otherwise they will be dropped.
144
146 See the README file for both a quick test scenario, and a detailed
147 description of real-world deployment.
148
150 Login is a relatively secure challenge-response MD5 hash, with the
151 password never passing the wire. However, all other data is NOT
152 encrypted in any way. The DNS traffic is also vulnerable to replay,
153 injection and man-in-the-middle attacks, especially when iodined is
154 used with the -c option. Use of ssh or vpn tunneling is strongly recom‐
155 mended. On both server and client, use iptables, pf or other firewalls
156 to block all traffic coming in from the tun interfaces, except to the
157 used ssh or vpn ports.
158
160 IODINED_PASS
161 If the environment variable IODINED_PASS is set, iodined will use the
162 value it is set to as password instead of asking for one. The -P option
163 still has precedence.
164
166 The README file in the source distribution contains some more elaborate
167 information.
168
170 File bugs at http://dev.kryo.se/iodine/
171
173 Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
174 contributions by Anne Bezemer.
175User Manuals JUN 2014 IODINE(8)