hev-socks5-tproxy: transparent SOCKS5 for a Linux router

Interception happens in the routing layer, not in the applications

HevSocks5TProxy is a simple, lightweight transparent proxy for Linux, and the design decision is what makes it transparent rather than merely a SOCKS5 client.

The features are three: IPv4 and IPv6 in dual stack, redirecting TCP connections, and redirecting UDP packets, with full cone NAT, UDP-in-UDP and UDP-in-TCP supported. The transparent part is achieved by putting the proxy in the packet path rather than asking applications to talk to it. A client on the LAN opens a normal TCP connection to what it believes is a local service, and the routing rules redirect that connection to the proxy, which then speaks SOCKS5 to the upstream server. The applications do not know, and do not need to know.

The topology diagram in the README shows the whole arrangement, and it is worth reading because the DNS handling is the subtle part. The LAN host connects to the downlink interface, the routing rules direct the traffic to the Socks5 TProxy process, and the proxy connects onward through the uplink to a Socks5 server and an upstream DNS. There are two DNS paths marked on the diagram, a direct dns and a proxy dns, and DNSMasq appears in the chain, with the DNSMasq instance sitting below the proxy and feeding the LAN.

The reason for that arrangement is that a transparent proxy which also carries UDP has to deal with name resolution itself. If the client resolved a name through the local resolver and the proxy then connected to a different address, the two would disagree and the connection would break. Sending DNS through the same path as the traffic keeps the two consistent.

So the two ingredients are a SOCKS5 server with UDP support, and a Linux host that sits between the LAN and the uplink and is willing to mess with its own routing tables. The program itself is written in C and the repository is MIT licensed.

Building it, on Linux and on Android

On Linux the build is three commands, and the recursive clone matters because the dependencies are submodules:

git clone --recursive https://github.com/heiher/hev-socks5-tproxy
cd hev-socks5-tproxy
make

The recursive flag is there because the repository depends on two third party projects that are fetched as submodules, and the Makefile builds them as part of the top level target rather than expecting them to be present.

The Android build is a different arrangement, because the NDK expects a different directory layout:

mkdir hev-socks5-tproxy
cd hev-socks5-tproxy
git clone --recursive https://github.com/heiher/hev-socks5-tproxy jni
cd jni
ndk-build

The clone goes into a directory called jni, which is what the Android NDK build system expects, and the build is driven by ndk-build rather than by make. The repository root has the Android.mk and Application.mk files that make that work, alongside a build.mk for the regular build and the conf/ and src/ directories.

There is a packaged route too, for OpenWrt 24.10 and later, with the package in the OpenWrt packages tree under net/hev-socks5-tproxy. Installing it is a package install, and the service is then configured through a file in /etc/config and restarted:

# Install package


/etc/init.d/hev-socks5-tproxy restart

That route matters more than it might seem, because it is the only supported configuration in the README for a device that people actually use this on. An OpenWrt router is where a transparent proxy belongs, since the router is already the thing all the traffic passes through.

The build itself is a plain Makefile with a few conveniences worth noting. There is a cross compile prefix variable, so the same tree builds for a different architecture by setting the prefix, and the compiler flags are -O3 with -Werror, so warnings are build failures. There is a stack overflow detector flag enabled by default, a static build option, and separate build and strip steps with their own coloured messages.

The config file, and the settings that matter for UDP

Everything is configured through a single YAML file, and the shipped default is readable enough to use as a reference.

main:
  # Worker threads
socks5:
  # Socks5 server port
  port: 1080
  # Socks5 server address
  address: 127.0.0.1
  # Socks5 UDP relay mode (tcp|udp)
  udp: 'udp'

The main section sets the number of worker threads, which defaults to one. The socks5 section is the upstream server, with the port defaulting to 1080 and the address to 127.0.0.1, and the udp setting choosing the UDP relay mode, tcp or udp, defaulting to udp. The commented lines show what is available but off: an override for the UDP address the SOCKS5 server provides, the pipeline handshake mode, a username and password, a socket mark, and TCP fastopen.

The socket mark is the one that connects this file to the routing rules, because the firewall rules match on it. And the commented dns section is described as being for proxy DNS in bridged mode, with its own port, address and upstream, which is the piece that makes the DNS path in the topology diagram configurable rather than fixed.

