tun2socks

https://github.com/xjasonlyu/tun2socks
Admin
A transparent proxy that routes all network traffic from any application through...
Tokens:36,938
Snippets:682
Trust Score:9.6
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Quickstart Command

Source: https://github.com/xjasonlyu/tun2socks/wiki/Home

A command-line example to start tun2socks, creating a TUN device and connecting to a SOCKS5 proxy.

```sh
tun2socks --device tun://tun0 --proxy socks5://1.2.3.4:1080
```

--------------------------------

### Setup with Interface Binding Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/dialer.md

Example function demonstrating setup with interface binding and optional routing mark.

```go
func setupDialer(interfaceName string, fwmark int) error {
    // Get interface
    iface, err := net.InterfaceByName(interfaceName)
    if err != nil {
        return err
    }
    
    // Register options on global dialer
    dialer.Reset()
    dialer.RegisterSockOpt(dialer.WithBindToInterface(iface))
    if fwmark > 0 {
        dialer.RegisterSockOpt(dialer.WithRoutingMark(fwmark))
    }
    return nil
}

// Use with dialer.DialContext()
```

--------------------------------

### Server Initialization Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example of how to start the REST API server in Go.

```go
go restapi.Start("127.0.0.1:9999", "admin-token-123")
```

--------------------------------

### Windows tun2socks Start Command

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Command to start tun2socks on Windows, assuming wintun is installed.

```shell
tun2socks --device wintun --proxy socks5://host:port --interface "WIFI"
```

--------------------------------

### Programmatic Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/INDEX.md

Example of how to initialize and start the tun2socks engine programmatically using the Go API.

```go
key := &engine.Key{Device: "tun://utun0", Proxy: "socks5://127.0.0.1:1080"}
engine.Insert(key)
engine.Start()
defer engine.Stop()
```

--------------------------------

### Linux TUN Interface Setup

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Commands to create a TUN interface, assign an IP address, and bring it up on Linux.

```shell
ip tuntap add mode tun dev tun0
ip addr add 198.18.0.1/15 dev tun0
ip link set dev tun0 up
```

--------------------------------

### Linux tun2socks Start Command

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Command to start tun2socks on Linux, binding it to the primary interface.

```shell
tun2socks --device tun0 --proxy socks5://host:port --interface eth0
```

--------------------------------

### macOS tun2socks Start Command

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Command to start tun2socks on macOS, which creates the TUN interface.

```shell
tun2socks --device utun123 --proxy socks5://host:port --interface en0
```

--------------------------------

### Device Configuration Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of different formats for the device configuration.

```bash
tun://utun0              # macOS
tun://tun0               # Linux
tun:///dev/net/tun       # Linux alternate
fd://3                   # File descriptor 3
direct                   # Assumes tun://direct
```

```bash
--device tun://utun0
```

--------------------------------

### Interface Binding Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of setting the network interface to bind outbound connections to.

```bash
--interface eth0        # Linux
--interface en0         # macOS
--interface Ethernet    # Windows
```

--------------------------------

### Addr() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for Addr.

```go
netAddr := m.Addr()
// Can be used wherever net.Addr is expected
```

--------------------------------

### Example config.yaml

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

An example of a YAML configuration file.

```yaml
device: tun://utun0
proxy: socks5://127.0.0.1:1080
mtu: 1500
logLevel: info
restapi: 127.0.0.1:9999
interface: eth0
fwmark: 0x1234
tcp-send-buffer-size: 256K
tcp-receive-buffer-size: 256K
tun-pre-up: "ip link set utun0 up"
tun-post-up: "route add 0.0.0.0 255.0.0.0 via 127.0.0.1"
multicast-groups:
  - 224.0.0.1
  - 224.0.0.251
```

--------------------------------

### Log Level Configuration Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of different log levels.

```bash
--loglevel debug    # Verbose output
--loglevel info     # Standard output (default)
--loglevel silent   # No output
```

--------------------------------

### TUN Pre-Up Hook Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of shell commands to execute before the TUN device is brought up.

```bash
--tun-pre-up "ip link add utun0 type tun"
--tun-pre-up "mkdir -p /tmp/tun2socks"
```

--------------------------------

### MTU Configuration Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of different values for the MTU setting.

```bash
--mtu 1500      # Standard Ethernet MTU
--mtu 9000      # Jumbo frames
--mtu 0         # Auto-detect (default)
```

--------------------------------

### Proxy Configuration Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of different formats for the proxy configuration.

