English | 中文
TCP over GRE tunnel - Encapsulate TCP traffic into GRE protocol (IP Protocol 47) for transmission with reliable delivery.
┌─────────────────┐ ┌─────────────────┐
│ Application │ │ Backend Server │
│ (e.g. browser) │ │ (e.g. ss-server)│
└────────┬────────┘ └────────▲────────┘
│ TCP │ TCP
▼ │
┌─────────────────┐ GRE Protocol 47 ┌─────────┴────────┐
│ shadow-gre │ ◄─────────────────────────────────► │ shadow-gre │
│ (client mode) │ Raw IP Socket │ (server mode) │
└─────────────────┘ └──────────────────┘
- Uses real GRE protocol (IP Protocol 47)
- Reliable transport layer with retransmission and SACK support
- Adaptive RTO based on RTT measurement (RFC 6298)
- Supports multiple connection multiplexing
- Simple authentication via GRE Key field
Download the latest release from GitHub Releases.
Available binaries:
shadow-gre-linux-amd64- Linux x86_64shadow-gre-linux-arm64- Linux ARM64shadow-gre-linux-armv7- Linux ARMv7shadow-gre-darwin-amd64- macOS Intelshadow-gre-darwin-arm64- macOS Apple Siliconshadow-gre-freebsd-amd64- FreeBSD x86_64
Requirements:
- Go 1.21+
- Linux (macOS theoretically supported but requires root)
- Root/sudo privileges (required for raw sockets)
go build -o shadow-gre ./cmd/shadow-greRun on the server side to receive GRE traffic and forward to backend services:
sudo ./shadow-gre \
-mode server \
-local 0.0.0.0 \
-backend 127.0.0.1:8388 \
-password YOUR_PASSWORDRun on the client side to listen for TCP connections and forward via GRE to the server:
sudo ./shadow-gre \
-mode client \
-listen 0.0.0.0:1080 \
-local 0.0.0.0 \
-remote SERVER_IP \
-password YOUR_PASSWORD| Parameter | Description |
|---|---|
-mode |
Running mode: client or server |
-listen |
TCP listen address (client mode only) |
-local |
Local IP address for GRE socket binding |
-remote |
Server IP address (client mode only) |
-backend |
Backend service address (server mode only) |
-password |
Shared password for generating GRE Key |
- Run Shadowsocks server on
127.0.0.1:8388 - Start shadow-gre server:
sudo ./shadow-gre -mode server -local 0.0.0.0 -backend 127.0.0.1:8388 -password YOUR_PASSWORD- Start shadow-gre client:
sudo ./shadow-gre -mode client -listen 0.0.0.0:1080 -local 0.0.0.0 -remote SERVER_IP -password YOUR_PASSWORD- Configure Shadowsocks client to connect to
127.0.0.1:1080
- Root Privileges Required: Raw socket operations require root/sudo privileges
- Firewall: Ensure firewall allows GRE protocol (IP Protocol 47)
- NAT Issues: GRE is an IP layer protocol, some NAT devices may not support it
Uses standard GRE format (RFC 2784 + RFC 2890):
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|C| |K|S| Reserved0 | Protocol Type (0x6558) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Key (from password) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Payload... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Custom reliable protocol over GRE for guaranteed delivery:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Stream ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flags | Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Seq (cont) | ACK Number (optional) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ACK (cont) | SACK Count | SACK Blocks... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Payload... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Flags:
0x01DATA - Contains payload data0x02ACK - Contains acknowledgment0x04CLOSE - Stream close0x08SYN - Stream synchronization0x10SACK - Contains selective ACK blocks
Reliability Features:
- Cumulative ACK with SACK (Selective Acknowledgment)
- Adaptive RTO calculation (RFC 6298)
- Fast retransmit on 3 duplicate ACKs
- Sliding window flow control (128 packets)
- Out-of-order packet buffering
- Sequence number wraparound handling
MIT