badvpn-tun2socks(8)

💅 badvpn-tun2socks — the manual page, but make it a group chat

okay so bestie, you're reading the badvpn-tun2socks page from the System Manager's Manual. she's a network utility and she's iconic, let's get into it 🫶

---

✨ NAME ✨

badvpn-tun2socks — create a TUN device to route TCP traffic through a SOCKS server

literally that's the whole job. a TUN device, TCP traffic, SOCKS server, slay. 💅

---

🌸 SYNOPSIS 🌸

badvpn-tun2socks
  [--help]
  [--version]
  [--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).

so here's the run-down on every single flag, no gatekeeping:

• --help — it's there in the synopsis, standing in the corner being helpful 🎀
• --version — also right there, doing its little version thing ⭐
• --logger <stdout/syslog> — you pick where the logging goes: <stdout/syslog>, that's the menu 🌈
• --syslog-facility <string> — takes a <string>, syslog facility vibes 💜
• --syslog-ident <string> — takes a <string> too, the ident one 🦋
• --loglevel <0-5/none/error/warning/notice/info/debug> — levels go <0-5/none/error/warning/notice/info/debug>, pick your energy 🔥
• --channel-loglevel <channel-name> <0-5/none/error/warning/notice/info/debug> — per-channel version of the above, and yes she can be repeated (that ... is doing a lot of work) 💀
• --tundev <name> — the TUN device name, <name> 🌸
• --netif-ipaddr <ipaddr> — required, takes an <ipaddr> 👑
• --netif-netmask <ipnetmask> — required, takes an <ipnetmask> 👑
• --socks-server-addr <addr> — required, takes an <addr> 👑
• --udpgw-remote-server-addr <addr> — optional, takes an <addr> 🧚
• --udpgw-max-connections <number> — optional, takes a <number> 🍓
• --udpgw-connection-buffer-size <number> — optional, takes a <number> ✨

and bestie, remember the address format, it matters:

a.b.c.d:port for IPv4, or [addr]:port for IPv6. don't freestyle it. 💖

---

🦋 DESCRIPTION 🦋

okay so badvpn-tun2socks is a network utility that "socksifies" TCP connections at the network layer. the way that she does this?? she implements a TUN device that accepts all incoming TCP connections — regardless of destination IP, yes ALL of them, she does not care — and forwards them through a SOCKS server. main character behaviour fr fr.

so the whole point: you can forward all connections through SOCKS with zero application support. no app has to know, no app has to care, they just vibe. ngl it can be used, for example, to forward connections through a remote SSH server. that's the example we're about to do 💅

---

🌈 EXAMPLE 🌈

this one demonstrates using tun2socks with SSH's dynamic forwarding feature. obsessed.

connect to the SSH server, and pass -D localhost:1080 to the ssh command to enable dynamic forwarding. this will make ssh open a local SOCKS server which tun2socks forwards connection through. 🫶

first, create a TUN device (eg. using openvpn):

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

then configure the IP of the new tun device:

ifconfig tun0 10.0.0.1 netmask 255.255.255.0

now start the badvpn-tun2socks program:

badvpn-tun2socks --tundev tun0 --netif-ipaddr 10.0.0.2 --netif-netmask 255.255.255.0 \
                 --socks-server-addr 127.0.0.1:1080

note that the address 10.0.0.2 is not a typo. bestie it specifies the IP address of the virtual router inside the TUN device, and it must be different from the IP of the TUN interface itself — but in the same subnet. don't come for me, that's just how it is 😭

now you should be able to ping the virtual router's IP (10.0.0.2):

ping -n 10.0.0.2

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 — because else SSH would go through the TUN device, which would go through... SSH. 💀 recursive queen.

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 10.0.0.2 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 127.0.0.1:7300

then tell tun2socks to forward UDP via the forwarder:

--udpgw-remote-server-addr 127.0.0.1:7300

---

👑 COPYRIGHT 👑

Copyright © 2010 Ambroz Bizjak <ambrop7@gmail.com>
This is free software; see the source for copying conditions.  There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.

---

and that's the page, bestie 🎀 this was badvpn-tun2socks(8) from the System Manager's Manual, dated February 2012 — yes she's an elder icon and she still ate. go socksify something, ily, bye 💖✨