TheArchive/iodine
1
0
Fork 0
mirror of https://github.com/yarrick/iodine.git synced 2024-11-28 20:45:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
frekky 2015-11-10 22:33:50 +08:00
parent 4a565fd664
commit 2f8125cf97
2 changed files with 145 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -16,6 +16,7 @@ relevant header files are found in `/usr/include`.
(See script at `./src/osflags`)
Run `make` to compile the server and client binaries.
Run `make debug` to compile the binaries with extra debugging enabled.
Run `make install` to copy binaries and manpage to the destination directory.
Run `make test` to compile and run the unit tests. (Requires the `check` library)
@ -25,8 +26,8 @@ QUICKSTART
Try it out within your own LAN! Follow these simple steps:
- On your server, run: `./iodined -f test.com 10.0.0.1`.
If you already use the `10.0.0.0` network, use another internal net like
`172.16.0.0`.
If you already use the `10.0.0.0/8` network, use another internal net like
`172.16.0.0/12`.
- Enter a password.
- On the client, run: `./iodine -f -r test.com 192.168.0.1`.
Replace `192.168.0.1` with your server's ip address.
@ -88,7 +89,7 @@ If there is a chance you'll be using an iodine tunnel from unexpected
environments, start `iodined` with a `-c` option.
Resulting commandline in this example situation:
./iodined -f -c -P secretpassword t1.mydomain.com 192.168.99.1
./iodined -f -c -P secretpassword 192.168.99.1 t1.mydomain.com
### Client side
All the setup is done, just start `iodine`. It takes one or more arguments, the
@ -184,15 +185,15 @@ these DNS relays much more stable. This is also useful on some “de-optimizing
DNS relays that stuff the response with two full copies of the query, leaving
very little space for downstream data (also not capable of EDNS0). The `-M`
switch can trade some upstream bandwidth for downstream bandwidth. Note that
the minimum `-M` value is about 100, since the protocol can split packets (1200
bytes max) in only 16 fragments, requiring at least 75 real data bytes per
fragment.
the minimum `-M` value is about 20, since the first 10 bytes or so are the
Base32 encoded data header and the remainder is the actual encoded data and
packets can be split into up to 255 fragments.
The upstream data is sent gzipped encoded with Base32; or Base64 if the relay
server supports mixed case and `+` in domain names; or Base64u if `_` is
supported instead; or Base128 if high-byte-value characters are supported.
This upstream encoding is autodetected. The DNS protocol allows one query per
packet, and one query can be max 256 chars. Each domain name part can be max
packet, and one query can be max 255 chars. Each domain name part can be max
63 chars. So your domain name and subdomain should be as short as possible to
allow maximum upstream throughput.
@ -220,24 +221,24 @@ when that hostname exceeds ca. 180 characters. In these and similar cases, use
the `-O` option to try other downstream codecs; Base32 should always work.
Normal operation now is for the server to _not_ answer a DNS request until
the next DNS request has come in, a.k.a. being “lazy”. This way, the server
it has timed out (see server timeout), a.k.a. being “lazy”. This way, the server
will always have a DNS request handy when new downstream data has to be sent.
This greatly improves (interactive) performance and latency, and allows to
slow down the quiescent ping requests to 4 second intervals by default, and
possibly much slower. In fact, the main purpose of the pings now is to force
a reply to the previous ping, and prevent DNS server timeouts (usually at
least 5-10 seconds per RFC1035). Some DNS servers are more impatient and will
give SERVFAIL errors (timeouts) in periods without tunneled data traffic. All
data should still get through in these cases, but `iodine` will reduce the ping
interval to 1 second anyway (-I1) to reduce the number of error messages. This
may not help for very impatient DNS relays like `dnsadvantage.com` (ultradns),
which time out in 1 second or even less. Yet data will still get trough, and
you can ignore the `SERVFAIL` errors.
possibly much slower. Some DNS servers are more impatient and will give SERVFAIL
errors (timeouts) randomly or consistently if the target timeout is too high. All
data should still get through in these cases, but `iodine` will reduce the target
interval slowly to reduce the number of SERVFAILS. In these scenarios, it is best
to manually set the target interval to something which is definitely less than the
most impatient DNS server timeout in the connection to ensure maximum reliability.
Some very impatient DNS relays like `dnsadvantage.com` (ultradns), which time
out in 1 second or even less can cause issues. Yet data will still get trough, and
you can probably ignore the `SERVFAIL` errors.
If you are running on a local network without any DNS server in-between, try
`-I 50` (iodine and iodined close the connection after 60 seconds of silence).
The only time you'll notice a slowdown, is when DNS reply packets go missing;
the `iodined` server then has to wait for a new ping to re-send the data. You can
the `iodined` server fragment will have to time-out to be resent. You can
speed this up by generating some upstream traffic (keypress, ping). If this
happens often, check your network for bottlenecks and/or run with `-I1`.
@ -256,7 +257,8 @@ If you have problems, try inspecting the traffic with network monitoring tools
like tcpdump or ethereal/wireshark, and make sure that the relaying DNS server
has not cached the response. A cached error message could mean that you
started the client before the server. The `-D` (and `-DD`) option on the server
can also show received and sent queries.
can also show received and sent queries. To assist in diagnosis, you may wish to
recompile with `make debug` and use `-DDDDD` to see more debug output.
TIPS & TRICKS
@ -306,9 +308,8 @@ explains why some values are exactly equal.
Ping round-trip times measured with `ping -c100`, presented are average rtt
and mean deviation (indicating spread around the average), in milliseconds.
### Situation 1: `Laptop -> Wifi AP -> Home server -> DSL provider -> Datacenter`
```
iodine DNS "relay" bind9 DNS cache iodined
downstr. upstream downstr. ping-up ping-down
@ -336,9 +337,9 @@ and mean deviation (indicating spread around the average), in milliseconds.
[174.7* : these all have 2frag/packet]
```
### Situation 2: `Laptop -> Wifi+vpn / wired -> Home server`
```
iodine iodined
downstr. upstream downstr. ping-up ping-down
@ -348,7 +349,7 @@ and mean deviation (indicating spread around the average), in milliseconds.
wifi + openvpn -Tnull 1186 166.0 1022.3 6.3 1.3 6.6 1.6
wired -Tnull 1186 677.2 2464.1 1.3 0.2 1.3 0.1
```
### Notes
@ -388,7 +389,7 @@ THANKS
AUTHORS & LICENSE
-----------------
Copyright (c) 2006-2014 Erik Ekman <yarrick@kryo.se>, 2006-2009 Bjorn
Copyright (c) 2006-2014 Erik Ekman <yarrick@kryo.se>, 2015 Frekky, 2006-2009 Bjorn
Andersson <flex@kryo.se>. Also major contributions by Anne Bezemer.
Permission to use, copy, modify, and/or distribute this software for any purpose

