.\" groff -man -Tascii iodine.8 .TH IODINE 8 "JUL 2008" "User Manuals" .SH NAME iodine, iodined \- tunnel IPv4 over DNS .SH SYNOPSIS .B iodine [-v] .B iodine [-h] .B iodine [-f] [-r] [-u .I user .B ] [-P .I password .B ] [-m .I fragsize .B ] [-t .I chrootdir .B ] [-d .I device .B ] [-m .I fragsize .B ] [-z .I context .B ] [-F .I pidfile .B ] .B [ .I nameserver .B ] .I topdomain .B iodined [-v] .B iodined [-h] .B iodined [-c] [-s] [-f] [-D] [-u .I user .B ] [-t .I chrootdir .B ] [-d .I device .B ] [-m .I mtu .B ] [-l .I listen_ip .B ] [-p .I port .B ] [-n .I external ip .B ] [-b .I dnsport .B ] [-P .I password .B ] [-z .I context .B ] [-F .I pidfile .B ] .I tunnel_ip .B [ .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 limited upstream and up to 1 Mbit/s downstream. .B iodine is the client application, .B iodined is the server. .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 -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 and otherwise tunX. .TP .B -P password Use 'password' to authenticate. If not used, .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. .SS Client Options: .TP .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 -m fragsize Maximum downstream fragsize. Not setting this will cause the client to probe the maximum accepted downstream packet size. .SS Server Options: .TP .B -c Disable checks on client IP on all incoming requests. .TP .B -s Don't try to configure IP address or MTU. 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. .TP .B -m mtu Set 'mtu' as mtu size for the tunnel device. This will be sent to the client on connect, and the client will use the same mtu. .TP .B -l listen_ip Make the server listen only on 'listen_ip' instead of on 0.0.0.0 for incoming connections. .TP .B -p port Make the server listen on 'port' instead of 53 for traffic. .B Note: You must make sure the dns requests are forwarded to this port yourself. .TP .B -n external ip The IP address to return in NS responses. Default is to return the address used as destination in the query. .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. .SS Client Arguments: .TP .B nameserver The nameserver to use to relay the dns traffic. This can be any relaying nameserver or the ip number of the server running iodined if reachable. This argument is optional, and if not specified a nameserver will be read from the .I /etc/resolv.conf file. .TP .B topdomain The dns traffic will be sent as querys of type NULL 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 must be the same on both the client and the server. .SS Server Arguments: .TP .B tunnel_ip[/netmask] This is the servers ip address on the tunnel 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 overriden by specifying it here. Using a smaller network will limit the number of concurrent users. .TP .B topdomain The dns traffic will is expected to be sent as querys of type NULL 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 the same on both the client and the server. .SH EXAMPLES .SS Quickstart: .TP Try it out within your own LAN! Follow these simple steps: .TP - On your server, run: ./iodined \-f 10.0.0.1 test.asdf (If you already use the 10.0.0.0 network, use another internal net like 172.16.0.0) .TP - Enter a password .TP - On the client, run: ./iodine \-f 192.168.0.1 test.asdf (Replace 192.168.0.1 with the server's ip address) .TP - Enter the same password .TP - Now the client has the tunnel ip 10.0.0.2 and the server has 10.0.0.1 .TP - Try pinging each other through the tunnel .TP - Done! :) .TP To actually use it through a relaying nameserver, see below. .SS Full setup: .TP .B Server side: To use this tunnel, you need control over a real domain (like mytunnel.com), and a server with a public IP number. If the server already runs a DNS server, change the listening port and then use the \-b option to let iodined forward the DNS requests. Then, delegate a subdomain (say, tunnel1.mytunnel.com) to the server. If you use BIND for the domain, add these lines to the zone file (replace 10.15.213.99 with your server ip): .nf tunnel1host IN A 10.15.213.99 tunnel1 IN NS tunnel1host.mytunnel.com. .fi Now any DNS querys for domains ending with tunnel1.mytunnnel.com will be sent to your server. Start iodined on the server. The first argument is the tunnel IP address (like 192.168.99.1) and the second is the assigned domain (in this case tunnel1.mytunnel.com). The \-f argument will keep iodined running in the foreground, which helps when testing. iodined will start a virtual interface, and also start listening for DNS queries on UDP port 53. Either enter a password on the commandline (\-P pass) or after the server has started. Now everything is ready for the client. .TP .B Client side: All the setup is done, just start iodine. It also takes two arguments, the first is the local relaying DNS server and the second is the domain used (tunnel1.mytunnnel.com). If DNS queries are allowed to any computer, you can use the tunnel endpoint (example: 10.15.213.99 or tunnel1host.mytunnel.com) as the first argument. The tunnel interface will get an IP close to the servers (in this case 192.168.99.2) and a suitable MTU. Enter the same password as on the server either by argument or after the client has started. Now you should be able to ping the other end of the tunnel from either side. .TP .B Routing: The normal case is to route all traffic through the DNS tunnel. To do this, first add a route to the nameserver you use with the default gateway as gateway. Then replace the default gateway with the servers IP address within the DNS tunnel, and configure the server to do NAT. .TP .B Troubleshooting: Use the \-D option on the server to show received and sent queries, or use a tool like Wireshark/tcpdump. The iodined server replies to NS requests sent for subdomains of the tunnel domain. If your domain is tunnel.com, send a NS request for foo.tunnel.com to see if the delegation works. dig is a good tool for this: .nf dig \-t NS foo123.tunnel.com .fi .TP .B MTU issues: These issues should be solved now, with automatic fragmentation of downstream packets. There should be no need to set the MTU explicitly on the server. .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 .B -P option still has preference. .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 option still has preference. .El .SH BUGS File bugs at http://dev.kryo.se/iodine/ .SH AUTHORS Erik Ekman and Bjorn Andersson