CascadeVPN

Промежуточный IPv4-сервер для TCP/UDP: клиент → ваш VPS → конечный VPN/прокси. Меню на русском, команда cascade. Подходит для WireGuard/AmneziaWG (UDP), VLESS/XRay и MTProto (TCP), а также перенаправления между разными портами.

Это NAT relay. Он не устанавливает VPN-сервер, не создаёт ключи и не добавляет шифрование. Параметры VPN, UUID, ключи, TLS/SNI и проверка сертификатов остаются от конечного сервера. Все правила перенаправления создаются и удаляются через iptables.

Установка

Поддерживаются Debian 12/13 и Ubuntu 22.04/24.04, systemd, root и обычное Linux-ядро с iptables/conntrack и поддержкой nftables для проверки совместимости (см. ниже). Используется уже выбранный в системе вариант iptables без переключения системных настроек. OpenVZ и непривилегированные контейнеры могут не иметь необходимых прав.

wget -O install.sh https://raw.githubusercontent.com/WeirdPhrog/CascadeVPN/main/install.sh && sudo bash install.sh

Для автоматизации: sudo bash install.sh --no-menu. Для воспроизводимой установки замените main на конкретный проверенный commit SHA и скачайте рядом cascade.py из того же коммита. Или клонируйте репозиторий и запустите установщик из клона. Локальный cascade.py проверяется по SHA-256 так же, как скачанный. Если main обновился между скачиваниями, несовпадение хеша останавливает установку: скачайте оба файла одной версии.

Системные зависимости устанавливаются через apt: python3, iptables, nftables, conntrack, iproute2, ca-certificates, curl. Команда nft из пакета nftables используется только для чтения существующих правил и проверки конфликтов с другими firewall. Эта проверка обязательна и при iptables-legacy: ядро должно поддерживать nftables, а команда nft -j list ruleset — успешно выполняться от root. Если её выполнение запрещено или поддержка в ядре отсутствует, добавить и применить перенаправления не получится. Самостоятельно устанавливать пакет заранее не нужно; запуск nftables.service не требуется. Правила CascadeVPN по-прежнему создаются через iptables.

Настройка

После первой установки перенаправлений ещё нет: создайте правило через меню или команду ниже. Конечный VPN/прокси должен быть уже настроен и доступен с промежуточного VPS.

sudo cascade

# Адрес назначения и порт VPN; локальный IP определяется по маршруту к цели:
sudo cascade add --proto udp --in-port 51820 --target 203.0.113.10 --out-port 51820

# Явный локальный адрес и разные порты:
sudo cascade add --proto tcp --listen 192.0.2.10 --in-port 8443 \
  --target 203.0.113.10 --out-port 443

sudo cascade list
sudo cascade status

Замените адреса из примеров своими. --listen — адрес, назначенный интерфейсу VPS. Если провайдер использует внешний NAT, это может быть внутренний IP, а клиент использует публичный IP VPS. Входящий порт также нужно открыть в firewall/security group провайдера. Не указывайте 0.0.0.0: явная привязка нужна для безопасного удаления conntrack и чтобы не перехватывать пакеты, предназначенные другим адресам.

В VPN-клиенте поменяйте только адрес подключения и порт на публичный IP промежуточного VPS и входящий порт правила. Для проверки используйте другую машину: локально созданные соединения VPS не проходят через PREROUTING и не перенаправляются.

Повторное добавление идентичного правила безопасно. Чтобы изменить цель существующего входа, используйте --replace. Проверка свободного входящего порта обязательна, в том числе при замене. В меню занятый порт отклоняется сразу, до создания правила.

Проверяются TCP/UDP-сокеты, чужие DNAT/REDIRECT (включая диапазоны), опубликованные порты Docker и резервации остановленных контейнеров (включая диапазоны вида 8000-8010). Учитываются протокол и локальный адрес: TCP и UDP с одинаковым номером — разные порты. Проверка Docker работает и без docker-proxy. Если локальный Docker socket есть, но получить список контейнеров не удалось, добавление останавливается. Флага для принудительного захвата занятого порта нет.

Также запрещены порт 0, неверные IP/порты, локальная цель, loopback, multicast, адрес, не назначенный VPS, и цель из link-local 169.254.0.0/16 (там, например, метаданные облака). Для цели требуется маршрут типа unicast; local/broadcast/blackhole не допускаются. Наличие маршрута не подтверждает работоспособность самого VPN. Перед добавлением и повторным применением проверяются маршруты, локальные адреса, занятость портов и совместимость firewall. Для уже сохранённых TCP-правил (загрузка, reload) конфликтом считается только сокет LISTEN: исходящее соединение, которому ядро случайно выдало тот же номер порта, применение не срывает. Для UDP проверка всегда строгая: сервис может вызвать connect() для UDP-сокета и продолжать принимать пакеты. После неудачного запуска cascade.service повторяет попытку с паузой 20 секунд; ограничение — 20 запусков за 10 минут. Это помогает, если адрес или маршрут появляется позже. Если лимит исчерпан, после устранения причины выполните sudo systemctl reset-failed cascade && sudo systemctl start cascade.