```bash
# SOCKS5 (no auth)
socks5://127.0.0.1:1080

# SOCKS5 with auth
socks5://user:pass@127.0.0.1:1080

# HTTP proxy
http://proxy.example.com:8080

# Direct (transparent proxy mode)
direct://

# Shadowsocks with AES-256-GCM
ss://aes-256-gcm:password123@127.0.0.1:8388
```

```bash
--proxy socks5://127.0.0.1:1080
```

--------------------------------

### Command-line Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/INDEX.md

Example of how to run tun2socks from the command line with essential options.

```bash
tun2socks --device tun://utun0 --proxy socks5://127.0.0.1:1080 --restapi 127.0.0.1:9999
```

--------------------------------

### Usage Example for ProcessAsync

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Example showing how to start the asynchronous processing of connections.

```go
t := tunnel.New(proxy, manager)
t.ProcessAsync()  // Start processing
// Connections are now routed through proxy
```

--------------------------------

### TUN Post-Up Hook Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of shell commands to execute after the TUN device is successfully brought up.

```bash
--tun-post-up "ip addr add 10.0.0.1/24 dev utun0"
--tun-post-up "ip route add default via 10.0.0.1"
```

--------------------------------

### UDPAddr() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for UDPAddr.

```go
udpAddr := m.UDPAddr()
if udpAddr != nil {
    // Valid UDP address
}
```

--------------------------------

### SourceAddress() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for SourceAddress.

```go
addr := m.SourceAddress()
// "203.0.113.1:54321"
```

--------------------------------

### Command-Line Flags Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of running tun2socks with command-line flags.

```bash
tun2socks \
  --device tun://utun0 \
  --proxy socks5://127.0.0.1:1080 \
  --mtu 1500 \
  --loglevel info
```

--------------------------------

### Firewall Mark Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of setting the firewall MARK for outbound connections on Linux/BSD.

```bash
--fwmark 0x1234         # Mark with 0x1234
--fwmark 4660           # Decimal equivalent (4660 = 0x1234)
```

--------------------------------

### Install using go install

Source: https://github.com/xjasonlyu/tun2socks/wiki/Install-from-Source

Installs the latest version of tun2socks using the go install command.

```shell
go install github.com/xjasonlyu/tun2socks/v2@latest
```

--------------------------------

### YAML Configuration Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/INDEX.md

Example of a basic tun2socks configuration file in YAML format.

```yaml
device: tun://utun0
proxy: socks5://127.0.0.1:1080
tcp-send-buffer-size: 256K
tcp-receive-buffer-size: 256K
```

--------------------------------

### Network.String() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for Network.String().

```go
m := &metadata.Metadata{Network: metadata.TCP}
m.Network.String()  // "tcp"
```

--------------------------------

### DestinationAddress() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for DestinationAddress.

```go
m := &metadata.Metadata{
    DstIP: netip.MustParseAddr("192.0.2.1"),
    DstPort: 443,
}
addr := m.DestinationAddress()
// addr == "192.0.2.1:443"
```

--------------------------------

### Build and install tun2socks

Source: https://github.com/xjasonlyu/tun2socks/wiki/Install-from-Source

Builds the tun2socks binary and copies it to the system's PATH.

```shell
make tun2socks
sudo cp ./build/tun2socks /usr/local/bin
```

--------------------------------

### Command-Line Usage with Config File

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example command to start tun2socks using a configuration file.

```bash
tun2socks --config config.yaml
```

--------------------------------

### Protocol Registration Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/proxy.md

Example of how a proxy protocol is registered during package initialization.

```go
func init() {
    proxy.RegisterProtocol("socks5", Parse)
}
```

--------------------------------

### SourceAddrPort() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for SourceAddrPort.

```go
ap := m.SourceAddrPort()
```

--------------------------------

### UDP Session Timeout Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of setting the timeout for UDP sessions.

```bash
--udp-timeout 30s       # 30 seconds
--udp-timeout 1m        # 1 minute
--udp-timeout 5m        # 5 minutes
```

--------------------------------

### TCP Send Buffer Size Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of setting the TCP send buffer size.

```bash
--tcp-sndbuf 64K        # 64 kilobytes
--tcp-sndbuf 256K       # 256 kilobytes (recommended)
--tcp-sndbuf 1M         # 1 megabyte
```

--------------------------------

### TCP Receive Buffer Size Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of setting the TCP receive buffer size.

```bash
--tcp-rcvbuf 64K        # 64 kilobytes
--tcp-rcvbuf 256K       # 256 kilobytes (recommended)
```

--------------------------------

### REST API Server Configuration Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Examples of different addresses for the REST API server.

```bash
--restapi 127.0.0.1:9999              # No authentication
--restapi admin-token@127.0.0.1:9999  # With token
--restapi :9999                       # All interfaces
--restapi localhost:8080              # IPv4 localhost
```

