Cascade

Self-hosted WireGuard / AmneziaWG router management platform

🇷🇺 Русский  ·  📖 User Manual

---

✨ Features

Module	Description
🔌 Interfaces	Multiple WireGuard / AmneziaWG tunnel interfaces, quick-create in one click, import .conf as uplink, per-interface MSS clamping
👥 Peers	Client and site-to-site (S2S) interconnect peers with QR codes, lifetime traffic stats, per-client bandwidth limiting and group membership
🌐 Routing	Static routes, policy-based routing (PBR), kernel route inspection, OSPF is on plans
🔀 NAT	Outbound MASQUERADE / SNAT with alias support + Port Forwarding (DNAT) with per-interface scoping
🛡️ Firewall	Filter rules (ACCEPT / DROP / REJECT) + PBR via gateway
📋 Aliases	7 types: host, network, ipset, client-group, group, port, port-group. Client groups are ipset-backed and auto-updated on peer changes
📡 Gateways	Live ping + HTTP monitoring, gateway groups, automatic failover
🎛️ AWG2 Templates	AmneziaWG 2.0 obfuscation parameter templates with built-in generator
🔐 Auth	Multi-user accounts, TOTP 2FA (Google Authenticator), long-lived API tokens
🔒 TLS	Let's Encrypt via acme.sh (bare IP shortlived cert or domain)
🎭 Decoy site	Caddy reverse proxy serves a fake streaming site on /; admin UI hidden behind a secret path
🖥️ Multi-Server 🆕	Manage multiple Cascade routers from one UI — switch servers in the sidebar, proxy all API calls transparently, self-signed cert support
📊 Monitoring 🆕	Real-time traffic metrics per interface, gateway status history (stacked bar chart), Diagnostics page with per-period history
⚡ Speed Test 🆕	iperf3-based speed test between any two managed servers — Auto / Tunnel / Internet mode, S2S tunnel autodetect, result history
🚦 Rate Limits 🆕	Per-client-group bandwidth limiting via tc HTB (kbps down/up enforced per IP)
🧙 Wizards 🆕	Step-by-step setup wizards: Simple Client VPN, Cascade via WireGuard Uplink, Cascade ↔ Cascade S2S interconnect

🎯 Why Cascade?

• ✅ Go binary — single static binary, no Node.js, no npm, no dependencies
• ✅ Multi-interface — manage multiple WireGuard/AWG interfaces from one UI
• ✅ Full AmneziaWG 2.0 — S3, S4, I5 parameters, H-range obfuscation, 7 CPS profiles + browser fingerprint
• ✅ Policy-based routing — route traffic per-source through different gateways
• ✅ Port Forwarding (DNAT) — transparent traffic cascading with optional source NAT
• ✅ Import .conf as uplink — connect Cascade as a client to any WireGuard server; use as PBR gateway without touching the routing table
• ✅ Gateway monitoring — ICMP ping + HTTP/S probes, auto-fallback on failure
• ✅ Multi-user + TOTP 2FA — per-user accounts with Google Authenticator support
• ✅ HTTPS by default — Caddy + acme.sh, works with bare IPs via Let's Encrypt shortlived certs
• ✅ Decoy protection — admin path is hidden; visitors see a fake streaming site
• ✅ 🆕 Multi-server management — control multiple Cascade routers from one browser tab, with transparent API proxying
• ✅ 🆕 Built-in speed test — iperf3 between any managed servers, S2S tunnel autodetect, result history
• ✅ 🆕 Traffic monitoring — per-interface metrics and gateway health history with configurable time periods
• ✅ 🆕 Setup wizards — guided wizards for Uplink VPN and S2S interconnect; auto-create interfaces, aliases, gateways, PBR rules and NAT in one flow

📋 Requirements

• Ubuntu 22.04 or 24.04 (other distros: manual setup)
• Root access
• Public IP address or domain name
• Ports: 443/tcp (HTTPS), 51820+/udp (WireGuard)

---

🚀 Quick Install

Userspace mode — recommended

Works on any VPS without a custom kernel. No reboot needed, no deadlocks.

git clone https://github.com/JohnnyVBut/cascade.git
cd cascade
sudo bash deploy/setup.sh --yes

--yes picks all defaults: userspace mode, auto-detected public IP, random admin path.

