tun2socks Documentation

tun2socks is a universal proxying tool that transparently routes all network traffic from any application through a proxy.

Key capabilities include:

• Multi-Protocol Support: Works with HTTP, SOCKS, Shadowsocks, SSH, and Relay proxies (with optional authentication).
• Cross-Platform: Optimized for Linux, macOS, Windows, FreeBSD, and OpenBSD.
• Gateway Mode: Can act as a Layer 3 gateway to route traffic from other devices on the same network.
• IPv6 Compatibility: Native IPv6 support with seamless tunneling between IPv4 and IPv6.
• User-Space Networking: Uses the gVisor network stack for performance and flexibility.

Detailed technical guides and setup instructions are maintained in the project Wiki. Use the following resources for specific tasks:

• Installation: For building from source, refer to the Install from Source guide.
• Usage Examples: For practical implementation scenarios, see Quickstart Examples.
• Performance Tuning: For guidance on reducing resource usage, see Memory Optimization.

The /traffic endpoint provides real-time network statistics (upload and download bytes). It supports both standard HTTP polling and WebSocket streaming.

• HTTP Polling: Returns a JSON object containing up and down fields. The server flushes the response every second.
• WebSocket Streaming: Upgrades the connection to a WebSocket. The server pushes a JSON message containing up and down every second.

JSON Response Format:

{
  "up": 12345,
  "down": 67890
}

The REST API uses token-based authentication. Depending on the request type, you must provide the token in one of two ways:

1. Standard HTTP Requests: Use the Authorization header with the Bearer scheme.

   • Header format: Authorization: Bearer <your-token>

2. WebSocket Upgrades: Since browsers do not support custom headers for WebSocket connections, provide the token as a query parameter.

   • URL format: ws://<addr>/traffic?token=<your-token>