--------------------------------

### DestinationAddrPort() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for DestinationAddrPort.

```go
m := &metadata.Metadata{
    DstIP: netip.MustParseAddr("192.0.2.1"),
    DstPort: 443,
}
ap := m.DestinationAddrPort()
// ap.String() == "192.0.2.1:443"
```

--------------------------------

### Build for all architectures

Source: https://github.com/xjasonlyu/tun2socks/wiki/Install-from-Source

Builds tun2socks binaries for all supported architectures.

```shell
make all-arch
```

--------------------------------

### Command-Line Usage: SOCKS5 Proxy

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example command to start tun2socks with a SOCKS5 proxy.

```bash
# SOCKS5 proxy
tun2socks \
  --device tun://utun0 \
  --proxy socks5://127.0.0.1:1080 \
  --restapi 127.0.0.1:9999
```

--------------------------------

### Parse Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/proxy.md

Example of how to parse a proxy URL into a Proxy instance.

```go
u, _ := url.Parse("socks5://127.0.0.1:1080")
p, err := proxy.Parse(u)
if err != nil {
    return err
}
```

--------------------------------

### TCPAddr() usage example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Usage example for TCPAddr.

```go
tcpAddr := m.TCPAddr()
if tcpAddr != nil {
    // Valid TCP address
    addr := net.DialTCP("tcp", nil, tcpAddr)
}
```

--------------------------------

### DialContext Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/dialer.md

Example of how to use the DialContext method.

```go
d := dialer.New(dialer.WithRoutingMark(0x1234))
conn, err := d.DialContext(ctx, "tcp", "example.com:80")
```

--------------------------------

### Version Flag Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of using the --version flag to print version information.

```bash
tun2socks --version
# Output:
# v2.5.0
# revision: abc123def456
# date: 2026-05-26T10:30:00Z
```

--------------------------------

### RegisterProtocol Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/proxy.md

Example of how to register a new proxy protocol handler.

```go
proxy.RegisterProtocol("socks5", func(u *url.URL) (proxy.Proxy, error) {
    return socks5.Parse(u)
})
```

--------------------------------

### Command-Line Usage: HTTP Proxy with Auth

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example command to start tun2socks with an HTTP proxy requiring authentication.

```bash
# HTTP proxy with auth
tun2socks \
  --device tun://tun0 \
  --proxy http://user:pass@proxy.example.com:8080 \
  --tcp-sndbuf 256K \
  --tcp-rcvbuf 256K
```

--------------------------------

### Multicast Groups CLI Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of specifying multicast groups to join on the TUN device NIC using the command-line flag.

```bash
--multicast-groups 224.0.0.1,224.0.0.251
```

--------------------------------

### Integration Pattern

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core.md

Example of how to create a stack within an engine, configuring various handlers and options.

```go
stack, err := core.CreateStack(&core.Config{
    LinkEndpoint:     device,           // TUN or FD device
    TransportHandler: tunnel.T(),       // Routes TCP/UDP
    ICMPHandler:      customICMP,       // Optional ICMP handler
    MulticastGroups:  multicastAddrs,   // Optional multicast
    Options: []option.Option{
        option.WithTCPModerateReceiveBuffer(true),
        option.WithTCPSendBufferSize(256 * 1024),
    },
})
```

--------------------------------

### Engine Configuration Key

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example of how to configure the engine using the `engine.Key` struct, which unifies CLI flags, YAML files, and programmatic setup.

```go
key := &engine.Key{
    Device: "tun://utun0",           // TUN device
    Proxy: "socks5://127.0.0.1:1080", // Proxy URL
    LogLevel: "info",                // Logging verbosity
    RestAPI: "127.0.0.1:9999",       // API server address
}
engine.Insert(key)
engine.Start()
```

--------------------------------

### NewUDPTracker Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example of how to use NewUDPTracker.

```go
baseConn, _ := net.ListenPacket("udp", "127.0.0.1:5353")
tracked := statistic.NewUDPTracker(baseConn, metadata, manager)
// Use tracked like normal net.PacketConn
n, _ := tracked.WriteTo(data, addr)  // Automatically tracked
```

--------------------------------

### NewTCPTracker Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example of how to use NewTCPTracker.

```go
baseConn, _ := net.Dial("tcp", "example.com:80")
tracked := statistic.NewTCPTracker(baseConn, metadata, manager)
// Use tracked like normal net.Conn, statistics auto-updated
n, _ := tracked.Write(data)  // Automatically tracked
```

--------------------------------

### YAML Configuration File Approach

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of using a YAML file for configuration and running tun2socks with it.