Kernel module mode

Maximum throughput, but the AmneziaWG kernel module has known deadlock issues that can freeze tunnel operations. Only recommended if you need peak performance and can tolerate occasional interface restarts.

git clone https://github.com/JohnnyVBut/cascade.git
cd cascade
# Interactive setup — choose [2] Kernel module at Step 2
sudo bash deploy/setup.sh

Switch mode on a running system

sudo bash deploy/switch-mode.sh --userspace   # → amneziawg-go (stable)
sudo bash deploy/switch-mode.sh --kernel      # → kernel module (fast)

The script handles kernel module install/unload, blacklisting, and container restart automatically.

---

🚀 Deployment Options

Option A — Router only (advanced users)

Run just the Cascade container. The web UI listens on localhost only — no public exposure, no TLS. You are responsible for network security, authentication and access control.

git clone https://github.com/JohnnyVBut/cascade.git
cd cascade
docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml up -d
# UI available at http://127.0.0.1:8888/

Use this if you already have a reverse proxy, firewall, or VPN-only access in place. Step-by-step guide: docs/DEPLOY.md

Option B — Full stack (recommended)

One command sets up everything: AmneziaWG, TLS certificate, Caddy reverse proxy with a decoy streaming site, and a hidden admin path. The router is never exposed directly to the internet.

git clone https://github.com/JohnnyVBut/cascade.git
cd cascade
sudo bash deploy/setup.sh

