Bypassing Captive Portals/Airport Pay Restrictions with Iodine on a Debian VPS Guide

This guide is intended for those who want to set up a Iodine on a Debian or Ubuntu VPS. Lots of time has been spent through trial and error trying to figure it out. Insight and portions of this guide have been taken

Server Setup:

1. Run one of the following scripts on your server below.
SSH into your server/VPS and run one of the below scripts:

1a. Ubuntu only installation!

cat >> /etc/apt/sources.list <<END
deb natty main restricted universe
apt-get update
apt-get -t natty install iodine
sed -i '$d' /etc/apt/sources.list

1b. Debian only installation!

cat >> /etc/apt/sources.list <<END
deb sid main
apt-get update
apt-get -t sid install iodine
sed -i '$d' /etc/apt/sources.list

2. Set up your DNS:
I used Namecheap FreeDNS for this example (as it requires no software installation, nor resources).
Point your domain (any domain is fine, even a free one like or .tk) to NameCheap’s FreeDNS service. The nameservers are: settings page

3. Point your DNS to your VPS:
You must fill in the IP Address box to point to your VPS/Linux server
The hostname “iodine” must point to your domain. For example it would be “” as a NS Record.

You can check if your DNS settings are valid at

Enter in the A record into the box (the one that is

NameCheap DNS page

4. Launch iodined on your server:
Make sure you have TUN/TAP enabled with your VPS provider, and also that nothing else is using it (eg. OpenVPN)

Launch iodined through SSH with a command like this:

iodined -c -f -P yourpasswordhere

Make sure to replace the password “yourpasswordhere” with your own. You must use this password for the client as well. Also make sure to replace the domain to your own.

It should return an output like this:

Opened dns0
Setting IP of dns0 to
Setting MTU of dns0 to 1130
Opened UDP socket
Listening to dns for domain

Client Setup:

5. Install the TAP Adapter:
Go to and download the newest installer for Windows. While going through the installation wizard, make sure you only select the line that says “TAP Virtual Ethernet Adapter” as shown below.

OpenVPN Install page

6. Download the Iodine client to your computer:
The current version is 0.6.0-rc1. You can find newer versions the project homepage in the future.

7. Extract the Iodine client:
You can use a program like 7-zip. Extract it to your desktop for ease of access.

8. Connect your computer to your server with iodine:
Open up the command prompt and type in:

iodine -f -P yourpasswordhere youriphere

Make sure you have changed directory to the iodine folder, and make sure you have replaced the relevant password, IP, and domain to match your server settings.

The console output should look something like this:
Opening device Local Area Connection 2
Opened UDP socket
Opened UDP socket
Opened UDP socket
Sending DNS queries for to
Autodetecting DNS query type (use -T to override).
Using DNS type NULL queries
Version ok, both using protocol v 0x00000502. You are user #0
Enabling interface 'Local Area Connection 2'
Setting IP of interface 'Local Area Connection 2' to (can take a few seconds)...

Server tunnel IP is
Testing raw UDP data to the server (skip with -r)
Server is at, trying raw login: OK
Sending raw traffic directly to
Connection setup complete, transmitting data.

9. Test if the tunnel works:
Open another command prompt and type in the following:

ping /t

If you get ping responses, then everything is good.

10. Tunnel through SSH (easier than using a web proxy):
Get an SSH client like KiTTY (it’s a revamped version of PuTTY).
Extract KiTTY and add a SSH Tunnel using the settings shown below. Make sure to hit “Add”.

KiTTY settings page

Connect to IP and enter in your login details that you usually use.

11. Get FoxyProxy for Mozilla Firefox or Proxy Switchy for Google Chrome.

Enter in the proxy info as shown below:
FoxyProxy settings page

Set your browser to connect through SSH, and check your IP address at

Special thanks to InsDel for all the help. Without you, this guide wouldn’t be up :).

Let me know if it works, or if you have any suggestions in the comments!