147
man/iodine.8
View File

@ -1,5 +1,5 @@
.\" groff -man -Tascii iodine.8
.TH IODINE 8 "APR 2012" "User Manuals"
.TH IODINE 8 "OCT 2015" "User Manuals"
.SH NAME
iodine, iodined \- tunnel IPv4 over DNS
.SH SYNOPSIS
@ -21,8 +21,22 @@ iodine, iodined \- tunnel IPv4 over DNS
.I rdomain
.B ] [-m
.I fragsize
.B ] [-w
.I downfrags
.B ] [-W
.I upfrags
.B ] [-i
.I sec
.B ] [-j
.I sec
.B ] [-c
.I 0|1
.B ] [-C
.I 0|1
.B ] [-s
.I ms
.B ] [-M
.I namelen
.I maxlen
.B ] [-z
.I context
.B ] [-F
@ -41,7 +55,9 @@ iodine, iodined \- tunnel IPv4 over DNS
.I nameserver
.B [
.I nameserver2
.B [...] ] ]
.B [
.I ...
.B ] ] ]
.B iodined [-v]
@ -84,17 +100,13 @@ iodine, iodined \- tunnel IPv4 over DNS
.I /netmask
.B ]
.I topdomain
.SH DESCRIPTION
.B 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.
but DNS queries are allowed. It needs a TUN/TAP device to operate.
.B iodine
is the client application,
.B iodined
@ -103,6 +115,28 @@ 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.
.SH PERFORMANCE
The bandwidth is asymmetrical,
with a measured maximum of 13.7 Mbits/sec upstream and 53.4 Mbits/sec downstream
with all data compression disabled in a wired LAN test network.
In the same situation with compression enabled, the measured data throughput was
approximately 46.1 Mbits/sec upstream and 37.4 Mbits/sec downstream.
Compression is enabled by default, and can allow faster
data transfer in both directions depending on the type of data being
transferred.
Realistic sustained throughput on a Wifi network using a carrier-grade
DNS cache has been measured at some 600 Kbit/s upstream and over 2 Mbits/sec
downstream once more with compression disabled, however that may be increased with
compression enabled.
All of the above test scenarios used lazy mode with upstream/downstream windowsizes of
8 fragments (default) and fixed fragment, DNS and server timeouts. These parameters
were manually adjusted to best suit the environment, and can be specified using the
.B iodine
options described under
.I "Fine-tuning options"
.SH OPTIONS
.SS Common Options:
.TP
@ -229,18 +263,67 @@ In these situations use \-L0 to force running in legacy mode
(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
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.
Target timeout for queries. This should be less than the smallest timeout for
any intermediate DNS servers to reduce SERVFAILS. If this is specified, the
server timeout will be adjusted automatically based on the round-trip time
so that queries remain pending for as long as possible (only in lazy mode).
This value will be used as the polling interval in immediate mode.
When too many SERVFAIL errors occur, iodine will gradually reduce this until
it reaches 0.5 seconds or below. If SERVFAILs continue to occur, lazy mode
will be disabled and the server will respond to all queries immediately.
To reduce DNS traffic, set this interval to something large and disable lazy
mode, or set the upstream and downstream window sizes to 1.
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,
SERVFAIL errors even with \-I1; data will still get through,
and these errors can be ignored.
Maximum useful value is 59, since iodined will close a client's
connection after 60 seconds of inactivity.
.SS Fine-tuning Options (Client-side):
.TP
.B -s milliseconds
Minimum query send interval. Increase this gradually if you notice that the
nameserver(s) tend to fail more often with a high data load (and frequent
queries) or drop excess DNS queries. This will affect throughput so use with
caution.
.B -w windowsize
Size of downstream fragment sending window, or the number of fragments that
can be in transit downstream at any point in time. The client will attempt to
maintain at least this number of queries pending on the server in lazy mode,
even when idle, so that the server can always send this number of fragments
immediately if new data arrives on the tun device.
The default value is 8 fragments. Increase this for high latency connections
to improve throughput. The maximum usable value is probably around 128, however note
that although higher values are possible there may be fragment overlaps and you may
experience problems.
.TP
.B -W windowsize
Number of fragments that can be in transit upstream at any point in time. The
client will send a maximum of this number of queries immediately to the server
when new data is received in addition to any already pending queries (such as
those used to maintain the downstream windowsize). The server will respond to
any excess queries using the oldest pending query first. The same limits apply
as the downstream window size.
.TP
.B -i timeout
The maximum amount of time in seconds the server should hold on to a pending
query so as to not cause any intermediate DNS relays to time out. This should
be less than the target timeout (set with
.BR -I )
by at least the round-trip time for the connection.
If not set, this will be calculated automatically based on the round-trip time
and the target timeout.
.TP
.B -c 0|1
Enable or disable downstream data compression. Enabled by default. This may
increase overall downstream throughput, or it may not depending on the type
of data being transferred.
.B -C 0|1
Enable/disable upstream data compression, also enabled by default.
.SS Server Options:
.TP
.B -c
@ -255,7 +338,9 @@ This should only be used if you have already configured the device that will be
used.
.TP
.B -D
Increase debug level. Level 1 prints info about each RX/TX packet.
Increase debug level. Higher levels (>2) will spam the terminal with LOTS
of debug messages. Recompile using `make debug` to enable extra debug output
and debug timestamping.
Implies the
.B -f
option.
@ -306,29 +391,30 @@ Make the server stop itself after max_idle_time seconds if no traffic have been
This should be combined with systemd or upstart on demand activation for being effective.
.SS Client Arguments:
.TP
.B nameserver
The nameserver to use to relay the dns traffic. This can be any relaying
.B nameservers
The nameservers 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
.I /etc/resolv.conf
file.
Multiple nameservers can be specified, separated by spaces.
.TP
.B 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
.B nameserver
is the iodined server, then the topdomain can be chosen freely. This argument
is the iodined server address, 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]
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.
10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 ranges. The default netmask is /27,
which can be overridden by specifying it here. Using a smaller network will
limit the number of concurrent users.
.TP
.B topdomain
The dns traffic is expected to arrive as queries for
@ -336,10 +422,12 @@ 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.
they will be ignored.
.SH EXAMPLES
See the README file for both a quick test scenario, and a detailed description
of real-world deployment.
.SH SECURITY
Login is a relatively secure challenge-response MD5 hash, with the
password never passing the wire.
@ -368,11 +456,14 @@ is set, iodined will use the value it is set to as password instead of asking
for one. The
.B -P
option still has precedence.
.SH SEE ALSO
The README file in the source distribution contains some more elaborate
The README.md file in the source distribution contains some more elaborate
information.
.SH BUGS
File bugs at http://dev.kryo.se/iodine/
.SH AUTHORS
Erik Ekman <yarrick@kryo.se> and Bjorn Andersson <flex@kryo.se>. Major
contributions by Anne Bezemer.
Erik Ekman <yarrick@kryo.se>, Bjorn Andersson <flex@kryo.se> and Frekky.
Major contributions by Anne Bezemer.