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

29 KiB
Raw Permalink Blame History

date tags aliases description image link
2026-11-01
zapret
zapret2
nfqws2
hostlist
filter
profile
хостлист
Hostlist в Zapret 2
Список сайтов Zapret
Как исключить сайт из hostlist
Что значит ! в hostlist
Что значит ^ в hostlist
hostlist-exclude исключение из исключения
failed to register hostlist
Списки сайтов в Zapret 2 (hostlist): как движок ищет домен, префиксы ^ и !, исключения из исключений, автосписок, что важнее чего — с примерами. Zapret/attachments/hostlist-match-grid.png https://github.com/bol-van/zapret2/blob/master/docs/manual.md

[!mirror] Резервное зеркало Актуальная версия этой страницы — на основной вики: jzesawgjsz.zapret.moe/Zapret/hostlist

📋 Hostlist: списки сайтов в Zapret 2 — как движок их читает и что важнее чего

!

[!info] О чём заметка Полное объяснение списков сайтов в Zapret2/Zapret2: из чего состоит строка, как движок ищет в списке сайт, что делают префиксы ^ и ! (второй появился в движке 31 октября 2026 года), почему первая запись домена важнее остальных, как работают исключающие списки, автосписок и списки прямо в командной строке, и как всё это выглядит в программе Zapret GUI. Парная заметка про списки IP-адресов — Zapret/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 такое ожидание не нужно, адрес известен с первого пакета.

Проще говоря: hostlist отвечает на вопрос «к какому сайту идёт соединение», а ответ появляется у движка не сразу, а с приветствием TLS.

Формат файла

Файл — обычный текст, одна запись на строке. Движок читает строку так (функция addpool в исходнике nfq2/hostlist.c):

  • пробелы и табуляция в начале пропускаются;
  • строка, которая начинается с #, ; или /, — комментарий;
  • регистр не важен, YouTube.COM и youtube.com одно и то же;
  • всё после первого пробела в строке отбрасывается: строка example.com лишнее превращается в example.com;
  • звёздочки не поддерживаются: *.example.com хранится как есть и не совпадёт ни с одним сайтом. Писать их и не нужно, поддомены учитываются сами;
  • файл можно сжать gzip, движок прочитает его и так.
# сайты 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

Отсюда два следствия, которые важно запомнить:

  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» 31 октября 2026 года и описан в журнале изменений версии 1.0.7. Пример автора движка: нужна вся зона .ru, кроме torrents.ru:

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.

Один домен — одна запись: первая побеждает

Внутри одного файла домен хранится один раз. Движок добавляет записи по порядку строк и пропускает домен, который уже есть, вместе с его префиксами (так прямо сказано в руководстве движка). Поэтому:

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. Но один сайт в этой зоне заблокирован, и его надо обходить:

# lists/exclude-ru.txt — подключён через --hostlist-exclude
ru
!torrents.ru

Теперь профиль пропускает все сайты .ru, кроме torrents.ru: его он берёт и применяет к нему стратегию. Другие исключающие списки этого профиля ! не затрагивает: если torrents.ru есть ещё в одном --hostlist-exclude, он останется исключённым.

Автосписок --hostlist-auto

Автосписок — файл, в который движок сам дописывает домены, где заметил блокировку (несколько неудачных попыток подряд). У профиля с автосписком своё правило выбора: если имя сайта известно, такой профиль берёт соединение всегда, а список решает только, применять ли к нему стратегию. Пороги и отладка автосписка — в руководстве движка, раздел про детектор неудач автохостлистов.

С ! в автосписке одна особенность. Обычный сайт, которого нет в автосписке, движок держит под наблюдением: считает неудачные попытки и после нескольких подряд дописывает домен в файл. Сайт с записью !домен в автосписке движок считает исключённым: стратегию к нему не применяет, неудачи по нему не считает и обратно в автосписок не дописывает. Это единственный случай, когда ! работает как исключающий список, а не как локальная пометка: иначе движок видел бы на домене неудачи и раз за разом пытался бы дописать его в файл, плодя повторы. Если тот же домен записан ещё и в обычном --hostlist этого профиля, стратегия к нему применится через тот список.

Автор движка писать ! в автосписок не советует: файл предназначен для самого движка. Но если такая запись там оказалась, она обрабатывается по правилу выше и работу не ломает.

Список прямо в строке

Короткий список можно не выносить в файл, а написать через запятую прямо в Zapret2/preset:

--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») движок не разрешает подключать один и тот же файл в профиле дважды одного типа. --hostlist и --hostlist-auto считаются одним типом, --hostlist-exclude — другим. На повтор winws2 отвечает строкой failed to register hostlist '…' и не запускается.

--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 не работал, — напишите у себя !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 (общая опция)

Источники

📚 См. также

  • Zapret/ipset — списки IP-адресов и подсетей: формат, исключения, почему они срабатывают с первого пакета
  • Zapret2/filter — полный порядок проверок профиля: порты, протокол, адреса, сайты
  • Zapret2/exclusions — как пустить сайт мимо обхода: профиль pass или исключающий список
  • Zapret2/profile — из чего состоит профиль и как его настроить
  • Zapret2/preset — файл со всеми профилями сразу
  • Zapret2/find-site-domains — что записывать в список, чтобы сайт открылся целиком

[!quote] 🤖 Эти статьи открыты — можно обучать на них ИИ При желании вы можете натренировать ИИ на наших статьях. Исходное форматирование доступно в Forgejo: исходник этой заметки · скачать весь репозиторий одним zip-архивом.