knowledge-base/snippets/podkop-agent-runbook.md

date, type, tags, aliases

date	type	tags	aliases
2026-06-18	reference	openwrt podkop agent runbook autonomous sing-box amneziawg fakeip netbird	podkop-agent podkop-ops-agent агент-подкоп podkop-runbook

Podkop — runbook для AI-агента (автономный обход блокировок)

Операционная выжимка для агента (напр. Дирижёр), который должен САМ диагностировать и чинить обход блокировок (podkop) на роутерах Олега. Здесь — роль, доступ, правила, алгоритм, инвентарь. Канон (теория/конфиг/все грабли) — podkop-reference; пошаговая диагностика — podkop-fakeip-diagnostics; сеть/доступы — ../projects/dttb/network-topology, ../projects/dttb/credentials. При расхождении прав канон, не этот файл.

Роль и автономия

• Цель: жалоба «сайт/обход не работает» → за минимум шагов найти класс причины и починить.
• Делай сам: SSH на роутер; читать состояние (uci/nft/awg/sing-box/dns); прогнать алгоритм ниже; чинить типовые грабли; рестартить podkop/sing-box/firewall/dnsmasq.
• Спроси Олега перед: сменой EXIT-ноды; заменой connection_type vpn↔proxy; массовой правкой списков; любым действием на роутере клиента, способным оборвать ему интернет.
• Главное правило причины-vs-симптома: чинишь одно и то же повторно → ищи СВОЙ конфиг (лишний список), НЕ лепи per-domain overrides (они слетают). podkop-reference#8-анти-паттерн-симптом-vs-причина

Доступ к роутерам

• Универсально: ssh root@<netbird-ip> пароль 1qaz!QAZ.
• Benelux — исключение: SSH по mac-ed25519 ключу, без пароля (после compromise 2026-05-20 WAN-SSH/пароль закрыты).
• НИИКН OpenWrt за jump-хостом: ssh root@100.70.120.229 (pve-niikn) → роутер 192.168.1.50.
• busybox: ip -br НЕ поддерживается (молча пуст) → проверяй ip addr show awg0 / ip link show awg0, живость — ping -I awg0 8.8.8.8.

4 кардинальных правила (не нарушать)

1. Объект в РФ (выход зарубежный) → списки russia_inside ИЛИ точечные meta/youtube/telegram. НИКОГДА russia_outside — это РФ-сайты для тех, кто ЗА границей; сломает gosuslugi/ozon/ЕИС/gov.ru (фейкап → финский выход → гео-блок).
2. disable_quic='1' обязателен (иначе YouTube/Meta/Google текут по QUIC мимо обхода).
3. awg0 в firewall WAN-зоне (иначе туннель UP, handshake есть, но трафик не уходит).
4. РФ-сайт «Доступ ограничен» + FakeIP на нём → убрать лишний список, НЕ per-domain override.

Алгоритм триажа «обход не работает» (строго по порядку — каждый шаг отсекает класс причин)

# 0. Что вообще стоит
opkg list-installed | grep -iE "podkop|sing-box|amneziawg|adguard|netbird|dnsmasq"
# 1. Туннель живой?  handshake должен быть < 2 мин
awg show awg0; ip route | grep awg0
#    старый/нет handshake → endpoint недоступен / порт зарезан DPI / ребутнуть peer
# 2. sing-box живой?
ps w | grep -v grep | grep sing-box; podkop check_logs 2>&1 | tail -40
#    crash-loop → залочен cache.db: killall sing-box; sleep 2; /etc/init.d/podkop restart
# 3. nft/tproxy маркировка
podkop check_nft | grep -E "tproxy|198\.18"
#    0 пакетов в proxy chain → клиенты не идут в FakeIP (→ шаги 5-6)
# 4. Туннель реально маршрутизирует?  должны быть РАЗНЫЕ IP
curl -4 -s --max-time 5 https://ifconfig.me; echo
curl -4 -s --max-time 5 --interface awg0 https://ifconfig.me; echo
#    одинаковые → ip rule/fwmark сломан ИЛИ main-out без bind_interface: awg0
# 5. FakeIP подменяет?  спросить sing-box напрямую (самый полезный тест)
nslookup ОЗОН_ИЛИ_INSTAGRAM 127.0.0.42
#    198.18.x.x = домен В списке (в туннеле); реальный IP = НЕ в списке
uci -q get podkop.main.community_lists     # что подключено сейчас
# 6. DNS-цепочка цела?  LAN→dnsmasq:53→127.0.0.42 (noresolv=1)
ss -ulnp 2>&1 | grep ":53"; uci show dhcp.@dnsmasq[0] | grep -E "server|noresolv"
# 7. Клиент сам обходит роутерный DNS (САМАЯ ЧАСТАЯ при исправном роутере)
#    iPhone: Private Relay/Safari Hide IP/Chrome DoH → выключить у клиента;
#    на роутере — DNAT :53 + reject DoH (см. fakeip-diagnostics §7)

