iodine/man/iodine.8

381 lines
12 KiB
Groff
Raw Permalink Normal View History

2007-02-10 12:33:10 +00:00
.\" groff -man -Tascii iodine.8
2023-04-17 08:26:14 +00:00
.TH IODINE 8 "APR 2023" "User Manuals"
2007-02-10 12:33:10 +00:00
.SH NAME
iodine, iodined \- tunnel IPv4 over DNS
.SH SYNOPSIS
.B iodine [-v]
.B iodine [-h]
.B iodine [-4] [-6] [-f] [-r] [-u
2007-02-10 12:33:10 +00:00
.I user
.B ] [-P
.I password
2009-01-10 20:53:09 +00:00
.B ] [-m
.I fragsize
2007-02-10 12:33:10 +00:00
.B ] [-t
.I chrootdir
.B ] [-d
.I device
.B ] [-R
.I rdomain
2009-03-21 13:34:02 +00:00
.B ] [-m
.I fragsize
2009-12-29 20:00:57 +00:00
.B ] [-M
.I namelen
.B ] [-z
.I context
.B ] [-F
.I pidfile
2009-09-20 15:11:10 +00:00
.B ] [-T
.I dnstype
.B ] [-O
.I downenc
2009-09-20 21:10:42 +00:00
.B ] [-L
.I 0|1
.B ] [-I
.I interval
2007-02-10 12:33:10 +00:00
.B ]
2007-07-12 13:23:44 +00:00
.B [
2007-02-10 12:33:10 +00:00
.I nameserver
2007-07-12 13:23:44 +00:00
.B ]
2007-02-10 12:33:10 +00:00
.I topdomain
.B iodined [-v]
.B iodined [-h]
.B iodined [-4] [-6] [-c] [-s] [-f] [-D] [-u
2007-02-10 12:33:10 +00:00
.I user
.B ] [-t
.I chrootdir
.B ] [-d
.I device
2007-02-10 12:33:10 +00:00
.B ] [-m
.I mtu
.B ] [-l
.I listen_ip4
.B ] [-L
.I listen_ip6
.B ] [-p
.I port
.B ] [-n
(
.B auto
|
2009-09-20 15:11:10 +00:00
.I external_ip
)
.B ] [-b
.I dnsport
.B ] [-P
.I password
.B ] [-z
.I context
.B ] [-F
.I pidfile
.B ] [-i
.I max_idle_time
.B ]
2007-02-10 12:33:10 +00:00
.I tunnel_ip
.B [
.I /netmask
.B ]
2007-02-10 12:33:10 +00:00
.I topdomain
.SH DESCRIPTION
.B iodine
lets you tunnel IPv4 data through a DNS
2007-02-10 12:33:10 +00:00
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
2009-09-20 21:10:42 +00:00
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.
2007-02-10 12:33:10 +00:00
.B iodine
is the client application,
.B iodined
is the server.
2009-12-29 20:00:57 +00:00
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.
2007-02-10 12:33:10 +00:00
.SH OPTIONS
.SS Common Options:
.TP
.B -v
Print version info and exit.
.TP
.B -h
Print usage info and exit.
.TP
.B -f
Keep running in foreground.
.TP
.B -4
Force/allow only IPv4 DNS queries
.TP
.B -6
Force/allow only IPv6 DNS queries
.TP
2007-02-10 12:33:10 +00:00
.B -u user
Drop privileges and run as user 'user' after setting up tunnel.
.TP
.B -t chrootdir
Chroot to 'chrootdir' after setting up tunnel.
.TP
.B -d device
Use the TUN device 'device' instead of the normal one, which is dnsX on Linux
2015-04-08 06:59:26 +00:00
and otherwise tunX. On Mac OS X 10.6, this can also be utunX, which will attempt
to use an utun device built into the OS.
.TP
2007-02-10 12:33:10 +00:00
.B -P password
Use 'password' to authenticate. If not used,
2007-02-10 12:33:10 +00:00
.B stdin
will be used as input. Only the first 32 characters will be used.
.TP
.B -z context
Apply SELinux 'context' after initialization.
.TP
.B -F pidfile
Create 'pidfile' and write process id in it.
2009-01-10 20:53:09 +00:00
.SS Client Options:
.TP
2009-08-15 22:02:00 +00:00
.B -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.
.TP
.B -R rdomain
Use OpenBSD routing domain 'rdomain' for the DNS connection.
.TP
2009-01-10 20:53:09 +00:00
.B -m fragsize
2009-09-20 15:11:10 +00:00
Force maximum downstream fragment size. Not setting this will cause the
client to automatically probe the maximum accepted downstream fragment size.
.TP
2009-12-29 20:00:57 +00:00
.B -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
2014-04-02 12:07:40 +00:00
hostnames, noticeable when fragment size autoprobe returns very
2009-12-29 20:00:57 +00:00
different results each time.
.TP
2009-09-20 15:11:10 +00:00
.B -T dnstype
2009-12-29 20:00:57 +00:00
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:
.IR NULL ,
.IR PRIVATE ,
2009-12-29 20:00:57 +00:00
.IR TXT ,
.IR SRV ,
.IR MX ,
2009-09-20 15:11:10 +00:00
.I CNAME
2009-12-29 20:00:57 +00:00
and
2009-09-20 15:11:10 +00:00
.I A
2009-12-29 20:00:57 +00:00
(returning CNAME).
Note that
.IR SRV ,
2009-09-20 15:11:10 +00:00
.I MX
2009-12-29 20:00:57 +00:00
and
.I A
may/will cause additional lookups by "smart" caching
2009-09-20 15:11:10 +00:00
nameservers to get an actual IP address, which may either slow down or fail
completely. The
.IR PRIVATE
type uses value 65399 (in the 'private use' range) and requires servers
implementing RFC 3597.
2009-09-20 15:11:10 +00:00
.TP
.B -O downenc
2009-12-29 20:00:57 +00:00
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.
2009-09-20 15:11:10 +00:00
.I Base32
2009-12-29 20:00:57 +00:00
is the lowest-grade codec and should always work; this is used when
autodetection fails.
2009-09-20 15:11:10 +00:00
.I Base64
provides more bandwidth, but may not work on all nameservers.
2009-12-29 20:00:57 +00:00
.I Base64u
is equal to Base64 except in using underscore ('_')
instead of plus sign ('+'), possibly working where
.I Base64
does not.
.I Base128
uses high byte values (mostly accented letters in iso8859-1),
which might work with some nameservers.
2009-09-20 15:11:10 +00:00
For TXT queries,
.I Raw
2009-12-29 20:00:57 +00:00
will provide maximum performance, but this will only work if the nameserver
2009-09-20 15:11:10 +00:00
path is fully 8-bit-clean for responses that are assumed to be "legible text".
2009-09-20 21:10:42 +00:00
.TP
.B -L 0|1
Lazy-mode switch.
2009-12-29 20:00:57 +00:00
\-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
2009-09-20 21:10:42 +00:00
(implies \-I1).
.TP
.B -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
2009-12-29 20:00:57 +00:00
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.
2009-09-20 21:10:42 +00:00
Maximum useful value is 59, since iodined will close a client's
connection after 60 seconds of inactivity.
2007-02-10 12:33:10 +00:00
.SS Server Options:
.TP
.B -c
2009-09-20 15:11:10 +00:00
Disable checking the client IP address on all incoming requests.
2014-04-02 12:07:40 +00:00
By default, requests originating from non-matching IP addresses will be
2009-09-20 15:11:10 +00:00
rejected, however this will cause problems when requests are routed
via a cluster of DNS servers.
.TP
.B -s
Don't try to configure IP address or MTU.
2009-09-20 15:11:10 +00:00
This should only be used if you have already configured the device that will be
used.
.TP
2008-08-05 22:37:40 +00:00
.B -D
Increase debug level. Level 1 prints info about each RX/TX packet.
2009-09-20 15:11:10 +00:00
Implies the
.B -f
option.
2014-04-02 12:07:40 +00:00
On level 2 (\-DD) or higher, DNS queries will be printed literally.
2009-12-29 20:00:57 +00:00
When using Base128 upstream encoding, this is best viewed as
ISO Latin-1 text instead of (illegal) UTF-8.
2014-04-02 12:07:40 +00:00
This is easily done with : "LC_ALL=C luit iodined \-DD ..."
2009-12-29 20:00:57 +00:00
(see luit(1)).
2008-08-05 22:37:40 +00:00
.TP
2007-02-10 12:33:10 +00:00
.B -m mtu
Set 'mtu' as mtu size for the tun device.
2009-09-20 15:11:10 +00:00
This will be sent to the client on login, and the client will use the same mtu
2009-12-29 20:00:57 +00:00
for its tun device. Default 1130. Note that the DNS traffic will be
2009-09-20 15:11:10 +00:00
automatically fragmented when needed.
2007-02-10 12:33:10 +00:00
.TP
.B -l external|listen_ip4
Make the server listen only on 'listen_ip4' for incoming IPv4 requests.
By default, incoming requests are accepted from all interfaces (0.0.0.0).
A domain name can be used as argument - use one with only one A record.
If listen_ip4 is 'external', iodined will use the opendns.com DNS service to
retrieve the external IP of the host and use that as listen address.
.TP
.B -L listen_ip6
Make the server listen only on 'listen_ip6' for incoming IPv6 requests.
By default, incoming requests are accepted from all interfaces (::).
A domain name can be used as argument - use one with only one AAAA record.
2007-02-10 12:33:10 +00:00
.TP
.B -p port
Make the server listen on 'port' instead of 53 for traffic.
If 'listen_ip4' does not include localhost, this 'port' can be the same
as 'dnsport'.
2007-02-10 12:33:10 +00:00
.B Note:
You must make sure the dns requests are forwarded to this port yourself.
.TP
.B -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 the opendns.com DNS service to
retrieve the external IP of the host and use that for NS responses.
.TP
.B -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'.
2009-09-20 15:11:10 +00:00
.B Note:
The forwarding is not fully transparent, and not advised for use
in production environments.
.TP
.B -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.
2007-02-10 12:33:10 +00:00
.SS Client Arguments:
.TP
.B nameserver
The nameserver to use to relay the dns traffic. This can be any relaying
2009-09-25 22:11:18 +00:00
nameserver or the server running iodined if reachable. This field can be
2014-02-05 22:08:56 +00:00
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
2007-02-10 12:33:10 +00:00
.I /etc/resolv.conf
file.
.TP
.B topdomain
2009-09-20 15:11:10 +00:00
The dns traffic will be sent as queries for subdomains under
2007-02-10 12:33:10 +00:00
\'topdomain'. This is normally a subdomain to a domain you own. Use a short
domain name to get better throughput. If
2007-02-10 12:33:10 +00:00
.B 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.
.SS Server Arguments:
.TP
.B tunnel_ip[/netmask]
2009-12-29 20:00:57 +00:00
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
2014-04-02 12:07:40 +00:00
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.
2007-02-10 12:33:10 +00:00
.TP
.B topdomain
2009-12-29 20:00:57 +00:00
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
2009-09-20 15:11:10 +00:00
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. The topdomain can start with '*' which will allow all
domains ending with the same suffix.
2007-02-10 12:33:10 +00:00
.SH EXAMPLES
2009-12-29 20:00:57 +00:00
See the README file for both a quick test scenario, and a detailed description
of real-world deployment.
2009-09-20 15:11:10 +00:00
.SH SECURITY
Login is a relatively secure challenge-response MD5 hash, with the
password never passing the wire.
However, all other data is
.B 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
2009-12-29 20:00:57 +00:00
.IR iptables ,
2009-09-20 15:11:10 +00:00
.I pf
2009-12-29 20:00:57 +00:00
or other firewalls to block all traffic coming in from the tun interfaces,
2009-09-20 15:11:10 +00:00
except to the used ssh or vpn ports.
2009-09-19 08:09:12 +00:00
.SH ENVIRONMENT
.SS IODINE_PASS
If the environment variable
.B IODINE_PASS
is set, iodine will use the value it is set to as password instead of asking
for one. The
2009-09-19 08:09:12 +00:00
.B -P
2009-12-29 20:00:57 +00:00
option still has precedence.
2009-09-19 08:09:12 +00:00
.SS IODINED_PASS
If the environment variable
.B IODINED_PASS
is set, iodined will use the value it is set to as password instead of asking
for one. The
.B -P
2009-12-29 20:00:57 +00:00
option still has precedence.
2009-09-20 15:11:10 +00:00
.SH SEE ALSO
The README file in the source distribution contains some more elaborate
information.
2007-02-10 12:33:10 +00:00
.SH BUGS
2020-06-04 21:51:41 +00:00
File bugs at https://github.com/yarrick/iodine
2007-02-10 12:33:10 +00:00
.SH AUTHORS
2009-12-29 20:10:02 +00:00
Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
contributions by Anne Bezemer.