```bash
# config.yaml
device: tun://utun0
proxy: socks5://127.0.0.1:1080
restapi: 127.0.0.1:9999
tcp-send-buffer-size: 256K
tcp-receive-buffer-size: 256K

# Run with config
tun2socks --config config.yaml
```

--------------------------------

### Clone the project source code

Source: https://github.com/xjasonlyu/tun2socks/wiki/Install-from-Source

Clones the tun2socks project repository from GitHub.

```shell
git clone https://github.com/xjasonlyu/tun2socks.git
```

--------------------------------

### Infof Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of using Infof to log engine configuration.

```go
log.Infof("[ENGINE] configured device: %s", deviceName)
```

--------------------------------

### Start Function

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/engine.md

Starts the default engine with the configuration previously set via Insert(). Blocks and handles all error cases fatally via logging. Must be called after Insert() to initialize the network stack, device, and proxy.

```Go
func Start(){
}
```

```Go
engine.Insert(key)
engine.Start()
defer engine.Stop()
```

--------------------------------

### Starting the Engine - Programmatic Steps

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Step-by-step Go code for initializing and starting the tun2socks engine.

```go
// 1. Create configuration
key := &engine.Key{...}

// 2. Load configuration
engine.Insert(key)

// 3. Start
engine.Start()

// 4. Stop (cleanup)
defer engine.Stop()
```

--------------------------------

### Example YAML Configuration

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/engine.md

Example YAML configuration for the Key struct.

```YAML
device: tun://utun0
proxy: socks5://127.0.0.1:1080
logLevel: info
mtu: 1500
tcp-send-buffer-size: "256K"
tcp-receive-buffer-size: "256K"
restapi: 127.0.0.1:9999
```

--------------------------------

### Fatalf Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of using Fatalf when configuration is not loaded.

```go
if key == nil {
    log.Fatalf("Configuration not loaded: %v", err)
}
```

--------------------------------

### Usage Example for New Tunnel

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Example demonstrating how to create and initialize a new Tunnel instance.

```go
import "github.com/xjasonlyu/tun2socks/v2/tunnel"
import "github.com/xjasonlyu/tun2socks/v2/tunnel/statistic"

proxy := socks5.New("127.0.0.1:1080", "", "")
mgr := statistic.DefaultManager
tun := tunnel.New(proxy, mgr)
tun.ProcessAsync()
```

--------------------------------

### Configuration File Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example YAML configuration file for tun2socks.

```yaml
# config.yaml
device: tun://utun0
proxy: socks5://127.0.0.1:1080
logLevel: info
restapi: 127.0.0.1:9999
tcp-send-buffer-size: 256K
tcp-receive-buffer-size: 256K
tcp-auto-tuning: true
tun-post-up: "ip route add 0.0.0.0/0 dev utun0"
```

--------------------------------

### Custom Dialer Instance Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/dialer.md

Example of creating an isolated dialer instance with specific options.

```go
// Create isolated dialer with specific options
customDialer := dialer.New(
    dialer.WithRoutingMark(0x1234),
)
conn, err := customDialer.DialContext(ctx, "tcp", "example.com:80")
```

--------------------------------

### GET / Endpoint Response Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example JSON response for the root endpoint.

```json
{
  "hello": "tun2socks"
}
```

--------------------------------

### Stack Options

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core.md

Examples of common functional options to customize stack behavior.

```go
option.WithTCPModerateReceiveBuffer(true)       // Auto-tune TCP buffers
option.WithTCPSendBufferSize(256 * 1024)        // 256KB send buffer
option.WithTCPReceiveBufferSize(256 * 1024)     // 256KB receive buffer
option.WithTCPCongestionControl("cubic")        // CUBIC congestion control
option.WithForwarding(true)                     // Enable IP forwarding
option.WithDefaultTTL(64)                       // Default TTL value
option.WithICMPBurst(50)                        // ICMP burst limit
option.WithICMPLimit(1000)                      // ICMP rate limit
```

--------------------------------

### Windows Default Route Configuration

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Command to route default traffic to the TUN interface on Windows.

```shell
netsh interface ipv4 add route 0.0.0.0/0 "wintun" 192.168.123.1 metric=1
```

--------------------------------

### GET / Endpoint Request Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example HTTP request for the root endpoint.

```http
GET / HTTP/1.1
Authorization: Bearer <token>
```

--------------------------------

### Windows DNS Configuration

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Command to set the DNS address for the wintun interface on Windows.

```shell
netsh interface ipv4 set dnsservers name="wintun" static address=8.8.8.8 register=none validate=no
```

--------------------------------

