Userspace WireGuard slirp Router

A high-performance, user-space WireGuard router that forwards decrypted IPv4 traffic via generic TCP/UDP/ICMP socket bridges (slirp-style), requiring zero kernel privileges or custom netstacks.

Table of Contents

• Overview
• Architecture
• Installation
  • Using Docker
  • Building from Source
• Quick Start
• Configuration
  • WireGuard Configuration
  • System Configuration
• Usage Examples
• Troubleshooting
• License
• Acknowledgments

Overview

This router combines WireGuard VPN with a userspace networking implementation to provide efficient, secure, container-friendly routing. It uses a slirp-style approach to handle TCP, UDP, and ICMP (when running with CAP_NET_RAW) traffic between WireGuard tunnels and the host network.

Key Features

• WireGuard Integration: Secure, modern VPN tunneling with WireGuard protocol
• User-space Networking: TCP/UDP bridges implemented in userspace
• Protocol Support: Handles TCP, UDP, and ICMP traffic with NAT capabilities
• Performance Monitoring: Built-in metrics collection and reporting
• Health Checking: Integrated health checks for monitoring system status
• Container Ready: Designed to run in containerized environments
• Configurable: Extensive configuration options via environment variables

Architecture

The router consists of several key components:

1. WireGuard Interface: Handles encrypted tunnel traffic using the WireGuard protocol
2. Socket Interface: Manages TCP/UDP bridges for network traffic translation
3. Slirp Bridges: Direct inline delivery between slirp bridges and the processor (No FlowManager or egress limiter — simpler, predictable pipeline).
4. Metrics Reporter: Collects and reports performance metrics

The system uses a packet processing pipeline to efficiently route traffic between WireGuard tunnels and the host network.

graph TD
    A[WireGuard Tunnel] -->|Encrypted| B[WG Interface]
    B -->|Plaintext| C[Packet Processor]
    C -->|IPv4 Packets| D[Socket Interface]
    D -->|TCP| E[TCP Bridge]
    D -->|UDP| F[UDP Bridge]
    D -->|ICMP| G[ICMP Bridge]
    E -->|Return| C
    F -->|Return| C
    G -->|Return| C
    C -->|Encrypted| B
    B -->|WireGuard Protocol| A
    I[Metrics & Health] -.->|Stats| B
    I -.->|Stats| C
    I -.->|Stats| D

Installation

Using Docker

The easiest way to run the router is using Docker:

services:
  wg-router:
    image: ghcr.io/irctrakz/wgslirp:latest
    container_name: wgslirp
    ports:
      - "51820:51820/udp"
    environment:
      
      # Sensible defaults - probably 99% of configs would use this
      - "POOLING=1"
      - "PROCESSOR_WORKERS=8"
      - "PROCESSOR_QUEUE_CAP=4096"
      - "WG_TUN_QUEUE_CAP=2048"
      - "TCP_ACK_DELAY_MS=5"
      - "TCP_ENABLE_SACK=1"
      
      #  If you want tcp / flow debugging enabled 
      #- "METRICS_INTERVAL=60s"
      #- "METRICS_FORMAT=text"
      #- "TCP_GATE_LOG=on"
      - "TCP_GATE_LOG=off"

      # If you want to fill up your logs fast
      #- "DEBUG=1"

      # WG config - this MUST be set
      - "WG_PRIVATE_KEY=<server-private-key>"
      - "WG_LISTEN_PORT=51820"
      - "WG_MTU=1200"
      
      - "WG_PEERS=0"
      - "WG_PEER_0_PUBLIC_KEY=<client-public-key>"
      - "WG_PEER_0_ALLOWED_IPS=10.77.0.2/32"
    restart: "no"

Building from Source

Container is at ghcr.io/irctrakz/wgslirp:latest

To build from source:

# Clone the repository
git clone https://github.com/irctrakz/wgslirp.git
cd wgslirp

# Build the binary
go build -o wgslirp ./cmd/wgslirp

# Or build the Docker image
docker build -t wgslirp -f Dockerfile .

Quick Start

Get up and running quickly with these steps:

1. Generate WireGuard Keys:

   # Generate private key
   wg genkey > private.key
   
   # Generate public key from private key
   cat private.key | wg pubkey > public.key
   
   # View your keys
   echo "Private key: $(cat private.key)"
   echo "Public key: $(cat public.key)"
   

2. Start the Router:

    docker run --name wgslirp \
      -p 51820:51820/udp \
      -e POOLING=1 \
      -e PROCESSOR_WORKERS=8 \
      -e PROCESSOR_QUEUE_CAP=4096 \
      -e WG_TUN_QUEUE_CAP=2048 \
      -e TCP_ACK_DELAY_MS=5 \
      -e TCP_ENABLE_SACK=1 \
      -e TCP_GATE_LOG=off \
      -e WG_PRIVATE_KEY=<private_key> \
      -e WG_LISTEN_PORT=51820 \
      -e WG_MTU=1200 \
      -e WG_PEERS=0 \
      -e WG_PEER_0_PUBLIC_KEY=<public_key> \
      -e WG_PEER_0_ALLOWED_IPS=10.77.0.2/32 \
      --restart=no \
      ghcr.io/irctrakz/wgslirp:latest
   

