Man Linux: Main Page and Category List


       iodine, iodined - tunnel IPv4 over DNS


       iodine [-v]

       iodine [-h]

       iodine  [-f]  [-u  user ] [-P password ] [-m fragsize ] [-t chrootdir ]
       [-d device ] [-m fragsize ] [ nameserver ] topdomain

       iodined [-v]

       iodined [-h]

       iodined [-c] [-s] [-f] [-D] [-u user ] [-t chrootdir ] [-d device ] [-m
       mtu  ]  [-l  listen_ip ] [-p port ] [-n external ip ] [-b dnsport ] [-P
       password ] tunnel_ip [ /netmask ] topdomain


       iodine 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  limited  upstream and up to 1 Mbit/s
       downstream.  iodine is the client application, iodined is the server.


   Common Options:
       -v     Print version info and exit.

       -h     Print usage info and exit.

       -f     Keep running in foreground.

       -u user
              Drop privileges and run as user ’user’ after setting up  tunnel.

       -t chrootdir
              Chroot to ’chrootdir’ after setting up tunnel.

       -d device
              Use  the TUN device ’device’ instead of the normal one, which is
              dnsX on Linux and otherwise tunX.

       -P password
              Use ’password’ to authenticate. If not used, stdin will be  used
              as input. Only the first 32 characters will be used.

   Client Options:
       -m fragsize
              Maximum  downstream  fragsize.  Not  setting this will cause the
              client to probe the maximum accepted downstream packet size.

   Server Options:
       -c     Disable checks on client IP on all incoming requests.

       -s     Don’t try to configure IP address or MTU. This  should  only  be
              used  if  you  have  already  configured the device that will be

       -D     Increase debug level. Level  1  prints  info  about  each  RX/TX

       -m mtu Set  ’mtu’  as mtu size for the tunnel device. This will be sent
              to the client on connect, and the client will use the same  mtu.

       -l listen_ip
              Make the server listen only on ’listen_ip’ instead of on
              for incoming connections.

       -p port
              Make the server listen on ’port’  instead  of  53  for  traffic.
              Note:  You must make sure the dns requests are forwarded to this
              port yourself.

       -n external ip
              The IP address to return in NS responses. Default is  to  return
              the address used as destination in the query.

       -b dnsport
              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.

   Client Arguments:
              The  nameserver to use to relay the dns traffic. This can be any
              relaying nameserver  or the ip  number  of  the  server  running
              iodined  if  reachable.   This  argument is optional, and if not
              specified a nameserver will be read  from  the  /etc/resolv.conf

              The  dns  traffic  will  be  sent  as  querys  of  type NULL for
              subdomains under ´topdomain’. This is normally a subdomain to  a
              domain   you  own.  Use  a  short  domain  name  to  get  better
              throughput. If  nameserver  is  the  iodined  server,  then  the
              topdomain  can  be chosen freely. This argument must be the same
              on both the client and the server.

   Server Arguments:
              This is the servers ip address  on  the  tunnel  interface.  The
              client  will  be  given  the  next ip number in the range. It is
              recommended to  use  the  or  ranges.  The
              default netmask is /27, can be overridden by specifying it here.
              Using a smaller network will  limit  the  number  of  concurrent

              The  dns  traffic  will is expected to be sent as querys of type
              NULL 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.


       Try it out within your own LAN! Follow these simple steps:

       - On your server, run: ./iodined -f test.asdf
              (If  you  already use the network, use another internal
              net like

       - Enter a password

       - On the client, run: ./iodine -f test.asdf
              (Replace with the server’s ip address)

       - Enter the same password

       - Now the client has the tunnel ip and the server has

       - Try pinging each other through the tunnel

       - Done! :)

       To actually use it through a relaying nameserver, see below.

   Full setup:
       Server side:
              To use this tunnel, you need control over a  real  domain  (like
    ,  and  a  server  with  a public IP number. If the
              server already runs a DNS server, change the listening port  and
              then  use the -b option to let iodined forward the DNS requests.
              Then, delegate a subdomain (say,  to  the
              server.  If  you use BIND for the domain, add these lines to the
              zone file (replace with your server ip):

              tunnel1host    IN   A
              tunnel1        IN   NS

              Now any DNS querys for domains ending with
              will  be  sent  to your server. Start iodined on the server. The
              first argument is the tunnel IP address (like  and
              the    second   is   the   assigned   domain   (in   this   case
     The -f argument will keep iodined running
              in  the foreground, which helps when testing. iodined will start
              a virtual interface, and 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.

       Client side:
              All  the  setup  is  done,  just start iodine. It also takes two
              arguments, the first is the local relaying DNS  server  and  the
              second  is  the  domain  used  (  If  DNS
              queries are allowed to any computer,  you  can  use  the  tunnel
              endpoint  (example: or as
              the first argument. The tunnel interface will get an IP close to
              the  servers  (in  this  case and a suitable MTU.
              Enter the same password as on the server either by  argument  or
              after the client has started. Now you should be able to ping the
              other end of the tunnel from either side.

              The normal case is to route all traffic through the DNS  tunnel.
              To do this, first add a route to the nameserver you use with the
              default gateway as gateway. Then  replace  the  default  gateway
              with the servers IP address within the DNS tunnel, and configure
              the server to do NAT.

       MTU issues:
              These issues should be solved now, with automatic  fragmentation
              of  downstream  packets.  There should be no need to set the MTU
              explicitly on the server.


       File bugs at


       Erik Ekman <> and Bjorn Andersson <>