nfqws2: update docs

docs/manual.md

@@ -443,7 +443,7 @@ MULTI-STRATEGY:
  --hostlist-auto-fail-threshold=<int>                   ; параметр автолиста : количество неудач подряд для занесения в лист. по умолчанию 3
  --hostlist-auto-fail-time=<int>                        ; параметр автолиста : максимальное время между неудачами без сброса счетчика. по умолчанию 60 секунд
  --hostlist-auto-retrans-threshold=<int>                ; параметр автолиста : количество tcp ретрансмиссий в одном сеансе для фиксации неудачи. по умолчанию 3
- --hostlist-auto-retrans-maxseq=<int>                   ; параметр автолиста : исходящий relative sequence, после которого детект неудачи прекращается. по умолчанию 65536
+ --hostlist-auto-retrans-maxseq=<int>                   ; параметр автолиста : исходящий relative sequence, после которого детект неудачи прекращается. по умолчанию 32768
  --hostlist-auto-incoming-maxseq=<int>                  ; параметр автолиста : входящий relative sequence, после которого детект неудачи прекращается, а счетчик сбрасывается. по умолчанию 4096
  --hostlist-auto-udp-out=<int>                          ; параметр автолиста : условие неудачи udp : количество исходящих пакетов больше или равно значению. по умолчанию 4
  --hostlist-auto-udp-in=<int>                           ; параметр автолиста : условие неудачи udp : количество входящих пакетов меньше или равно значению. по умолчанию 1
