todo/Zapret/hostlist.md
loop-uh d523a6d7ef
Some checks failed
Published content check / validate (push) Failing after 28s
hostlist, ipset, filter: статьи переписаны с нуля — примеры, что важнее чего, схемы и анимации
- Zapret/hostlist: как движок ищет домен (от точного имени к общему),
  префиксы ^ и ! (движок 1.0.7), первая запись побеждает, несколько
  списков в профиле, исключения из исключающего списка, автосписок,
  --hostlist-domains, один файл — один раз, как это устроено в Zapret GUI,
  частые ошибки, справочник опций.
- Zapret/ipset: что такое подсеть /24 простыми словами, формат файла,
  почему адрес решает с первого пакета, исключения сильнее включений,
  ipset и hostlist в одном профиле, откуда брать адреса, частые ошибки.
- Zapret2/filter: порядок проверок внутри профиля, адрес раньше имени,
  сводная таблица «что важнее чего», справочник фильтров, примеры
  пресетов; встроенные ![[ipset]]/![[hostlist]] заменены сравнением и
  ссылками. Якоря «Как выбирается профиль» и «Списки IP и доменов»
  сохранены (на второй ссылается экскурсия программы).
- Анимации (scripts/wiki-anim-specs.py): hostlist-walk, hostlist-layers,
  ipset-check, profile-lists-timing. Диаграммы (render.py):
  hostlist-match-grid (значения посчитаны кодом Zapret GUI),
  ipset-vs-hostlist-timing, filter-check-chain.
- Zapret/--wf-raw-part: ссылка на новый якорь hostlist.

Правила сверены с исходниками zapret2 nfq2/hostlist.c, ipset.c, desync.c.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 16:20:21 -05:00