### macOS TUN Interface Configuration

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Commands to bring up the TUN interface and assign addresses on macOS.

```shell
sudo ifconfig utun123 198.18.0.1 198.18.0.1 up
```

--------------------------------

### Integration with CreateStack

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example of passing core options to the `core.CreateStack()` function.

```go
stack, err := core.CreateStack(&core.Config{
    LinkEndpoint: device,
    TransportHandler: tunnel.T(),
    Options: []option.Option{
        option.WithDefault(),
        option.WithTCPSendBufferSize(256 * 1024),
        option.WithTCPModerateReceiveBuffer(true),
    },
})
```

--------------------------------

### Warnf Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of using Warnf to log a connection timeout.

```go
log.Warnf("Connection timeout: %v", err)
```

--------------------------------

### GET /traffic Endpoint Request Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example HTTP request for the traffic endpoint.

```http
GET /traffic HTTP/1.1
Authorization: Bearer <token>
```

--------------------------------

### Programmatic Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example demonstrating how to use the tun2socks engine programmatically in Go.

```go
package main

import (
    "github.com/xjasonlyu/tun2socks/v2/engine"
)

func main() {
    key := &engine.Key{
        Device: "tun://utun0",
        Proxy: "socks5://127.0.0.1:1080",
        LogLevel: "info",
        RestAPI: "127.0.0.1:9999",
    }
    
    engine.Insert(key)
    engine.Start()
    defer engine.Stop()
    
    // Server runs in background
    select {}
```

--------------------------------

### REST API Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/engine.md

Examples of REST API formats, including authentication.

```text
127.0.0.1:9999                    # No auth required
token@127.0.0.1:9999             # Token auth via header
http://admin@127.0.0.1:9999      # User portion used as token
```

--------------------------------

### Configuration File Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of using the --config flag to specify a YAML configuration file.

```bash
--config /etc/tun2socks/config.yaml
```

--------------------------------

### Usage Example for ParseLevel

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of how to use the ParseLevel function to set the log level.

```go
level, err := log.ParseLevel("info")
if err != nil {
    return err
}
```

--------------------------------

### Example TUN Post UP Script

Source: https://github.com/xjasonlyu/tun2socks/wiki/TUN-Pre-and-Post-UP

Demonstrates how to use the tun-post-up argument to execute a script after the TUN device is created.

```shell
--tun-post-up "./your_script.sh"
```

--------------------------------

### GET /version Endpoint Request Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example HTTP request for the version endpoint.

```http
GET /version HTTP/1.1
Authorization: Bearer <token>
```

--------------------------------

### Internal Usage Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Examples demonstrating the internal usage of the log module throughout tun2socks, showing the '[COMPONENT]' prefix pattern.

```go
// Engine startup
log.Infof("[ENGINE] failed to start: %v", err)

// Device configuration
log.Infof("[DIALER] bind to interface: %s", iface.Name)

// Proxy setup
log.Infof("[STACK] %s <-> %s", k.Device, k.Proxy)

// Errors
log.Errorf("[TUN] failed to pre-execute: %s: %v", cmd, err)
```

--------------------------------

### PushDownloaded Method Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example usage of the PushDownloaded method.

```go
// Called by connection trackers
manager.PushDownloaded(len(data))
```

--------------------------------

### Debugf Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of using Debugf to log connection details.

```go
log.Debugf("Connection from %s to %s", src, dst)
```

--------------------------------

### Now Method Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example usage of the Now method.

```go
up, down := manager.Now()
// up and down are bytes transferred in the last second
```

--------------------------------

### Multicast Groups YAML Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of specifying multicast groups to join on the TUN device NIC using YAML configuration.

```yaml
multicast-groups:
  - 224.0.0.1
  - 224.0.0.251
  - ff02::1
```

--------------------------------

### Error Handling in CreateStack

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example demonstrating how errors from `core.CreateStack()` are propagated and handled.

```go
stack, err := core.CreateStack(&cfg)
if err != nil {
    // error applying one of the options
    log.Fatalf("Failed to create stack: %v", err)
}
```

--------------------------------

### Usage Example for UDPIn

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Demonstrates direct access to the UDP input queue.

```go
t.UDPIn() <- conn
```

--------------------------------

### REST API Endpoint: GET /netstats

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example curl command to get network stack statistics.

```bash
curl -H "Authorization: Bearer token" http://127.0.0.1:9999/netstats
```

--------------------------------

### Usage Example for Global Tunnel Access

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Example showing how to interact with the global tunnel instance.

```go
tunnel.T().SetProxy(newProxy)
tunnel.T().SetUDPTimeout(5 * time.Second)
```

--------------------------------

### WithBindToInterface Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/dialer.md

