badvpn-tun2socks - Man Page

create a TUN device to route TCP traffic through a SOCKS server


 [--logger <stdout/syslog>]
 [--syslog-facility <string>] [--syslog-ident <string>]
 [--loglevel <0-5/none/error/warning/notice/info/debug>]
 [--channel-loglevel <channel-name> <0-5/none/error/warning/notice/info/debug>] ...
 [--tundev <name>]
 --netif-ipaddr <ipaddr>
 --netif-netmask <ipnetmask>
 --socks-server-addr <addr>
 [--udpgw-remote-server-addr <addr>]
 [--udpgw-max-connections <number>]
 [--udpgw-connection-buffer-size <number>]

Address format is a.b.c.d:port (IPv4) or [addr]:port (IPv6).


badvpn-tun2socks is a network utility used to "socksify" TCP connections at the network layer. It implements a TUN device which accepts all incoming TCP connections (regardless of destination IP), and forwards them through a SOCKS server. This allows you to forward all connections through SOCKS, without any need for application support. It can be used, for example, to forward connections through a remote SSH server.


This example demonstrates using tun2socks in combination with SSH's dynamic forwarding feature.

Connect to the SSH server, passing -D localhost:1080 to the ssh command to enable dynamic forwarding. This will make ssh open a local SOCKS server which tun2socks forward connection through.

First create a TUN device (eg. using openvpn):

  openvpn --mktun --dev tun0 --user <someuser>

Configure the IP of the new tun device:

  ifconfig tun0 netmask

Now start the badvpn-tun2socks program:

  badvpn-tun2socks --tundev tun0 --netif-ipaddr --netif-netmask \

Note that the address is not a typo. It specifies the IP address of the virtual router inside the TUN device, and must be different from the IP of the TUN interface itself (but in the same subnet).

Now you should be able to ping the virtual router's IP (

  ping -n

All that remains is to route connections through the TUN device instead of the existing default gateway. This is done as follows:

1. Add a route to the SSH server through your existing gateway, with a lower metric than the original default route.

2. If your DNS servers are in a network that is not direcly attached (e.g. in the Internet), also add routes for them (like for the SSH server). This is needed because tun2socks does not forward UDP by default (see below).

3. Add a default route through the virtual router in the TUN device, with a lower metric than the original default route, but higher than the SSH and DNS routes.

This will make all external connections go through the TUN device, except for the SSH connection (else SSH would go through the TUN device, which would go through... SSH).

For example (assuming there are no existing default routes with metric <=6; otherwise remove them or change their metrics):

  route add <IP_of_SSH_server> gw <IP_of_original_gateway> metric 5
  <same for DNS>
  route add default gw metric 6

UDP Forwarding

tun2socks can forward UDP, however this requires a forwarder daemon, badvpn-udpgw to run on the remote SSH server:

  badvpn-udpgw --listen-addr

Then tell tun2socks to forward UDP via the forwarder:



February 2012