vproxy - High-Performance eBPF-Powered Transparent Proxy & Dynamic Router

Project Repository: github.com/qtopie/vproxy

Navigating network proxying in modern development environments is notoriously painful. Developers often struggle with heavy global VPNs, brittle environment variables (HTTP_PROXY/HTTPS_PROXY), loop-prone transparent proxies, or unstable upstream connections.

Enter vproxy—a next-generation, high-performance transparent proxy and rule-based router. Crafted in Go and powered by Linux eBPF (Extended Berkeley Packet Filter), vproxy intercepts and routes network traffic transparently at the socket layer. By decoupling the interception mechanism from target applications and introducing kernel-level process-aware routing, it provides a seamless, zero-config, and highly resilient networking experience.

Why Choose vproxy?

Traditional proxy solutions either route all system traffic indiscriminately or rely on applications respecting user-space environment flags. vproxy bypasses these limitations completely by operating at the kernel socket boundary.

Core Features

1. eBPF Socket-Layer Interception: Intercepts TCP connection establishment (connect syscall) inside designated cgroups. Bypasses user-space interception loops completely by utilizing socket marks (SO_MARK).
2. Process-Level Routing Rules: Allows routing rules based on the executable binary’s path or name (e.g., direct only wget or route bin/test_ebpf through a proxy).
3. Dynamic Upstream Failover: Active and passive health probing dynamically monitors the status of multiple SOCKS5/HTTP upstream proxies.
4. Resilient Reconnection & Dial Retries: Re-tries connection attempts automatically, using a fail-fast timeout (defaults to 5 seconds) to ensure that temporary network drops are resolved instantly.
5. MITM HTTPS Inspection & Decoupling: Dynamically signs certificates on the fly to inspect TLS traffic for logging, debugging, or custom proxy-side routing.
6. Triple Interception Engine: Fallback support for legacy Linux environments via iptables (TPROXY/REDIRECT) and cross-platform compatibility utilizing a gVisor TCP/IP TUN stack.

Unmatched Versatility: Multi-Platform & Multi-Mode Support

vproxy is engineered for ultimate flexibility, supporting diverse platforms, networking stack layers, and transport protocols. Whether running on a modern Linux kernel with eBPF, a legacy firewall with iptables, or macOS/Windows via virtual TUN interfaces, vproxy offers robust, uniform coverage.

Features & Capabilities Support Matrix

Technical Deep-Dive: Under the Hood

To appreciate vproxy’s performance and stability, we must look at how it solves kernel-level traffic redirection and maintains connection resilience.

1. eBPF Redirection Architecture

Rather than intercepting packets at the network interface layer (which incurs expensive packet-to-socket demultiplexing overhead), vproxy hooks directly into the socket lifecycle via eBPF program types: sockops and sk_msg.

direction: down

user_space: "User Space" {
  app: "Target Application"
  vproxy: "vproxy daemon"
}

kernel_space: "Kernel Space (eBPF & Sockets)" {
  cgroup: "cgroup v2\n/sys/fs/cgroup/vproxy"
  sockops: "eBPF\nsockops program"
  map: "eBPF Map\naddr_map" {
    shape: page
  }
  redirect: "eBPF\nsk_msg redirect"
}

internet: "Upstream / Internet" {
  shape: cloud
}

user_space.app -> kernel_space.cgroup: "connect()" {
  style.stroke: "#2563eb"
}
kernel_space.cgroup -> kernel_space.sockops: "Triggers"
kernel_space.sockops -> kernel_space.map: "Store connection details"
user_space.app -> kernel_space.redirect: "Sends Payload"
kernel_space.redirect -> user_space.vproxy: "Bypass TCP Stack" {
  style.stroke: "#16a34a"
}
user_space.vproxy -> internet: "Proxies to Upstream"

When an application inside the vproxy cgroup calls connect():

• The sockops eBPF program intercepts the event.
• It stores the socket details, mapping the source IP/port to the original destination IP/port.
• Instead of letting the packet route out of the local network stack, it transparently redirects the connection to the vproxy local transparent listener (running on port 10080).
• To prevent infinite loops (where vproxy itself tries to dial the remote destination and gets intercepted by its own eBPF rule), vproxy dials out using a specific socket mark (SO_MARK). The eBPF program checks for this mark and bypasses redirection for marked sockets.

2. High-Resilience Connection Pipeline

Real-world internet connections are unstable. Latency spikes, packet loss, or crashed upstream servers can cause user applications to hang or crash. vproxy solves this with a multi-layered resilience engine consisting of passive failover, active probing, and dial-level retries with fail-fast timeouts.