Example of using WithBindToInterface to bind sockets to a specific network interface.

```go
iface, _ := net.InterfaceByName("eth0")
dialer.RegisterSockOpt(dialer.WithBindToInterface(iface))
// All outbound connections use eth0
```

--------------------------------

### REST API Endpoint: GET /connections

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example curl command to get active connection snapshots.

```bash
curl -H "Authorization: Bearer token" http://127.0.0.1:9999/connections
```

--------------------------------

### Proxy URL Examples

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/engine.md

Examples of different proxy URL formats supported by the engine.

```text
127.0.0.1:1080                    # Defaults to socks5://
socks5://127.0.0.1:1080
socks5://user:pass@127.0.0.1:1080
http://proxy.example.com:8080
direct://                         # Direct connection
```

--------------------------------

### SetLogger Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of setting a new leveled logger.

```go
logger, err := log.NewLeveled(log.InfoLevel)
if err != nil {
    panic(err)
}
log.SetLogger(logger)
```

--------------------------------

### REST API Endpoint: GET /traffic

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example curl command to get per-second traffic statistics.

```bash
curl -H "Authorization: Bearer token" http://127.0.0.1:9999/traffic
```

--------------------------------

### TUN Device with GUID Option (Windows)

Source: https://github.com/xjasonlyu/tun2socks/wiki/Device-Models

Example of configuring a TUN device with a persistent GUID on Windows.

```bash
tun://wintun?guid={7FE5A4A1-1326-40E2-974C-EF617156ACA8}
```

--------------------------------

### Creating Metadata for UDP Connection

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Example of creating Metadata for a UDP connection and using it with a proxy.

```go
metadata := &metadata.Metadata{
    Network: metadata.UDP,
    SrcIP: netip.MustParseAddr("10.0.0.2"),
    SrcPort: 53,
    DstIP: netip.MustParseAddr("1.1.1.1"),
    DstPort: 53,
}

// Use with proxy
pc, err := proxyInstance.DialUDP(metadata)
```

--------------------------------

### Usage Example for Replacing Global Tunnel

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Example demonstrating how to replace the global tunnel and restore it later.

```go
oldTunnel := tunnel.T()
newTunnel := tunnel.New(proxy, manager)
restore := tunnel.ReplaceGlobal(newTunnel)
defer restore()
```

--------------------------------

### GET /connections Endpoint WebSocket Response Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example JSON response for the connections endpoint via WebSocket streaming.

```json
{"same format as HTTP response"}
```

--------------------------------

### Usage Example for TCPIn

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Demonstrates direct access to the TCP input queue.

```go
t.TCPIn() <- conn
```

--------------------------------

### WithRoutingMark Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/dialer.md

Example of using WithRoutingMark to set the Linux firewall MARK socket option.

```go
// Route outbound connections with mark 0x1234
dialer.RegisterSockOpt(dialer.WithRoutingMark(0x1234))
```

--------------------------------

### NewLeveled Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of creating and setting a new logger with a parsed level.

```go
level, err := log.ParseLevel("info")
if err != nil {
    return err
}
logger, err := log.NewLeveled(level)
if err != nil {
    return err
}
log.SetLogger(logger)
```

--------------------------------

### Go Usage Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example Go code demonstrating how to retrieve and print statistics using the tun2socks library.

```go
import (
    "github.com/xjasonlyu/tun2socks/v2/tunnel"
    "github.com/xjasonlyu/tun2socks/v2/tunnel/statistic"
)

func printStats() {
    snap := statistic.DefaultManager.Snapshot()
    
    // Lifetime traffic
    fmt.Printf("Uploaded: %d bytes\n", snap.UploadTotal)
    fmt.Printf("Downloaded: %d bytes\n", snap.DownloadTotal)
    
    // Active connections
    fmt.Printf("Active connections: %d\n", len(snap.Connections))
    
    // Per-second traffic
    up, down := statistic.DefaultManager.Now()
    fmt.Printf("Per-second - Up: %d, Down: %d\n", up, down)
}
```

--------------------------------

### TCP Auto-Tuning Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Example of enabling TCP receive buffer auto-tuning.

```bash
--tcp-auto-tuning       # Enable auto-tuning
```

--------------------------------

### GET /connections Endpoint HTTP Response Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example JSON response for the connections endpoint via HTTP polling.

```json
{
  "uploadTotal": 1048576,
  "downloadTotal": 2097152,
  "connections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "start": "2026-05-26T10:30:00Z",
      "metadata": {
        "network": "tcp",
        "sourceIP": "10.0.0.2",
        "sourcePort": 54321,
        "dialerIP": "10.0.0.2",
        "dialerPort": 0,
        "destinationIP": "192.0.2.1",
        "destinationPort": 443
      },
      "upload": 5120,
      "download": 10240
    }
  ]
}
```

