Create a gist now

Instantly share code, notes, and snippets.


Iodine Setup

Table of Contents


I'm using Arch Linux on both my server and client, so installation is as simple as running pacman -S iodine on both. Iodine packages are available for different distributions as well; however, according to the documentation, both the client and server should use the same version. If your server and client are using different distributions, you may need to install iodine from source.

For more information about installation, see

Domain Setup

In order to use iodine, you will need access to the DNS records for a domain. I'll be using You will need to choose 2 subdomains: one for the DNS lookups that iodine will send, and one for the nameserver record that will allow you to access the iodine server from a restricted environment.

Assuming that your iodine server has IP address, set up the following records:

  • Add an A record for pointing to
  • Add an NS record for pointing to

Running the Server

To start the iodine server, run the following command as root:

# iodined -c -P password -f

The -c flag disables checking the client IP address:

-c 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.

The -f flag keeps iodined running in the foreground-- this is handy for observing the output while you're getting things set up and testing the connection.

Replace password with a password of your choice. The client will need to provide this password in order to connect.

I picked an address of for the server on the virtual network. You can change this to a different address if needed, as long as the address range won't conflict with the real network that the client or server is connected to.

The last parameter is the subdomain that you picked which has an NS record pointing to the iodine server.

Connecting the Client

To connect to your iodine server, run the following command as root:

# iodine -f

Once again, the -f flag is used to keep iodine in the foreground so we can observe the output. Iodine should print some informational messages while it is starting up.

After the connection is established, you should be able to ping (or whichever address you chose when running the server). You can also SSH into the server by using ssh user@

For internet access, you can set up an SSH tunnel, but for arbitrary applications to use the DNS tunnel, you will need to set up routing information to route IP traffic through the tunnel.

Routing: Server

Before you can route traffic through the DNS tunnel, the server needs to be configured for NAT. You can do this with a few simple commands:

# echo 1 > /prov/sys/net/ipv4/ip_forward
# iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
# iptables -A FORWARD -i eth0 -o dns0 -m state --state RELATED,ESTABLISHED
# iptables -A FORWARD -i dns0 -o eth0 -j ACCEPT

You may need to replace eth0 with the appropriate network adapter on your server.

Routing: Client

Now that the server is configured for NAT, we can establish a route on the client system to use it. For this I will make the following assumptions:

  • The IP address of the iodine server is
  • The default gateway for the client's network connection is
  • The virtual network address of the iodine server is

You will need to substitute these for the actual values of your configuration.

The gist of it is that we need to set up a route to the iodine server over the real network, then replace the default route with a route through the DNS tunnel. You can do this with the following commands:

# route add gw
# ip route del default via
# ip route add default via

If all is well, you should be able to access the internet. You can check that your traffic is being tunneled by visiting a website that displays your IP address, e.g. curl


  • Iodine requires the TUN kernel module. If you are running the server on an OpenVZ server, you may need to contact your host or check the control panel to see if TUN is enabled.
  • Traffic is not encrypted through the tunnel. If you desire secure communication, you may wish to use an encrypted VPN within the tunnel.
  • IP over DNS is pretty slow. You should only use this if the ordinary network is unusable.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment