iodine: tunnel IPv4 data through a DNS server
iodine lets you tunnel IPv4 data through a DNS server. This can be usable in different situations where internet access is firewalled, but DNS queries are allowed.
It runs on Linux, Mac OS X, FreeBSD, NetBSD, OpenBSD and Windows and needs a TUN/TAP device. The bandwidth is asymmetrical with limited upstream and up to 1 Mbit/s downstream.
Compared to other DNS tunnel implementations, iodine offers:
- Higher performance
- iodine uses the NULL type that allows the downstream data to be sent without encoding. Each DNS reply can contain over a kilobyte of compressed payload data.
- Portability
- iodine runs on many different UNIX-like systems as well as on Win32. Tunnels can be set up between two hosts no matter their endianness or operating system.
- Security
- iodine uses challenge-response login secured by MD5 hash. It also filters out any packets not coming from the IP used when logging in.
- Less setup
- iodine handles setting IP number on interfaces automatically, and up to 16 users can share one server at the same time. Packet size is automatically probed for maximum downstream throughput.
Install
Iodine has no configure script. There are two optional features for Linux (SELinux and systemd support) that will be enabled automatically if the relevant header files are found in /usr/include. (See script at ./src/osflags)
git clone https://github.com/yarrick/iodine.git
Run make to compile the server and client binaries. Run make install to copy binaries and manpage to the destination directory. Run make test to compile and run the unit tests. (Requires the check library)
QUICKSTART
Try it out on your own LAN! Follow these simple steps:
- On your server, run: ./iodined -f 10.0.0.1 test.com. If you already use the 10.0.0.0 network, use another internal net like 172.16.0.0.
- Enter a password.
- On the client, run: ./iodine -f -r 192.168.0.1 test.com. Replace 192.168.0.1 with your server’s ip address.
- Enter the same password.
- Now the client has the tunnel ip 10.0.0.2 and the server has 10.0.0.1.
- Try pinging each other through the tunnel.
- Done! 🙂
To actually use it through a relaying nameserver, see below.
HOW TO USE
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.
Server side
To use this tunnel, you need control over a real domain (like mydomain.com), and a server with a public IP address to run iodined on. If this server already runs a DNS program, change its listening port and then use iodined’s -b option to let iodined forward the DNS requests. (Note that this procedure is not advised in production environments because iodined’s DNS forwarding is not completely transparent.)
Then, delegate a subdomain (say, t1.mydomain.com) to the iodined server. If you use BIND for your domain, add two lines like these to the zone file:
t1 IN NS t1ns.mydomain.com. ; note the dot!
t1ns IN A 10.15.213.99
The NS line is all that’s needed to route queries for the t1 subdomain to the t1ns server. We use a short name for the subdomain, to keep as much space as possible available for the data traffic. At the end of the NS, line is the name of your iodined server. This can be any name, pointing anywhere, but in this case, it’s easily kept in the same zone file. It must be a name (not an IP address), and that name itself must have an A record (not a CNAME).
If your iodined server has a dynamic IP, use a dynamic DNS provider. Simply point the NS line to it, and leave the A line out:
t1 IN NS myname.mydyndnsprovider.com. ; note the dot!
Then reload or restart your nameserver program. Now any DNS queries for domains ending in t1.mydomain.com will be sent to your iodined server.
Finally, start iodined on your server. The first argument is the IP address inside the tunnel, which can be from any range that you don’t use yet (for example 192.168.99.1), and the second argument is the assigned domain (in this case t1.mydomain.com). Using the -f option will keep iodined running in the foreground, which helps when testing. iodined will open a virtual interface (“tun device”), and will also start listening for DNS queries on UDP port 53. Either enter a password on the commandline (-P pass) or after the server has started. Now everything is ready for the client.
If there is a chance you’ll be using an iodine tunnel from unexpected environments, start iodined with a -c option. Resulting commandline in this example situation:
./iodined -f -c -P secretpassword 192.168.99.1 t1.mydomain.com
Client side
All the setup is done, just start iodine. It takes one or two arguments, the first is the local relaying DNS server (optional) and the second is the domain you used (t1.mydomain.com). If you don’t specify the first argument, the system’s current DNS setting will be consulted.
If DNS queries are allowed to any computer, you can directly give the iodined server’s address as first argument (in the example: t1ns.mydomain.com or 10.15.213.99). In that case, it may also happen that any traffic is allowed to the DNS port (53 UDP) of any computer. Iodine will detect this, and switch to raw UDP tunneling if possible. To force DNS tunneling, in any case, use the -r option (especially useful when testing within your own network).
The client’s tunnel interface will get an IP close to the server’s (in this case 192.168.99.2 or .3 etc.) and a suitable MTU. Enter the same password as on the server either as commandline option or after the client has started. Using the -f option will keep the iodine client running in the foreground.
Resulting commandline in this example situation, adding -r forces DNS tunneling even if raw UDP tunneling would be possible:
./iodine -f -P secretpassword t1.mydomain.com
From either side, you should now be able to ping the IP address on the other end of the tunnel. In this case, ping 192.168.99.1 from the iodine client, and 192.168.99.2 from the iodine server.
