SPP (Simple & Powerful Proxy)

!image

Table of Contents

• Features
• Installation
• Quick Start

• Proxy Modes & Examples

• Configuration Files
• Health Check & Monitoring
• Ecosystem & Plugins
• Documentation
• License

Features

• Multi-Protocol Transit: Supports establishing tunnel connections over TCP, UDP, RUDP (Reliable UDP), RICMP (Reliable ICMP ping tunnel), RHTTP (Reliable HTTP), KCP, QUIC, and RDNS (Reliable DNS tunnel).
• Protocol Multiplexing & Conversion: Transparently tunnel TCP or UDP traffic through any supported reliable transit protocol across network boundaries. Multiple forwarding rules share a single multiplexed transit tunnel.
• Versatile Proxy Topologies:

• Strong Security:

• High Performance & Low Latency:

• Operational Reliability:

Installation

Precompiled Binaries

Download ready-to-use binaries for Linux, macOS, and Windows from the Releases page.

Build from Source

Requirements: Go 1.20 or newer.

git clone https://github.com/esrrhs/spp.git
cd spp
go build -o spp .

Docker

SPP provides an official container image:

# Pull image
docker pull esrrhs/spp:latest
Run SPP server with host networking
docker run -d --name spp-server --net=host esrrhs/spp \
  -type server -proto tcp -listen :8888 -key "your-auth-key" -encrypt "your-encrypt-key"

Quick Start

1. Automatic Configuration Generator (Recommended)

Generate an all-protocol server configuration alongside ready-to-use client templates with a single command:

./spp -genconfig
Or generate into a dedicated directory:
./spp -genconfig -outdir ./conf -force

This generates paired configurations pre-populated with matching secure random keys:

• config_server.json: Preconfigured with multi-protocol listeners (tcp, rudp, ricmp, kcp, quic, rhttp, rdns).
• config_proxy_client.json: Forward port proxy client.
• config_reverse_proxy_client.json: Reverse port proxy client.
• config_socks5_client.json: Local SOCKS5 proxy client.
• config_reverse_socks5_client.json: Reverse SOCKS5 proxy client.
• config_http_client.json: Local HTTP/HTTPS proxy client.
• config_reverse_http_client.json: Reverse HTTP/HTTPS proxy client.

# Run server
./spp -config config_server.json

Run desired client (e.g., SOCKS5)
./spp -config config_socks5_client.json

2. Command-Line Usage

Both endpoints must use matching -key (authentication) and -encrypt (wire encryption) flags.

1. Start Server

./spp -type server -proto tcp -listen :8888 \
  -key "your-auth-key" -encrypt "your-encrypt-key"

The server can also listen on multiple protocols and ports simultaneously:

./spp -type server \
  -proto tcp -listen :8888 \
  -proto rudp -listen :9999 \
  -proto quic -listen :4433 \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Proxy Modes & Examples

Port Forwarding (Forward Proxy)

Forward a local port through the SPP server to a target destination:

# Forward local port 8080 to target remote 8080 over TCP
./spp -type proxy_client -server www.server.com:8888 \
  -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Forward multiple ports (TCP + UDP) over one tunnel:

./spp -type proxy_client -server www.server.com:8888 \
  -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
  -fromaddr :9000 -toaddr :9000 -proxyproto udp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

NAT Traversal / Intranet Penetration (Reverse Proxy)

Expose a local internal service to visitors reaching the public SPP server:

# External clients accessing server:8080 are routed to local service on 8080
./spp -type reverse_proxy_client -server www.server.com:8888 \
  -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

SOCKS5 Proxy (Forward & Reverse)

Local SOCKS5 Proxy

./spp -type socks5_client -server www.server.com:8888 \
  -fromaddr :1080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

With authentication:

./spp -type socks5_client -server www.server.com:8888 \
  -fromaddr :1080 -proxyproto tcp \
  -username "admin" -password "secret" \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Reverse SOCKS5 Proxy

./spp -type reverse_socks5_client -server www.server.com:8888 \
  -fromaddr :1080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

HTTP / HTTPS Proxy (Forward & Reverse)

Local HTTP/HTTPS Proxy

./spp -type http_client -server www.server.com:8888 \
  -fromaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

