iodine

iodine - <https://code.kryo.se/iodine>
=====================================


This is a piece of software that lets you tunnel IPv4 data through a DNS
server. This can be usable in different situations where internet access is
firewalled, but DNS queries are allowed.


COMPILING
---------

To compile iodine you need meson.
Run the following commands to compile inside the `build` directory:

```
meson setup build
cd build
ninja
```

To build and run the tests you need the `check` library. Start them by
running `ninja test` inside the build directory.


QUICKSTART
----------

Try it out within your own LAN! Follow these simple steps:
- On your server, run: `./iodined -f 10.0.0.1 test.com`.
  If you already use the `10.0.0.0` network, use another internal net like
  `172.16.0.0`.
- Enter a password.
- On the client, run: `./iodine -f -r 192.168.0.1 test.com`.
  Replace `192.168.0.1` with your server's ip address.
- Enter the same password.
- Now the client has the tunnel ip `10.0.0.2` and the server has `10.0.0.1`.
- Try pinging each other through the tunnel.
- Done! :)

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


HOW TO USE
----------

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.

### Server side
To use this tunnel, you need control over a real domain (like `mydomain.com`),
and a server with a public IP address to run `iodined` on. If this server
already runs a DNS program, change its listening port and then use `iodined`'s
`-b` option to let `iodined` forward the DNS requests. (Note that this procedure
is not advised in production environments, because `iodined`'s DNS forwarding
is not completely transparent, for example zone transfers will not work.)
Alternatively you can forward the subdomain from your DNS server to `iodined`
which must then run on a different port (`-p`).

Then, delegate a subdomain (say, `t1.mydomain.com`) to the iodined server.
If you use BIND for your domain, add two lines like these to the zone file:

	t1		IN	NS	t1ns.mydomain.com.		; note the dot!
	t1ns		IN	A	10.15.213.99

The `NS` line is all that's needed to route queries for the `t1` subdomain
to the `t1ns` server. We use a short name for the subdomain, to keep as much
space as possible available for the data traffic. At the end of the `NS` line
is the name of your `iodined` server. This can be any name, pointing anywhere,
but in this case it's easily kept in the same zone file. It must be a name
(not an IP address), and that name itself must have an `A` record
(not a `CNAME`).

If your `iodined` server has a dynamic IP, use a dynamic DNS provider. Simply
point the `NS` line to it, and leave the `A` line out:

	t1		IN	NS	myname.mydyndnsprovider.com.	; note the dot!

Then reload or restart your nameserver program. Now any DNS queries for
domains ending in `t1.mydomain.com`