3. Configure Client: Create a WireGuard client configuration:

   [Interface]
   PrivateKey = <client-private-key>
   Address = 10.77.0.2/32
   DNS = 8.8.8.8
   MTU = 1200
   
   [Peer]
   PublicKey = <your-public-key>
   Endpoint = <your-server-ip>:51820
   AllowedIPs = 0.0.0.0/0
   PersistentKeepalive = 25
   

4. Verify Connection:

   # Check router logs
   docker logs wgslirp
   
   # From client, ping through the tunnel
   ping 10.0.0.1
   

Note: If you're not running with CAP_NET_RAW you can't ping, try a tcp connection

Configuration

The router is configured primarily through environment variables:

WireGuard Configuration

| Environment Variable | Description | Default | |----------------------|-------------|---------| | WG_PRIVATE_KEY | Base64-encoded WireGuard private key (required) | - | | WG_LISTEN_PORT | UDP port for WireGuard to listen on | 51820 | | WG_PEERS | Comma-separated list of peer configurations | - | | WG_OVERLAY_ROUTING | Enable overlay routing mode (1/true/yes/on) | - | | WG_OVERLAY_EXCLUDE_CIDRS | Comma-separated CIDRs to exclude from overlay routing | - |

System Configuration

| Environment Variable | Description | Default | |----------------------|-------------|---------| | DEBUG | Enable debug logging (1/true/yes/on) | - | | METRICS_LOG | Enable metrics logging | - | | METRICS_INTERVAL | Interval for metrics reporting | 30s | | METRICS_FORMAT | Format for metrics output (text/json) | text | | HEALTHCHECK | Enable health checking | - |

Environment Variables (reference)

Core WireGuard (required/primary)

• WG_PRIVATE_KEY: Base64 private key for the device (required).
• WG_LISTEN_PORT: UDP listen port, default 51820.
• WG_MTU: Plaintext MTU for the userspace TUN (default 1380).
• WG_PEERS: Comma-separated peer indices (e.g., 0,1). For each index i:
  • WG_PEER_i_PUBLIC_KEY: base64 peer public key (required for each peer).
  • WG_PEER_i_ALLOWED_IPS: comma-separated CIDRs for overlay routing decisions.
  • WG_PEER_i_ENDPOINT: host:port (optional if static endpoint is used).
  • WG_PEER_i_KEEPALIVE: seconds (optional; typical 25).

Overlay routing (optional)

• WG_OVERLAY_ROUTING: enable overlay re-route for packets destined to AllowedIPs.
• WG_OVERLAY_EXCLUDE_CIDRS: CIDRs that should always egress via slirp.
• WG_DISABLE_IPV6: truthy to attempt disabling IPv6 sysctls (best effort).

Logging and diagnostics

• DEBUG: enable verbose logging and disable packet copy-elision in wrappers.
• WG_DEBUG: verbose wireguard-go logging (chatty).
• WG_PCAP: file path to write plaintext IPv4 frames (DLT_RAW) captured by the userspace TUN.

Metrics and health

• METRICS_LOG: any non-empty value enables periodic metrics logging.
• METRICS_INTERVAL: duration like 15s (default 30s).
• METRICS_FORMAT: text (default) or json.
• HEALTHCHECK: any non-empty value enables auxiliary health probes.
• HEALTH_HTTP_URL: optional HTTP URL to fetch periodically.
• HEALTH_DNS_NAME: optional DNS name to resolve (A-record).
• HEALTH_DNS_IP: optional dotted-quad to check reachability.

Packet processing and TUN (userspace)

• PROCESSOR_WORKERS: number of workers in the socket processor (default 4).
• PROCESSOR_QUEUE_CAP: processor channel capacity (default 1000).
• WG_TUN_QUEUE_CAP: capacity of the WGTun outbound queue to wireguard-go (default 1024).
• POOLING: enable pooled buffers (1/true/on) for lower GC when throughput is high.

TCP slirp (userspace)

• TCP_ACK_DELAY_MS: delayed ACK timer (ms). Lower (e.g., 5) reduces ACK latency.
• TCP_ENABLE_SACK: advertise SACK permitted in SYN-ACK (recommended 1 for modern stacks).
• TCP_MSS_CLAMP: clamp advertised MSS (bytes). Leave unset unless troubleshooting PMTUD.
• TCP_PACE_US: microseconds to sleep between host→guest segments (0 disables). Use only when packet bursts cause loss/ECN on marginal paths.
• TCP_GATE_LOG: controls send-gating logs; off disables, debug logs at debug level, info logs at info level (default).
• TCP_CC: congestion control algo for host→guest path; off to disable, default newreno.
• TCP_ERROR_SIGNAL: how to signal outbound connect failure to the guest: icmp (default), rst, or none.
• TCP_FAST_DIAL_MS: fast pre-dial timeout (ms) to map immediate refusals to ICMP/RST without sending SYN-ACK first (default ~5ms).
• TCP_SOCK_RCVBUF, TCP_SOCK_SNDBUF: optional OS socket buffer sizes for host TCP connections.
• TCP_ACK_IDLE_GATE_MS, TCP_ACK_IDLE_MIN_INFLIGHT, TCP_ACK_IDLE_FAIL_SEC: advanced gating of host reads when no guest ACK progress. Defaults: TCP_ACK_IDLE_GATE_MS=6000, TCP_ACK_IDLE_FAIL_SEC=120; TCP_ACK_IDLE_MIN_INFLIGHT defaults to ~1 MSS when unset.

IP header synthesis