Bookmark the permalink.
  • tom

    This is great information.

    I am stuck at the DNS setup stage.

    I understand that I have to create my DNS server somehow, and point to the DNS inquiry to the domain name. I am using a Godaddy’s account, and I am not so sure how to direct the DNS traffic to a sub domain in my VPS.

    Any information would be much appreciated.

  • admin

    Thank you for the comment.

    You must have this for your DNS setup:

    1. – A record – point to your VPS/server
    2. – NS record – point to

  • John

    Hello, thank you for this guide.

    I have a problem, everything is setup correctly and I get no error messages. Only that I can not ping through the tunnel, or get network access. What could this depend on?

    • admin

      So iodine has connected successfully? Does the TUN/TAP adapter show that it is connected?

      • John

        The Windows adapter I use on the client shows that it is connected, it both receives an send packets. Only that it has no network access.

        On the server I get the right output as well.
        “Opened dns0
        Setting IP of dns0 to
        Setting MTU of dns0 to 1130
        Opened UDP socket
        Listening to dns for domain”

        Although, I am using Debian on the server, and I believe that TUN/TAP is enabled. I’m not quite sure, any suggestion on how I enable it/install a bridge to it or something. I have it enabled in the config file as CONFIG_TUN=y.

        • admin

          Are you using it on OpenVZ? You can check if TUN/TAP is enabled on OpenVZ with this command:
          root@test:~# cat /dev/net/tun
          cat: /dev/net/tun: File descriptor in bad state

          If you’re not using OpenVZ, try this out:

          • x-men

            CommanderWaffles  do u have such tutorial on DNS2TCP tunneling?I hear its faster than iodine.

          • CommanderWaffles

            Sorry, I’m not familiar with DNS2TCP. If you figure it out, you can edit my script as a base.

          • x-men

            i need your contact so we could work on the DNS2TCP n post it .I heard its faster than iodine.I ll be looking forward to it

  • Pingback: 有DNS的地方就能上网 | 天蓝色的彼岸()

  • Ramson

    I have exactly the same setup. (I have a purchased domain)
    Do I have to use bind9 or do I have to stop bind9 completly? (Or any dns)When I try the test at it states an error due my server did not answerd.Really, I don’t get that, it’s too complicated.

    • Anonymous

      You don’t need bind9 running as Namecheap will do all the DNS work. It takes some trial and error unfortunately.

  • Yan

    Nice tutorial… tried this between an ubuntu 10.04 box on home router, as the server, with compiled latest 0.6 rc1 to have same version as windows binaries (client is an XP EeePC901 netbook)…

    Setup DNS is a bit different, as I already have a dyndns account (but dyndns does not provide free NS subdomains) I have setup a NS subdomain at that is directly linked to my “historical” dyndns one (that is supported by my adsl box for IP refresh).

    Test page you mention, provided iodined is launched on server side is OK.

    On XP client side: it stops when trying to autodetect DNS query type…

    No clue on the reason. Did you have a setup for tun windows driver, as wireless connection is seen as “limited” by windows (connected to hot-spot, but no internet connectivity) in such case?

    • Anonymous

      You have to use the TUN driver as shown before. It won’t work without that.

  • John

    Thank you for the great tutorial! =)

  • John

    nice really save me a lot of time.thank you!

  • peterson

    i dig my tunnel as everything you direct,but got out error when using iodine online check :”Analyzing DNS setup for tunnel domain ‘’… (might take some time)

    Looking for nameserver for got (at
    Looking for nameserver for got (at
    Resolving delegation of at… not known.

    Error: The tunnel name is not delegated to any host according to nameserver”
    any hint?thank you!

    • Anonymous

      Do you have the iodine daemon running?

      • Incandle

        yes I do.

  • Pingback: 学习笔记 » 通过iodine实现DNS tunnel(DNS隧道)()

  • x-men


  • tismon

    What about throwing Tomato or DD-WRT into the mix as your SSH server? How can one connect through iodine on a server to the router?

    • CommanderWaffles

      I believe you would require iodine to run on your router.

  • Pingback: iodine – IP over DNS « - Freedom, Electronics and Tech()

  • Pingback: DNS隧道架设详解 | GERFALKE()

  • Pingback: 通过iodine实现DNS tunnel(DNS隧道) | GERFALKE()

  • maxx

    pls upload total process vedio

  • porfavor si pudieran ayudarme no tengo la posibilidad de un servidor si pudieran ayudarme y prestarme un servicio ya listo estoy en cuba y no tengo salida tengo los dns nadamas. porfavoe espero respuesta.

  • Pingback: 通过iodine实现DNS tunnel(DNS隧道) | mobi′s Blog()

  • Ive been using dns and icmp tunnels for years to get free cellular data via rooted android devices, tetherable…. used over 100gb in december 🙂

    • Yves Fontaine

      please how to speed up it