Удаление

sudo cascade delete --proto udp --listen 192.0.2.10 --in-port 51820
sudo cascade clear --yes             # только правила CascadeVPN
sudo bash install.sh --uninstall     # правила, программа и systemd unit

Удаление убирает DNAT/MASQUERADE и очищает conntrack только по удалённым входящим адресу/порту, протоколу и адресу/порту цели. Чужие правила и цепочки сохраняются. Повторное удаление отсутствующего правила или уже удалённой программы допустимо. При ошибке очистки conntrack операция завершается с ошибкой и запускает откат прежних правил. Если откат тоже не удался, сообщение содержит обе ошибки. Конфигурация сохраняется для повторной попытки: устраните причину ошибки и повторите удаление. Уже завершённые соединения при откате не восстанавливаются.

При успешном --uninstall удаляются собственные цепочки и переходы CascadeVPN, программа, команда cascade, state.json и unit cascade.service. Сервис останавливается и отключается от автозапуска. Каталоги /etc/cascade и /usr/local/lib/cascade удаляются, если они пусты; при дополнительных файлах или оставленном файле блокировки выводится предупреждение. Удаление сообщает об успехе после проверки отсутствия правил с меткой cascade:v2 в обоих вариантах iptables и удаления файлов, кроме явно описанных остатков. Отсутствие утилиты iptables-*-save не считается доказательством отсутствия правил: её могли удалить уже после настройки. Исключение — вариант legacy, если в ядре доказуемо нет его таблиц: список /proc/net/ip_tables_names прочитан и пуст или отсутствует, потому что модуль ip_tables не загружен. Ошибка чтения этого списка считается невозможностью проверки.

Если во время удаления открыто меню CascadeVPN, например запущенное ещё до обновления и работающее со старым кодом, /etc/cascade/.lock остаётся с отметкой удаления: такое меню не сможет изменить firewall. Закройте его и повторите удаление, чтобы убрать и этот файл. Меню CascadeVPN считается любой процесс Python от root, среди аргументов которого есть файл cascade.py (установленный, копия или клон) либо путь к программе или команде cascade, в том числе относительный.

Удаление доводит до конца и частичную установку, например если программу удалили вручную. Если же правила CascadeVPN остались или firewall не удалось проверить, а программы нет, удаление остановится и сохранит файлы: устраните ошибку или запустите установку, затем удаление. При наличии unit его автозапуск отключается до проверки и очистки firewall. Если не удалось получить блокировку или выполнить systemctl disable, удаление останавливается раньше: в этом случае нельзя считать автозапуск отключённым.

При первой установке ошибка размещения файлов или запуска сервиса запускает то же удаление. Для отката действуют описанные выше условия очистки и исключения. Если откат не завершён, устраните ошибку и выполните sudo bash install.sh --uninstall.

Удаление проверяет сохранённые снимки /etc/iptables/rules.v4, /etc/iptables.rules и /etc/iptables.up.rules и предупреждает, если в них есть правила или цепочки CascadeVPN. Загрузчик такого снимка может вернуть их после перезагрузки; остальные пути и сторонние средства сохранения нужно проверить самостоятельно. Эти файлы CascadeVPN не переписывает. Если используете netfilter-persistent, после успешного удаления пересохраните текущие правила: sudo netfilter-persistent save. Если правите файл вручную, удалите строки с cascade:v2 и объявления цепочек :CSCD_DNAT, :CSCD_SNAT, :CSCD_FWD: оставшиеся пустые цепочки помешают следующей установке.

Удаление не возвращает ОС к состоянию до установки. В системе остаются:

• /run/cascade-install.lock — файл блокировки установщика, исчезает при перезагрузке;
• установленные через apt зависимости: ими могут пользоваться другие сервисы;
• включённый net.ipv4.ip_forward, если CascadeVPN включил его при применении правила; после перезагрузки значение определяется настройками ОС и другими сервисами;
• таблицы и базовые цепочки iptables (nat, filter), загруженные модули ядра (conntrack, NAT). CascadeVPN не удаляет эти общие объекты и не выгружает модули. После перезагрузки их могут снова создать или загрузить другие сервисы;
• скачанный install.sh (или клон репозитория), системный журнал и журналы apt.

Состояние и firewall

Технические имена cascade, cascade.service, /etc/cascade, cascade:v2 и CSCD_* сохранены для совместимости обновлений уже установленных версий CascadeVPN.