shape: sequence_diagram

client: "Target App"
ph: "Proxy Handler"
sm: "Server Manager"
proxies: "Upstream Servers"

client -> ph: "Transparent TCP Connection Request"
ph -> sm: "GetBestServer()"
sm -> ph: "Return Active Upstream (Server A)"

ph -> proxies: "Dial Server A (Timeout: 5s)"
proxies -> ph: "FAIL (unstable network)"
ph -> sm: "ReportFailure(Server A)"

ph -> sm: "GetBestServer() (dynamic)"
sm -> ph: "Return Fallback Server B"
ph -> proxies: "Dial Server B"
proxies -> ph: "SUCCESS"
ph -> sm: "ReportSuccess(Server B)"

ph -> client: "Established transparent tunnel"

A. Dial-Level Retries & Fail-Fast Timeout

Each time vproxy attempts to forward an intercepted socket to an upstream server:

1. It applies a fail-fast timeout (configured by dial_timeout_ms, defaulting to 5 seconds). This is critical: if a proxy route is dead, we want to fail quickly rather than letting the client application hang indefinitely.
2. It wraps the dialing phase (including TCP handshake and SOCKS5/HTTP CONNECT negotiation) under an explicit deadline.
3. If the attempt fails, it will retry up to 3 times by default.

B. Dynamic Upstream Failover Integration

What makes vproxy’s retry mechanism exceptionally robust is its coordination with the ServerManager:

• When an attempt to connect through the active upstream server fails, vproxy immediately calls ReportFailure(failedServer).
• This clears the failed server from the activeServer slot and schedules an asynchronous, high-priority active probe to find the next available healthy upstream server from the list.
• On the next retry attempt (which happens after a short 100ms settle duration), vproxy queries GetBestServer() again. Because the failed server was just cleared, it instantly picks the next healthy fallback proxy!
• The entire failover process happens seamlessly mid-request—the client application is completely unaware that the primary proxy collapsed and traffic was routed through a backup.

Getting Started with vproxy

Setting up vproxy is simple. Below is a guide to building, configuring, and executing it on a Linux system.

1. Build from Source

Ensure you have Go (1.20+) installed on your machine.

# Clone the repository
git clone https://github.com/qtopie/vproxy.git
cd vproxy

# Compile the daemon
make

# Compile the test suite
make build-tests

2. Configure Your Rules (vproxy.json)

vproxy is configured via a simple JSON file. Define your upstream proxies and domain/process-specific routing rules:

{
  "upstreams": [
    "socks5://192.168.50.31:1080",
    "http://127.0.0.1:8080"
  ],
  "rules": [
    "8.8.8.8,DIRECT",
    "google.com,PROXY",
    "FINAL,PROXY",
    "PROCESS,wget,PROXY",
    "PROCESS,bin/test_ebpf,PROXY",
    "PROCESS,/usr/bin/curl,DIRECT"
  ],
  "test_interval": 30,
  "enable_ebpf": true,
  "direct_dns": true,
  "dial_timeout_ms": 5000,
  "dial_retry_count": 3
}

3. Initialize & Run the Daemon

vproxy configures eBPF maps and cgroups automatically during initialization. Because this touches the kernel boundaries, it requires root capabilities:

# Clean and initialize the local TUN and cgroup interfaces
sudo bin/vproxy clean
sudo bin/vproxy init

# Start vproxy and launch a test binary under transparent interception
sudo bin/vproxy -v bin/test_google

Benchmark & Performance Report

To showcase the efficiency of eBPF socket-layer interception over traditional user-space alternatives (like iptables-based routing or proxy wrappers), we performed a simulated throughput test.

System Configuration

• Kernel: Linux 6.8.0-generic
• CPU: AMD Ryzen 7 5800X (8 Cores, 16 Threads)
• Memory: 32GB RAM

Latency Comparison (TTFB)

Operating at the socket layer via sockops reduces the context-switching overhead dramatically, matching the performance of direct env-variable proxying while maintaining 100% transparent interception coverage across all system binaries.

Conclusion: The Ultimate Interceptor

vproxy is more than a simple proxy client; it is an engineering showcase of modern Linux kernel APIs. By combining eBPF socket-layer interception with a highly resilient dynamic retry and failover engine, it provides absolute stability for network routing under unstable conditions.

If you are building microservices, crawling the web, or simply wanting a zero-maintenance transparent router for your local developer setup, vproxy is the ultimate tool.

Check it out, star the repository, and elevate your networking stack:
👉 github.com/qtopie/vproxy