elmprodvpn/selective-vpn-api/OPS_CHECKLIST.md

Ops Checklist (Selective VPN) / Боевой чеклист

RU: Практический чеклист для проверки и восстановления работы маршрутизации и DNS. EN: Practical runbook/checklist for validating and recovering routing + DNS behavior.

RU: DNS mode и Traffic mode это две независимые оси. EN: DNS mode and Traffic mode are independent.

0) Safety First / Безопасность

RU:

• Лучше тестировать изменения, пока у тебя есть стабильный SSH.
• direct traffic mode это аварийный режим: он убирает базовые policy rules.
• Если ты сидишь удаленно и доступ только через VPN, избегай direct без плана отката.

EN:

• Prefer to test changes while you still have a stable SSH session.
• direct traffic mode is an emergency option: it removes base policy rules.
• If VPN is your only access, avoid switching to direct without a rollback plan.

1) Quick Health (API)

curl -s http://127.0.0.1:8080/healthz
curl -s http://127.0.0.1:8080/api/v1/status
curl -s http://127.0.0.1:8080/api/v1/dns/status
curl -s http://127.0.0.1:8080/api/v1/traffic/mode/test

RU: смотри, чтобы traffic/mode/test вернул healthy=true, probe_ok=true. EN: make sure traffic/mode/test returns healthy=true, probe_ok=true.

2) Quick Health (Linux)

ip rule show
ip -4 route show table agvpn
ip -4 route get 1.1.1.1
ip -4 route get 1.1.1.1 mark 0x66

RU: ожидаемые паттерны:

• Selective: есть правило типа pref 12000 fwmark 0x66 lookup agvpn.
• Full tunnel: есть правило типа pref 11900 lookup agvpn.
• В VPN-режимах в agvpn таблице есть default dev <vpn-iface>.

EN: expected patterns:

• Selective mode: rule like pref 12000 fwmark 0x66 lookup agvpn.
• Full tunnel: rule like pref 11900 lookup agvpn.
• In VPN modes agvpn has default dev <vpn-iface>.

3) Validate LAN and Containers / Проверка локалки и Docker

RU: цель: в full_tunnel обычно нужно, чтобы LAN и Docker продолжали работать. EN: goal: in full_tunnel you usually want LAN and Docker networks to keep working.

RU: если в full_tunnel ломается доступ к LAN/docker:

• включи auto_local_bypass.
• если нужно, чтобы контейнеры ходили в интернет direct (а хост через VPN), добавь docker CIDR в Force Direct subnets.

EN: if LAN/docker break in full_tunnel:

• enable auto_local_bypass.
• if you want containers direct in full tunnel, add docker CIDRs to Force Direct subnets.

4) Validate nft sets / Проверка nft

RU: обычно используются два сета:

• agvpn4: direct-resolved IPs + static
• agvpn_dyn4: wildcard/smartdns dynamic IPs

nft list table inet agvpn
nft list set inet agvpn agvpn4
nft list set inet agvpn agvpn_dyn4

5) Wildcard DNS / SmartDNS

RU: state и артефакты:

• Canonical wildcard state: /var/lib/selective-vpn/smartdns-wildcards.json
• Generated rules file: /etc/selective-vpn/smartdns.conf

RU: runtime accelerator (опционально):

• когда включен, SmartDNS конфиг может содержать nftset ... agvpn_dyn4.
• когда выключен, wildcard все равно работает через resolver job + prewarm.

systemctl is-active smartdns-local.service
ls -la /etc/selective-vpn/smartdns.conf /var/lib/selective-vpn/smartdns-wildcards.json

6) Safe Recovery / Безопасный откат

A) Clear routes (save cache) / Clear с сохранением снапшота

GUI: Clear routes (save cache).

RU: очищает routes/nft, но сохраняет снапшот для восстановления. EN: clears routes/nft but saves a snapshot for restore.

B) Restore cached routes / Восстановление снапшота

GUI: Restore cached routes.

RU:

• часть маршрутов может быть linkdown (docker bridge). Restore пропускает некритичные ошибки.

EN:

• some routes can be linkdown (docker bridges). Restore skips non-critical failures.

C) Restart services / Рестарт сервисов

sudo systemctl restart selective-vpn-api.service

7) Logs / Логи

journalctl -u selective-vpn-api.service -n 200 --no-pager
journalctl -u selective-vpn-api.service -f

8) Common Pitfalls / Частые грабли

• Docker bridge маршруты могут существовать, но быть linkdown (best-effort).
• UID/cgroup overrides влияют на процессы хоста (OUTPUT) и обычно не управляют forwarded Docker-трафиком.
• Если overrides списки слишком большие, backend отвергнет их (лимит на каждый тип).