magisk-zapret2/docs/README.md

# Zapret2 для Android

<p align="center">
  <a href="https://git.zapret.moe/zapretdiscordyoutube/magisk-zapret2/releases/latest"><img alt="Последний релиз" src="https://img.shields.io/badge/Forgejo-%D0%A0%D0%B5%D0%BB%D0%B8%D0%B7%D1%8B-609926?style=for-the-badge&logo=forgejo&logoColor=white"></a>
  <a href="https://git.zapret.moe/zapretdiscordyoutube/magisk-zapret2"><img alt="Исходный код" src="https://img.shields.io/badge/Forgejo-%D0%98%D1%81%D1%85%D0%BE%D0%B4%D0%BD%D1%8B%D0%B9_%D0%BA%D0%BE%D0%B4-609926?style=for-the-badge&logo=forgejo&logoColor=white"></a>
  <a href="https://git.zapret.moe/zapretdiscordyoutube/magisk-zapret2/stars"><img alt="Звёзды в Forgejo" src="https://img.shields.io/badge/Forgejo-%D0%97%D0%B2%D1%91%D0%B7%D0%B4%D1%8B-FFD700?style=for-the-badge&logo=forgejo&logoColor=black"></a>
  <a href="https://git.zapret.moe/zapretdiscordyoutube/magisk-zapret2/commits/branch/main"><img alt="История изменений" src="https://img.shields.io/badge/Forgejo-%D0%9A%D0%BE%D0%BC%D0%BC%D0%B8%D1%82%D1%8B-8250DF?style=for-the-badge&logo=forgejo&logoColor=white"></a>
</p>

<p align="center">
  <a href="https://git.zapret.moe/zapretdiscordyoutube/magisk-zapret2/actions"><img alt="Сборка" src="https://img.shields.io/badge/Forgejo_Actions-%D0%A1%D0%B1%D0%BE%D1%80%D0%BA%D0%B0-609926?style=for-the-badge&logo=forgejo&logoColor=white"></a>
  <a href="LICENSE.md"><img alt="Лицензия" src="https://img.shields.io/badge/Лицензия-AGPL--3.0--only-BC4C00?style=for-the-badge&logo=gnu&logoColor=white"></a>
  <a href="https://github.com/bol-van/zapret2"><img alt="Upstream" src="https://img.shields.io/badge/Upstream-bol--van%2Fzapret2-24292F?style=for-the-badge&logo=github&logoColor=white"></a>
</p>

<p align="center">
  <img alt="Android 7.0+" src="https://img.shields.io/badge/Android-7.0%2B_(API_24)-3DDC84?style=for-the-badge&logo=android&logoColor=white">
  <img alt="ABI" src="https://img.shields.io/badge/ABI-arm64--v8a_%7C_armeabi--v7a-555555?style=for-the-badge&logo=arm&logoColor=white">
  <img alt="Root-доступ" src="https://img.shields.io/badge/Root-Magisk_%7C_KernelSU_%7C_APatch-8957E5?style=for-the-badge&logo=magisk&logoColor=white">
</p>

