IODINE(8)

📦
version 0.9.0 · 4 versions
, in arch rolling

🌸 iodine(8) — tunnel IPv4 over DNS, bestie! 🦋

okay so picture this: it's the manual page for iodine from the System Manager's Manual, and I'm about to walk you through it like we're in the group chat and you need to understand this for a vibe check. ✨

✨ NAME ✨

iodine — tunnel IPv4 over DNS. that's it. that's the whole name. iconic. 💅

🌈 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

like, there are so many flags, but it's giving "I have options" energy and honestly? we love that for us. 🎀

💖 DESCRIPTION 💖

okay so iodine lets you tunnel IPv4 data through a DNS server. and like, why is that a slay? because it's useful in situations where Internet access is firewalled, but DNS queries are allowed. 🧚 It needs a TUN/TAP device to operate, so that's the main character requirement.

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. so it's not gonna stream 4K, but it's something, bestie. 😭

iodine is the client application, iodined is the server. and 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. so like, you and the server need to be on the same page. no cap. 🔥

✨ OPTIONS ✨

okay bestie, buckle up, because there are a lot of options and I'm gonna list every single one because we don't skip details in this house. 💅

  • -v — Print version info and exit. like a quick lil vibe check of what version you're on. ⭐
  • -h — Print usage info and exit. your help menu, your bestie when you're lost. 🫶
  • -f — Keep running in foreground. no backgrounding, just vibes in your face. 🌸
  • -4 — Force/allow only IPv4 DNS queries. IPv4 only, periodt. 💜
  • -6 — Force/allow only IPv6 DNS queries. IPv6 only, main character energy. 🦋
  • -u user — Drop privileges and run as user 'user' after setting up tunnel. like, be responsible and downgrade your power after the tunnel is up. 💖
  • -t chrootdir — Chroot to 'chrootdir' after setting up tunnel. you're locking yourself in a directory, but like, for security. 🎀
  • -d device — Use the TUN device 'device' instead of the normal one, which is dnsX on Linux and otherwise tunX. On macOS 10.6 or newer, this can also be utunX, which will attempt to use an utun device built into the OS. so you can pick your device like you pick your outfit. 🔥
  • -P password — Use 'password' to authenticate. If not used, stdin will be used as input. Only the first 32 characters will be used. so like, keep it short and sweet. no cap. 😭
  • -z context — Apply SELinux 'context' after initialization. SELinux besties, this one's for you. 🌈
  • -F pidfile — Create 'pidfile' and write process id in it. like a little name tag for your process. 🏷️
  • -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. so -r is like "nah, skip the direct route." 💀
  • -R rdomain — Use OpenBSD routing domain 'rdomain' for the DNS connection. OpenBSD besties, this is your moment. 🦋
  • -m fragsize — Force maximum downstream fragment size. Not setting this will cause the client to automatically probe the maximum accepted downstream fragment size. so you can force it or let it figure itself out. 🌸
  • -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. so like, if your DNS server is being flaky, this is your fix. 💜
  • -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. so like, if autodetection is being extra, you can override it. 🎀
  • -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". this is like choosing your encoding outfit — pick the one that slays for your setup. 💅
  • -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). so like, lazy mode is the default vibe, but if your relay is being weird, force legacy. 😭
  • -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. so like, this controls how often you ping to keep the connection alive. don't go above 59 or you'll get ghosted by the server. 👻

🫶 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. so like, you can tell it where to go, or it'll just figure it out from your system. 🌸
  • 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. so like, this is your domain, your rules. but it's gotta match the server. periodt. 💜

🌈 EXAMPLES 🌈

See the README file for both a quick test scenario, and a detailed description of real-world deployment. like, the README is your bestie for the full tea. 🍵

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

so like, the login is secure but everything else is not. this is not the vibe for sensitive data. please use ssh or vpn, bestie. I'm begging. 😭🔒

🦋 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. so like, you can set it in your env and skip the prompt, but -P wins if both are there. 💅

✨ SEE ALSO ✨

The README file in the source distribution contains some more elaborate information. like, go read it, it's giving details. 🎀

💀 BUGS 💀

File bugs at https://github.com/yarrick/iodine. like, if something's broken, tell the devs. they wanna know. 🫶

👑 AUTHORS 👑

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

🎀 sign-off 🎀

this page is from the User Manuals, and the date on it is OCT 2026. so like, it's fresh and it's iconic and now you know all the tea about iodine(8). go tunnel that IPv4 over DNS, bestie. slay. ✨💅🦋

📦 where this page comes from