From 3e724c381065ba6eee72cdb6a5465f3509680d66 Mon Sep 17 00:00:00 2001
From: bol-van <none@none.none>
Date: Mon, 12 Jan 2026 10:03:35 +0300
Subject: [PATCH] update docs

---
 docs/manual.en.md | 39 ++++++++++++++++++++++++++++++++-------
 docs/manual.md    | 40 +++++++++++++++++++++++++++++++++-------
 2 files changed, 65 insertions(+), 14 deletions(-)

diff --git a/docs/manual.en.md b/docs/manual.en.md
index 89fffe9..6a4c1db 100644
--- a/docs/manual.en.md
+++ b/docs/manual.en.md
@@ -15,6 +15,7 @@
 - [nfqws2](#nfqws2)
   - [General principles for setting parameters](#general-principles-for-setting-parameters)
   - [Full list of options](#full-list-of-options)
+  - [Protocol detection](#protocol-detection)
   - [Using multiple profiles](#using-multiple-profiles)
     - [Profile templates](#profile-templates)
     - [Filtering by lists](#filtering-by-lists)
@@ -634,7 +635,7 @@ MULTI-STRATEGY:
  --filter-l3=ipv4|ipv6                                  ; profile filter: IP protocol version
  --filter-tcp=[~]port1[-port2]|*                        ; profile filter: TCP ports or port ranges (comma-separated)
  --filter-udp=[~]port1[-port2]|*                        ; profile filter: UDP ports or port ranges (comma-separated)
- --filter-l7=proto[,proto]                              ; profile filter: list of application-layer protocols. A full list is available in the program's help text.
+ --filter-l7=proto[,proto]                              ; profile filter: list of application-layer protocols
  --ipset=<filename>                                     ; profile filter: inclusion list of IP addresses or subnets from a file (supports mixed IPv4/IPv6)
  --ipset-ip=<ip_list>                                   ; profile filter: fixed inclusion list of IP addresses or subnets (comma-separated)
  --ipset-exclude=<filename>                             ; profile filter: exclusion list of IP addresses or subnets from a file (supports mixed IPv4/IPv6)
@@ -655,7 +656,7 @@ MULTI-STRATEGY:
  --hostlist-auto-debug=<logfile>                        ; auto-list debug log
 
 LUA PACKET PASS MODE:
- --payload=type[,type]                                  ; in-profile filter: payload filter for subsequent instances within the profile. A list of payloads is available in the program's help text.
+ --payload=type[,type]                                  ; in-profile filter: payload filter for subsequent instances within the profile
  --out-range=[(n|a|d|s|p)<int>](-|<)[(n|a|d|s|p)<int>]  ; in-profile filter: conntrack counter range for subsequent instances within the profile - outgoing direction
  --in-range=[(n|a|d|s|p)<int>](-|<)[(n|a|d|s|p)<int>]   ; in-profile filter: conntrack counter range for subsequent instances within the profile - incoming direction
 
@@ -703,6 +704,30 @@ LOGICAL NETWORK FILTER:
  --nlm-list[=all]                       ; display a list of connected NLM networks. "all" shows all NLM networks.
 ```
 
+## Protocol detection
+
+nfqws2 signatures the payload types of individual packets or groups of packets.
+All packets without data have payload empty, undetected - unknown.
+The flow protocol is assigned after receiving the first known payload and remains with the flow for the rest of its existence.
+In this case, subsequent payloads can have both a known type and an unknown one.
+In payload and flow protocol filters special values are available - "all" and "known". "all" means any, "known" - not "empty" and not "unknown".
+
+Table of recognizable payload types and flow protocols
+
+| flow protocol   | L4  | payloads |
+| :-------------- | :-- | :------- |
+| http            | tcp | http_req<br>http_reply |
+| tls             | tcp | tls_client_hello<br>tls_server_hello |
+| xmpp            | tcp | xmpp_stream<br>xmpp_starttls<br>xmpp_proceed<br>xmpp_features |
+| quic            | udp | quic_initial |
+| wireguarв       | udp | wireguard_initiation<br>wireguard_response<br>wireguard_cookie<br>wireguard_keepalive |
+| dht             | udp | dht |
+| discord         | udp | discord_ip_discovery |
+| stun            | udp | stun |
+| dns             | udp | dns_query dns_response |
+| mtproto         | udp | mtproto_initial |
+| dtls            | udp | dtls_client_hello<br>dtls_server_hello |
+
 ## Using multiple profiles
 
 Profiles exist to select a specific traffic manipulation strategy based on the specified filter conditions.
@@ -958,7 +983,7 @@ Direct file operations from Lua code are not recommended unless absolutely neces
 
 These come in three types: `--payload`, `--in-range`, and `--out-range`. Filter values remain active from the moment they are specified until the next override.
 
-- `--payload=type1[,type2][,type2]...` accepts a comma-separated list of known payloads, "all", or "known". The list of known payloads is available in the `nfqws2` help text. The default is `--payload=all`.
+- `--payload=type1[,type2][,type2]...` accepts a comma-separated list of known [payloads](#protocol-detection), "all", or "known". The default is `--payload=all`.
 - `--(in-range|out-range)=[(n|a|d|s|p)<int>](-|<)[(n|a|d|s|p)<int>]` sets conntrack counter ranges for inbound and outbound directions. The default is `--in-range=x`, `--out-range=a`.
 
 Ranges are specified in the following formats: `mX-mY`, `mX<mY`, `-mY`, `<mY`, `mX-`, where `m` is the counter mode, `X` is the lower bound, and `Y` is the upper bound. Modes `x` and `a` are specified as a single letter without a range or counter value. The `-` sign indicates an inclusive upper bound, while `<` indicates an exclusive one.
@@ -1416,12 +1441,12 @@ The same applies to optional `track` fields. Test your code with `--ctrack-disab
 | Field          | Type   | Description                                                     | Note                                             |
 | :------------- | :----- | :-------------------------------------------------------------- | :----------------------------------------------- |
 | incoming_ttl   | number | TTL/HL of the first incoming packet in the stream               | May be absent if not determined                  |
-| l7proto        | string | Stream protocol. A list of possible values is available in the nfqws2 help text | Always present; defaults to "unknown"            |
+| l7proto        | string | [flow protocol](#protocol-detection)                            | Always present; defaults to "unknown"            |
 | hostname       | string | Hostname, determined through L6/L7 protocol analysis            | Appears only after identification               |
 | hostname_is_ip | bool   | Whether the hostname is an IP address                           | Only present if a hostname exists                |
 | lua_state      | table  | A table for storing state associated with the stream            | Always present; passed with every packet         |
 | lua_in_cutoff  | bool   | Lua cutoff for the incoming direction                           | Read-only                                        |
-| lua_out_cutoff | bool   | Lua cutoff for the outgoing direction                          | Read-only                                        |
+| lua_out_cutoff | bool   | Lua cutoff for the outgoing direction                           | Read-only                                        |
 | t_start        | number | Unix time of the first packet in the stream                     | Includes a high-precision fractional part        |
 | pos            | table  | Counters for various directions                                 | Contains the tables: client, server, direct, and reverse |
 
@@ -3153,7 +3178,7 @@ function payload_match_filter(l7payload, l7payload_filter, def)
 function payload_check(desync, def)
 ```
 
-These functions operate on a string representing a comma-separated list of payloads. A list of known payload types can be found in the `nfqws2` help text. All empty packets have the payload `empty`, and unknown ones are `unknown`. Special values include `all` and `known`. `all` means any payload; `known` means anything that is not `unknown` or `empty`. A `~` prefix at the beginning denotes logical inversion (non-match).
+These functions operate on a string representing a comma-separated list of [payloads](#protocol-detection). All empty packets have the payload `empty`, and unknown ones are `unknown`. Special values include `all` and `known`. `all` means any payload; `known` means anything that is not `unknown` or `empty`. A `~` prefix at the beginning denotes logical inversion (non-match).
 
 - `payload_match_filter` checks if `l7payload` matches the `l7payload_filter` list, or `def` if `l7payload_filter` is `nil`. If both are `nil`, the list defaults to "known".
 - `payload_check` calls `payload_match_filter(desync.l7payload, desync.arg.payload, def)`.
@@ -3297,7 +3322,7 @@ Direction filter. In most functions using a direction filter, the default value
 
 ### standard payload
 
-The payload filter accepts a list of payload types. A list of known payload types can be retrieved from the `nfqws2` help text. All empty packets are assigned the `empty` payload type, while unrecognized ones are labeled `unknown`. Special values include `all` and `known`: `all` matches any payload, while `known` matches anything that is neither `unknown` nor `empty`.
+The payload filter accepts a list of [payload types](#protocol-detection). All empty packets are assigned the `empty` payload type, while unrecognized ones are labeled `unknown`. Special values include `all` and `known`: `all` matches any payload, while `known` matches anything that is neither `unknown` nor `empty`.
 
 **standard payload**
 
diff --git a/docs/manual.md b/docs/manual.md
index 4d82ea2..95f716a 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -14,6 +14,7 @@
 - [nfqws2](#nfqws2)
   - [Общие принципы задания параметров](#общие-принципы-задания-параметров)
   - [Полный список опций](#полный-список-опций)
+  - [Распознавание протоколов](#распознавание-протоколов)
   - [Использование множественных профилей](#использование-множественных-профилей)
     - [Шаблоны профилей](#шаблоны-профилей)
     - [Фильтрация по листам](#фильтрация-по-листам)
@@ -690,7 +691,7 @@ MULTI-STRATEGY:
  --filter-l3=ipv4|ipv6                                  ; фильтр профиля : версия ip протокола
  --filter-tcp=[~]port1[-port2]|*                        ; фильтр профиля : порты tcp или диапазоны портов через запятую
  --filter-udp=[~]port1[-port2]|*                        ; фильтр профиля : порты udp или диапазоны портов через запятую
- --filter-l7=proto[,proto]                              ; фильтр профиля : список протоколов потока. полный список доступен в help тексте программы.
+ --filter-l7=proto[,proto]                              ; фильтр профиля : список протоколов потока
  --ipset=<filename>                                     ; фильтр профиля : включающий список ip адресов или подсетей из файла. может быть смешанным ipv4+ipv6.
  --ipset-ip=<ip_list>                                   ; фильтр профиля : включающий фиксированный список ip адресов или подсетей через запятую
  --ipset-exclude=<filename>                             ; фильтр профиля : исключающий список ip адресов или подсетей из файла. может быть смешанным ipv4+ipv6.
@@ -711,7 +712,7 @@ MULTI-STRATEGY:
  --hostlist-auto-debug=<logfile>                        ; дебаг лог автолиста
 
 LUA PACKET PASS MODE:
- --payload=type[,type]                                  ; внутрипрофильный фильтр : фильтр пейлоада для последующих инстансов внутри профиля. список пейлоадов доступен в help тексте программы.
+ --payload=type[,type]                                  ; внутрипрофильный фильтр : фильтр пейлоада для последующих инстансов внутри профиля
  --out-range=[(n|a|d|s|p)<int>](-|<)[(n|a|d|s|p)<int>]  ; внутрипрофильный фильтр : диапазон счетчиков conntrack для последующих инстансов внутри профиля - исходящее направление
  --in-range=[(n|a|d|s|p)<int>](-|<)[(n|a|d|s|p)<int>]   ; внутрипрофильный фильтр : диапазон счетчиков conntrack для последующих инстансов внутри профиля - входящее направление
 
@@ -759,6 +760,30 @@ LOGICAL NETWORK FILTER:
  --nlm-list[=all]                       ; вывести список подключенных NLM сетей. all - список всех NLM сетей
 ```
 
+## Распознавание протоколов
+
+nfqws2 сигнатурно распознает типы пейлоадов отдельно взятых пакетов или групп пакетов.
+Все пустые пакеты имеют пейлоад empty, неизвестные - unknown.
+Протокол потока присваивается после получение первого известного пейлоада и остается с потоком до конца его существования.
+При этом последующие пейлоады могут иметь как известный тип, так и неизвестный.
+В фильтрах по пейлоаду и протоколу потока доступны специальные значения - all и known. All означает любой, known - не empty и не unknown.
+
+Таблица распознаваемых типов пейлоада и протоколов потока
+
+| Протокол потока | L4  | Пейлоады |
+| :-------------- | :-- | :------- |
+| http            | tcp | http_req<br>http_reply |
+| tls             | tcp | tls_client_hello<br>tls_server_hello |
+| xmpp            | tcp | xmpp_stream<br>xmpp_starttls<br>xmpp_proceed<br>xmpp_features |
+| quic            | udp | quic_initial |
+| wireguarв       | udp | wireguard_initiation<br>wireguard_response<br>wireguard_cookie<br>wireguard_keepalive |
+| dht             | udp | dht |
+| discord         | udp | discord_ip_discovery |
+| stun            | udp | stun |
+| dns             | udp | dns_query dns_response |
+| mtproto         | udp | mtproto_initial |
+| dtls            | udp | dtls_client_hello<br>dtls_server_hello |
+
 ## Использование множественных профилей
 
 Профили существуют, чтобы в зависимости от указанных условий фильтра выбрать ту или иную стратегию воздействия на трафик.
@@ -1086,7 +1111,7 @@ Lua код выполняется с ограниченными правами,
 Они бывают трех видов - `--payload`, `--in-range`, `--out-range`.
 Значения фильтров действуют с момента их указания до следующего переопределения.
 
-- `--payload=type1[,type2][,type2]...` принимает список известных пейлоадов через зяпятую, "all" или "known". Список известных пейлоадов доступен в help тексте nfqws2. По умолчанию `--payload=all`.
+- `--payload=type1[,type2][,type2]...` принимает список известных пейлоадов через зяпятую, "all" или "known". [Список известных пейлоадов](#распознавание-протоколов). По умолчанию `--payload=all`.
 - `--(in-range|out-range)=[(n|a|d|s|p)<int>](-|<)[(n|a|d|s|p)<int>]` задает диапазоны счетчиков conntrack по входящему и исходящему направлениям. По умолчанию `--in-range=x`, `--out-range=a`.
 
 Диапазоны задаются в формах : `mX-mY`, `mX<mY`, `-mY`, `<mY`, `mX-`, где m - режим счетчика, X - нижнее значение, Y - верхнее значение.
@@ -1418,7 +1443,7 @@ desync
 | replay_piece       | number | номер проигрываемой части                                                                    | нумерация с 1                                               |
 | replay_piece_count | number | количество проигрываемых частей                                                              |                                                             |
 | replay_piece_last  | bool   | последняя проигрываемая часть                                                                |                                                             |
-| l7payload          | string | тип пейлоада текущего пакета или группы пакетов. список возможных в help тексте nfqws2       | если неизвестно - unknown                                   |
+| l7payload          | string | [тип пейлоада](#распознавание-протоколов) текущего пакета или группы пакетов                 | если неизвестно - unknown                                   |
 | l7proto            | string | тип протокола потока                                                                         | если неизвестно - unknown                                   |
 | reasm_data         | string | результат сборки многопакетного сообщения, либо сам пейлоад, если сборки не было             | пока применяется только для tcp                             |
 | reasm_offset       | string | смещение текущего переигрываемого пакета в сборке                                            | пока применяется только для tcp                             |
@@ -1555,7 +1580,7 @@ ipv6 extension headers и tcp options представляются в форме
 | Поле           | Тип    | Описание                                                        | Примечание                                       |
 | :------------- | :----- | :-------------------------------------------------------------- | :----------------------------------------------- |
 | incoming_ttl   | number | ttl/hl первого входящего пакета по потоку                       | может не быть, если не определено                |
-| l7proto        | string | протокол потока. список возможных доступен в help тексте nfqws2 | есть всегда. если неизвестно - unknown           |
+| l7proto        | string | [протокол потока](#распознавание-протоколов)                    | есть всегда. если неизвестно - unknown           |
 | hostname       | string | имя хоста. определяется на основе анализа L6/L7 протоколов      | появляется только после определения              |
 | hostname_is_ip | bool   | является ли hostname ip адресом                                 | только если есть hostname                        |
 | lua_state      | table  | таблица для хранения состояния, привязанного к потоку           | есть всегда, передается с каждым пакетом потока  |
@@ -3331,7 +3356,8 @@ function payload_match_filter(l7payload, l7payload_filter, def)
 function payload_check(desync, def)
 ```
 
-Функции работают со строкой - списком пейлоадов через запятую. Список известных типов пейлоада можно получить из help текста nfqws2. Все пустые пакеты имеют пейлоад empty, неизвестные - unknown. Особые значения - all и known. all означает любой пейлоад, known - не unknown и не empty. Префикс `~` в начале означает логическую инверсию - несоответствие списку.
+Функции работают со строкой - списком пейлоадов через запятую. Особые значения - all и known. all означает любой пейлоад, known - не unknown и не empty. Префикс `~` в начале означает логическую инверсию - несоответствие списку.
+См. [распознавание протоколов](#распознавание-протоколов).
 
 - payload_match_filter проверяет соответствие l7payload списку l7payload_filter или def, если l7payload_filter=nil. Если оба nil - список берется как "known".
 - payload_check вызывает `payload_match_filter(desync.l7payload, desync.arg.payload, def)`
@@ -3480,7 +3506,7 @@ nfqws2 ничего не знает о том, что нужно `--lua-desync`
 
 ### standard payload
 
-Фильтр по пейлоаду берет список типов пейлоада. Список известных типов пейлоада можно получить из help текста nfqws2. Все пустые пакеты имеют пейлоад empty, неизвестные - unknown. Особые значения - all и known. all означает любой пейлоад, known - не unknown и не empty.
+Фильтр по пейлоаду берет список [типов пейлоада](#распознавание-протоколов).
 
 **standard payload**