Further down the file the tcp and udp sections have their own ports and addresses, both defaulting to port 1088 on the address ::, and there is a misc section with the task stack size, the UDP receive buffer size, the number of UDP copy buffers, connect and read-write timeouts, the log file and log level, the pid file for running as a daemon, and the rlimit nofile value. The comment on the copy buffers notes they are 1500 bytes per buffer.

The defaults are conservative in a useful way. tcp-fastopen is off, pipeline mode is off, and the mark is zero, so the shipped configuration assumes a plain SOCKS5 server on localhost with no credential and no special socket attributes. Everything else is there when you need it and commented out when you do not, which is the right way to ship a default for a network component that other people will read line by line.

Policy routing and the two firewall backends

The redirect rules are the part that has to be right, and the project documents two backends.

The nftables route is a single table inet mangle with two sets of bypass addresses, byp4 for IPv4 and byp6 for IPv6, and a prerouting chain that returns early for traffic already marked, returns early for addresses in the bypass sets, and otherwise matches l4proto of tcp or udp and hands the packet to the tproxy target while setting the mark. There is a second chain, output, which is commented as being for local mode only.

The bypass sets are the interesting part, because they list the ranges that must never be proxied: the private IPv4 ranges, the loopback, link-local, the shared address space, several documentation and test ranges, multicast and the reserved block, and the equivalent IPv6 sets including the loopback, the IPv4-mapped range, the translation prefix, the unique local range, the link-local range and the multicast range.

The policy routing that goes with it is four commands, two for IPv4 and two for IPv6:

ip rule add fwmark 1088/0x7ff table 100
ip route add local default dev lo table 100
ip -6 rule add fwmark 1088/0x7ff table 100
ip -6 route add local default dev lo table 100

The fwmark matches the port number, 1088, and the mask 0x7ff, and the route is a local default through the loopback device in table 100. That is the whole trick: the firewall marks the packet, the routing rule sends marked packets to the local table, and the local route sends them to loopback, where the proxy is listening.

The iptables route is the older equivalent, and it uses ipset to hold the bypass lists rather than nftables sets, with one set per family. The netfilter rules then match on the mark, return for the bypass sets, and use the TPROXY target for tcp and for udp with the same on-port and tproxy-mark values.

The nftables version is the one to prefer on a current system, and the ipset version exists for the older distributions and for the OpenWrt case.

Running it, and the capabilities the binary needs

The run step grants the binary the two capabilities it needs and then points it at the config file:

# Capabilities
setcap cap_net_admin,cap_net_bind_service+ep bin/hev-socks5-tproxy
bin/hev-socks5-tproxy conf/main.yml

The capabilities are cap_net_admin, which is what the tproxy operations require, and cap_net_bind_service, which is what lets it bind the low ports in the configuration. Setting them with setcap rather than running the whole thing as root is the point of the exercise, and the binary is started with the path to the YAML file.

The Makefile shows the build layout in more detail. The project is named hev-socks5-tproxy, the compiler and linker are plain gcc and cpp with a cross compile prefix, and the flags are -O3, -pipe, -Wall and -Werror. There is a conditional flag for stack clash protection that is added only if the compiler actually supports it, which is checked by compiling a trivial program against the flag, so the build works on compilers that do not have it.

The link line pulls in the YAML library and the hev-task-system library, both from the third-part directory, along with pthreads, and the include paths reference the misc and core include directories plus the two third party sources. The output directories are set out separately, with bin, conf, build and third-part, and the install prefix is /usr/local.

The release history is quick. Version 2.12.0 came out on 2026-07-20, 2.13.0 on 2026-08-05 and 2.13.1 on 2026-08-12, and the last push was on 2026-10-20. Three releases inside a month on a component that sits in the network path of a router is a fairly active maintenance rate, which is reassuring for something that has to keep working with nftables changes and with the SOCKS5 servers people point it at.

Editorial conclusion

hev-socks5-tproxy suits someone running a small Linux router or OpenWrt box who wants every device on the network to share one SOCKS5 upstream without configuring a proxy on each client, because the interception happens in the routing layer rather than per application. It does not suit you if you need per-application or per-user policy, since the redirect rules in the README are host based, and it does not suit you if the SOCKS5 server does not support UDP relay, since the UDP path depends on it. Before you deploy it, read the topology diagram in the README carefully, because the DNS arrangement differs between bridged and gateway mode, and note that the release cadence is fast, with three 2.12 and 2.13 releases in a single month.

Frequently asked questions

Official sources

1. heiher/hev-socks5-tproxy on GitHub
2. Issues
3. License: MIT
4. README
5. Releases