• Настройки: /etc/cascade/state.json, права 0600, каталог 0700.
• Программа: /usr/local/lib/cascade/cascade.py; команда /usr/local/bin/cascade.
• Свои цепочки: nat/CSCD_DNAT, nat/CSCD_SNAT, filter/CSCD_FWD. Правила и переходы помечены комментарием cascade:v2; чужие цепочки не очищаются.
• cascade.service восстанавливает правила и forwarding после загрузки сети. sudo systemctl reload cascade повторно применяет сохранённые правила.
• sudo cascade stop временно убирает правила, сохраняя конфигурацию; sudo cascade apply, sudo systemctl reload cascade или следующий запуск сервиса возвращают их.
• При первом правиле включается net.ipv4.ip_forward. После удаления он остаётся включённым: выключение общей маршрутизации нарушило бы работу Docker/Amnezia. sysctl.conf, BBR, конфигурация UFW и политики INPUT/FORWARD не редактируются. Если при включении forwarding политика FORWARD не DROP, CascadeVPN предупреждает: сервер начнёт пересылать и другой транзитный трафик, направленный на него.
• Для параллельных команд используется файловая блокировка. Ошибка применения/записи состояния запускает откат собственных правил. Перед применением выполняется iptables-restore --test; --noflush сохраняет чужие цепочки.
• Меню не держит блокировку, пока ждёт ввода, поэтому открытое меню не мешает удалению, переустановке и systemctl reload.
• Удаление сначала запрещает обычные команды управления, включая уже ожидающие блокировку, и только затем удаляет файлы. Команды остановки и внутренней очистки остаются доступны.

Docker и Amnezia на том же VPS

CascadeVPN может работать рядом с обычным Docker, использующим iptables, и Amnezia в его контейнерах. Выбирайте свободный входящий порт. Правила внутри VPN-контейнеров не меняются, публикации Docker сохраняются. Проверены настоящий Docker без userland proxy, TCP/UDP, политика FORWARD DROP и перезапуск Docker без повторного применения CascadeVPN.

Переходы в CSCD_FWD добавляются в начало FORWARD и, если она существует, DOCKER-USER. Разрешаются только соединения выбранного перенаправления, ответы и связанные ICMP-ошибки: проверяются исходный адрес/порт назначения и адрес/порт конечного сервера через conntrack. Поэтому FORWARD DROP не мешает каскаду, а остальной трафик продолжает проходить по прежним правилам. Эти точечные разрешения имеют приоритет над более поздними фильтрами FORWARD, включая UFW. Фильтры raw/mangle и firewall провайдера по-прежнему могут блокировать трафик.

Поддерживаются оба системных варианта iptables: iptables-legacy и iptables-nft (с обязательной проверкой через nft, описанной в разделе установки). Второй использует механизм nftables в ядре, сохраняя команды и формат правил iptables. Это совместимо с CascadeVPN. Но одновременные активные правила в обоих вариантах, отдельный firewall с собственными правилами nftables на пути пересылки или Docker, настроенный напрямую на nftables, требуют ручной настройки. При их обнаружении CascadeVPN отказывается добавлять правила; удаление своих правил остаётся доступным. Совместимость с произвольной конфигурацией firewall не гарантируется.

Не сохраняйте правила CascadeVPN дополнительно через netfilter-persistent save или общий снимок firewall: ими управляет cascade.service. Если сторонняя программа полностью сбросила firewall, выполните sudo systemctl reload cascade.

Проверка занятости отражает состояние на момент добавления/загрузки; она не резервирует порт в ОС и не мешает другому администратору позднее опубликовать его через Docker. Не используйте уже выделенный CascadeVPN порт для нового сервиса.

IPv6, диапазоны портов, DNS-имена целей, балансировка и настройка VPN-сервера не поддерживаются. Частные IPv4 назначения разрешены для работы через приватную сеть.

Тестирование

CI выполняет модульные тесты, проверку Bash/ShellCheck, установку и удаление с настоящим systemd на Ubuntu 22.04/24.04 и в контейнерах Debian 12/13, TCP/UDP-тесты в трёх Linux network namespaces, оба backend iptables на Ubuntu и отдельный тест с настоящим Docker и правилами по образцу AmneziaWG. Контейнеры Debian используют ядро Ubuntu-хоста. VPN-рукопожатие самой Amnezia, реальная перезагрузка VPS и firewall провайдера этими тестами не проверяются. Дополнительно проверяются параллельные команды, сохранность правил при ошибках NAT, записи конфигурации и conntrack, повреждённая конфигурация, откат неудачной первой установки и переустановки, удаление частичной установки, удаление при открытом меню (в том числе с кодом предыдущего выпуска 2.0.1), а также сохранённые TCP-правила рядом с исходящими соединениями на том же порту. После полного удаления, включая повторное удаление после закрытия меню, проверяется отсутствие файлов и каталогов CascadeVPN, ссылки автозапуска, упавшего unit и правил с меткой cascade:v2. Ветки отказа удаления (firewall не проверяется, нет одной из утилит iptables, ошибка удаления файлов, правила в другом варианте iptables) и поиск открытых меню на модели /proc (абсолютные и относительные пути, копии cascade.py) проверяются тестом tests/install-functions.sh с подменёнными системными командами.

python3 -m unittest discover -s tests -v
python3 tests/check_integrity.py
bash tests/install-functions.sh   # без root: системные команды подменены
# Только Linux с root; создаёт и удаляет собственные временные network namespaces:
sudo python3 tests/integration.py