@@ -495,3 +495,112 @@ LOGICAL NETWORK FILTER:
  --nlm-filter=net1[,net2,net3,...]      ; список сетей Network List Manager, при наличии подключения к которым перехват включается, а иначе не включается.
  --nlm-list[=all]                       ; вывести список подключенных NLM сетей. all - список всех NLM сетей
 ```
+
+## Использование множественных профилей
+
+Профили существуют, чтобы в зависимости от указанных условий фильтра выбрать ту или иную стратегию воздействия на трафик.
+Общая схема использования профилей следующая :
+
+```
+nfqws2 <глобальные_параметры>
+<фильтр 1> <стратегия 1> -- new
+<фильтр 2> <стратегия 2> -- new
+...............
+<фильтр N> <стратегия N>
+```
+
+Когда на вход поступает пакет, и для него еще нет записи в conntrack, происходит выбор профиля.
+Фильтры профиля проверяются от первого до последнего - с начала в конец - слева направо, и никак иначе.
+Всегда выигрывает только один профиль - по первому совпадению условий фильтра, а все остальные не задействуются.
+Если не сработал ни один фильтр, выбирается пустой профиль с номером 0, не предполагающий никаких действий с трафиком.
+
+Все условия, кроме `--filter-l7` и хостлистов, являются однозначными и известными с момента начала обработки потока (с начала соединения).
+В начале как правило еще неизвестнен протокол потока и имя хоста, выделяемое из сообщений потока.
+Когда эти величины становятся известны, происходит поиск профиля заново. Если выбирается другой профиль - происходит перескок.
+Таких перескоков может быть до двух, поскольку есть только 2 величины, влияющие на выбор, неизвестные с самого начала.
+Для протоколов потока tls, http, quic обычно бывает только 1 перескок, поскольку определение протокола и имени хоста
+происходит по одному пакету или группе пакетов. Для XMPP это 2 перескока - сначала определяется xmpp как таковой,
+затем ловится переход на TLS, и только в нем выделяется имя хоста.
+При написании стратегий следует их продумывать с учетом логики перескоков.
+Если нужно, чтобы стратегия начала работу с самого первого пакета и продолжила работать дальше после изменения профиля,
+нужно дублировать вызовы во всех профилях, по которым может пройти поток.
+
+Когда имеются много сложных и повторяющихся стратегий, может быть удобно использовать шаблоны.
+Шаблон - это такой же профиль, только он не идет в работу, а попадает в отдельный список шаблонов.
+Шаблоном профиль становится через задание параметра `--template=<name>`.
+Далее он может быть имортирован (`--import=<name>`). Импорт предполагает копирование профиля полностью,
+а не только тех настроек, которые в нем были указаны - все остальные настройки имеют значения по умолчанию.
+Любые настройки текущего профиля стираются, включая и имя.
+Поэтому `--import` надо писать в начале, а потом добавлять уникальные для профиля параметры.
+Шаблоны могут импортировать и друг друга. Для шаблона обязательно уникальное имя, а при импорте имя копируется,
+поэтому обязательно надо задать уникальное имя через `--name`.
+
+```
+nfqws2 <глобальные_параметры>
+--template=tpl1 <базовые параметры 1> --new
+--template=tpl2 <базовые параметры 2> --new
+--template --import tpl1 --name tpl3 <базовые параметры 3> --new
+--import tpl1 --name prof1 <дополнительные параметры 1> --new
+--import tpl3 --name prof2 <дополнительные параметры 2> --new
+--name prof3 <параметры 3>
+```
+
+В примере имеется 3 рабочих профиля и 3 шаблона, 1 из которых импортирует настройки другого.
+
+* Профиль prof1 получает обьединение `<базовые параметры 1>` и `<дополнительные параметры 1>`.
+* Профиль prof2 получает обьединение `<базовые параметры 2>`, `<базовые параметры 3>` и `<дополнительные параметры 2>`
+* Профиль prof3 получает `<параметры 3>`. Он не импортирует шаблоны.
+
+В шаблонах допустимы любые параметры, относящиеся к профилям, включая и фильтры.
+
+### Фильтрация по листам
+
+Если имеются фильтры по хостлистам, и есть хотя бы один домен в любом хостлисте или указан автохостлист,
+то профиль никогда не будет выбран при отсутствующем имени хоста.
+Случай, когда нет автохостлиста, а все файлы листов пустые, приравнивается к отсутствию фильтра по хостлисту.
+
+Если нет автохостлиста, но есть записи в обычных хостлистах, то профиль выбирается только если текущий
+хост проходит по любому из включающих хостлистов, но не проходит ни по одному из исключающих.
+
+Если есть автохостлист, то при наличии имени хоста профиль выбирается всегда вне зависимости от его вхождения
+в какие-либо листы этого профиля. Действия зависят от вхождения в листы.
+
+* Если хост входит в исключающие листы, не происходит никаких действий и не происходит попытки выяснить работает ли ресурс.
+* Если хост не входит в исключающие листы, но входит во включающие - происходит применение стратегии без
+попыток выяснить работает ли ресурс с ней.
+* Если хост не входит ни в исключающие листы, ни во включающие - стратегия не применяется, происходит обнаружение
+неудачи доступа к ресурсу. Если случилась неудача, увеличивается счетчик неудач. Если случается удача или превышается
+интервал времени между неудачами `--hostlist-auto-fail-time` - счетчик сбрасывается.
+Когда счетчик достигает `--hostlist-auto-fail-threshold`, происходит занесение хоста в автолист.
+При следующем запросе будет считаться, что хост входит во включающий лист.
+
+Файлы хостлистов и ipset-ов перечитываются автоматически при изменении - перезапуск nfqws2 не нужен.
+
+Хостлисты и ipset-ы поддерживают комментарии. Пустые строки и строки, начинающиеся с `#`, игнорируются.
+
+ipset-ы могут включать адреса и подсети как ipv4, так и ipv6.
+
+### Детектор неудач автохостлистов
+
+Детектор срабатывает только при наличии имени хоста. Неудачей считается :
+
+* tcp : происходит не менее `--hostlist-auto-retrans-threshold` ретрансмиссий в пределах исходящего relative sequence `--hostlist-auto-retrans-maxseq`
+* tcp : приходит RST в пределах входящего relative sequence от 1 до `--hostlist-auto-incoming-maxseq`
+* tcp : принят пейлоад `http_reply` и http ответ является переадресацией 302 или 307 на абсолютный URL с доменом 2 уровня, не совпадающим с доменом 2 уровня хоста.
+* udp : ушло не менее `--hostlist-auto-udp-out` пакетов, пришло не более `--hostlist-auto-udp-in` пакетов. Эта ситуация означает, что клиент шлет запросы, а сервер на них не отвечает или отвечает меньше, чем должен по протоколу.
+
+Удачей считается :
+
+* tcp : превышение исходящего relative sequence `--hostlist-auto-retrans-maxseq` . Клиент смог отослать достаточно много, что вряд ли бы случилось в случае реакции DPI.
+* tcp : превышение входящего relative sequence `--hostlist-auto-incoming-maxseq` . Сервер прислал достаточно много, чтобы это не было похоже на ответ DPI.
+* udp : превышение количества пришедших пакетов `--hostlist-auto-udp-in` . Сервер ответил достаточно много.
+
+При неудаче, если с прошлой неудачи прошло не более `--hostlist-auto-fail-time` секунд, счетчик неудач увеличивается.
+Если прошло больше времени - счетчик сбрасывается, счет идет заново.
+
+При удаче счетчик сбрасывается. Считается, что ресурс работает, а сбой был временным и не связанным с блокировкой/
+
+При достижении счетчиком `--hostlist-auto-fail-threshold` происходит занесение хоста в лист.
+
+Большинство критериев удачи или неудачи требует анализа входящего и исходящего трафика, поэтому необходим их перехват в достаточном обьеме
+для возможности срабатывания критериев.