--------------------------------

### WithTCPReceiveBufferSizeRange Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example usage for setting TCP receive buffer range.

```go
option.WithTCPReceiveBufferSizeRange(4096, 256*1024, 2*1024*1024)
```

--------------------------------

### GET /traffic Endpoint WebSocket Response Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example JSON response for the traffic endpoint via WebSocket streaming.

```json
{"up": 1024, "down": 2048}
```

--------------------------------

### WithTCPRecovery Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example usage for setting TCP loss recovery algorithm.

```go
option.WithTCPRecovery(tcpip.TCPRACKLossDetection)
```

--------------------------------

### Linux Default Route Configuration

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Commands to modify the default route table with different metrics on Linux.

```shell
ip route del default
ip route add default via 198.18.0.1 dev tun0 metric 1
ip route add default via 172.17.0.1 dev eth0 metric 10
```

--------------------------------

### Creating Metadata for TCP Connection

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/metadata.md

Example of creating Metadata for a TCP connection and using it with a proxy.

```go
metadata := &metadata.Metadata{
    Network: metadata.TCP,
    SrcIP: netip.MustParseAddr("10.0.0.2"),
    SrcPort: 54321,
    DstIP: netip.MustParseAddr("192.0.2.1"),
    DstPort: 443,
}

// Use with proxy
conn, err := proxyInstance.DialContext(ctx, metadata)
```

--------------------------------

### Join Method Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example usage of the Join method.

```go
// Called automatically by NewTCPTracker/NewUDPTracker
tracker := statistic.NewTCPTracker(conn, metadata, manager)
// manager.Join(tracker) is called internally
```

--------------------------------

### PushUploaded Method Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example usage of the PushUploaded method.

```go
// Called by connection trackers
manager.PushUploaded(len(data))
```

--------------------------------

### Basic Logging in Startup

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/log.md

Example of setting up the logger with a log level parsed from an environment variable during application startup.

```go
func main() {
    // Parse and set log level
    level, err := log.ParseLevel(os.Getenv("LOG_LEVEL"))
    if err != nil {
        log.SetLogger(log.Must(log.NewLeveled(log.InfoLevel)))
    } else {
        log.SetLogger(log.Must(log.NewLeveled(level)))
    }
    
    log.Infof("[MAIN] Starting application")
}
```

--------------------------------

### GET /traffic Endpoint HTTP Response Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example JSON response for the traffic endpoint via HTTP polling.

```json
{
  "up": 1024,
  "down": 2048
}
```

--------------------------------

### Usage Example for HandleTCP

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Illustrates how HandleTCP is typically called by the network stack.

```go
// Called by network stack, not typically called directly
tunnel.T().HandleTCP(incomingConn)
```

--------------------------------

### GET /version Endpoint Response Example

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

Example JSON response for the version endpoint, including application version, git commit, and module information.

```json
{
  "version": "2.5.0",
  "commit": "abc123def456",
  "modules": [
    {
      "path": "github.com/xjasonlyu/tun2socks/v2",
      "version": "v2.5.0"
    },
    {
      "path": "gvisor.dev/gvisor",
      "version": "v0.0.0-20260506221003"
    }
  ]
}
```

--------------------------------

### WithTCPModerateReceiveBuffer Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example usage for enabling TCP receive buffer auto-tuning.

```go
option.WithTCPModerateReceiveBuffer(true)  // Enable auto-tuning
```

--------------------------------

### Statistics Snapshot

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/README.md

Example of capturing and printing connection statistics.

```go
snap := statistic.DefaultManager.Snapshot()
fmt.Printf("Total uploaded: %d bytes\n", snap.UploadTotal)
fmt.Printf("Active connections: %d\n", len(snap.Connections))
```

--------------------------------

### Usage Example for HandleUDP

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/tunnel.md

Illustrates how HandleUDP is typically called by the network stack.

```go
// Called by network stack, not typically called directly
tunnel.T().HandleUDP(incomingConn)
```

--------------------------------

### WithTCPDelay Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example usage for enabling or disabling Nagle's algorithm.

```go
option.WithTCPDelay(false)  // Disable Nagle (recommended)
option.WithTCPDelay(true)   // Enable Nagle (conservative)
```

--------------------------------

### GET /traffic Usage Example (WebSocket)

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

JavaScript code to connect to the traffic endpoint via WebSocket.

```javascript
const ws = new WebSocket("ws://127.0.0.1:9999/traffic?token=token");
ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log(`Up: ${data.up}, Down: ${data.down}`);
};
```

