High-performance tunneling between Iran and abroad — built in Go.
Tutorials · Documentation · فارسی · Telegram · Community
BackPack is a high-performance tunnel engine for connecting Iran ⇄ abroad (kharej) servers.
It is written in Go and distributed as a self-contained binary with:
- Interactive CLI
- Web monitoring panel
- Multiple tunnel transports
- Full IP direct tunneling
- Automatic failover and transport fallback
- Health checks and route diagnostics
- Backup, rollback and verified updates
- Telegram monitoring
- Multi-server management
BackPack is designed for routes where connectivity is not something you can simply assume will stay healthy.
Instead of depending on one protocol or one path, it gives you several transport and recovery strategies and lets you measure the route before choosing one.
The normal BackPack tunnel is a reverse tunnel:
INTERNET
│
│ user traffic
▼
┌──────────────┐
│ IRAN SERVER │
│ │
│ Exposed port │
└──────┬───────┘
│
│ BackPack tunnel
│
▼
┌──────────────┐
│ KHAREJ SERVER│
│ │
│ Real service │
└──────────────┘
The direction is important:
KHAREJ ───────────────▶ IRAN
tunnel
The kharej server dials the Iran server, while user traffic enters through the Iran server and is forwarded to the service on kharej.
| Server | Setup | Role |
|---|---|---|
| Iran | Setup Iran |
Listens for the tunnel and exposes forwarded ports |
| Kharej | Setup Kharej |
Dials Iran and forwards traffic to the real service |
This means:
- The kharej server does not need an inbound tunnel port.
- The Iran server needs the tunnel port open.
- The Iran side should be configured first.
- The kharej side needs the Iran address, tunnel port and token generated by the Iran side.
The tunnel port and the forwarded ports are different things. The tunnel port carries BackPack itself; forwarded ports are the ports your users connect to.
For the complete explanation, see Before you start.
BackPack also supports a direct tunnel, where Iran initiates the connection to kharej.
IRAN ─────────────────────────▶ KHAREJ
tunnel
The current Setup → Direct wizard builds BackPack's full layer-3 tunnel.
Instead of forwarding individual connections, it creates a private point-to-point network interface between the two machines and carries complete IP packets through it.
┌──────────────┐ ┌──────────────┐
│ IRAN │ │ KHAREJ │
│ │ │ │
│ 10.10.0.1 │══════════════════│ 10.10.0.2 │
│ │ BackPack │ │
└──────────────┘ └──────────────┘
The direct tunnel uses:
- GRE encapsulation
- Noise encryption
- Automatic MTU handling
- Multiple carrier options
- Full IP routing
Set up the Iran server first: Setup Iran → Direct → carrier. Its summary, right before Create This Tunnel, shows a one-line setup link (backpack://…) and, under it, one command that installs Backpack on a fresh kharej and builds the tunnel from that link; on a kharej that already runs Backpack choose Setup Kharej → Direct → the same carrier → Setup Link, or run backpack link apply '<link>'. The token, addresses and tuning come across in the link. For several kharej servers behind one Iran server, repeat it once per kharej — each gets its own link.
The older stream-based
[direct]engine still exists for existing configurations, but the current wizard builds the layer-3 direct tunnel.
There are four things responsible for most first-time setup problems:
Users
│
▼
Iran ────────────────▶ Kharej
BackPack │
▼
Real service
The Iran side generates a random 64-character token.
Both ends must use the same token.
A mismatch can look like a dead tunnel, especially on encrypted transports where the server may intentionally not respond.
For example:
443
means:
Iran :443
↓
Kharej 127.0.0.1:443
while:
443=127.0.0.1:2096
means:
Iran :443
↓
Kharej 127.0.0.1:2096
You can also use explicit backend addresses, multiple backends and port ranges.
See Port mappings.
Forwarded ports carry TCP by default.
UDP forwarding is a separate per-tunnel setting.
Enable it when the service behind the tunnel requires UDP, such as:
- Xray / 3x-ui
- Shadowsocks UDP
- WireGuard
- DNS
- Games
See Forwarded UDP.
On both servers:
bash <(curl -fsSL https://raw.githubusercontent.com/AminMGMT/BackPack/main/install.sh)Then:
sudo backpackThe installer downloads the release for the server architecture, verifies its published checksum, installs it and opens the CLI.
Supported release architectures currently include:
x86_64 → amd64
aarch64 → arm64
If the server cannot reach GitHub, BackPack also supports a completely offline installation.
See Installation.
sudo backpackThen:
1. Setup Iran
→ Reverse
→ Transport
→ Iran IP Or Domain (the detected one is the default)
→ Tunnel Port
→ Forwarded Ports
→ Tunnel Name
→ Security Token (generated — press Enter)
→ Carry UDP As Well As TCP
→ the transport's own questions (certificate for WSS, flags for PCK, …)
→ How Should The Tunnel Be Tuned?
The summary before Create This Tunnel shows a one-line Setup Link (backpack://…). Copy it.
For a first deployment, TCP is the simplest starting point.
sudo backpackThen:
2. Setup Kharej
→ Reverse
→ Same transport
→ Setup Link → paste the link → Tunnel Name → Create This Tunnel
Manual is there too: Iran IP, the same tunnel port, a name, the same token, the same preset.
Use:
Manage → Status
Then:
Manage → Health Check
If you are unsure which transport to use:
Manage → Link Test
Link Test measures the route over TCP, including latency, jitter and packet loss, and recommends a suitable transport.
See Choosing a transport.
If you don't know where to start, use this:
| Situation | Start with |
|---|---|
| Clean / ordinary route | TCP |
| Many short-lived connections | TCP Mux |
| TCP is filtered or unstable | TCP + Stealth |
| TCP connects but stalls, resets or gets throttled | TCP + PCK |
| You specifically need raw UDP | UDP |
| Lossy route / real-time traffic / gaming | UDP + KCP + FEC |
| You want to test QUIC | UDP + QUIC |
| HTTP/WebSocket traffic is useful | WS / WS Mux |
| HTTPS-style traffic is required | WSS / WSS Mux |
| TCP and UDP are filtered but ICMP works | xDi (ICMP) |
| Inbound access to Iran is unavailable | Direct tunnel |
The easiest way to choose is:
Kharej
↓
Manage → Link Test
↓
Measure route
↓
Get recommendation
See Choosing a transport and all transports.
BackPack currently provides twelve reverse-tunnel transports.
| Transport | Family | Encryption | PROXY v2 | Requirements |
|---|---|---|---|---|
| TCP | TCP | — | ✓ | — |
| TCP Mux | TCP | — | ✓ | — |
| TCP + Stealth | TCP | Noise | ✓ | — |
| TCP + PCK | TCP | Token-derived | ✓ | Linux + root |
| UDP | UDP | — | — | UDP open |
| UDP + KCP + FEC | UDP | Token-derived | ✓ | UDP open |
| UDP + QUIC | UDP | TLS 1.3 | ✓ | UDP open |
| WS | WebSocket | — | — | — |
| WS Mux | WebSocket | — | ✓ | — |
| WSS | WebSocket | TLS | — | Certificate |
| WSS Mux | WebSocket | TLS | ✓ | Certificate |
| xDi (ICMP) | Experimental | Token-derived | ✓ | Linux + root + ICMP |
Plain reliable TCP.
Low overhead and the simplest starting point on a clean route.
Multiplexes multiple logical connections over a small pool of TCP connections.
Useful for services that create many short-lived connections.
TCP wrapped in a Noise record layer.
The handshake and encrypted stream do not use a TLS ClientHello or a recognizable application protocol header.
Useful when plain TCP is being identified, filtered or killed.
Builds TCP segments without using the kernel's normal TCP connection state.
Useful when normal TCP connects but later stalls, resets or gets throttled.
Requires Linux and root on both ends.
Raw UDP transport with minimal overhead.
There is no reliability or ordering layer.
Reliable, ordered transport over UDP with forward error correction.
Designed for routes where packet loss makes TCP back off too aggressively, and for latency-sensitive traffic.
QUIC over UDP with TLS 1.3, multiplexing, congestion control and loss recovery.
It is available for testing, but BackPack's route testing does not generally recommend it over KCP for lossy Iran routes.
WebSocket transport for routes where HTTP traffic is useful or where the tunnel needs to sit behind a CDN.
WS Mux adds multiplexing and PROXY protocol support.
WebSocket over TLS.
WSS can use a real certificate and Chrome-style TLS behavior and can provide a decoy site for probes.
Carries the KCP transport inside ICMP echo packets instead of UDP.
Designed for the specific case where TCP and UDP are filtered but ICMP remains available.
It is a last-resort transport rather than the normal starting point.
See the complete Transport reference.
UDP forwarding is independent of the transport carrying the tunnel.
For example:
Iran :443/tcp + :443/udp
│
▼
BackPack
│
▼
Kharej :443/tcp + :443/udp
This is useful for:
- Xray / 3x-ui
- WireGuard
- DNS
- Games
- Other services that require UDP
UDP forwarding is off by default.
BackPack is built around routes that can change or fail.
A tunnel can have multiple server addresses.
BackPack can:
- automatically fail over between addresses
- health-score available addresses
- load-balance across healthy addresses
See Failover & load balancing.
A tunnel can also have a fallback chain.
For example:
transport = "wss"
fallback_transports = [
"quic",
"kcp",
"tcpmux"
]If the active carrier stops getting through, BackPack can move through the configured fallback chain.
See Transport fallback.
BackPack includes a watchdog that detects stopped or stalled tunnels and performs recovery.
Services are managed through systemd and survive reboots.
Updates and relevant configuration changes can create restore points and roll back when the tunnel does not return successfully.
BackPack includes diagnostics directly in the CLI.
Measures:
- latency
- jitter
- packet loss
It also recommends a transport for the measured route.
Checks the server, panel and tunnels and provides a suggested fix when it detects a problem.
Provides tunnel-level statistics including traffic, connections and transport-specific metrics such as KCP retransmissions, loss and FEC repairs.
See:
BackPack provides four performance presets:
- Balance
- Turbo
- Aggressive
- Throughput
The first three tune the queues and transport behavior for a full IP tunnel; Throughput is intended for maximizing sustained transfer.
BackPack also includes kernel/network optimization through the CLI.
See Performance presets.
BackPack provides several security mechanisms depending on the transport and deployment mode.
Encrypted tunnel options include:
- TCP + Stealth
- TCP + PCK
- UDP + KCP + FEC
- UDP + QUIC
- WSS
- WSS Mux
- xDi
On plain transports such as TCP, TCP Mux, UDP, WS and WS Mux, the tunnel credential itself is not encrypted by the transport.
The Web Panel supports:
- Password authentication
- Two-factor authentication
- Recovery codes
- Scoped API tokens
- Authorization records
See Access control.
Release archives are verified against the published SHA-256 checksum.
An archive that cannot be verified is refused rather than installed.
See Updates & rollback.
Backends normally see the connection as coming from the tunnel itself.
BackPack can instead send the original client address using PROXY protocol v2.
This allows applications and panels behind the tunnel to see the real client IP and keep per-user/device limits working.
Supported transports and limitations are documented in:
Real client IP / PROXY protocol v2
BackPack includes a monitoring-focused web dashboard.
It provides:
- CPU usage
- RAM usage
- Disk usage
- Traffic
- Tunnel state
- Real ping
- Logs
- Backup and Telegram settings
- Panel security settings
The panel listens on port 7777 by default.
Iran server
│
└── Web Panel :7777
The panel is primarily for monitoring and management around the deployment; tunnel creation and detailed tunnel configuration remain available through the CLI.
It also supports:
- HTTPS
- Custom certificates
- Two-factor authentication
- Recovery codes
- API access control
See:
The Web Panel can register remote servers as managed nodes.
Once registered, BackPack can use the panel to build and manage both ends of a tunnel without requiring you to repeat the entire SSH setup manually.
Managed servers can be:
- registered
- edited
- tested
- used to create tunnels
- started
- stopped
- restarted
- removed
See Managed servers.
BackPack can send status and alert messages through Telegram.
The built-in Telegram integration can relay its connection through a tunnel peer, allowing Telegram monitoring from environments where direct Telegram access is unavailable.
It supports:
- periodic status reports
- tunnel status
- resource alerts
- recovery messages
- monitoring events
See:
BackPack can create a portable backup containing the important deployment state, including:
- tunnel configurations
- panel settings
- panel password
- Telegram settings
- TLS certificates
- scheduled tasks
Backups are stored as .tar.gz archives.
They can also be restored onto another machine.
See Backup & Restore.
BackPack can update itself from the GitHub release system.
The update process:
- Detects the available release.
- Downloads the architecture-specific archive.
- Verifies the published SHA-256.
- Installs the release.
- Uses restore points and recovery logic if the updated tunnel does not return successfully.
Updates can also use a tunnel peer when the server itself cannot reach GitHub.
If neither direct access nor a tunnel path is available, BackPack supports offline updates.
See Updates & rollback.
BackPack does not require the VPS itself to have GitHub access.
Download the release from a machine with internet access and copy it to the server.
For example:
scp install.sh SHA256SUMS backpack_linux_amd64.tar.gz root@SERVER_IP:/root/
ssh root@SERVER_IP \
"cd /root && sudo bash install.sh"Or install manually after verifying the checksum:
sha256sum backpack_linux_amd64.tar.gz
tar xzf backpack_linux_amd64.tar.gz
mkdir -p /etc/backpack /root/BackPack/backups
install -m 0755 backpack /usr/local/bin/backpack
echo /root/BackPack > /etc/backpack/install_path
sudo backpackSee Installation.
For operators who need more than the basic setup, BackPack documents its internal configuration and operational behavior separately.
Complete reference for:
- Setup Iran
- Setup Kharej
- Direct setup
- Tunnel management
- Built-in proxy
- Backup & Restore
- Web Panel
- Optimize
- Telegram
- Updates
- Fine Tune
- File locations
Generated from the configuration declarations and documents every configuration key BackPack reads.
/root/BackPack
/root/BackPack/backups
/etc/backpack
/usr/local/bin/backpack
See Server layout.
BackPack intentionally separates setup tutorials from technical reference.
The tutorial/ directory explains how to actually build a tunnel, step by step, following the CLI wizard.
- TCP
- TCP Mux
- TCP + Stealth
- TCP + PCK
- UDP
- UDP + KCP + FEC
- UDP + QUIC
- WS / WS Mux
- WSS / WSS Mux
- xDi / ICMP
- Transports
- Choosing a transport
- Transport fallback
- Direct layer-3 tunnel
- Direct stream tunnel
- TCP + PCK
- IP Spoofing
- Port mappings
- Forwarded UDP
- TCP MSS clamp
- Filtered / dirty IP
- WSS camouflage
- Installation
- CLI menu
- Server layout
- Web Panel
- Web Panel screens
- Managed servers
- Health Check
- Tunnel Metrics
- Monitor service
- Troubleshooting
- Failover & load balancing
- Transport fallback
- Backup & Restore
- Updates & rollback
- Performance presets
- Per-tunnel limits
- Real client IP
Every documentation page includes a Persian summary where applicable.
If BackPack is useful to you:
- Star the repository
- Report bugs through GitHub Issues
- Contribute improvements
- Join the Telegram community
- Channel: @BlackProtocols
- Community: @BlackProtocolsGroup
Pull requests, bug reports and technical improvements are welcome.
Before contributing:
- Read CONTRIBUTING.md.
- Check the relevant documentation.
- Keep changes focused.
- Add or update tests where appropriate.
- Update documentation when behavior or configuration changes.
For the release process, see Releasing.
Copyright © 2026 Amin Mohammadi (AminMGMT).
BackPack is released under the GNU Affero General Public License v3.0 (AGPL-3.0).
See:
You may use, study, modify, redistribute and build a business on BackPack under the terms of the license.
Additional attribution and trademark conditions apply.
Modified versions must keep this line, unaltered, in their README (and in NOTICE):
Based on BackPack by Amin Mohammadi (AminMGMT)
https://github.com/AminMGMT/BackPack
BackPack, its name and logo are not licensed as part of the source code.
Forks should use their own name and branding.
It is permitted to truthfully state that a project is based on or compatible with BackPack.
See TRADEMARK.md for the complete terms.