🛡️ pasarguard-outbound-setup

Automated setup for a multi-outbound PasarGuard (Xray-core) VPN panel — with NordVPN (WireGuard) and Windscribe (WireGuard + OpenVPN) upstream tunnels, and a management CLI.

English · فارسی

---

🇬🇧 English

Overview

This repository is a set of idempotent scripts you run on your own Debian/Ubuntu VPS to stand up a PasarGuard proxy panel (powered by Xray-core) with several outbound VPN tunnels chained through commercial providers, plus a small Python CLI (vpn-panel-manager) to add/remove/verify those tunnels.

The idea: clients connect to your panel, and you route different inbounds out through different upstream VPN exits (a different country per outbound) — a self-hosted multi-hop / multi-exit proxy.

⚠️ These scripts are designed to be run by you, on your server. No secret (token, password, key) is ever hardcoded — everything is read from a local .env / config file with 600 permissions.

✨ Features

• One-command or phase-by-phase setup (./run-all.sh or phase1..5), with a confirmation gate before every destructive step and an automatic backup to /etc/vpn-panel/backups/ first.
• PasarGuard install + TLS + admin creation, fully scripted.
• NordVPN WireGuard outbounds for any list of countries — using the correct API method (account NordLynx key + recommended-server public key).
• Windscribe outbounds via WireGuard and OpenVPN (the latter through an SSH-safe, source-routed transparent tunnel, since Xray can't speak OpenVPN natively).
• vpn-panel-manager CLI — list / add-nord / add-windscribe-wg / remove / status / reload / doctor. Pure Python stdlib (no pip install needed).
• Live verification — each tunnel is probed through a temporary WireGuard interface (Table = off, so it never touches your host routing or SSH session) and its real exit IP is reported.

🧭 How it works

                         ┌─────────────────────── PasarGuard / Xray-core ───────────────────────┐
                         │  routing rules: inboundTag ──▶ outboundTag                            │
   clients ──────────────▶  inbound-nord-de        ─▶ wg-nord-de        ─▶ NordVPN  🇩🇪          │
                         │  inbound-nord-nl        ─▶ wg-nord-nl        ─▶ NordVPN  🇳🇱          │
                         │  inbound-windscribe-wg  ─▶ wg-windscribe-1   ─▶ Windscribe (WireGuard) │
                         │  inbound-windscribe-ovpn─▶ ovpn-windscribe ──┐                         │
                         └───────────────────────────────────────────┼─────────────────────────┘
                                                                       │ sendThrough = tun0 IP
                                                          ┌────────────▼───────────┐
                                                          │ OpenVPN client (tun0)  │ ─▶ Windscribe (OpenVPN)
                                                          │ policy route: table 200│
                                                          └────────────────────────┘

Each outbound is a separate WireGuard instance inside Xray; routing rules map an inbound tag to its outbound tag. The OpenVPN exit is handled at the OS level (a tun interface) and reached via a Xray freedom outbound bound to the tun IP (sendThrough), with source-based policy routing so only that traffic uses the tunnel.

⚠️ Corrections vs. common assumptions

This project intentionally diverges from a few widespread-but-incorrect ideas:

Common assumption	Reality	What this repo does
"PasarGuard = Passwall"	PasarGuard (a Marzban-lineage Xray panel) and Passwall (an OpenWrt router package) are different products.	Installs PasarGuard via its official Docker-Compose script.
Set admin user/pass via install flags	PasarGuard configures via /opt/pasarguard/.env and creates admins through its CLI.	phase2 edits .env and runs pasarguard cli admins --create.
NordVPN: generate a key and register your public key to get an assigned IP	That's how Mullvad / self-hosted WG work. NordVPN gives you one account-bound NordLynx private key; the client address is always 10.5.0.2/32.	phase3 fetches the key from GET /v1/users/services/credentials + a recommended-server pubkey. No key registration.
Xray WG: keepAlive at outbound level	keepAlive and preSharedKey live inside the peer object.	Generated outbounds use the correct schema.
Manager edits POST /api/xray/config	PasarGuard keeps the config in its DB, edited through an authenticated API (Marzban-compatible).	Auths at /api/admin/token, reads/writes /api/core/config — all routes overridable in manager.conf; verify at <panel>/docs.

📦 Repository layout

File	Phase	Role
.env.example	—	Copy to .env, fill in your values
lib/common.sh	—	Shared bash helpers (logging, backup, env validation, confirm)
phase1_system_prep.sh	1	Packages, WireGuard module, IP forwarding, SSH-safe UFW, system report
phase2_pasarguard_install.sh	2	Install/configure PasarGuard, TLS, admin, install manager
phase3_nordvpn_wireguard.sh	3	NordVPN WireGuard outbounds
phase4_windscribe.sh	4	Windscribe WG + OpenVPN outbounds
phase5_manager_finalize.sh	5	Finalize/verify the management CLI
vpn-panel-manager	5	Python3 management CLI (the engine phases 3–4 call)
run-all.sh	—	Runs phases 1→5 in order, with a confirm gate at each boundary

✅ Prerequisites

• A fresh Debian 11/12 or Ubuntu 22.04/24.04 server with root/sudo.
• A NordVPN access token (NordVPN account → Manual setup → Access token).
• (Optional) Windscribe WireGuard and/or OpenVPN config files.

🚀 Quick start

# 0) On the server, normalize line endings + make executable
sudo apt-get update && sudo apt-get install -y dos2unix
find . -type f \( -name '*.sh' -o -name 'vpn-panel-manager' \) -exec dos2unix {} +
chmod +x *.sh vpn-panel-manager lib/*.sh

# 1) Configure
cp .env.example .env && chmod 600 .env
nano .env                      # fill EVERY value — leftover {{ ... }} placeholders are rejected

# 2) Run — all at once...
sudo ./run-all.sh
#    ...or phase by phase:
sudo ./phase1_system_prep.sh
sudo ./phase2_pasarguard_install.sh
sudo ./phase3_nordvpn_wireguard.sh
sudo ./phase4_windscribe.sh
sudo ./phase5_manager_finalize.sh

🛠️ Management CLI

sudo vpn-panel-manager list                                 # list outbounds (tag/protocol/endpoint)
sudo vpn-panel-manager status                               # probe each tunnel, show real exit IPs
sudo vpn-panel-manager add-nord --location GB               # add a NordVPN WireGuard outbound
sudo vpn-panel-manager add-windscribe-wg --config uk.conf   # add a Windscribe WG outbound
sudo vpn-panel-manager remove --tag wg-nord-de              # remove an outbound + its routing rule
sudo vpn-panel-manager reload                               # reload xray-core config
sudo vpn-panel-manager doctor                               # check panel auth + API routes

🔐 Security model

• Secrets live only in .env (600) and /etc/vpn-panel/manager.conf (600) — never on a command line, never hardcoded.
• Generated keys are written to /etc/vpn-panel/*.key with mode 600.
• .gitignore excludes .env, *.key, *.pem, registry.json, manager.conf, generated/, and backups/ so you never commit secrets.
• Every config change is backed up first to /etc/vpn-panel/backups/.

🩺 Troubleshooting

• Panel won't authenticate / config calls fail → your PasarGuard build's API routes may differ. Open https://DOMAIN:PORT/docs (Swagger; enabled via DOCS=True) and correct the three paths in /etc/vpn-panel/manager.conf. Then re-run sudo vpn-panel-manager doctor.
• Self-signed TLS warning → expected when you use an IP instead of a domain.
• Admin not created → run sudo pasarguard cli admins --create <user> --sudo manually.
• OpenVPN exit unstable → if Windscribe assigns a new tun IP after reconnect, re-bind: sudo vpn-panel-manager add-freedom --tag ovpn-windscribe --inbound-tag inbound-windscribe-ovpn --send-through <new tun ip> --iface <tun>.

📝 Caveats

• NordVPN manual WireGuard is unofficial. It works today but Nord may rotate keys/servers or change terms; treat it as best-effort.
• A real domain + certificate is strongly recommended over a self-signed cert on an IP.
• Outbound client tunnels don't require inbound UDP 51820/1194 to be open (those are only for WireGuard/OpenVPN inbounds).

⚖️ Disclaimer

Provided as-is, without warranty, for legitimate self-hosting and privacy use. You are responsible for complying with your local laws and with the terms of service of NordVPN, Windscribe, and any other provider you use. The authors are not affiliated with PasarGuard, NordVPN, or Windscribe.

---

🇮🇷 فارسی

معرفی

این مخزن مجموعه‌ای از اسکریپت‌های idempotent است که آن‌ها را روی سرور Debian/Ubuntu خودتان اجرا می‌کنید تا یک پنل پراکسی PasarGuard (مبتنی بر Xray-core) به‌همراه چند خروجی (outbound) VPN که از طریق سرویس‌های تجاری زنجیر شده‌اند بالا بیاورید؛ به‌علاوهٔ یک ابزار خط‌فرمان پایتونی (vpn-panel-manager) برای افزودن/حذف/بررسی این تونل‌ها.

ایده این است: کلاینت‌ها به پنل شما وصل می‌شوند و شما هر ورودی (inbound) را از یک خروجی VPN متفاوت (کشوری متفاوت برای هر خروجی) عبور می‌دهید — یک پراکسی چند-خروجی / چند-هاپ self-hosted.

⚠️ این اسکریپت‌ها برای اجرا توسط خودتان روی سرورتان طراحی شده‌اند. هیچ مقدار حساسی (توکن، رمز، کلید) داخل کد نوشته نشده — همه‌چیز از فایل .env/کانفیگ با دسترسی 600 خوانده می‌شود.

✨ امکانات

• نصب یک‌مرحله‌ای یا فاز‌به‌فاز (./run-all.sh یا phase1..5) با یک تأییدیه پیش از هر عملیات مخرب و بکاپ خودکار در /etc/vpn-panel/backups/.
• نصب و پیکربندی کامل PasarGuard (پورت، TLS، ساخت ادمین).
• خروجی‌های WireGuard نورد‌وی‌پی‌ان برای هر فهرستی از کشورها — با روش صحیح API (کلید خصوصی حساب NordLynx + کلید عمومی سرور پیشنهادی).
• خروجی‌های Windscribe هم با WireGuard و هم با OpenVPN (مورد دوم از طریق یک تونل شفاف و ایمن برای SSH با مسیریابی مبتنی بر مبدأ؛ چون Xray به‌صورت بومی OpenVPN را پشتیبانی نمی‌کند).
• ابزار vpn-panel-manager با دستورات list / add-nord / add-windscribe-wg / remove / status / reload / doctor — فقط با کتابخانهٔ استاندارد پایتون (بدون نیاز به pip install).
• بررسی زنده: هر تونل از طریق یک اینترفیس موقت WireGuard آزمایش می‌شود (Table = off، تا هرگز به مسیریابی سرور و نشست SSH شما دست نزند) و IP خروجی واقعی‌اش گزارش می‌شود.

⚠️ تصحیح چند برداشت رایج

برداشت رایج	واقعیت	کاری که این مخزن می‌کند
«PasarGuard همان Passwall است»	این دو محصول متفاوت‌اند (PasarGuard پنل Xray از خانوادهٔ Marzban، و Passwall پکیج روتر OpenWrt).	نصب PasarGuard با اسکریپت رسمی.
تنظیم یوزر/پسورد ادمین با فلگ نصب	پیکربندی از طریق /opt/pasarguard/.env و ساخت ادمین با CLI انجام می‌شود.	phase2 فایل .env را ویرایش و pasarguard cli admins --create را اجرا می‌کند.
«کلید بساز و public key را در نورد ثبت کن»	این روش مولوادـ/وایرگارد شخصی است. نورد یک کلید خصوصی NordLynx می‌دهد و آدرس کلاینت همیشه 10.5.0.2/32 است.	کلید از GET /v1/users/services/credentials گرفته و با pubkey سرور پیشنهادی جفت می‌شود.
keepAlive در سطح outbound	keepAlive و preSharedKey داخل آبجکت peer قرار می‌گیرند.	اسکیمای صحیح Xray رعایت شده.
مدیریت با POST /api/xray/config	کانفیگ در دیتابیس پنل است و از طریق API احرازشده ویرایش می‌شود.	احراز با /api/admin/token و خواندن/نوشتن /api/core/config؛ مسیرها در manager.conf قابل تغییرند (در <panel>/docs بررسی کنید).

✅ پیش‌نیازها

• سرور تازهٔ Debian 11/12 یا Ubuntu 22.04/24.04 با دسترسی root/sudo.
• یک Access token از NordVPN (حساب نورد → Manual setup → Access token).
• (اختیاری) فایل‌های کانفیگ WireGuard و/یا OpenVPN از Windscribe.

🚀 شروع سریع

# ۰) روی سرور: اصلاح line ending و اجرایی‌کردن فایل‌ها
sudo apt-get update && sudo apt-get install -y dos2unix
find . -type f \( -name '*.sh' -o -name 'vpn-panel-manager' \) -exec dos2unix {} +
chmod +x *.sh vpn-panel-manager lib/*.sh

# ۱) پیکربندی
cp .env.example .env && chmod 600 .env
nano .env                      # همهٔ مقادیر را پر کنید — placeholderهای {{ ... }} پذیرفته نمی‌شوند

# ۲) اجرا — یکجا...
sudo ./run-all.sh
#    ...یا فاز‌به‌فاز:
sudo ./phase1_system_prep.sh
sudo ./phase2_pasarguard_install.sh
sudo ./phase3_nordvpn_wireguard.sh
sudo ./phase4_windscribe.sh
sudo ./phase5_manager_finalize.sh

🛠️ دستورات مدیریت

sudo vpn-panel-manager list                                 # فهرست خروجی‌ها
sudo vpn-panel-manager status                               # تست هر تونل و نمایش IP خروجی واقعی
sudo vpn-panel-manager add-nord --location GB               # افزودن خروجی WireGuard نورد
sudo vpn-panel-manager add-windscribe-wg --config uk.conf   # افزودن خروجی WireGuard ویندسکرایب
sudo vpn-panel-manager remove --tag wg-nord-de              # حذف یک خروجی و قانون مسیریابی‌اش
sudo vpn-panel-manager reload                               # ری‌لود کانفیگ Xray
sudo vpn-panel-manager doctor                               # بررسی احراز هویت و مسیرهای API

🔐 مدل امنیتی

• مقادیر حساس فقط در .env (با مود 600) و /etc/vpn-panel/manager.conf (با مود 600) قرار دارند — نه در خط فرمان، نه داخل کد.
• کلیدهای تولیدشده در /etc/vpn-panel/*.key با مود 600 نوشته می‌شوند.
• فایل .gitignore مواردی مثل .env، *.key، registry.json و manager.conf را کنار می‌گذارد تا هرگز سهواً کامیت نشوند.
• پیش از هر تغییر، بکاپ گرفته می‌شود (/etc/vpn-panel/backups/).

📝 نکات مهم

• WireGuard دستی نورد رسمی نیست؛ امروز کار می‌کند ولی ممکن است کلیدها/سرورها تغییر کنند — به‌عنوان best-effort در نظر بگیرید.
• استفاده از دامنه و گواهی واقعی به‌جای self-signed روی IP اکیداً توصیه می‌شود.
• تونل‌های خروجی نیازی به باز بودن پورت‌های ورودی UDP 51820/1194 ندارند (آن‌ها فقط برای inbound‌ها لازم‌اند).

⚖️ سلب مسئولیت

این پروژه بدون هیچ ضمانتی و برای استفادهٔ مشروع شخصی و حفظ حریم خصوصی ارائه می‌شود. رعایت قوانین محلی و شرایط استفادهٔ سرویس‌ها (NordVPN، Windscribe و غیره) بر عهدهٔ خودتان است. این پروژه هیچ وابستگی رسمی به PasarGuard، NordVPN یا Windscribe ندارد.

---

Made for self-hosted privacy. Run it on your own server. 🛡️