--------------------------------

### Snapshot Method Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/statistics.md

Example usage of the Snapshot method.

```go
snap := manager.Snapshot()
log.Printf("Total uploaded: %d bytes", snap.UploadTotal)
log.Printf("Active connections: %d", len(snap.Connections))
for _, conn := range snap.Connections {
    // Process connection info
}
```

--------------------------------

### WithTCPCongestionControl Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example usage for selecting TCP congestion control algorithm.

```go
option.WithTCPCongestionControl("cubic")  // Modern, higher throughput
option.WithTCPCongestionControl("reno")   // Conservative, stable
```

--------------------------------

### GET /connections Usage Example (WebSocket)

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/endpoints.md

JavaScript code to connect to the connections endpoint via WebSocket with a custom interval.

```javascript
const ws = new WebSocket("ws://127.0.0.1:9999/connections?token=token&interval=500");
```

--------------------------------

### WithTCPSendBufferSizeRange Usage

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example usage for setting TCP send buffer range.

```go
option.WithTCPSendBufferSizeRange(4096, 256*1024, 2*1024*1024)
// Min 4KB, default 256KB, max 2MB
```

--------------------------------

### Windows Interface IP Assignment

Source: https://github.com/xjasonlyu/tun2socks/wiki/Examples

Command to assign a static IP address to the wintun interface on Windows.

```shell
netsh interface ipv4 set address name="wintun" source=static addr=192.168.123.1 mask=255.255.255.0
```

--------------------------------

### With REST API and Buffer Tuning

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Configuration including REST API and TCP buffer tuning.

```bash
tun2socks \
  --device tun://utun0 \
  --proxy socks5://127.0.0.1:1080 \
  --restapi admin-token@127.0.0.1:9999 \
  --tcp-sndbuf 256K \
  --tcp-rcvbuf 256K \
  --tcp-auto-tuning
```

--------------------------------

### Multiple Commands with TUN Post UP (Windows)

Source: https://github.com/xjasonlyu/tun2socks/wiki/TUN-Pre-and-Post-UP

Illustrates executing multiple commands using 'powershell -Command' with the tun-post-up argument on Windows.

```powershell
--tun-post-up "powershell -Command 'command1 ; command2 ; command3'"
```

--------------------------------

### Stack Lifecycle

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core.md

Demonstrates the typical lifecycle of a stack: creation, usage, and cleanup.

```go
// Create
stack, err := core.CreateStack(cfg)

// Use (handled by engine)
// stack processes packets from device
// and calls handlers for connections

// Cleanup
stack.Close()      // Gracefully close
stack.Wait()       // Wait for cleanup
```

--------------------------------

### Multiple Commands with TUN Post UP (Linux)

Source: https://github.com/xjasonlyu/tun2socks/wiki/TUN-Pre-and-Post-UP

Shows how to execute multiple commands sequentially using 'sh -c' with the tun-post-up argument on Linux.

```shell
--tun-post-up "sh -c 'echo 1234567890 > a.txt && ./run_some_scripts.sh && rm -rf a.txt'"
```

--------------------------------

### Balanced (Typical Internet) Options

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core-option.md

Example of core options for typical internet usage, balancing performance and resource usage.

```go
options := []option.Option{
    option.WithDefault(),
    option.WithTCPSendBufferSize(256 * 1024),    // 256KB
    option.WithTCPReceiveBufferSize(256 * 1024),
    option.WithTCPModerateReceiveBuffer(true),
}
```

--------------------------------

### With HTTP Proxy and Authentication

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Configuration for an HTTP proxy with authentication.

```bash
tun2socks \
  --device tun://tun0 \
  --proxy http://user:pass@proxy.example.com:8080 \
  --loglevel debug
```

--------------------------------

### Basic Transparent Proxy (Linux)

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/configuration.md

Basic configuration for a transparent proxy on Linux.

```bash
tun2socks \
  --device tun://tun0 \
  --proxy socks5://127.0.0.1:1080 \
  --loglevel info
```

--------------------------------

### Start tun2socks service

Source: https://github.com/xjasonlyu/tun2socks/wiki/Use-docker-compose

Command to start the tun2socks service in detached mode using docker-compose.

```sh
docker-compose up -d
```

--------------------------------

### Device Interface

Source: https://github.com/xjasonlyu/tun2socks/blob/main/_autodocs/api-reference/core.md

Combines gVisor's LinkEndpoint with metadata methods for network devices.

```go
type Device interface {
    stack.LinkEndpoint
    Name() string
    Type() string
}
```
Tokens:
Raw