Provided by: iodine_0.7.0-10_amd64 bug

NAME

       iodine, iodined - tunnel IPv4 over DNS

SYNOPSIS

       iodine [-v]

       iodine [-h]

       iodine  [-4]  [-6]  [-f] [-r] [-u user ] [-P password ] [-m fragsize ] [-t chrootdir ] [-d
       device ] [-R rdomain ] [-m fragsize ] [-M namelen ]  [-z  context  ]  [-F  pidfile  ]  [-T
       dnstype ] [-O downenc ] [-L 0|1 ] [-I interval ] [ 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 ( auto | external_ip ) ] [-b  dnsport  ]  [-P  password  ]  [-z
       context ] [-F pidfile ] [-i max_idle_time ] tunnel_ip [ /netmask ] topdomain

DESCRIPTION

       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 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.  iodine is the client application, iodined
       is the server.

       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.

OPTIONS

   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.

       -z context
              Apply SELinux 'context' after initialization.

       -F pidfile
              Create 'pidfile' and write process id in it.

   Client Options:
       -4     Force IPv4 DNS queries

       -6     Force IPv6 DNS queries

       -r     Skip  raw  UDP  mode. If not used, iodine will try getting the public IP address of
              the iodined host and test if it is reachable directly. If it is,  traffic  will  be
              sent to the server instead of the DNS relay.

       -R rdomain
              Use OpenBSD routing domain 'rdomain' for the DNS connection.

       -m fragsize
              Force  maximum  downstream fragment size. Not setting this will cause the client to
              automatically probe the maximum accepted downstream fragment size.

       -M namelen
              Maximum length of upstream hostnames, default 255.  Usable range ca.  100  to  255.
              Use  this option to scale back upstream bandwidth in favor of downstream bandwidth.
              Also useful  for  DNS  servers  that  perform  unreliably  when  using  full-length
              hostnames,  noticeable  when fragment size autoprobe returns very different results
              each time.

       -T dnstype
              DNS request type override.  By default, autodetection will probe  for  working  DNS
              request  types,  and  will  select the request type that is expected to provide the
              most bandwidth.  However, it may turn out that a DNS relay imposes limits that skew
              the  picture,  which  may  lead  to an "unexpected" DNS request type providing more
              bandwidth.  In that case, use  this  option  to  override  the  autodetection.   In
              (expected)  decreasing  bandwidth order, the supported DNS request types are: NULL,
              PRIVATE, TXT, SRV, MX, CNAME and A (returning CNAME).  Note  that  SRV,  MX  and  A
              may/will  cause  additional lookups by "smart" caching nameservers to get an actual
              IP address, which may either slow down or fail completely. The  PRIVATE  type  uses
              value  65399  (in  the  'private  use' range) and requires servers implementing RFC
              3597.

       -O downenc
              Force downstream encoding type for all query type responses except  NULL.   Default
              is  autodetected,  but may not spot all problems for the more advanced codecs.  Use
              this option to override the autodetection.  Base32 is the  lowest-grade  codec  and
              should  always  work;  this is used when autodetection fails.  Base64 provides more
              bandwidth, but may not work on all nameservers.  Base64u is equal to Base64  except
              in using underscore ('_') instead of plus sign ('+'), possibly working where Base64
              does not.  Base128 uses high byte values (mostly accented  letters  in  iso8859-1),
              which  might work with some nameservers.  For TXT queries, Raw will provide maximum
              performance, but this will only work if the nameserver path  is  fully  8-bit-clean
              for responses that are assumed to be "legible text".

       -L 0|1 Lazy-mode  switch.   -L1  (default):  Use  lazy  mode  for improved performance and
              decreased latency.  A very small minority of DNS relays appears  to  be  unable  to
              handle  the  lazy  mode traffic pattern, resulting in no or very little data coming
              through.  The iodine client will detect this and try to switch back to legacy mode,
              but  this  may  not  always  work.  In these situations use -L0 to force running in
              legacy mode (implies -I1).

       -I interval
              Maximum interval between requests (pings) so that intermediate DNS servers will not
              time  out.  Default is 4 in lazy mode, which will work fine in most cases. When too
              many SERVFAIL errors occur, iodine will automatically reduce this  to  1.   To  get
              absolute  minimum DNS traffic, increase well above 4, but not so high that SERVFAIL
              errors start to occur.  There are some DNS relays with very small timeouts, notably
              dnsadvantage.com  (ultradns),  that  will  give SERVFAIL errors even with -I1; data
              will still get trough, and these errors can be ignored.  Maximum  useful  value  is
              59, since iodined will close a client's connection after 60 seconds of inactivity.

   Server Options:
       -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.

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

       -D     Increase debug level. Level 1 prints info about each RX/TX packet.  Implies the  -f
              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 : "LC_ALL=C luit iodined -DD ..."  (see
              luit(1)).

       -m mtu 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.

       -l listen_ip
              Make the server listen only on 'listen_ip'  for  incoming  requests.   By  default,
              incoming requests are accepted from all interfaces.

       -p port
              Make  the  server  listen on 'port' instead of 53 for traffic.  If 'listen_ip' does
              not include localhost, this 'port' can be the same as 'dnsport'.   Note:  You  must
              make sure the dns requests are forwarded to this port yourself.

       -n auto|external_ip
              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
              externalip.net web service to retrieve the external IP of the host and use that for
              NS responses.

       -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.  If
              'listen_ip' does not include localhost, this 'dnsport' can be the same  as  'port'.
              Note:  The  forwarding  is  not  fully  transparent,  and  not  advised  for use in
              production environments.

       -i max_idle_time
              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.

   Client Arguments:
       nameserver
              The nameserver to use to relay the dns traffic. This can be any relaying nameserver
              or the server running iodined if reachable. This field can be given as an IPv4/IPv6
              address or as a hostname. This  argument  is  optional,  and  if  not  specified  a
              nameserver will be read from the /etc/resolv.conf file.

       topdomain
              The  dns  traffic will be sent 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.  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:
       tunnel_ip[/netmask]
              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.

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

EXAMPLES

       See  the  README  file for both a quick test scenario, and a detailed description of real-
       world deployment.

SECURITY

       Login is a relatively secure challenge-response MD5 hash, with the password never  passing
       the  wire.   However,  all other data is NOT 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 iptables, pf or other firewalls to block all traffic coming in from
       the tun interfaces, except to the used ssh or vpn ports.

ENVIRONMENT

   IODINE_PASS
       If  the environment variable IODINE_PASS is set, iodine will use the value it is set to as
       password instead of asking for one. The -P option still has precedence.

   IODINED_PASS
       If the environment variable IODINED_PASS is set, iodined will use the value it is  set  to
       as password instead of asking for one. The -P option still has precedence.

SEE ALSO

       The README file in the source distribution contains some more elaborate information.

BUGS

       File bugs at http://dev.kryo.se/iodine/

AUTHORS

       Erik  Ekman  <yarrick@kryo.se>  and Bjorn Andersson <flex@kryo.se>. Major contributions by
       Anne Bezemer.