254 lines
29 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
date: 2026-11-01
tags:
- zapret
- zapret2
- nfqws2
- hostlist
- filter
- profile
aliases:
- хостлист
- Hostlist в Zapret 2
- Список сайтов Zapret
- Как исключить сайт из hostlist
- Что значит ! в hostlist
- Что значит ^ в hostlist
- hostlist-exclude исключение из исключения
- failed to register hostlist
description: "Списки сайтов в Zapret 2 (hostlist): как движок ищет домен, префиксы ^ и !, исключения из исключений, автосписок, что важнее чего — с примерами."
image: Zapret/attachments/hostlist-match-grid.png
link: https://github.com/bol-van/zapret2/blob/master/docs/manual.md
---
> [!mirror] Резервное зеркало
> Актуальная версия этой страницы — на основной вики: [jzesawgjsz.zapret.moe/Zapret/hostlist](https://otukcszfwr.zapret.moe/Zapret/hostlist)
# 📋 Hostlist: списки сайтов в Zapret 2 — как движок их читает и что важнее чего
![[hostlist-match-grid.png]]
> [!info] О чём заметка
> Полное объяснение списков сайтов в [[Zapret2/Zapret2|Zapret 2]]: из чего состоит строка, как движок ищет в списке сайт, что делают префиксы `^` и `!` (второй появился в движке 31 октября 2026 года), почему первая запись домена важнее остальных, как работают исключающие списки, автосписок и списки прямо в командной строке, и как всё это выглядит в программе Zapret GUI. Парная заметка про списки IP-адресов — [[Zapret/ipset|ipset]], общий порядок проверок профиля — [[Zapret2/filter|фильтры профиля]].
## TL;DR
- Hostlist — файл с доменами, по одному на строку. Профиль с таким списком работает только для этих сайтов, и **поддомены учитываются сами**: `youtube.com` ловит и `www.youtube.com`, и `m.youtube.com`.
- Движок ищет сайт **от точного имени к общему** (`www.torrents.ru` → `torrents.ru` → `ru`), и решает **первая найденная** запись. Порядок строк в файле на это не влияет.
- `^домен` — только сам домен, без поддоменов. `!домен` — **локальное исключение**: домен и его поддомены не считаются частью **этого** файла. `ru` и `!torrents.ru` — все сайты `.ru`, кроме torrents.ru. Префиксы сочетаются в любом порядке.
- Домен в одном файле учитывается **один раз — по первой записи**. В Zapret GUI ваши записи стоят перед встроенными, поэтому ваше `!youtube.com` отключает встроенное `youtube.com`.
- Исключающий список (`--hostlist-exclude`) сильнее включающего. Главная польза `!` — исключения **из** исключающего списка: раньше такой возможности не было.
## Зачем профилю список сайтов
[[Zapret2/profile|Профиль]] в Zapret 2 — это набор условий («какой трафик мой») и стратегия («что с ним делать»). Условия бывают разные: порты, протокол, адреса серверов. Список сайтов — самое понятное из них: профиль срабатывает только тогда, когда соединение идёт к сайту из списка. Так в одном [[Zapret2/preset|пресете]] живут разные стратегии для YouTube, Discord и всех остальных сайтов, и каждая не мешает другим.
Движок берёт имя сайта из самого соединения: из поля SNI в приветствии TLS (первое сообщение браузера в HTTPS-соединении, где открытым текстом написано, к какому сайту он обращается), из заголовка `Host` в обычном HTTP и из приветствия QUIC. Пока такого сообщения не было, имени у движка нет, и профиль со списком сайтов в выборе не участвует — первые пакеты соединения обрабатывает профиль ниже. Подробно этот момент разобран в [[Zapret2/filter#Как выбирается профиль|заметке о фильтрах профиля]]; списку адресов [[Zapret/ipset|ipset]] такое ожидание не нужно, адрес известен с первого пакета.
Проще говоря: hostlist отвечает на вопрос «к какому сайту идёт соединение», а ответ появляется у движка не сразу, а с приветствием TLS.
## Формат файла
Файл — обычный текст, одна запись на строке. Движок читает строку так (функция `addpool` в [исходнике nfq2/hostlist.c](https://github.com/bol-van/zapret2/blob/master/nfq2/hostlist.c)):
- пробелы и табуляция в начале пропускаются;
- строка, которая начинается с `#`, `;` или `/`, — комментарий;
- регистр не важен, `YouTube.COM` и `youtube.com` одно и то же;
- всё после первого пробела в строке отбрасывается: строка `example.com лишнее` превращается в `example.com`;
- звёздочки не поддерживаются: `*.example.com` хранится как есть и не совпадёт ни с одним сайтом. Писать их и не нужно, поддомены учитываются сами;
- файл можно сжать gzip, движок прочитает его и так.
```text
# сайты YouTube
youtube.com
googlevideo.com
^youtu.be
!music.youtube.com
```
> [!warning] Пустой файл — это «все сайты»
> Если в файле нет ни одной записи, движок считает, что списка у профиля нет вовсе, и профиль срабатывает **для любого сайта**. Это старое поведение, его автор движка оставил ради совместимости. Zapret GUI поэтому никогда не оставляет список пустым: в пустой список программа сама дописывает заглушку `www.example.com`. Если правите файлы руками, помните об этом.
## Как движок ищет сайт в списке
Это главный механизм, от которого зависит всё остальное. Получив имя сайта, движок проверяет сначала само имя, потом убирает слева по одной части и проверяет родителя, пока имя не кончится. Для `www.torrents.ru` это три шага: `www.torrents.ru`, `torrents.ru`, `ru`. На каждом шаге он смотрит, есть ли в списке запись ровно с таким доменом. **Первая найденная запись решает всё**, дальше поиск не идёт (функция `SearchHostList` там же).
![[wiki-anim-hostlist-walk.svg|Анимация: движок ищет mail.ru, www.torrents.ru, m.vk.com и vk.com в списке из строк ru, !torrents.ru и ^vk.com]]
Отсюда два следствия, которые важно запомнить:
1. **Порядок строк в файле не влияет на поиск.** `!torrents.ru` сильнее `ru`, даже если стоит ниже: поиск идёт от точного имени к общему и упирается в `torrents.ru` раньше, чем в `ru`.
2. **Самая конкретная запись выигрывает.** Если в списке есть `!youtube.com` и `music.youtube.com`, то `music.youtube.com` в списке (его запись найдена первой), а `www.youtube.com` — нет.
Проще говоря: движок идёт по имени сайта справа налево, от длинного к короткому, и останавливается на первом совпадении.
## Префикс `^`: только сам домен
Обычная запись ловит домен со всеми поддоменами. Если поддомены не нужны, перед доменом ставят `^`. Запись `^vk.com` ловит `vk.com`, но не `m.vk.com` и не `api.vk.com`.
Технически запись с `^` срабатывает только на первом шаге поиска, когда проверяется полное имя сайта. На шагах с родительскими именами движок её пропускает и ищет дальше. Поэтому `^vk.com` вместе с `com` поймает `m.vk.com` через `com`: запись `^vk.com` на родительском шаге просто не считается.
| В списке | `vk.com` | `m.vk.com` | `api.vk.com` |
|---|---|---|---|
| `vk.com` | ✓ | ✓ | ✓ |
| `^vk.com` | ✓ | — | — |
| `^vk.com` и `com` | ✓ | ✓ (через `com`) | ✓ (через `com`) |
## Префикс `!`: локальное исключение
`!` перед доменом означает: этот домен и его поддомены **не считаются частью этого файла**. Если поиск дошёл до записи с `!`, он останавливается с ответом «сайта в этом списке нет».
Префикс добавлен в движок коммитом [«nfqws2: ! support in hostlists»](https://github.com/bol-van/zapret2/commit/48ec126f6286553adfa31d016a5a6690b58bf832) 31 октября 2026 года и описан в [журнале изменений версии 1.0.7](https://github.com/bol-van/zapret2/blob/master/docs/changes.txt). Пример автора движка: нужна вся зона `.ru`, кроме `torrents.ru`:
```text
ru
!torrents.ru
```
С таким файлом `mail.ru` и `yandex.ru` в списке, а `torrents.ru` и `www.torrents.ru` — нет. Если нужно исключить только сам домен и оставить его поддомены, префиксы сочетают: `!^torrents.ru` (или `^!torrents.ru`, порядок префиксов не важен). Тогда `torrents.ru` вне списка, а `www.torrents.ru` остаётся в нём через `ru`. Все варианты собраны на диаграмме в начале заметки.
> [!important] «Локальное» — значит только внутри своего файла
> Исключение не переходит в другие файлы и не превращается в запись противоположного типа. Если у профиля два включающих списка, в первом `ru` и `!torrents.ru`, а во втором `torrents.ru`, профиль **возьмёт** torrents.ru через второй файл: исключение из первого файла второму не указ. И `!` во включающем списке не делает домен исключением всего профиля — для этого есть `--hostlist-exclude`.
## Один домен — одна запись: первая побеждает
Внутри одного файла домен хранится один раз. Движок добавляет записи по порядку строк и пропускает домен, который уже есть, **вместе с его префиксами** (так прямо сказано в [руководстве движка](https://github.com/bol-van/zapret2/blob/master/docs/manual.md)). Поэтому:
```text
ru
!ru ← не действует: домен ru уже записан строкой выше
```
Здесь порядок строк важен, но только для одинаковых доменов. `ru` и `!ru` — один домен, первая запись `ru` победила. `ru` и `!torrents.ru` — разные домены, обе записи работают, и решает уже поиск от точного имени к общему.
## Несколько списков в одном профиле: что важнее чего
У профиля может быть несколько включающих списков (`--hostlist`) и несколько исключающих (`--hostlist-exclude`). Движок проверяет их в таком порядке (функция `HostlistCheck_`):
1. **Сначала все исключающие списки.** Если сайт нашёлся хотя бы в одном — профиль его не берёт, и включающие списки уже не смотрят. Исключение всегда сильнее включения.
2. **Потом включающие.** Хватит совпадения в любом из них.
3. Если включающих списков нет или все они пустые, профиль подходит любому сайту, который не попал в исключения.
Если профиль сайт не взял, соединение проверяют следующие профили [[Zapret2/preset|пресета]] — по [[Zapret2/filter#Как выбирается профиль|общему правилу выбора профиля]] сверху вниз.
| Ситуация | Итог для torrents.ru |
|---|---|
| `--hostlist` с `ru` | профиль берёт |
| `--hostlist` с `ru` и `!torrents.ru` | профиль не берёт |
| `--hostlist` (файл A: `ru`, `!torrents.ru`) и `--hostlist` (файл B: `torrents.ru`) | профиль берёт — через файл B |
| `--hostlist` с `ru` и `--hostlist-exclude` с `torrents.ru` | профиль не берёт — исключение сильнее |
| `--hostlist-exclude` с `ru` и `!torrents.ru`, включающего списка нет | профиль берёт: из исключений torrents.ru «вычеркнут» |
## Исключения из исключающего списка — главная польза `!`
До `!` у включающего списка был способ убрать лишнее — добавить исключающий список. А у исключающего списка такого способа не было: он и так самый сильный, «исключить из исключений» было нечем. Автор движка называет это главной причиной появления префикса.
Пример. Широкий профиль «все сайты» не должен трогать российские сайты, поэтому в его исключающем списке стоит вся зона `ru`. Но один сайт в этой зоне заблокирован, и его надо обходить:
```text
# lists/exclude-ru.txt — подключён через --hostlist-exclude
ru
!torrents.ru
```
Теперь профиль пропускает все сайты `.ru`, кроме torrents.ru: его он берёт и применяет к нему стратегию. Другие исключающие списки этого профиля `!` не затрагивает: если `torrents.ru` есть ещё в одном `--hostlist-exclude`, он останется исключённым.
## Автосписок `--hostlist-auto`
Автосписок — файл, в который движок сам дописывает домены, где заметил блокировку (несколько неудачных попыток подряд). У профиля с автосписком своё правило выбора: если имя сайта известно, такой профиль берёт соединение всегда, а список решает только, применять ли к нему стратегию. Пороги и отладка автосписка — в [руководстве движка](https://github.com/bol-van/zapret2/blob/master/docs/manual.md), раздел про детектор неудач автохостлистов.
С `!` в автосписке одна особенность. Обычный сайт, которого нет в автосписке, движок держит под наблюдением: считает неудачные попытки и после нескольких подряд дописывает домен в файл. Сайт с записью `!домен` в автосписке движок считает **исключённым**: стратегию к нему не применяет, неудачи по нему не считает и обратно в автосписок не дописывает. Это единственный случай, когда `!` работает как исключающий список, а не как локальная пометка: иначе движок видел бы на домене неудачи и раз за разом пытался бы дописать его в файл, плодя повторы. Если тот же домен записан ещё и в обычном `--hostlist` этого профиля, стратегия к нему применится через тот список.
Автор движка писать `!` в автосписок не советует: файл предназначен для самого движка. Но если такая запись там оказалась, она обрабатывается по правилу выше и работу не ломает.
## Список прямо в строке
Короткий список можно не выносить в файл, а написать через запятую прямо в [[Zapret2/preset|пресете]]:
```bash
--hostlist-domains=youtube.com,googlevideo.com,^youtu.be
--hostlist-exclude-domains=ru,!torrents.ru
```
Здесь работают те же `#`, `^` и `!`. Важная деталь: в одном профиле такой встроенный список **один** каждого вида. Несколько строк `--hostlist-domains` не создают новые списки, а дописывают в тот же, и повтор домена отбрасывается по правилу первой записи. Значит, `--hostlist-domains=ru` и ниже `--hostlist-domains=!ru` — это `ru`, а `!ru` не действует.
## Один файл — один раз в профиле
С 31 октября 2026 года (коммит [«do not allow registering same file more than once in a single profile»](https://github.com/bol-van/zapret2/commit/abbe48056d62011d93e7a475c953535f18c5caa3)) движок не разрешает подключать один и тот же файл в профиле дважды одного типа. `--hostlist` и `--hostlist-auto` считаются одним типом, `--hostlist-exclude` — другим. На повтор winws2 отвечает строкой `failed to register hostlist '…'` и не запускается.
```bash
--hostlist=lists/youtube.txt
--hostlist=lists/youtube.txt # ошибка: файл уже подключён
--hostlist-auto=lists/youtube.txt # тоже ошибка: тот же тип
--hostlist-exclude=lists/youtube.txt # можно: другой тип
```
В соседнем профиле тот же файл подключать можно. Если перед `failed to register` стоит строка `cannot access hostlist file`, причина другая — файла нет на диске.
## Как это выглядит в Zapret GUI
В программе у профиля есть вкладка со списком сайтов: слева поле «Ваши записи», справа «Встроенные записи (только просмотр)». Встроенные записи приходят с программой и обновляются вместе с ней, ваши лежат отдельным файлом в папке `lists/user` и при обновлении не пропадают. Движку программа отдаёт один итоговый файл, и с ноября 2026 года в нём **сначала ваши записи, потом встроенные**.
![[wiki-anim-hostlist-layers.svg|Анимация: ваши строки !youtube.com и ^vk.com попадают в итоговый файл первыми, встроенные youtube.com и vk.com отбрасываются как повторы]]
По правилу первой записи это означает простую вещь: **ваша строка перебивает встроенную**. Хотите, чтобы встроенный `youtube.com` не работал, — напишите у себя `!youtube.com`. Хотите сузить встроенный `vk.com` до самого домена — `^vk.com`.
Редактор списка помогает не ошибиться:
- префиксы `^` и `!` подсвечены, строка-исключение выделена отдельным цветом;
- при наведении на строку подсказка объясняет, что она делает, например «без этой строки домен попал бы сюда через «ru»»;
- предупреждения: домен уже записан выше (вторая запись не действует), исключению нечего исключать (в списке нет записи, которая захватывает этот домен), строка уже есть во встроенных;
- `Ctrl+.` на строке — сделать её исключением `!` или «только этим доменом» `^` и обратно, `Ctrl+Пробел` в начале строки — те же префиксы списком;
- кнопка **«Что это?»** внизу вкладки — подробное объяснение с кнопками на статьи вики.
Редактор пресета подчёркивает повтор файла списка в профиле, а если такой пресет всё же запущен, программа пишет причину словами вместо `failed to register hostlist`.
> [!warning] Режим Zapret 1
> Старый движок `winws` (режим Zapret 1) понимает `^`, но **не понимает `!`**: строку `!torrents.ru` он примет за имя сайта, и исключение не сработает. Папка `lists` у режимов общая, поэтому в режиме Zapret 1 редактор списка предупреждает о каждой строке с `!`. Проверено по исходникам zapret (`nfq/hostlist.c`) 1 ноября 2026 года.
## Частые ошибки
| Что написано | Что происходит | Как правильно |
|---|---|---|
| `*.youtube.com` | не совпадёт ни с чем | `youtube.com` — поддомены учтутся сами |
| `https://youtube.com/` | не домен, программа не сохранит строку | `youtube.com` |
| `ru`, ниже `!ru` | `!ru` не действует: первая запись победила | решите, что нужно, и оставьте одну запись |
| `!torrents.ru` в одном файле, `torrents.ru` в другом | профиль берёт сайт через второй файл | уберите `torrents.ru` из второго файла или исключите сайт через `--hostlist-exclude` |
| `!site.com` без родительской записи (`com`) | ничего не меняет: исключать нечего | `!` нужен только вместе с более общей записью |
| пустой файл | профиль срабатывает для любого сайта | хотя бы одна запись или заглушка |
| два `--hostlist` с одним файлом в профиле | winws2 не запускается | одна строка на файл |
## Справочник опций
| Опция | Что делает |
|---|---|
| `--hostlist=<файл>` | профиль только для доменов из файла; можно несколько файлов, хватит совпадения в любом |
| `--hostlist-domains=<домены>` | то же, домены через запятую прямо в строке; все такие строки профиля — один список |
| `--hostlist-exclude=<файл>` | не применять профиль к доменам из файла; проверяется раньше включающих списков |
| `--hostlist-exclude-domains=<домены>` | то же через запятую |
| `--hostlist-auto=<файл>` | автосписок: движок сам дописывает заблокированные домены; один на профиль |
| `--hostlist-auto-fail-threshold`, `--hostlist-auto-fail-time`, `--hostlist-auto-retrans-threshold` | пороги, после которых домен попадает в автосписок |
| `--hostlist-auto-debug=<файл>` | журнал решений автосписка (общая опция) |
| `--ipcache-hostname` | запоминать имя сайта по адресу, чтобы список срабатывал и без SNI (общая опция) |
## Источники
- [Руководство nfqws2, docs/manual.md — раздел о хостлистах и ipset](https://github.com/bol-van/zapret2/blob/master/docs/manual.md)
- [Коммит 48ec126 «nfqws2: ! support in hostlists», 31 октября 2026](https://github.com/bol-van/zapret2/commit/48ec126f6286553adfa31d016a5a6690b58bf832)
- [Коммит abbe480 — один файл в профиле только один раз, 31 октября 2026](https://github.com/bol-van/zapret2/commit/abbe48056d62011d93e7a475c953535f18c5caa3)
- [docs/changes.txt — журнал изменений, версия 1.0.7](https://github.com/bol-van/zapret2/blob/master/docs/changes.txt)
- [Исходник nfq2/hostlist.c — разбор строки и поиск домена](https://github.com/bol-van/zapret2/blob/master/nfq2/hostlist.c)
## 📚 См. также
- [[Zapret/ipset|ipset]] — списки IP-адресов и подсетей: формат, исключения, почему они срабатывают с первого пакета
- [[Zapret2/filter|Фильтры профиля]] — полный порядок проверок профиля: порты, протокол, адреса, сайты
- [[Zapret2/exclusions|Исключения]] — как пустить сайт мимо обхода: профиль `pass` или исключающий список
- [[Zapret2/profile|Профиль]] — из чего состоит профиль и как его настроить
- [[Zapret2/preset|Пресет]] — файл со всеми профилями сразу
- [[Zapret2/find-site-domains|Как найти домены сайта]] — что записывать в список, чтобы сайт открылся целиком
---
> [!quote] 🤖 Эти статьи открыты — можно обучать на них ИИ
> При желании вы можете натренировать ИИ на наших статьях. Исходное форматирование доступно в Forgejo: [исходник этой заметки](https://iianajhlkh.zapret.moe/zapretdiscordyoutube/todo/src/branch/main/Zapret/hostlist.md) · [скачать весь репозиторий одним zip-архивом](https://iianajhlkh.zapret.moe/zapretdiscordyoutube/todo/archive/main.zip).