Step	What happens
0	1 GB swap (prevents OOM during build)
1	Kernel upgrade to HWE 6.x (Ubuntu 22.04 only) — reboot, then re-run
2	AmneziaWG run mode — choose Userspace (recommended) or Kernel module
2b	Docker network mode — choose Host (default) or Bridge (port range for Docker publish)
3	Docker CE install
4	sysctl: ip_forward, UDP buffers
4b	TCP tuning: BBR congestion control, FQ scheduler, rp_filter
5a	Generate decoy video via ffmpeg (60 s noise — looks like a real stream)
5	Build Cascade Docker image
6	Collect config interactively (IP, secret path, email)
7	Start Cascade (localhost only)
8	Issue TLS certificate via acme.sh (Let's Encrypt)
9	Start Caddy (HTTPS + decoy site + hidden admin path)
10	Verify: health-check Cascade + Caddy, print summary

At the end you get:

Admin URL: https://YOUR_IP/<secret-path>/

Open it — first-run shows a Create First User form (no auth required until the first account exists). After creating your account, enable TOTP 2FA in Settings → Users for an extra layer of protection.

Re-run safe: setup.sh is idempotent — safe to run again after a reboot or update. On re-run, Step 2 asks Change run mode? [y/N] — press y to switch between modes.

Testing TLS without rate limits: use --staging to issue an untrusted certificate from the Let's Encrypt staging CA. Switch to production later by removing ACME_STAGING=1 from deploy/.env and re-running setup.sh.

sudo bash deploy/setup.sh --staging        # staging CA (browser shows warning — expected)
sudo bash deploy/setup.sh --yes --staging  # non-interactive + staging

---

⚙️ AWG Run Modes

	Userspace (amneziawg-go)	Kernel module
Performance	~70% of kernel	Maximum
Stability	✅ Stable	⚠️ Known deadlocks
Kernel module required	❌ No	✅ Yes
Works on any VPS	✅ Yes	Depends on kernel
Reboot after install	❌ No	Sometimes

The current mode is shown as a badge in the sidebar of the web UI (blue = userspace, green = kernel). The Docker network mode is shown as a separate badge (gray = HOST, amber = BRIDGE, red = NONE).

---

⚙️ Configuration

Configuration is collected interactively by setup.sh and saved to deploy/.env.

Variable	Default	Description
WG_HOST	auto-detected	Public IP or domain of the server
ADMIN_PATH	random hex	Secret path for admin UI (e.g. /a1b2c3d4.../)
PORT	8888	Internal port for Cascade (Caddy proxies to this)
BIND_ADDR	127.0.0.1	Bind address for Cascade (use 127.0.0.1 behind Caddy)
ACME_EMAIL	optional	Email for Let's Encrypt notifications
ACME_STAGING	0	1 = use LE staging CA (untrusted cert, no rate limits — for testing)
AWG_USERSPACE_IMPL	amneziawg-go	amneziawg-go or kernel
NETWORK_MODE	host	host or bridge — Docker network mode
BRIDGE_PORT_RANGE	(bridge only)	Published UDP port range for WireGuard in bridge mode (e.g. 51831-65535)

Additional settings (WireGuard defaults, DNS, etc.) are configurable in the Web UI under Settings.

🔒 Security Model

• Admin UI is served only via https://HOST/<ADMIN_PATH>/ — plain https://HOST/ shows a decoy site
• HTTPS with HTTP/3 (QUIC) via Caddy
• TLS certificates: shortlived (6-day) for bare IPs, standard 90-day for domains
• Session cookie: HttpOnly, Secure, SameSite=Strict
• bcrypt password hashing (cost 12)
• Multi-user accounts — each user has a separate username and password
• TOTP 2FA — Google Authenticator / Authy (enable per-user in Settings → Users)
• API tokens — long-lived bearer tokens for scripts; bypass TOTP; revocable
• Input validation on all API endpoints

Full threat model: docs/SECURITY.md

🔄 Updating

Host network mode (default)

git pull origin master
docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml up -d

Full stack (Caddy + setup.sh)

git pull origin master
sudo bash deploy/setup.sh --yes

📱 Compatible VPN Clients

⚠️ Standard WireGuard clients do NOT work with AmneziaWG 2.0 interfaces. WireGuard 1.0 interfaces work with standard clients normally.

Platform	App
Android	Amnezia VPN · AmneziaWG
iOS / macOS	Amnezia VPN · AmneziaWG
Windows	Amnezia VPN · AmneziaWG
Linux	amneziawg-tools · Amnezia VPN

🛠️ Troubleshooting

Check container status:

docker logs cascade
docker compose -f deploy/caddy/docker-compose.yml logs

Check WireGuard interfaces:

docker exec cascade awg show
docker exec cascade wg show

Check AWG run mode:

docker exec cascade env | grep WG_QUICK
# WG_QUICK_USERSPACE_IMPLEMENTATION=amneziawg-go  → userspace
# (empty or not present)                          → kernel module

Check firewall / NAT:

docker exec cascade iptables-nft -t nat -L -n -v
docker exec cascade ip rule show

Switch AWG mode:

sudo bash deploy/switch-mode.sh --userspace
sudo bash deploy/switch-mode.sh --kernel

Re-run setup (e.g. after reboot or cert renewal):

sudo bash deploy/setup.sh

🔌 REST API

Cascade exposes a full REST API — everything the web UI does, your scripts can do too.

# Authenticate
curl -c cookies.txt -X POST http://127.0.0.1:8888/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}'

# List interfaces
curl -b cookies.txt http://127.0.0.1:8888/api/tunnel-interfaces

# Create a peer
curl -b cookies.txt -X POST http://127.0.0.1:8888/api/tunnel-interfaces/wg10/peers \
  -H "Content-Type: application/json" \
  -d '{"name":"laptop"}'

Use it to automate peer provisioning, integrate with your own dashboards, or build custom clients.

Full reference: docs/API.en.md · docs/API.md (RU)

📖 Documentation

• Deploy guide
• API reference (EN)
• API reference (RU)
• Security model

🏗️ Stack

Layer	Technology
Backend	Go 1.23, Fiber v2
Frontend	Vue 2, Tailwind CSS (embedded in binary)
Database	SQLite (modernc.org/sqlite, CGO-free)
Reverse proxy	Caddy 2 (HTTP/3 + QUIC)
VPN	AmneziaWG 2.0 / WireGuard 1.0

☕ Support the Project

If Cascade is useful to you, consider supporting its development:

Method	Address
TRC20	TDm1VvwoLaRdjpp7149QNacBzQtXnGresW
Yoomoney RU	https://yoomoney.ru/to/4100119568549598

---

🙏 Credits

• Based on wg-easy
• AmneziaVPN for the AmneziaWG protocol
• Vadim-Khristenko/AmneziaWG-Architect — math and code for AWG 2.0 obfuscation profile generation (CPS signatures, H-ranges, browser fingerprint packet sizing)

📄 License

MIT — see LICENSE

---

Made with ❤️ for secure and private internet access