Iodine
Iodine is a DNS tunneling tool that encapsulates IP traffic within DNS queries and responses, allowing you to tunnel network traffic through restrictive firewalls and captive portals that only permit DNS traffic. It establishes a PPP tunnel interface (dns0) over DNS, enabling full network access when direct connections are blocked.
Installation
Linux (Debian/Ubuntu)
sudo apt update
sudo apt install iodinemacOS
brew install iodineCompile from Source
git clone https://github.com/yarrick/iodine.git
cd iodine
make
sudo make installVerify installation:
iodine --version
iodined --versionInfrastructure Setup
Domain Requirements
- Delegated subdomain: Use a domain you control (e.g.,
tunnel.example.com) - DNS nameserver: The delegated domain must point to your iodined server
DNS Configuration
Create NS record delegation at your domain registrar:
tunnel.example.com NS ns1.tunnel.example.com
ns1.tunnel.example.com A <your-server-ip>This routes all DNS queries for *.tunnel.example.com to your iodined server listening on port 53.
Verification:
nslookup test.tunnel.example.com
# Should resolve to your server IPServer Setup
Basic iodined Server
Start the DNS tunneling server:
sudo iodined -f -c -P "SecurePassword123" 10.0.0.1 tunnel.example.comServer Options Reference
| Option | Description |
|---|---|
-f | Run in foreground (don’t daemonize) |
-c | Disable IP check of incoming packets (enables NAT clients) |
-P password | Set tunnel authentication password |
-n auto|IP | Listen address (auto or specific IP, default: 0.0.0.0) |
-l 0.0.0.0 | Explicitly bind to all interfaces |
-p 53 | Listen port (default 53, requires root) |
-u username | Drop privileges to user after bind |
-t /var/empty | Chroot to directory |
-d device | Use specific TUN device |
-m mtu | Set tunnel MTU (default 1024) |
-M | Use lazy mode for faster transfers |
-w downstream | Fragment size downstream (default 3333) |
Production Setup
sudo iodined -u iodine -t /var/empty \
-c -P "ComplexPassword!" \
-n auto \
-m 1024 \
10.0.0.1 tunnel.example.comVerify server is running:
sudo netstat -tulnp | grep 53
ps aux | grep iodinedClient Setup
Basic Connection
sudo iodine -f -P "SecurePassword123" tunnel.example.comClient Options Reference
| Option | Description |
|---|---|
-f | Run in foreground |
-P password | Authentication password (must match server) |
-r | Force specific DNS resolver IP |
-R | Bind to specific DNS port on client |
-T record_type | DNS record type: NULL (default), TXT, SRV, MX, CNAME, A |
-m mtu | Set tunnel MTU (should match server) |
-M | Enable lazy mode (faster transfers) |
-I interval | Ping interval in seconds (default 4) |
-L lazy_mode | Set lazy mode strength (0-3) |
-O encoding | Set encoding: base32 (default), base64, base128, raw |
-W window_size | Set window size for flow control |
Force Custom DNS Resolver
sudo iodine -f -r 8.8.8.8 -P "password" tunnel.example.comSpecify Record Type
sudo iodine -f -T TXT -P "password" tunnel.example.comDNS Record Types
Bandwidth Comparison
| Type | Bandwidth | Notes |
|---|---|---|
| NULL | 200-300 KB/s | Best (most nameservers allow) |
| TXT | 150-200 KB/s | Good fallback when NULL blocked |
| A | 50-80 KB/s | Limited, some networks block |
| CNAME | 50-80 KB/s | Can trigger warnings, avoid |
| MX | 100-150 KB/s | Reasonable fallback |
| SRV | 100-150 KB/s | Possible but uncommon |
Selection Strategy
- Try NULL first (fastest, widely supported)
- Fall back to TXT if NULL blocked
- Use A records as last resort (slowest)
# Try NULL (default)
sudo iodine -f tunnel.example.com
# Fall back to TXT
sudo iodine -f -T TXT tunnel.example.com
# Try A record
sudo iodine -f -T A tunnel.example.comTunnel Interface
Interface Configuration
Once connected, you’ll see:
ifconfig dns0
# Shows: 10.0.0.x/255.255.255.0 (tun interface)Verify Connectivity
# Test tunnel is up
ping 10.0.0.1
# Test external connectivity
traceroute 8.8.8.8Routing Through Tunnel
Configure which traffic flows through the tunnel:
# Route all traffic through tunnel
sudo route add default gw 10.0.0.1
# Route specific subnet
sudo route add 192.168.1.0/24 gw 10.0.0.1
# Route to specific host
sudo route add 10.20.30.40 gw 10.0.0.1SOCKS Proxy Over Tunnel
Create a SOCKS proxy via SSH tunneling:
# Terminal 1: Establish iodine tunnel
sudo iodine -f -P "password" tunnel.example.com
# Terminal 2: SSH SOCKS proxy (once tunnel is up)
ssh -D 1080 user@10.0.0.1
# Terminal 3: Use SOCKS proxy
curl --socks5 127.0.0.1:1080 https://example.comDNS Configuration on Tunnel
Set DNS for tunnel traffic:
# Temporary (single session)
echo "nameserver 10.0.0.1" | sudo tee -a /etc/resolv.conf
# Or use client option
sudo iodine -f -P "password" tunnel.example.com
# DNS automatically configuredPerformance Tuning
MTU Optimization
Start conservative, then increase:
# Server (smaller MTU = more reliable)
sudo iodined -m 1024 10.0.0.1 tunnel.example.com
# Client (must match or be smaller than server)
sudo iodine -m 1024 tunnel.example.com
# Increase for faster speeds (if stable)
sudo iodined -m 2048 10.0.0.1 tunnel.example.com
sudo iodine -m 2048 tunnel.example.comFragment Size Control
# Server: reduce downstream fragment size for stability
sudo iodined -w 2000 10.0.0.1 tunnel.example.comLazy Mode (Faster Transfers)
Reduces ping overhead, increases speed:
# Server
sudo iodined -M 10.0.0.1 tunnel.example.com
# Client
sudo iodine -M tunnel.example.comEncoding Selection
Choose encoding to optimize for network conditions:
# base32 (default, most compatible)
sudo iodine -O base32 tunnel.example.com
# base64 (faster, may be filtered)
sudo iodine -O base64 tunnel.example.com
# base128 (fastest, least compatible)
sudo iodine -O base128 tunnel.example.comCaptive Portal Bypass
Typical Workflow
# 1. Connect to WiFi (will show captive portal)
# Don't authenticate if you want pure DNS tunnel
# 2. Start iodine tunnel
sudo iodine -f -P "password" tunnel.example.com
# 3. Once connected, traffic routes through DNS tunnel
# You have full network access regardless of captive portal
# 4. Verify connectivity
ping 8.8.8.8
curl https://example.comHandling Aggressive Filtering
Some networks block DNS on non-standard ports or filter record types:
# Try different DNS resolvers
sudo iodine -r 1.1.1.1 tunnel.example.com
sudo iodine -r 8.8.8.8 tunnel.example.com
# Try different record types
sudo iodine -T TXT tunnel.example.com
sudo iodine -T A tunnel.example.com
# Combine strategies
sudo iodine -r 1.1.1.1 -T TXT tunnel.example.comRouting Configuration
Split Tunneling (Selective Routes)
Route only specific traffic through tunnel:
# Assume tunnel is up: 10.0.0.1
# Route corporate network through tunnel
sudo route add 10.20.0.0/16 gw 10.0.0.1
# Route specific server
sudo route add 10.30.40.50 gw 10.0.0.1
# All other traffic uses normal route (local ISP)Full Tunnel (All Traffic)
Route all traffic through tunnel (careful with latency):
# Save default route first
ip route show > /tmp/routes.bak
# Replace default route
sudo route del default
sudo route add default gw 10.0.0.1
# Restore later
sudo route del default
cat /tmp/routes.bak | while read line; do sudo route add $line; doneView Current Routes
route -n
ip route show
netstat -rTroubleshooting
Connection Fails
# 1. Verify DNS resolution
nslookup test.tunnel.example.com
dig @ns1.example.com test.tunnel.example.com
# 2. Check server is listening
sudo netstat -tulnp | grep 53
sudo ss -tulnp | grep 53
# 3. Check firewall
sudo iptables -L -n | grep 53
sudo firewall-cmd --list-all
# 4. Enable firewall port
sudo ufw allow 53/udp
sudo firewall-cmd --permanent --add-port=53/udpSlow Tunnel
# 1. Test with lazy mode
sudo iodine -M -f tunnel.example.com
# 2. Increase MTU
sudo iodine -m 2048 tunnel.example.com
# 3. Try different encoding
sudo iodine -O base64 tunnel.example.com
# 4. Check latency
ping -c 5 10.0.0.1Password Authentication Issues
# Verify server password
sudo ps aux | grep iodined
# Look for -P flag
# Ensure exact match on client
sudo iodine -P "ExactSamePassword" tunnel.example.com
# Check for special characters
# Use quotes to preserve spaces/special charsTUN/TAP Device Errors
# Check device exists
ls -la /dev/net/tun
# Create if missing
sudo mkdir -p /dev/net
sudo mknod /dev/net/tun c 10 200
sudo chmod 600 /dev/net/tunNo DNS Resolution in Tunnel
# Manually set DNS
echo "nameserver 10.0.0.1" | sudo tee /etc/resolv.conf
# Or use resolvconf
echo "nameserver 10.0.0.1" | sudo resolvconf -a tun0
# Verify
cat /etc/resolv.confBest Practices
Security
- Use strong passwords: At least 16 characters, mix of complexity
- Restrict server access: Firewall port 53 to authorized IPs only
- Run as unprivileged user: Use
-u iodine -t /var/empty - Use HTTPS tunneling: Encrypt data within the tunnel
- Rotate credentials: Change password regularly in production
Stability
- Start conservative: Begin with default MTU (1024), increase carefully
- Monitor packet loss: Check
pingoutput for drops - Use lazy mode judiciously: Faster but less reliable on poor connections
- Match MTU on client and server: Prevents fragmentation
- Test in staging: Verify before production deployment
Operational
- Monitor DNS logs: Track tunnel usage at the DNS level
- Set up alerts: Monitor connection drops and errors
- Document configuration: Keep record of MTU, encoding, record type settings
- Have fallbacks: Prepare alternative tunneling methods (dnscat2, dns2tcp)
- Test regularly: Verify tunnel works from different networks
Related Tools
| Tool | Purpose | Comparison |
|---|---|---|
| dnscat2 | DNS tunneling with C&C capabilities | Full shell over DNS, more features, complex setup |
| dns2tcp | TCP tunneling over DNS | Lighter weight, simpler than iodine, slower |
| Chisel | HTTP/HTTPS reverse proxy tunneling | Modern, SSH-like syntax, easier setup, not DNS-based |
| NSTX | DNS tunneling via SSH | Older, less maintained, similar to iodine |
| DNSExfil | DNS exfiltration only | One-way data extraction, not bidirectional |
When to Use Iodine
- Firewall bypass: When only DNS port 53 is open
- Captive portal evasion: Hotel/airport WiFi restrictions
- Low-bandwidth pivoting: Need minimal bandwidth for command execution
- Reliable covert channel: More stable than ICMP or other methods
When to Use Alternatives
- Full shell needed: Use dnscat2 (more features)
- Modern infrastructure: Use Chisel (simpler, faster)
- Quick lightweight tunnel: Use dns2tcp (minimal overhead)