Content-type: text/html; charset=UTF-8

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of IODINE</TITLE>
</HEAD><BODY>
<H1>IODINE</H1>
Section: Maintenance Commands (8)<BR>Updated: APR 2023<BR><A HREF="#index">Index</A>
<A HREF="/man/man2html">Return to Main Contents</A><HR>

<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

iodined - tunnel IPv4 over DNS
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<P>
<B>iodined [-v]</B>

<P>
<B>iodined [-h]</B>

<P>
<B>iodined [-4] [-6] [-c] [-s] [-f] [-D] [-u</B>

<I>user</I>

<B>] [-t</B>

<I>chrootdir</I>

<B>] [-d</B>

<I>device</I>

<B>] [-m</B>

<I>mtu</I>

<B>] [-l</B>

<I>listen_ip4</I>

<B>] [-L</B>

<I>listen_ip6</I>

<B>] [-p</B>

<I>port</I>

<B>] [-n</B>

(
<B>auto</B>

|
<I>external_ip</I>

)
<B>] [-b</B>

<I>dnsport</I>

<B>] [-P</B>

<I>password</I>

<B>] [-z</B>

<I>context</I>

<B>] [-F</B>

<I>pidfile</I>

<B>] [-i</B>

<I>max_idle_time</I>

<B>]</B>

<I>tunnel_ip</I>

<B>[</B>

<I>/netmask</I>

<B>]</B>

<I>topdomain</I>

<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<B>iodine</B>

lets you tunnel IPv4 data through a DNS
server. This can be useful in situations where Internet access is firewalled,
but DNS queries are allowed. It needs a TUN/TAP device to operate. The
bandwidth is asymmetrical,
with a measured maximum of 680 kbit/s upstream and 2.3 Mbit/s
downstream in a wired LAN test network.
Realistic sustained throughput on a Wifi network using a carrier-grade
DNS cache has been measured at some 50 kbit/s upstream and over 200 kbit/s
downstream.
<B>iodine</B>

is the client application,
<B>iodined</B>

is the server.
<P>
Note: server and client are required to speak the exact same protocol. In most
cases, this means running the same iodine version. Unfortunately, implementing
backward and forward protocol compatibility is usually not feasible.
<A NAME="lbAE">&nbsp;</A>
<H2>OPTIONS</H2>

<DL COMPACT>
<DT><B>-v</B>

<DD>
Print version info and exit.
<DT><B>-h</B>

<DD>
Print usage info and exit.
<DT><B>-f</B>

<DD>
Keep running in foreground.
<DT><B>-4</B>

<DD>
Force/allow only IPv4 DNS queries
<DT><B>-6</B>

<DD>
Force/allow only IPv6 DNS queries
<DT><B>-u user</B>

<DD>
Drop privileges and run as user 'user' after setting up tunnel.
<DT><B>-t chrootdir</B>

<DD>
Chroot to 'chrootdir' after setting up tunnel.
<DT><B>-d device</B>

<DD>
Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
and otherwise tunX. On macOS 10.6 or newer, this can also be utunX, which will
attempt to use an utun device built into the OS.
<DT><B>-P password</B>

<DD>
Use 'password' to authenticate. If not used,
<B>stdin</B>

will be used as input. Only the first 32 characters will be used.
<DT><B>-z context</B>

<DD>
Apply SELinux 'context' after initialization.
<DT><B>-F pidfile</B>

<DD>
Create 'pidfile' and write process id in it.
<P>
<DT><B>-c</B>

<DD>
Disable checking the client IP address on all incoming requests.
By default, requests originating from non-matching IP addresses will be
rejected, however this will cause problems when requests are routed
via a cluster of DNS servers.
<DT><B>-s</B>

<DD>
Don't try to configure IP address or MTU.
This should only be used if you have already configured the device that will be
used.
<DT><B>-D</B>

<DD>
Increase debug level. Level 1 prints info about each RX/TX packet.
Implies the
<B>-f</B>

option.
On level 2 (-DD) or higher, DNS queries will be printed literally.
When using Base128 upstream encoding, this is best viewed as
ISO Latin-1 text instead of (illegal) UTF-8.
This is easily done with : &quot;LC_ALL=C luit iodined -DD ...&quot;
(see <A HREF="/man/man2html?1+luit">luit</A>(1)).
<DT><B>-m mtu</B>

<DD>
Set 'mtu' as mtu size for the tun device.
This will be sent to the client on login, and the client will use the same mtu
for its tun device.  Default 1130.  Note that the DNS traffic will be
automatically fragmented when needed.
<DT><B>-l external|listen_ip4</B>

<DD>
Make the server listen only on 'listen_ip4' for incoming IPv4 requests.
By default, incoming requests are accepted from all interfaces (0.0.0.0).
A domain name can be used as argument - use one with only one A record.
If listen_ip4 is 'external', iodined will use the opendns.com DNS service to
retrieve the external IP of the host and use that as listen address.
<DT><B>-L listen_ip6</B>