Root-модуль для Magisk, KernelSU и APatch, предназначенный для обхода некоторых
видов DPI-блокировок и замедления трафика на Android. Внутри используется
[`nfqws2`](https://github.com/bol-van/zapret2) с Lua-стратегиями, а приложение
**Zapret2 Control** позволяет управлять модулем без терминала.

![Интерфейс Zapret2 Control](assets/zapret2-control-ui.png)

> [!IMPORTANT]
> Zapret2 — не VPN. Он не меняет ваш IP-адрес, не скрывает трафик от провайдера и
> не добавляет шифрование. Модуль изменяет отдельные сетевые пакеты так, чтобы
> затруднить их распознавание DPI. Результат зависит от сети, провайдера и
> выбранной стратегии.

## Что понадобится

- Android 7.0 или новее;
- устройство с процессором ARM или ARM64;
- Magisk 20.4+, KernelSU или APatch с рабочим root-доступом;
- ядро с поддержкой `iptables` и `NFQUEUE`;
- приложение Zapret2 Control — необязательно, но рекомендуется.

Сборок для x86 и x86_64 нет.

Модуль обрабатывает трафик самого телефона. Устройства, подключённые к его
точке доступа, обслуживаются отдельным переключателем **Обход для точки
доступа** (по умолчанию выключен) — см. [ниже](#обход-для-точки-доступа).

## Установка

### 1. Скачайте файлы

Откройте страницу
**[последнего релиза](https://git.zapret.moe/zapretdiscordyoutube/magisk-zapret2/releases/latest)**
и скачайте:

- `zapret2-magisk-v*.zip` — универсальный root-модуль (историческое имя файла);
- `zapret2-control-v*.apk` — приложение для управления;
- файлы `.sha256` — если хотите вручную проверить контрольные суммы.

Не распаковывайте ZIP.

### 2. Установите модуль

1. Откройте Magisk, KernelSU Manager или APatch Manager.
2. Перейдите в **Модули** → **Установить из хранилища**.
3. Выберите `zapret2-magisk-v*.zip`.
4. Дождитесь завершения установки и перезагрузите устройство.

Устанавливайте ZIP только из работающей системы через root-менеджер. Прошивка
через TWRP или другое recovery не поддерживается ни одним из трёх режимов.

Для KernelSU 3.x заранее установите metamodule, если нужны команды
`zapret2-*` в `/system/bin` или системный hosts-оверлей: KernelSU делегирует
монтирование каталога `system/` metamodule. Сам сервис, приложение и
iptables/NFQUEUE не зависят от подмены файлов `/system`.

### 3. Установите приложение

1. Откройте `zapret2-control-v*.apk`.
2. При необходимости разрешите установку из этого источника.
3. Запустите Zapret2 Control и предоставьте ему root-доступ через активный
   root-менеджер.

Приложение необязательно: модуль может работать самостоятельно и запускаться при
загрузке Android.

## Первый запуск

1. Откройте в приложении раздел **Управление**.
2. Убедитесь, что root-доступ и модуль определены, а служба запущена.
3. Проверьте нужный сайт или приложение.
4. Если обход не работает, выберите другой готовый набор в разделе **Наборы**.

По умолчанию используется `Default v1 (game filter).txt`. Универсальной
стратегии для всех провайдеров нет, поэтому иногда нужно попробовать несколько
вариантов.

Для QUIC/HTTP3 может понадобиться отдельная UDP-стратегия. Если сервис работает
нестабильно, временное отключение QUIC в нём или браузере также поможет понять,
связан ли сбой с UDP.

## Обход для точки доступа

По умолчанию модуль обрабатывает только трафик самого телефона: правила стоят на
локальных цепочках `OUTPUT` и `INPUT`, а пакеты подключённых к точке доступа
устройств проходят через `FORWARD` и их не встречают.

Переключатель **Управление** → **Обход для точки доступа** добавляет те же
цепочки ещё и в `FORWARD`, поэтому трафик клиентов точки доступа обрабатывается
теми же правилами и той же стратегией. Новых правил при этом не появляется:
запрос клиента — это то же исходное направление соединения с портом сервера в
получателе, а ответ — то же обратное направление с портом сервера в источнике.

Что нужно учитывать:

- переключение перезапускает службу: топология публикуется при старте, поэтому
  соединения на несколько секунд прерываются;
- нагрузка растёт — через очередь проходит трафик всех подключённых устройств;
- на Android 11 и новее работает аппаратная и eBPF-разгрузка тетеринга. Она
  обходит netfilter для уже установленных потоков, поэтому часть трафика может
  не попасть в очередь. Обходу это обычно не мешает, так как `nfqws2` работает с
  первыми пакетами соединения, но при нестабильном результате разгрузку стоит
  отключить: `settings put global tether_offload_disabled 1` и повторное
  включение точки доступа.

## Наборы, профили и стратегии

- **Набор** — полный TXT-файл с конфигурацией запуска.
- **Профиль** — часть набора для определённого трафика или сервиса.
- **Стратегия** — последовательность действий `nfqws2`, применяемая внутри
  профиля.
- **`--skip`** — отключает профиль, не удаляя его.

Обычный порядок настройки:

1. Выберите готовый вариант в разделе **Наборы**.
2. Если нужна точная настройка, откройте **Профили**.
3. Выберите другую стратегию для нужного профиля или отключите ненужный профиль.
4. Сохраните изменения — приложение проверит конфигурацию и применит её через
   перезапуск службы.

В редакторе набора можно посмотреть итоговые аргументы запуска до сохранения.
Некорректные или неподдерживаемые параметры отклоняются до запуска `nfqws2`.
Там же можно импортировать собственный UTF-8 `.txt`: приложение не переписывает
стратегию, не заменяет существующий файл и добавляет её в каталог только после
общей проверки и `nfqws2 --dry-run`.

Подробный формат описан в
[`PRESET_PROFILE_STRATEGY_CONTRACT_RU.md`](PRESET_PROFILE_STRATEGY_CONTRACT_RU.md).

## Возможности приложения

| Раздел | Что в нём находится |
| --- | --- |
| **Управление** | Состояние модуля и службы, запуск, остановка, автозапуск, обход для точки доступа, обновления и восстановление |
| **Профили** | Включение профилей и выбор стратегий |
| **Наборы** | Выбор, импорт и редактирование полных TXT-конфигураций |
| **Списки хостов** | Просмотр, импорт и редактирование списков |
| **Редактор хостов** | Управление системным hosts-оверлеем |
| **Управление DNS** | Выбор DNS-набора и служб |
| **Журналы** | Логи и диагностические данные |
| **О приложении** | Версии, ссылки и сведения о лицензии |

## Обновление

### Через Zapret2 Control

1. Откройте **Управление** → **Проверить обновления**.
2. Просмотрите версию и состав обновления.
3. Нажмите **Обновить**.
4. Подтвердите установку APK в системном установщике, если он откроется.
5. Перезагрузите устройство, если обновлялся root-модуль.

Приложение проверяет контрольные суммы, подпись APK и структуру ZIP до установки.
Для установки оно автоматически выбирает официальный backend активной среды:
`magisk --install-module`, `ksud module install` или `apd module install`.
Новая версия сначала помещается в `/data/adb/modules_update/zapret2` и
становится активной только после перезагрузки.

### Вручную

Скачайте новый релиз, установите ZIP через свой root-менеджер, APK — поверх
текущего приложения, затем перезагрузите устройство.

> [!WARNING]
> Обновление модуля устанавливает чистое содержимое нового релиза. Изменённые
> настройки, пользовательские наборы, списки хостов и Lua-файлы из текущей
> установки автоматически не переносятся. Сохраните нужные данные заранее.

Подробнее об обновлении, восстановлении и удалении:
[`USER_OPERATIONS_RU.md`](USER_OPERATIONS_RU.md).

## Если обход не работает

Проверяйте по порядку:

1. В разделе **Управление** убедитесь, что служба запущена без ошибок.
2. Попробуйте другой готовый набор.
3. Проверьте, что нужный профиль не отключён через `--skip`.
4. Для QUIC/HTTP3 попробуйте набор с UDP-стратегией.
5. Временно отключите AdGuard, NetGuard, AFWall+ и другие программы, которые
   изменяют firewall или перенаправляют трафик.
6. Сравните работу через Wi-Fi и мобильную сеть: у них могут быть разные DPI и
   подходящие стратегии.
7. Откройте **Журналы**, сохраните диагностику и приложите её к сообщению об
   ошибке.

### Служба не запускается

Чаще всего причина — отсутствие обязательных возможностей ядра или firewall.
Для IPv4 нужны `iptables`, `iptables-restore`, `NFQUEUE` с `--queue-bypass`, а
также модули `multiport` и `mark`. Поддержка `connbytes` желательна, но не
обязательна. Если IPv6-бэкенд недоступен, IPv6-трафик не перехватывается.

Точный порядок проверки устройства описан в
[`tests/device/README.md`](../tests/device/README.md).

### Интернет стал медленнее

Отключите ненужные профили через `--skip` и оставьте только те TCP/UDP-фильтры,
которые действительно нужны. Затем перезапустите службу и проверьте ещё раз.

## Команды терминала

Для ручного управления из Termux или `adb shell`:

```sh
# Состояние
su -c zapret2-status

# Запуск
su -c zapret2-start

# Остановка
su -c zapret2-stop

# Перезапуск
su -c zapret2-restart

# Журнал Android
su -c "logcat -s Zapret2"
```

На KernelSU команды `zapret2-*` требуют metamodule, который монтирует
`system/`. Без него используйте Zapret2 Control или запускайте скрипты из
каталога модуля.

## Совместимость root-менеджеров

Архитектура следует общему контракту трёх проектов:

- module scripts получают свой корень через `MODDIR=${0%/*}`;
- installer использует переданный root-менеджером `MODPATH`;
- активная и ожидающая перезагрузки генерации находятся соответственно в
  `/data/adb/modules/zapret2` и `/data/adb/modules_update/zapret2`;
- встроенное обновление выбирает installer backend, а не изменяет активное
  дерево самостоятельно.

Это соответствует официальным руководствам
[Magisk](https://topjohnwu.github.io/Magisk/guides.html),
[KernelSU](https://kernelsu.org/guide/module.html) и
[APatch](https://apatch.dev/apm-guide.html).

Другие root-менеджеры могут оказаться ZIP-совместимыми, но не заявлены как
поддерживаемые, пока у них нет проверенного installer API и совместимого
контракта `modules`/`modules_update`.

## Как это работает

1. `iptables` направляет подходящие TCP/UDP-пакеты в очередь `NFQUEUE`.
2. `nfqws2` получает их в пользовательском пространстве.
3. Lua-стратегия изменяет порядок, разбиение или содержимое отдельных пакетов.
4. Пакеты возвращаются в сетевой стек Android и отправляются напрямую, без
   стороннего VPN-сервера.

Перехватываются только порты, которые нужны включённым профилям активного
набора.

Каждая релизная сборка получает последний стабильный релиз исходного
[`bol-van/zapret2`](https://github.com/bol-van/zapret2), проверяет архив и
контрольные суммы, а затем записывает точную версию исходного кода в пакет.

## Частые вопросы

### Работает ли Zapret2 в любой сети?

Нет гарантии. Результат зависит от провайдера, используемого DPI, протокола и
стратегии. Один набор может работать в мобильной сети и не работать через Wi-Fi.

### Скрывает ли модуль мой IP-адрес?

Нет. Соединение идёт напрямую к сайту, поэтому ваш обычный публичный IP-адрес не
меняется.

### Шифрует ли Zapret2 трафик?

Нет. Шифрование определяется самим приложением или протоколом, например HTTPS.
Zapret2 не создаёт дополнительный зашифрованный туннель.

### Работает ли он вместе с VPN или сетевым фильтром?

Иногда, но совместимость не гарантируется. VPN, блокировщики рекламы и firewall-
приложения могут использовать те же сетевые таблицы и конфликтовать с модулем.

### Где получить подробную диагностику?

В разделе **Журналы** приложения или с помощью `zapret2-status`. Расширенные
эксплуатационные инструкции находятся в
[`USER_OPERATIONS_RU.md`](USER_OPERATIONS_RU.md), включая раздел «Модуль не
запускается и не останавливается». Устройство модуля и принципы, по которым он
принимает решения, описаны в [`ARCHITECTURE_2_2.md`](ARCHITECTURE_2_2.md).

## Благодарности

- [bol-van/zapret2](https://github.com/bol-van/zapret2) — исходный проект,
  `nfqws2` и Lua-стратегии;
- участникам сообщества — за тестирование наборов и устройств.

## Лицензия

Материалы, на которые правообладатели проекта вправе выдать лицензию,
распространяются строго на условиях
[GNU Affero General Public License v3](LICENSE.md) (`AGPL-3.0-only`).
Покрываемые производные нельзя распространять под закрытой или иной
несовместимой лицензией; для них должны выполняться требования AGPL о доступе
к соответствующему исходному коду.

Сторонние компоненты, включая загружаемые материалы `bol-van/zapret2`, не
перелицензируются этим проектом. Точная область действия лицензии и правила
использования товарных знаков описаны в
[политике лицензирования](LICENSING.md).