1IODINE(8)                   System Manager's Manual                  IODINE(8)
2
3
4

NAME

6       iodine - tunnel IPv4 over DNS
7

SYNOPSIS

9       iodine [-v]
10
11       iodine [-h]
12
13       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
18
19

DESCRIPTION

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
30       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

OPTIONS

36   Common Options:
37       -v     Print version info and exit.
38
39       -h     Print usage info and exit.
40
41       -f     Keep running in foreground.
42
43       -u user
44              Drop privileges and run as user 'user' after setting up tunnel.
45
46       -t chrootdir
47              Chroot to 'chrootdir' after setting up tunnel.
48
49       -d device
50              Use the TUN device 'device' instead of the normal one, which  is
51              dnsX on Linux and otherwise tunX.
52
53       -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
57       -z context
58              Apply SELinux 'context' after initialization.
59
60       -F pidfile
61              Create 'pidfile' and write process id in it.
62
63   Client Options:
64       -4     Force IPv4 DNS queries
65
66       -6     Force IPv6 DNS queries
67
68       -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
73       -R rdomain
74              Use OpenBSD routing domain 'rdomain' for the DNS connection.
75
76       -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
81       -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
89       -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
104       -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
119       -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
127       -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

ENVIRONMENT

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

SEE ALSO

147       The README file in the source distribution contains some more elaborate
148       information.
149

BUGS

151       File bugs at http://dev.kryo.se/iodine/
152

AUTHORS

154       Erik  Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
155       contributions by Anne Bezemer.
156
157
158
159User Manuals                       JUN 2014                          IODINE(8)
Impressum