jeka/utun2
1
0 Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update monitor usage and asynchronous TCP architecture docs

Browse Source
This commit is contained in:
evgeny committed 2026-10-27 14:00:49 +01:00
1 parent 89c27b8fca
commit cb50e268a4
2 files changed
+59 -275
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

tools/etcpmon/IMPLEMENTATION.md
+22 -166
View File
@@ -1,171 +1,27 @@
# ETCP Monitor - Implementation Summary
# Устройство etcpmon
## Overview
ETCP Monitor is a Windows GUI utility for real-time monitoring of ETCP connections in uTun.
Действующие контракты и использование описаны в [etcpmon_doc.md](etcpmon_doc.md),
API — в `etcpmon_client.h`, `etcpmon_gui.h`, `etcpmon_graph.h` и `etcpmon_protocol.h`.
Серверная реализация: `src/control_server.c/h` и
[control_server_doc.md](../../src/control_server_doc.md).
## Architecture
`WinMain` создаёт `etcpmon_app`, инициализирует Winsock/классы окон, создаёт окно и запускает
message loop. Таймер GUI вызывает неблокирующий `etcpmon_client_process()`; фонового сетевого
потока нет. Client завершает connect, разбирает TCP-кадры, обновляет кеши и вызывает GUI callbacks.
Сэмпл истории добавляет только парсер ответа метрик; GUI отображает уже сохранённую историю.
### Protocol (Binary)
- **Format**: `[2 bytes: size] [1 byte: type] [payload...]`
- **Period**: 100ms updates
- **Transport**: TCP socket
Все команды клиента проходят через один TX FIFO с лимитом 64 КиБ/256 кадров и смещением досылки.
Pending с ненулевым seq регистрируется вместе с кадром, но срок ответа начинается после полной отправки.
Тип и payload ответа проверяются до снятия pending и вызова callback.
### Message Types
**Client → Server:**
- `0x01` - Request connection list
- `0x02` - Select connection by peer_node_id
- `0x03` - Request metrics
- `0x04` - Disconnect
Сервер использует `ll_queue` с одним кадром до 32 КиБ и отдельным смещением частичной отправки.
Чтение/разбор команд ждут пустой очереди через отменяемый deferred waiter. Начальная подписка
хранит ID узлов и сериализует актуальную запись при освобождении TX; live-изменения объединяются
в ограниченном наборе из 256 ID. Переполнение отключает подписчика с диагностикой.
Перед освобождением клиента отменяются таймер и waiter, затем освобождаются снимок и очередь.
Метрики выдаются по запросу, а сообщения об узлах UTUN — только после явной подписки другого клиента;
сам GUI etcpmon подписку не использует.
**Server → Client:**
- `0x81` - Connection list response
- `0x82` - Metrics response (ETCP + TUN + Links)
- `0xFF` - Error response
## Files Created
### Protocol (Shared)
- `tools/etcpmon/etcpmon_protocol.h` - Protocol definitions and structures
### Server (uTun)
- `src/control_server.h` - Control server interface
- `src/control_server.c` - TCP server implementation
- Modified `src/utun_instance.c` - Integration with uTun lifecycle
- Modified `src/Makefile.am` - Added control_server.c to build
- Modified `lib/debug_config.h` - Added DEBUG_CATEGORY_CONTROL
### Client (Windows GUI)
- `tools/etcpmon/etcpmon_client.h/c` - Network layer (Winsock)
- `tools/etcpmon/etcpmon_gui.h/c` - WinAPI GUI implementation
- `tools/etcpmon/etcpmon_main.c` - Entry point
- `tools/etcpmon/Makefile.mingw` - MinGW build
- `tools/etcpmon/build.bat` - Windows build script
- `tools/etcpmon/build.sh` - Unix build script
- `tools/etcpmon/clean.bat` - Clean script
- `tools/etcpmon/README.md` - Documentation
### Test
- `tests/test_control_server.c` - Integration test for control server protocol
### Library Fix
- `lib/u_async.c` - Modified to use select() on Windows instead of WSAPoll
## Build Instructions
### Windows (Recommended)
```cmd
cd tools\etcpmon
build.bat
```
### Unix/MinGW
```bash
cd tools/etcpmon
bash build.sh
```
## Usage
### 1. Configure uTun
Add to `utun.conf`:
```ini
control_ip=127.0.0.1
control_port=9090
```
### 2. Start uTun
```bash
./utun
```
### 3. Start ETCP Monitor
```cmd
etcpmon.exe
```
### 4. Connect
- Enter server IP:port (default: 127.0.0.1:9090)
- Click "Connect"
- Select connection from list
- View real-time metrics
## Metrics Displayed
### ETCP Connection
- RTT (last, avg 10, avg 100)
- Jitter
- Bytes sent total
- Retransmission count
- ACK count
- Unacked bytes
- Links count
### TUN Interface
- Bytes read/written
- Packets read/written
- Read/write errors
### Links (per link)
- Status (UP/DOWN)
- Encrypt/decrypt errors
- Send/receive errors
- Total encrypted/decrypted bytes
- Bandwidth (Kbps)
- NAT changes count
## Technical Details
### Windows select() Implementation
On Windows, the uasync library now uses `select()` instead of `WSAPoll()` for socket monitoring. This resolves issues with accepted TCP sockets that caused WSAPoll to fail with error 10022 (WSAEINVAL).
**Changes in `lib/u_async.c`:**
- Added Windows-specific code path using `select()`
- Maintains compatibility with Linux (uses `poll()`)
- Properly handles both regular FDs and socket_t types
### Binary Protocol
The protocol uses fixed-size binary structures for efficient communication:
- Header: 3 bytes (2 size + 1 type)
- Connection list item: 40 bytes (8 peer_id + 32 name)
- ETCP metrics: 40 bytes
- Link metrics: 32 bytes per link
- TUN metrics: 24 bytes
## Testing
### Unit Test
```bash
cd tests
./test_control_server
```
Expected output:
```
================================
Control Server Protocol Test
================================
[TEST] Setting up mock data...
[TEST] Mock data ready (1 conn, 2 links)
[TEST] Starting control server on port 19090...
[TEST] Control server started ✓
[TEST] Starting client thread...
[TEST] Running event loop...
[CLIENT] Connecting to 127.0.0.1:19090...
[CLIENT] Connected
[CLIENT] Sending CMD_LIST_CONN...
[CLIENT] Waiting for response...
[CLIENT] Received connection list: 1 connection(s)
[CLIENT] Connection verified: peer_id=0x1234567890ABCDEF ✓
[CLIENT] All tests passed ✓
[TEST] Cleaning up...
================================
[PASS] All tests passed!
================================
```
## License
See main project LICENSE file.
Проверки клиента: `make -C tools/etcpmon CC=x86_64-w64-mingw32-gcc TEST_RUNNER=wine check`.
Проверки серверных очередей/cleanup/метрик: цель `test_control_server` из `tests/Makefile.am`.
Они проверяют разные стороны протокола и не заменяют интеграционный запуск клиента с сервером.
tools/etcpmon/README.md
+37 -109
View File
@@ -1,137 +1,65 @@
# ETCP Monitor
Windows GUI утилита для мониторинга ETCP подключений uTun в реальном времени.
WinAPI-монитор соединений uTun. Работает под Windows и Wine, подключается по IPv4 TCP
к `control_server`. Метрики выбранного соединения запрашиваются раз в 100 мс,
списки соединений и сокетов — раз в секунду. Сеть обрабатывается в GUI-потоке.
## Описание
Полное описание протокола, интерфейса, владения ресурсами и текущих ограничений:
[etcpmon_doc.md](etcpmon_doc.md). Серверная часть: [control_server_doc.md](../../src/control_server_doc.md).
ETCP Monitor - это Windows GUI приложение, которое подключается к работающему экземпляру uTun и отображает статистику ETCP подключений в реальном времени с периодом обновления 100мс.
## Сборка и запуск
## Архитектура
### Протокол управления (бинарный)
Формат сообщения: `[2 байта: размер] [1 байт: тип] [payload...]`
**Команды клиента:**
- `0x01` - запрос списка подключений
- `0x02` - выбор подключения по `peer_node_id`
- `0x03` - запрос метрик выбранного подключения
- `0x04` - отключение
**Ответы сервера:**
- `0x81` - список подключений
- `0x82` - метрики ETCP + линки + TUN
- `0xFF` - ошибка
### Файлы
**Общие (протокол):**
- `etcpmon_protocol.h` - определения структур и констант протокола
**Сервер (utun):**
- `src/control_server.h` - интерфейс control server
- `src/control_server.c` - реализация TCP сервера
**Клиент (Windows GUI):**
- `etcpmon_client.h/c` - сетевая часть (Winsock)
- `etcpmon_gui.h/c` - GUI (WinAPI)
- `etcpmon_main.c` - точка входа
## Сборка
### Клиент (Windows) - Рекомендуемый способ
**Используя MSYS2 UCRT64 (рекомендуется):**
Windows/MSYS2 UCRT64:
```cmd
cd tools\etcpmon
build.bat
etcpmon.exe
```
Это автоматически запустит MSYS2 UCRT64 shell и выполнит сборку.
`build.bat` использует `C:\msys64`, либо `MSYS2_ROOT`/`MSYS2`. Внутри MSYS2 можно выполнить `bash build.sh`.
Требования:
- Установленный MSYS2 (обычно в `C:\msys64`)
- Или переменная окружения `MSYS2_ROOT` с путем к MSYS2
**Альтернативные способы:**
Linux с установленными MinGW и Wine, из корня проекта:
```bash
# Через MSYS2 напрямую
cd tools/etcpmon
bash build.sh
# Через Makefile (если установлен make для Windows)
make -f Makefile.mingw
make -C tools/etcpmon CC=x86_64-w64-mingw32-gcc
wine tools/etcpmon/etcpmon.exe
make -C tools/etcpmon CC=x86_64-w64-mingw32-gcc TEST_RUNNER=wine check
```
**Очистка:**
```cmd
clean.bat
```
Для запуска GUI и WinAPI-тестов нужен дисплей; без рабочего стола можно использовать `xvfb-run -a`.
### Сервер (utun)
## Подключение
Control server интегрирован в utun. Сборка стандартная:
```bash
./configure
make
```
## Настройка
### Конфигурация uTun
Добавьте в `utun.conf`:
В конфиге uTun:
```ini
control_ip=127.0.0.1
control_port=9090
[control]
ip=127.0.0.1
port=9090
allow=127.0.0.1/32
```
### Использование
Без `allow` все подключения отклоняются. Транспорт управления не шифруется и не аутентифицирует
ключи ETCP: используйте loopback или доверенный защищённый канал.
1. Запустите uTun с настроенным control socket
2. Запустите etcpmon.exe
3. Введите IP и порт control сервера
4. Нажмите "Connect"
5. Выберите подключение из списка для просмотра метрик
При открытии окна etcpmon автоматически начинает connect к `192.168.40.1:9091`.
Нажмите Disconnect, задайте числовой IPv4/порт своего сервера и нажмите Connect.
Первое соединение выбирается автоматически. Enter в адресе/порту подключает, Escape отключает.
## Отображаемые метрики
## Состав
### ETCP Connection:
- RTT Last/Avg10/Avg100 (микросекунды)
- Jitter (микросекунды)
- Bytes Sent (всего)
- Retransmissions (число)
- ACK received (число)
- Unacked bytes (текущие)
- Links count (число линков)
- `etcpmon_client.c/h`: неблокирующий Winsock-клиент, разбор кадров, pending ответов, кеши и история.
- `etcpmon_gui.c/h`: окно, контролы, опрос списков, обработка событий и Action Result.
- `etcpmon_graph.c/h`: график восьми метрик первого линка и выбор сэмпла курсором.
- `etcpmon_protocol.h`: общий с сервером wire-layout: `[size:2][type:1][seq_id:1][payload]`.
- `test_etcpmon.c`: регрессии клиента/GUI с локальным TCP-сервером; запускаются через `make check`.
### TUN Interface:
- Bytes Read/Written
- Packets Read/Written
- Read/Write Errors
Команда Action `nodes` возвращает текст узлов, `nat` подтверждает запуск NAT/STUN-проверки.
Неизвестная команда или недоступная служба возвращает ошибку с сохранением TCP-соединения.
### Links:
- Status (UP/DOWN)
- Encrypt/Decrypt Errors
- Send/Receive Errors
- Total Encrypted/Decrypted Bytes
- Bandwidth (Kbps)
- NAT Changes Count
Клиент досылает частичные кадры через ограниченный TX (64 КиБ/256 кадров). Сервер формирует
один кадр до 32 КиБ, приостанавливая чтение до его отправки; список узлов передаётся порциями.
Таймауты и ограничения подписки описаны в [etcpmon_doc.md](etcpmon_doc.md).
## Период обновления
100 мс (10 обновлений в секунду)
## Безопасность
- Поддержка нескольких одновременных клиентов
- Отдельный TCP сокет (не путать с ETCP UDP)
- Рекомендуется использовать localhost (127.0.0.1) для локального мониторинга
## Лицензия
См. основной LICENSE файл проекта uTun.
Клиент пишет `etcpmon.log`, сервер — `control_server.log` в текущем рабочем каталоге каждого процесса.