podkop: канонический справочник (модель/списки/грабли/инвентарь)

Свёл разрозненные знания о podkop в один single-source-of-truth: snippets/podkop-reference.md.
Главное — семантика inside/outside (причина НИИКН-косяка), каталог листов + decision guide,
правильный конфиг, каталог граблей (busybox ip -br, слетающие overrides, fwmark vs NetBird,
cache.db lock, disable_quic, MTU), инвентарь podkop по объектам. Линки из runbook + CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -47,6 +47,14 @@
 - Домены NPM: смотри `projects/dttb/npm-proxy-hosts.md`
 - Карта сети: смотри `projects/dttb/network-topology.md`
 
+## Podkop (обход РКН на OpenWrt — почти все объекты)
+**Канонический справочник:** `snippets/podkop-reference.md` (модель, списки, конфиг, грабли, инвентарь). Диагностика «не работает»: `snippets/podkop-fakeip-diagnostics.md`.
+Кардинальные правила (за них уже наступали на грабли):
+- Объект **в РФ** (выход туннеля зарубежный) → списки `russia_inside` / точечные `meta`/`youtube`/`telegram`. **НИКОГДА `russia_outside`** (это РФ-сайты для тех, кто ЗА границей — сломает gosuslugi/ozon/ЕИС).
+- РФ-сайт «Доступ ограничен» + FakeIP → убирать лишний **список**, а не лепить per-domain override (overrides слетают при реконфиге podkop).
+- Фейкапится ли домен: `ssh root@<router> 'nslookup ДОМЕН 127.0.0.42'` (198.18.x = ушёл в туннель).
+- busybox `ip -br` не работает; `disable_quic=1` обязателен; awg0 в firewall WAN-зоне.
+
 ## Как работать
 - Перед правкой — читай текущее состояние файла
 - Не предлагай решения, которые уже описаны в `decisions/`

snippets/podkop-fakeip-diagnostics.md

@@ -10,6 +10,7 @@ tags: [openwrt, podkop, fakeip, amneziawg, sing-box, diagnostics, playbook]
 
 > SSH-доступ ко всем роутерам Олега: `ssh root@<netbird-ip>` пароль `1qaz!QAZ`.
 > На Сергее проверено 2026-05-12 — см. [[../decisions/2026-05-12-sergey-instagram-iphone-fakeip]].
+> 📖 **Модель / списки / правильный конфиг / грабли / инвентарь → [[podkop-reference]]** (это — только пошаговая диагностика).
 
 ## 0. Базовое — что вообще стоит
 
@@ -90,6 +91,8 @@ podkop list_update                       # обновить вручную
 
 Доступные community-листы podkop: `russia_inside`, `russia_outside`, `telegram`, `meta`, `discord`, `cloudflare`, `oai` (OpenAI/ChatGPT), `twitter`, `hdrezka` и др.
 