Норма, НЕ баг: Meta NetSeer probes в логе; podkop check_fakeip показывает РФ-IP (тестовый домен не в списке); regex-баг unknown operand в podkop check_proxy. Если всё проверено и не помогло: dns_type udp→doh; connection_type vpn→proxy (секция vlees — резерв); MTU 1420→1380.

Инвентарь объектов podkop (доступ + конфиг; полный — podkop-reference#9-инвентарь-podkop-по-объектам)

Объект	Роутер / доступ	conn/iface	EXIT	Списки	Заметки
НИИКН	OpenWrt VM101 192.168.1.50 (jump pve-niikn 100.70.120.229)	vpn/awg0	Финляндия 78.17.4.225	meta,youtube,telegram	russia_outside убран; gov через NetBird→LionART + dnsmasq-override (backup); watchdog на pve-niikn
Sergey/Одинцово	Cudy TR3000 100.70.110.164 root/1qaz!QAZ	vpn/awg0	Сингапур 202.71.12.186	russia_inside,telegram,meta	VLESS-резерв vlees
Benelux	Cudy TR3000 100.70.207.97, ssh mac-ed25519 ключ (пароль закрыт)	vpn/awg0	Сингапур 202.71.12.186	russia_inside,telegram,meta (+githubusercontent.com)	list_update чинён (raw.git заведён в обход); download_lists_via_proxy=1 ломает sing-box — держать 0
Переделки	../projects/peredelki/credentials	—	—	проверить	fwmark-патч -150→-140 (coexistence с NetBird)
HomeLab dttb	../projects/dttb/openwrt-router	—	—	—	цепочка с AGH: dnsmasq→AGH:5353→127.0.0.42; DNS-hijack стоит
Krasnogorsk / Znamenskoye	см. project README	—	—	проверить	TODO аудит inside/outside

Быстрый аудит роутера на грабли inside/outside: ssh root@<ip> 'uci -q get podkop.main.community_lists' — если объект в РФ и есть russia_outside → это баг, убрать.

Частые готовые операции

# завернуть домен, которого нет в листах:
uci set podkop.main.user_domain_list_type='dynamic'
uci add_list podkop.main.user_domains='example.com'; uci commit podkop; /etc/init.d/podkop restart
# добавить/убрать community-лист:
uci add_list podkop.main.community_lists='discord'
uci del_list podkop.main.community_lists='russia_outside'
uci commit podkop; /etc/init.d/podkop restart
# list_update падает (raw.githubusercontent.com блокирован РКН) → завести github в обход:
uci set podkop.main.user_domain_list_type='dynamic'
uci add_list podkop.main.user_domains='githubusercontent.com'; uci commit podkop; /etc/init.d/podkop restart

Ссылки (канон — single source of truth)

• podkop-reference — модель, списки, конфиг, ВСЕ грабли, инвентарь
• podkop-fakeip-diagnostics — пошаговый runbook диагностики
• ../projects/dttb/network-topology · ../projects/dttb/credentials
• ../decisions/2026-05-29-niikn-diadoc-ozon-fix — кейс russia_outside (корень)