From 901ffdfe5a547df918715739301a87c9a252d12f Mon Sep 17 00:00:00 2001 From: bol-van Date: Mon, 15 Dec 2025 15:52:43 +0300 Subject: [PATCH] update docs --- docs/manual.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 154 insertions(+), 1 deletion(-) diff --git a/docs/manual.md b/docs/manual.md index bb7fed2..63bb9d3 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -723,6 +723,24 @@ ipcache представляет собой структуру в памяти * **SIGUSR1** выводит содержимое пула conntrack * **SIGUSR2** выводит счетчики autohostlist и содержимое пула ipcache +## Отладка + +Параметр `--debug` включает вывод отладочных сообщений. + +* `--debug=0` выключает вывод +* `--debug`, `--debug=1` вывод на консоль +* `--debug=@` вывод в файл. размер файла ничем не ограничивается, но файл может быть удален в любой момент, и запись продолжится с чистого листа +* `--debug=syslog` вывод в syslog. чтение зависит от syslog daemon. rsyslog пишет файлы в /var/log. busybox logd читается через logread. +* `--debug=android` вывод в android log. чтение через logcat. доступно только в версиях, собранных в Android NDK + +Умение обращаться с `--debug` логом совершенно необходимо для отладки настроек и тем более для написания собственного LUA кода. + +Все сообщения об ошибках (DLOG_ERR) и особо важные сообщения (DLOG_CONDUP) дублируются на консоли вне зависимости от log target. +Сообщения об ошибках выводятся в stderr. + +Параметр `--dry-run` позволяет протестировать корректность опций командной строки и доступность используемых файлов под сброшенными привилегиями. +`--dry-run` не инициализирует движок LUA, и поэтому не может обнаружить синтаксические ошибки LUA. + ## Песочница В целях безопасности nfqws2 после инициализации сбрасывает свои привилегии. @@ -734,7 +752,7 @@ BSD : Linux : * Меняется UID/GID на указанные в параметрах `--user`, `--uid`. По умолчанию на 0x7FFFFFFF. * Сбрасываются capabilities до cap_net_raw, cap_net_admin (требуется для NFQUEUE). Сбрасывается bounding set до нуля. -* Выставляется признак NO_NEW_PRIVS, чтобы не работали suid биты и caps на файлах. Если ядро старее 3.5, NO_NEW_PRIVS не поддерживается. В этом случае выводится предупреждение, но выполнение не прекращается. +* Выставляется признак NO_NEW_PRIVS, чтобы не работали suid биты и caps на файлах. Если ядро старее 3.5, NO_NEW_PRIVS не поддерживается. В этом случае выводится предупреждение, выполнение не прекращается. * Включается seccomp фильтр, запрещающий exec и ряд файловых операций - чтение содержимого каталогов, создание/удаление каталогов, создание специальных файлов (линки, девайсы), chmod, chown, посылание сигналов (kill), ptrace. В случае нарушения процесс аварийно завершается. Если ядро не поддерживает seccomp, выводится предупреждение, но выполнение не прекращается. @@ -1304,3 +1322,138 @@ mss дублируется в поле `desync.tcp_mss` независимо о | IPTOS_DSCP_MASK | number | битовая маска поля ip_tos, соответствующая DSCP | 0xFC | | IP6F_MORE_FRAG | number | бит "More fragment" поля ip6f_offlg из ipv6 fragment header | 0x0001 | | IPPROTO_IP
IPPROTO_IPV6
IPPROTO_ICMP
IPPROTO_TCP
IPPROTO_UDP
IPPROTO_ICMPV6
IPPROTO_HOPOPTS
IPPROTO_ROUTING
IPPROTO_FRAGMENT
IPPROTO_AH
IPPROTO_ESP
IPPROTO_DSTOPTS
IPPROTO_MH
IPPROTO_HIP
IPPROTO_SHIM6
IPPROTO_NONE | number | [номера IP протоколов](https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml) | используются в ipv4 и ipv6 | + +## C функции + +### Логгинг + +``` +function DLOG(string) +function DLOG_ERR(string) +function DLOG_CONDUP(string) +``` + +Функции выводят строку с добавлением EOL в --debug лог. +* DLOG - обычный вывод +* DLOG_CONDUP - обычный вывод + вывод на консоль, если включено логирование в файл или syslog +* DLOG_ERR - вывод в stderr + на консоль + +### Конвертация IP + +``` +function ntop(raw_ip) +function pton(string_ip) +``` + +* ntop конвертирует строку с байтами ipv4 или ipv6 адреса в строковое представление. версия IP определяется по размеру raw_ip - 4 или 16 байт. При несоответствии размера возвращается nil. +* pton конвертирует строковое представление ipv4 или ipv6 адреса в raw_ip. Если строковое представление не является корректным ipv4 или ipv6 адресом, возвращается nil. + +### Битовые операции + +LUA 5.1, на котором основан luajit, не имеет встроенных битовых операций. Luajit имеет встроенный модуль bitop. +LUA 5.3 имеет встроенные битовые операции, но не имеет встроенного модуля bitop. Он может быть подгружен, +но только если не использована статическая компиляция и если модуль установлен. nfqws2 на github собирается статически. + +При работе с полями сетевых пакетов без битовых операций никуда. +Битовые операции и сдвиги обычно реализуются одной машинной командой. Для процессора это родные операции. +Заменять их конструкциями, основанных на математике с плавающей точкой неразумно (возведение в степень, деление, округление и тд), +особенно в условиях частого отсутствия FPU на роутерах и других embedded устройствах. + +Чтобы не зависеть от всей этой неразберихи, в nfqws2 выставляется свой собственный набор битовых функций и функций сдвига, +который не зависит от типа движка LUA и его версии. Все типы битовых операций работают с беззнаковыми числами от 8 до 32 бит. +При передаче отрицательных чисел они интерпретируются в дополнительном коде. Например, в 32 битах -2 становится 0xFFFFFFFE, в 8 битах - 0xFE. +Большая разрядность не поддерживается, поскольку возникают несовместимости между LUA 5.3+ и более старыми версиями. +Только в LUA 5.3 реализова тип integer 64 bit. В более старых исползьзуется формат плавающей точки - double с мантиссой 53 бит. + +Стандартные операции сдвига и побитовые логические операции : +``` +function bitlshift(u32, bits) +function bitrshift(u32, bits) +function bitand(u32_1, u32_2, ...., u32_N) +function bitor(u32_1, u32_2, ...., u32_N) +function bitxor(u32_1, u32_2, ...., u32_N) +function bitnot(u32) +``` + +bitand, bitor и bitxor работает с произвольным количеством чисел. + +Операции получения и установки отдельных битов : +``` +function bitget(u32, bit_from, bit_to) +function bitset(u32, bit_from, bit_to, set) +``` + +* bitget получает число из диапазона битов u32 с номерами от bit_from до bit_to. нумерация битов с 0. +* bitset записывает число set в диапазон битов u32 с номерами от bit_from до bit_to. нумерация битов с 0. старшие биты set, выходящие за пределы (bit_to-bit_from), игнорируются. + +### Операции с беззнаковыми числами + +При операциях с числями без знака всегда важна разрядность. От нее зависит результат. +Поэтому все функции имеют в своем названии разрядность. При передаче аргументов, выходящих за пределы разрядности, вызывается error. + +``` +function u8(raw_string, offset) +function u16(raw_string, offset) +function u24(raw_string, offset) +function u32(raw_string, offset) +``` + +Эти функции используются для извлечения числовых полей в формате big endian из raw строки. +offset - номер байта от начала raw строки, начиная с 1. +Аналогичные встроенные средства (string.unpack) есть только в LUA 5.3. + +``` +function bu8(u8) +function bu16(u16) +function bu24(u24) +function bu32(u32) +``` + +Преобразуют число в raw строку в формате big endian. +Чтобы собрать структуру из числовых полей, можно использовать обычную операцию конкатенации строк `..`. + +``` +function swap16(u16) +function swap32(u32) +``` + +Инвертируют порядок следования байт в u16 или u32. Если в вашей структуре порядок байт little endian, +можно использовать uX/buX + swap. + +``` +function u8add(u8_1, u8_2, ...., u8_N) +function u16add(u16_1, u16_2, ...., u16_N) +function u24add(u24_1, u24_2, ...., u24_N) +function u32add(u32_1, u32_2, ...., u32_N) +``` + +Функции для сложения произвольного количества беззнаковых чисел указанной разрядности. +Операнды должны вписываться в указанную разрядность, иначе вызывается error. +Перенос старшего разряда игнорируется. + +### Целочисленное деление + +Встроенное целочисленное деление есть только в LUA 5.3+, где есть тип данных integer. +Чтобы не возиться с округлением, целочисленное деление реализовано C функцией : + +``` +function divint(dividend, divisor) +``` + +В этой функции нет ограничения на разрядность. Внутри используется тип int64_t. +В LUA 5.3+ потерь разрядности нет, в более старых - разрядность будет обрезана до размера мантиссы типа double. + +### Генерация случайных данных + +Функции генерируют raw строку указанного размера , состоящую из случайных байт. +``` +function brandom(size) +function brandom_az(size) +function brandom_az09(size) +``` + +* brandom возвращает байты с 0 до 255 +* brandom_az - символы от 'a' до 'z' +* brandom_az09 - символы от 'a' до 'z' и числа от '0' до '9' + +