+> ⚠️ **inside ≠ outside!** Объект в РФ (обход РКН, зарубежный выход) → `russia_inside` или точечные `meta`/`youtube`/`telegram`. **НИКОГДА `russia_outside`** — он гонит РФ-сайты (gosuslugi/ozon/ЕИС) в зарубежный выход → гео-блок. Полная семантика: [[podkop-reference#2-списки-insideoutside-главные-грабли]].
+
 Добавить — `uci add_list podkop.main.community_lists='discord'; uci commit podkop; /etc/init.d/podkop restart`.
 
 ## 6. DNS-цепочка целая?

snippets/podkop-reference.md

@@ -0,0 +1,201 @@
+---
+date: 2026-05-29
+type: reference
+tags: [openwrt, podkop, sing-box, amneziawg, fakeip, netbird, reference, handbook]
+aliases: [podkop, подкоп, podkop-handbook, podkop-справочник]
+---
+
+# Podkop — канонический справочник
+
+> **Single source of truth по podkop.** Почти все объекты Олега на этом стеке (NIIKN, Sergey, Переделки, Benelux, Krasnogorsk, Znamenskoye, HomeLab dttb).
+> Здесь — **модель, списки, правильный конфиг, грабли, инвентарь**. Пошаговая диагностика «обход не работает» — в [[podkop-fakeip-diagnostics]].
+> Цель документа: перестать наступать на одни и те же грабли (история: [[../decisions/2026-05-29-niikn-diadoc-ozon-fix]] — месяц лечил симптом вместо причины).
+
+---
+
+## 1. Модель — понимать, а не копировать
+
+Podkop = обёртка над **sing-box** (+ туннель AmneziaWG/VLESS), которая селективно заворачивает ТОЛЬКО нужные домены в туннель через механизм **FakeIP**.
+
+```
+Клиент LAN
+  └─DNS→ dnsmasq:53 ──(noresolv)──► sing-box FakeIP DNS 127.0.0.42:53
+                                      ├─ домен В списке  → отдаёт FakeIP 198.18.x.x
+                                      └─ домен НЕ в списке→ резолвит реально (upstream)
+  └─пакет на 198.18.x.x → роутер: маршрут 198.18.0.0/15 → внутрь
+                          → nftables fwmark + tproxy → sing-box
+                          → sing-box знает реальный адрес (из FakeIP-кэша)
+                          → main-out (bind_interface awg0) → туннель → EXIT
+  └─пакет на реальный IP → обычный WAN напрямую
+```
+
+**Главное, что нужно усвоить:**
+- FakeIP (`198.18.0.0/15`) получают **только домены из подключённых списков**. Всё остальное идёт напрямую.
+- Туннель несёт **только** FakeIP-трафик. Значит «что заворачивается» = «какие списки подключены». Ошибся со списком → не тот трафик в туннеле.
+- **EXIT-нода туннеля определяет, КУДА выходит завёрнутый трафик.** У всех объектов Олега EXIT — **зарубежный** (Финляндия/Сингапур). Поэтому в туннель должно попадать только то, что нужно открывать с **зарубежного** IP (заблокированное РКН). Российский сайт в туннеле → выходит с зарубежного IP → гео-блок.
+
+---
+
+## 2. ⚠️ Списки inside/outside — ГЛАВНЫЕ грабли
+
+itdoginfo называет списки по тому, **где находится пользователь**, а не где сайт. Легко перепутать. Запомнить намертво:
+
+| Список | Что внутри | Для кого | Куда заворачивать |
+|--------|-----------|----------|-------------------|
+| **`russia_inside`** | Зарубежные сайты, заблокированные **внутри** России (РКН): соцсети, новости, и т.п. | Для тех, кто **внутри РФ** и хочет обойти РКН | ✅ в зарубежный туннель |
+| **`russia_outside`** | **Российские** сайты, доступные только из РФ-подсетей (gosuslugi, ozon, банки, gov.ru) | Для тех, кто **за границей** и хочет попасть на РФ-сервисы | ⛔ в **РОССИЙСКИЙ** выход (или вообще не заворачивать, если ты в РФ) |
+
+**Мнемоника:** `inside` = «я ВНУТРИ РФ, мне нужно наружу» (зарубежное заблокированное). `outside` = «я СНАРУЖИ РФ, мне нужно внутрь» (российское гео-фенсенное).
+
+### Decision guide
+
+| Сценарий объекта | EXIT туннеля | Какие списки | НЕ ставить |
+|------------------|-------------|--------------|------------|
+| Офис/дом **в РФ**, обойти РКН (типовой случай Олега) | зарубежный (FI/SG) | `russia_inside` ИЛИ точечно `meta`+`youtube`+`telegram`+(`twitter`/`discord`/`tiktok` по нужде) | ⛔ **`russia_outside`** — сломает РФ-сайты (gosuslugi/ozon/ЕИС → гео-блок) |
+| Доступ к РФ-сервисам из-за границы | **российский** | `russia_outside` | inside-списки |
+
+> **НИИКН-урок (2026-05-29):** стоял `russia_outside` при финском выходе → gosuslugi/ozon/ЕИС/nspd фейкапились и уходили в Финляндию → «Доступ ограничен». Лечилось dnsmasq-override'ами, которые слетали при каждом реконфиге → месяц повторяющихся жалоб. Корень — убрать `russia_outside`. **Если объект в РФ — `russia_outside` НЕ ставить никогда.**
+
+### Точечные списки vs бандл
+
+Для рабочего объекта **лучше точечные** (`meta`, `youtube`, `telegram`) чем `russia_inside` целиком: `russia_inside` тащит и `porn`/`anime`/`hdrezka`/`news` — лишняя нагрузка на туннель и не всегда уместно. `russia_inside` оправдан, когда нужен «всё заблокированное разом».
+
+---
+
+## 3. Каталог community-листов
+
+Источник: <https://github.com/itdoginfo/allow-domains>. Подключённые: `uci -q get podkop.main.community_lists`.
+
+| Список | Содержимое |
+|--------|-----------|
+| `meta` | Instagram, Facebook, WhatsApp, Threads — все Meta |
+| `youtube` | YouTube/Google video CDN |
+| `telegram` | Telegram (домены + IP) |
+| `twitter` | X/Twitter |
+| `discord` | Discord (вкл. голосовые IP) |
+| `tiktok` | TikTok |
+| `cloudflare` | CF-инфра (осторожно — широкий) |
+| `oai` | OpenAI / ChatGPT |
+| `hdrezka`,`anime`,`news`,`porn` | контент-категории |
+| `russia_inside` | бандл зарубежного заблокированного (см. §2) |
+| `russia_outside` | ⛔ российские гео-фенсенные сайты (см. §2) |
+
+Добавить/убрать:
+```sh
+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
+```
+
+---
+
+## 4. Базовый правильный конфиг (типовой объект в РФ)
+
+```sh
+# /etc/config/podkop
+uci set podkop.main.connection_type='vpn'      # vpn=AWG-интерфейс | proxy=VLESS/SS
+uci set podkop.main.interface='awg0'
+uci set podkop.settings.disable_quic='1'        # ⚠️ ОБЯЗАТЕЛЬНО (см. грабли)
+# списки — точечные под РФ-объект:
+for L in meta youtube telegram; do uci add_list podkop.main.community_lists="$L"; done
+uci commit podkop && /etc/init.d/podkop restart
+```
+
+Обязательные внешние условия (иначе туннель «есть, но не работает»):
+1. **awg0 в firewall WAN-зоне** — иначе пакеты не уходят:
+   `uci add_list firewall.@zone[1].network='awg0'; uci commit firewall; /etc/init.d/firewall reload`
+   Проверка: `nft list chain inet fw4 output | grep awg0` → `oifname "awg0" jump output_wan`.
+2. **DNS клиентов = роутер** (DHCP option 6), цепочка `LAN→dnsmasq→127.0.0.42` с `noresolv=1`.
+3. **Маршрут FakeIP-диапазона** на upstream-роутере, если podkop не на дефолтном шлюзе (как НИИКН, где шлюз — MikroTik):
+   `/ip route add dst-address=198.18.0.0/15 gateway=<podkop-router>` (MikroTik-синтаксис).
+4. **EXIT зарубежный** для inside-сценария.
+
+---
+
+## 5. Грабли (то, на что я наступал) — проверять в первую очередь
+
+| Грабли | Симптом | Что делать |
+|--------|---------|-----------|
+| **`russia_outside` на РФ-объекте** | РФ-сайты (gov/ozon/банки) «Доступ ограничен», заграница работает | Убрать список (§2). НЕ лепить per-domain override. |
+| **busybox `ip -br` не поддерживается** | `ip -br link` молча пуст → ложный вывод «интерфейса нет» | Проверять `ip addr show awg0` / `ip link show awg0`, живость — `ping -I awg0 8.8.8.8`. [[../../.claude/projects/-Users-ai-knowledge-base/memory/feedback_busybox_ip_br_flag\|памятка]] |
+| **dnsmasq-overrides слетают** | «вчера работало, сегодня нет» после реконфига | podkop владеет `dhcp.@dnsmasq[0].server` и переписывает его. **Не бороться за override — убрать причину фейкапа (список).** Если override нужен — выносить в `/etc/dnsmasq.d/` (podkop не трогает). |
+| **`disable_quic=0`** | YouTube/Meta/Google текут мимо обхода | QUIC/HTTP3 на UDP:443 идёт мимо tproxy. `disable_quic='1'` обязателен. |
+| **awg0 не в WAN-зоне** | туннель UP, handshake есть, но трафик не уходит | добавить awg0 в firewall WAN (§4). |
+| **NetBird + podkop конфликт fwmark** | tproxy-счётчик не растёт там, где есть NetBird (Переделки) | оба вешают chain на `prerouting priority mangle (-150)`, NetBird перетирает mark `0x00100000`. Фикс: патч `/usr/bin/podkop` — priority `-150 → -140`. [[../decisions/2026-04-17-peredelki-podkop-stability-fix]] |
+| **sing-box crash-loop / cache.db lock** | sing-box рестартует по кругу после ребута | залочен `cache.db` (две копии): `killall sing-box; sleep 2; /etc/init.d/podkop restart` |
+| **sing-box без procd-автозапуска** | после ребута обход мёртв | `/etc/init.d/sing-box enabled` должно быть включено |
+| **AmneziaWG H-значения диапазоном** | handshake не встаёт | H1–H4 на сервере и клиенте — фиксированные числа, не диапазоны |
+| **MTU/фрагментация** | сайты открываются наполовину | MTU awg0 1420→1380; `ping -M do -s 1380 8.8.8.8 -I awg0` |
+| **Клиент сам обходит DNS роутера** | curl с роутера ок, у клиента нет | iPhone Private Relay/Safari Hide IP/Chrome DoH. Выключить у клиента; на роутере — DNAT :53 + reject DoH (см. runbook §7). [[../../.claude/projects/-Users-ai-knowledge-base/memory/feedback_iphone_breaks_fakeip\|памятка]] |
+| **`podkop restart` сбрасывает `shutdown_correctly`** | редкие странности после рестарта | проверять флаг после рестарта |
+
+---
+
+## 6. Частые операции
+
+```sh
+# Завернуть конкретный домен, которого нет в листах (через туннель):
+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
+
+# ИСКЛЮЧИТЬ домен из проксирования (форсировать реальный IP → напрямую).
+# ⚠️ Сначала спроси: а почему он вообще фейкапится? Может, лишний список (§2).
+# Если правда нужен — override в dnsmasq:
+uci add_list dhcp.@dnsmasq[0].server='/example.ru/77.88.8.8'
+uci commit dhcp && /etc/init.d/dnsmasq restart
+rm -f /tmp/sing-box/cache.db && /etc/init.d/sing-box restart   # сбросить старый FakeIP
+
+# Обновить листы вручную:
+podkop list_update
+```
+
+---
+
+## 7. Диагностика (кратко; полный runbook отдельно)
+
+**Самый полезный тест — спросить sing-box напрямую, фейкапит ли он домен:**
+```sh
+nslookup ozon.ru 127.0.0.42
+#  198.18.x.x → домен В списке (заворачивается). Реальный IP → идёт напрямую.
+```
+Этим я доказал НИИКН-фикс: до удаления `russia_outside` РФ-сайты = 198.18.x, после = реальные, а instagram/youtube остались 198.18.x.
+
+Дальше — по шагам: **[[podkop-fakeip-diagnostics]]** (туннель → sing-box → nft/tproxy → маршрут → FakeIP → DNS-цепочка → клиент).
+
+---
+
+## 8. Анти-паттерн: симптом vs причина
+
+- Жалоба «РФ-сайт не открывается» + FakeIP на нём → **не лепить override**, а спросить «какой список его поймал» и убрать список.
+- «Overrides слетают» → не строить watchdog на доливку overrides, а убрать причину фейкапа.
+- Повторяется второй раз → проверить **свой исходный конфиг**, а не обход.
+- [[../../.claude/projects/-Users-ai-knowledge-base/memory/feedback_root_cause_recurring|памятка: корень vs band-aid]]
+
+---
+
+## 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` убран 2026-05-29; gov через NetBird→LionART маршруты + dnsmasq-overrides (backup); watchdog на pve-niikn |
+| **Sergey/Одинцово** | Cudy TR3000 `100.70.110.164` root/`1qaz!QAZ` | vpn / awg0 | Сингапур `202.71.12.186` | `russia_inside`,`telegram`,`meta` | ✅ корректно (inside); VLESS-резерв `vlees` |
+| **Переделки** | см. [[../projects/peredelki/README]] / [[../projects/peredelki/credentials]] | — | — | проверить | fwmark-патч -150→-140 (NetBird coexistence) |
+| **Benelux** | см. [[../projects/benilux/README]] (ключ mac-ed25519, был compromise 2026-05-20) | — | — | проверить | проверить на `russia_outside` |
+| **HomeLab dttb** | [[../projects/dttb/openwrt-router]] | — | — | — | цепочка с AGH: `dnsmasq→AGH:5353→127.0.0.42`; DNS-hijack стоит |
+| Krasnogorsk / Znamenskoye | см. project README | — | — | проверить | проверить |
+
+> Быстрый аудит любого роутера на «грабли inside/outside»:
+> `ssh root@<ip> 'uci -q get podkop.main.community_lists'` — если объект в РФ и видишь `russia_outside` → это баг.
+> TODO: пройтись по Переделки/Benelux/Krasnogorsk/Znamenskoye этим аудитом.
+
+---
+
+## Ссылки
+- [[podkop-fakeip-diagnostics]] — пошаговый runbook «обход не работает»
+- [[../decisions/2026-05-29-niikn-diadoc-ozon-fix]] — кейс russia_outside (корень)
+- [[../decisions/2026-04-17-peredelki-podkop-stability-fix]] — fwmark vs NetBird
+- [[../decisions/2026-04-30-openwrt-homelab-agh-podkop-chain]] — AGH + podkop цепочка
+- [[../decisions/2026-05-12-sergey-instagram-iphone-fakeip]] — клиент обходит DNS
+- [[../projects/niikn/openwrt-bypass]] — детальный конфиг AWG/НИИКН
+- itdoginfo allow-domains: <https://github.com/itdoginfo/allow-domains>