With Basic Auth:

./spp -type http_client -server www.server.com:8888 \
  -fromaddr :8080 -proxyproto tcp \
  -username "admin" -password "secret" \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Reverse HTTP/HTTPS Proxy

./spp -type reverse_http_client -server www.server.com:8888 \
  -fromaddr :8080 -proxyproto tcp \
  -key "your-auth-key" -encrypt "your-encrypt-key"

Cross-Protocol Tunneling (QUIC / KCP / RUDP / RICMP / RHTTP / RDNS)

SPP allows wrapping application traffic (proxyproto) inside any supported transit protocol (proto).

• Tunnel over QUIC:

./spp -type proxy_client -proto quic -server www.server.com:4433 \
    -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
    -key "your-auth-key" -encrypt "your-encrypt-key"

• Tunnel over KCP with Reed-Solomon FEC:

# Client side with 10 data shards and 3 parity shards
  ./spp -type socks5_client -proto kcp -server www.server.com:8888 \
    -kcpfecdata 10 -kcpfecparity 3 \
    -fromaddr :1080 -proxyproto tcp \
    -key "your-auth-key" -encrypt "your-encrypt-key"

• Tunnel over Reliable UDP (RUDP):

./spp -type proxy_client -proto rudp -server www.server.com:9999 \
    -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
    -key "your-auth-key" -encrypt "your-encrypt-key"

• Tunnel over ICMP Echo Ping (RICMP, bypasses TCP/UDP blocking):

# Server listening on ICMP (requires root/CAP_NET_RAW)
  ./spp -type server -proto ricmp -listen 0.0.0.0 -key "your-key" -encrypt "your-key"
# Client connecting via ICMP
  ./spp -type socks5_client -proto ricmp -server www.server.com \
    -fromaddr :1080 -proxyproto tcp -key "your-key" -encrypt "your-key"

• Tunnel over Reliable HTTP (RHTTP):

./spp -type proxy_client -proto rhttp -server www.server.com:8888 \
    -fromaddr :8080 -toaddr :8080 -proxyproto tcp \
    -key "your-auth-key" -encrypt "your-encrypt-key"

• Tunnel over DNS Queries/Responses (RDNS, bypasses restrictive firewalls):

# Server listening on DNS port 53 (requires root/CAP_NET_BIND_SERVICE)
  ./spp -type server -proto rdns -listen :53 -rdnsdomain "tunnel.example.com" \
    -key "your-key" -encrypt "your-key"
# Client connecting via public recursive DNS (e.g. 114.114.114.114 or 8.8.8.8)
  ./spp -type socks5_client -proto rdns -server 114.114.114.114:53 -rdnsdomain "tunnel.example.com" \
    -fromaddr :1080 -proxyproto tcp -key "your-key" -encrypt "your-key"

Configuration Files

Instead of lengthy CLI commands, manage configurations with JSON files:

{
  "type": "socks5_client",
  "server": "1.2.3.4:8888",
  "proto": ["tcp"],
  "proxyproto": ["tcp"],
  "fromaddr": [":1080"],
  "key": "your-auth-key",
  "encrypt": "your-encrypt-key",
  "encrypttype": "chacha20",
  "compress": 128,
  "compresstype": "zstd"
}

Load the configuration file:

./spp -config client.json

Health Check & Monitoring

SPP provides a built-in lightweight HTTP status server via -statusaddr:

./spp -type server -proto tcp -listen :8888 -statusaddr 127.0.0.1:6060 -key "key"

Endpoints:

• http://127.0.0.1:6060/healthz — Returns 200 OK ("ok") for orchestrator readiness and liveness probes.
• http://127.0.0.1:6060/status — Returns internal telemetry and state.

Ecosystem & Plugins

• Android App: spp_client_android provides an easy-to-use VPN GUI for Android devices powered by SPP.
• Shadowsocks Plugin: spp-shadowsocks-plugin integrates SPP as a SIP003 transport plugin for Shadowsocks.

Documentation

For advanced scenarios, full parameter descriptions, protocol matrix details, and fine-tuning options: 👉 Read the Full Usage Guide (USAGE.md)

License

This project is licensed under the MIT License.