<DD>
Make the server listen only on 'listen_ip6' for incoming IPv6 requests.
By default, incoming requests are accepted from all interfaces (::).
A domain name can be used as argument - use one with only one AAAA record.
<DT><B>-p port</B>

<DD>
Make the server listen on 'port' instead of 53 for traffic.
If 'listen_ip4' does not include localhost, this 'port' can be the same
as 'dnsport'.
<B>Note:</B>

You must make sure the dns requests are forwarded to this port yourself.
<DT><B>-n auto|external_ip</B>

<DD>
The IP address to return in NS responses. Default is to return the address used
as destination in the query.
If external_ip is 'auto', iodined will use the opendns.com DNS service to
retrieve the external IP of the host and use that for NS responses.
<DT><B>-b dnsport</B>

<DD>
If this port is specified, all incoming requests not inside the tunnel domain
will be forwarded to this port on localhost, to be handled by a real dns.
If 'listen_ip' does not include localhost, this 'dnsport' can be the
same as 'port'.
<B>Note:</B>

The forwarding is not fully transparent, and not advised for use
in production environments.
<DT><B>-i max_idle_time</B>

<DD>
Make the server stop itself after max_idle_time seconds if no traffic have been received.
This should be combined with systemd or upstart on demand activation for being effective.
</DL>
<A NAME="lbAF">&nbsp;</A>
<H3>Arguments:</H3>

<DL COMPACT>
<DT><B>tunnel_ip[/netmask]</B>

<DD>
This is the server's ip address on the tun interface. The client will be
given the next ip number in the range. It is recommended to use the
10.0.0.0 or 172.16.0.0 ranges. The default netmask is /27, can be overridden
by specifying it here. Using a smaller network will limit the number of
concurrent users.
<DT><B>topdomain</B>

<DD>
The dns traffic is expected to arrive as queries for
subdomains under 'topdomain'. This is normally a subdomain to a domain you
own. Use a short domain name to get better throughput. This argument must be
the same on both the client and the server. Queries for domains other
than 'topdomain' will be forwarded when the -b option is given, otherwise
they will be dropped. The topdomain can start with '*' which will allow all
domains ending with the same suffix.
</DL>
<A NAME="lbAG">&nbsp;</A>
<H2>EXAMPLES</H2>

See the README file for both a quick test scenario, and a detailed description
of real-world deployment.
<A NAME="lbAH">&nbsp;</A>
<H2>SECURITY</H2>

Login is a relatively secure challenge-response MD5 hash, with the
password never passing the wire.
However, all other data is
<B>NOT</B>

encrypted in any way. The DNS traffic is also vulnerable to replay,
injection and man-in-the-middle attacks, especially when iodined is used
with the -c option. Use of ssh or vpn tunneling is strongly recommended.
On both server and client, use
<I>iptables</I>,

<I>pf</I>

or other firewalls to block all traffic coming in from the tun interfaces,
except to the used ssh or vpn ports.
<P>
<A NAME="lbAI">&nbsp;</A>
<H2>ENVIRONMENT</H2>

<A NAME="lbAJ">&nbsp;</A>
<H3>IODINED_PASS</H3>

If the environment variable
<B>IODINED_PASS</B>

is set, iodined will use the value it is set to as password instead of asking
for one. The
<B>-P</B>

option still has precedence.
<A NAME="lbAK">&nbsp;</A>
<H2>SEE ALSO</H2>

<B><A HREF="/man/man2html?8+iodine">iodine</A></B>(8)

<P>

The README file in the source distribution contains some more elaborate
information.
<A NAME="lbAL">&nbsp;</A>
<H2>BUGS</H2>

File bugs at <A HREF="https://github.com/yarrick/iodine">https://github.com/yarrick/iodine</A>
<A NAME="lbAM">&nbsp;</A>
<H2>AUTHORS</H2>

Erik Ekman &lt;<A HREF="mailto:yarrick@kryo.se">yarrick@kryo.se</A>&gt; and Bjorn Andersson &lt;<A HREF="mailto:flex@kryo.se">flex@kryo.se</A>&gt;. Major
contributions by Anne Bezemer.
<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">OPTIONS</A><DD>
<DL>
<DT><A HREF="#lbAF">Arguments:</A><DD>
</DL>
<DT><A HREF="#lbAG">EXAMPLES</A><DD>
<DT><A HREF="#lbAH">SECURITY</A><DD>
<DT><A HREF="#lbAI">ENVIRONMENT</A><DD>
<DL>
<DT><A HREF="#lbAJ">IODINED_PASS</A><DD>
</DL>
<DT><A HREF="#lbAK">SEE ALSO</A><DD>
<DT><A HREF="#lbAL">BUGS</A><DD>
<DT><A HREF="#lbAM">AUTHORS</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 19:13:44 GMT, October 25, 2026
</BODY>
</HTML>