From affb717a887b0494b34aaae5cf343ff3287d6812 Mon Sep 17 00:00:00 2001 From: Compot Developer Date: Fri, 16 Oct 2026 14:23:16 +0000 Subject: [PATCH] docs: align Markdown tables for reading as plain text Columns padded to the widest cell (CJK characters count as two), one space around the text, separator rows filled with dashes, alignment colons kept. Whitespace only. --- README.md | 52 +++++++++++----------- README.ru.md | 54 +++++++++++------------ README.zh-CN.md | 54 +++++++++++------------ bench/README.md | 18 ++++---- bench/vectors/README.md | 12 +++--- docs/architecture.md | 50 ++++++++++----------- docs/protocol.md | 36 ++++++++-------- docs/testing.md | 56 ++++++++++++------------ docs/usage.md | 96 ++++++++++++++++++++--------------------- server/README.md | 4 +- 10 files changed, 216 insertions(+), 216 deletions(-) diff --git a/README.md b/README.md index 31987f4..bb11b71 100644 --- a/README.md +++ b/README.md @@ -29,13 +29,13 @@ A resource access microsystem: a client for existing **VTun** servers (`vtund -s Static binaries (no dependencies) are on the [releases page](https://github.com/compot-dev/vtesse/releases): [`latest`](https://github.com/compot-dev/vtesse/releases/tag/latest) is rebuilt from every push to `main` (stable file names, used below). The release title shows the VTesse version; the change history is in [CHANGELOG.md](CHANGELOG.md). -| Platform | `ARCH` | -|---|---| -| OpenIPC cameras: HiSilicon, Goke, SigmaStar, other 32-bit ARM; Raspberry Pi with a 32-bit OS | `arm32` | +| Platform | `ARCH` | +|-------------------------------------------------------------------------------------------------|----------| +| OpenIPC cameras: HiSilicon, Goke, SigmaStar, other 32-bit ARM; Raspberry Pi with a 32-bit OS | `arm32` | | OpenIPC cameras: Ingenic (T31 and others); MIPS little-endian routers (MediaTek MT7621, MT7628) | `mipsel` | -| MIPS big-endian routers (Qualcomm Atheros ath79 and others) | `mips` | -| 64-bit ARM: Raspberry Pi with a 64-bit OS, Rockchip, other ARM64 boards | `arm64` | -| PCs and servers | `x86_64` | +| MIPS big-endian routers (Qualcomm Atheros ath79 and others) | `mips` | +| 64-bit ARM: Raspberry Pi with a 64-bit OS, Rockchip, other ARM64 boards | `arm64` | +| PCs and servers | `x86_64` | Two binaries per platform: `vtesse-ARCH` (lwIP and TAP backends: SOCKS5 / port forwards without root, or a kernel interface with `--tap`) and `vtesse-tap-ARCH` (TAP only, about half the size). The TAP backend needs root and the `tun` driver (`/dev/net/tun`), and the hook scripts `vtesse-hook.sh` and `vtesse-udhcpc.script`. @@ -140,31 +140,31 @@ The session name is the device ID (12 characters `0-9A-F`, also used as the MAC) ## Documentation -| Document | Contents | -|---|---| -| [Usage](docs/usage.md) | building, `vtesse-cli` options, configuration file, device ID, DHCP and routes, local proxy, error messages, probe tool | -| [VTun protocol](docs/protocol.md) | handshake, challenge response, session flags, framing, keepalive, server behaviour that affects clients, UDP | -| [Architecture](docs/architecture.md) | layers, `tunnel_ops_t`, VTun client, lwIP stack, proxy and flow control, repository layout | -| [Embedding](docs/embedding.md) | using the libraries in another application, loop integration, example | -| [Security](docs/security.md) | VTun authentication weaknesses, clear-text data, local proxy exposure | -| [VTun server](server/README.md) | patched vtund builds, release binaries, patch list | -| [Testing](docs/testing.md) | unit tests, sanitizers, big-endian MIPS, Docker test bench and acceptance tests | +| Document | Contents | +|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| [Usage](docs/usage.md) | building, `vtesse-cli` options, configuration file, device ID, DHCP and routes, local proxy, error messages, probe tool | +| [VTun protocol](docs/protocol.md) | handshake, challenge response, session flags, framing, keepalive, server behaviour that affects clients, UDP | +| [Architecture](docs/architecture.md) | layers, `tunnel_ops_t`, VTun client, lwIP stack, proxy and flow control, repository layout | +| [Embedding](docs/embedding.md) | using the libraries in another application, loop integration, example | +| [Security](docs/security.md) | VTun authentication weaknesses, clear-text data, local proxy exposure | +| [VTun server](server/README.md) | patched vtund builds, release binaries, patch list | +| [Testing](docs/testing.md) | unit tests, sanitizers, big-endian MIPS, Docker test bench and acceptance tests | ## Roadmap Stages and tasks are tracked as [GitHub issues](https://github.com/compot-dev/vtesse/issues): -| Stage | Status | Issues | -|---|---|---| -| 0. Test bench (VTun 3.0.2 in Docker, bridge, DHCP with option 121) | ✅ Done | [#1](https://github.com/compot-dev/vtesse/issues/1) ✅ | -| 1. CLI prototype on Linux: TCP + `type ether` + DHCP over lwIP | ✅ Done | [#2](https://github.com/compot-dev/vtesse/issues/2) ✅ [#3](https://github.com/compot-dev/vtesse/issues/3) ✅ [#4](https://github.com/compot-dev/vtesse/issues/4) ✅ [#5](https://github.com/compot-dev/vtesse/issues/5) ✅ [#6](https://github.com/compot-dev/vtesse/issues/6) ✅ [#7](https://github.com/compot-dev/vtesse/issues/7) ✅ [#8](https://github.com/compot-dev/vtesse/issues/8) ✅ | -| 2. Local proxy: SOCKS5 and port forwarding | ✅ Done | [#10](https://github.com/compot-dev/vtesse/issues/10) ✅ [#11](https://github.com/compot-dev/vtesse/issues/11) ✅ | -| 3. Embedded Linux: ARM/MIPS cross builds, footprint, CI | ✅ Done | [#12](https://github.com/compot-dev/vtesse/issues/12) ✅ [#20](https://github.com/compot-dev/vtesse/issues/20) ✅ | -| 3. TAP/TUN backend (kernel interface instead of lwIP, Linux targets) | ✅ Done | [#19](https://github.com/compot-dev/vtesse/issues/19) ✅ | -| 4. Android app (no VpnService) | ✅ Done | [#13](https://github.com/compot-dev/vtesse/issues/13) ✅ | -| 5. Optional: UDP transport, TLS wrapper, Blowfish auth | ⏸ Deferred | [#14](https://github.com/compot-dev/vtesse/issues/14) [#15](https://github.com/compot-dev/vtesse/issues/15) [#16](https://github.com/compot-dev/vtesse/issues/16) | -| 6. Reuse of the upper layers for camex | ⏸ Deferred | [#17](https://github.com/compot-dev/vtesse/issues/17) | -| Cross-cutting: tests, license | ✅ Done | [#9](https://github.com/compot-dev/vtesse/issues/9) ✅ [#18](https://github.com/compot-dev/vtesse/issues/18) ✅ | +| Stage | Status | Issues | +|----------------------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0. Test bench (VTun 3.0.2 in Docker, bridge, DHCP with option 121) | ✅ Done | [#1](https://github.com/compot-dev/vtesse/issues/1) ✅ | +| 1. CLI prototype on Linux: TCP + `type ether` + DHCP over lwIP | ✅ Done | [#2](https://github.com/compot-dev/vtesse/issues/2) ✅ [#3](https://github.com/compot-dev/vtesse/issues/3) ✅ [#4](https://github.com/compot-dev/vtesse/issues/4) ✅ [#5](https://github.com/compot-dev/vtesse/issues/5) ✅ [#6](https://github.com/compot-dev/vtesse/issues/6) ✅ [#7](https://github.com/compot-dev/vtesse/issues/7) ✅ [#8](https://github.com/compot-dev/vtesse/issues/8) ✅ | +| 2. Local proxy: SOCKS5 and port forwarding | ✅ Done | [#10](https://github.com/compot-dev/vtesse/issues/10) ✅ [#11](https://github.com/compot-dev/vtesse/issues/11) ✅ | +| 3. Embedded Linux: ARM/MIPS cross builds, footprint, CI | ✅ Done | [#12](https://github.com/compot-dev/vtesse/issues/12) ✅ [#20](https://github.com/compot-dev/vtesse/issues/20) ✅ | +| 3. TAP/TUN backend (kernel interface instead of lwIP, Linux targets) | ✅ Done | [#19](https://github.com/compot-dev/vtesse/issues/19) ✅ | +| 4. Android app (no VpnService) | ✅ Done | [#13](https://github.com/compot-dev/vtesse/issues/13) ✅ | +| 5. Optional: UDP transport, TLS wrapper, Blowfish auth | ⏸ Deferred | [#14](https://github.com/compot-dev/vtesse/issues/14) [#15](https://github.com/compot-dev/vtesse/issues/15) [#16](https://github.com/compot-dev/vtesse/issues/16) | +| 6. Reuse of the upper layers for camex | ⏸ Deferred | [#17](https://github.com/compot-dev/vtesse/issues/17) | +| Cross-cutting: tests, license | ✅ Done | [#9](https://github.com/compot-dev/vtesse/issues/9) ✅ [#18](https://github.com/compot-dev/vtesse/issues/18) ✅ | ✅ — closed issue. ⏸ — deferred. diff --git a/README.ru.md b/README.ru.md index a323d85..0df05ce 100644 --- a/README.ru.md +++ b/README.ru.md @@ -29,13 +29,13 @@ Статические бинарники (без зависимостей) — на [странице релизов](https://github.com/compot-dev/vtesse/releases): [`latest`](https://github.com/compot-dev/vtesse/releases/tag/latest) пересобирается при каждом push в `main` (постоянные имена файлов, используются ниже). Версия VTesse указана в заголовке релиза; история изменений — в [CHANGELOG.md](CHANGELOG.md). -| Платформа | `ARCH` | -|---|---| -| Камеры OpenIPC: HiSilicon, Goke, SigmaStar, другие 32-битные ARM; Raspberry Pi с 32-битной ОС | `arm32` | -| Камеры OpenIPC: Ingenic (T31 и другие); роутеры MIPS little-endian (MediaTek MT7621, MT7628) | `mipsel` | -| Роутеры MIPS big-endian (Qualcomm Atheros ath79 и другие) | `mips` | -| 64-битный ARM: Raspberry Pi с 64-битной ОС, Rockchip, другие платы ARM64 | `arm64` | -| ПК и серверы | `x86_64` | +| Платформа | `ARCH` | +|-----------------------------------------------------------------------------------------------|----------| +| Камеры OpenIPC: HiSilicon, Goke, SigmaStar, другие 32-битные ARM; Raspberry Pi с 32-битной ОС | `arm32` | +| Камеры OpenIPC: Ingenic (T31 и другие); роутеры MIPS little-endian (MediaTek MT7621, MT7628) | `mipsel` | +| Роутеры MIPS big-endian (Qualcomm Atheros ath79 и другие) | `mips` | +| 64-битный ARM: Raspberry Pi с 64-битной ОС, Rockchip, другие платы ARM64 | `arm64` | +| ПК и серверы | `x86_64` | На каждую платформу два бинарника: `vtesse-ARCH` (режимы lwIP и TAP: SOCKS5 / проброс портов без root или интерфейс ядра с `--tap`) и `vtesse-tap-ARCH` (только TAP, примерно вдвое меньше). Режиму TAP нужны root, драйвер `tun` (`/dev/net/tun`) и хук-скрипты `vtesse-hook.sh` и `vtesse-udhcpc.script`. @@ -142,31 +142,31 @@ ffplay -rtsp_transport tcp rtsp://127.0.0.1:8554/stream Документация на английском языке. -| Документ | Содержание | -|---|---| -| [Usage](docs/usage.md) | сборка, опции `vtesse-cli`, файл конфигурации, ID устройства, DHCP и маршруты, локальный прокси, сообщения об ошибках, утилита-зонд | -| [VTun protocol](docs/protocol.md) | рукопожатие, ответ на challenge, флаги сессии, кадры, keepalive, особенности сервера, важные для клиента, UDP | -| [Architecture](docs/architecture.md) | слои, `tunnel_ops_t`, клиент VTun, стек lwIP, прокси и управление потоком, структура репозитория | -| [Embedding](docs/embedding.md) | использование библиотек в другом приложении, интеграция с циклом событий, пример | -| [Security](docs/security.md) | слабые места аутентификации VTun, открытый трафик, доступ к локальному прокси | -| [VTun server](server/README.md) | сборки vtund с патчами, бинарники в релизах, список патчей | -| [Testing](docs/testing.md) | юнит-тесты, санитайзеры, big-endian MIPS, тестовый стенд в Docker и приёмочные тесты | +| Документ | Содержание | +|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| [Usage](docs/usage.md) | сборка, опции `vtesse-cli`, файл конфигурации, ID устройства, DHCP и маршруты, локальный прокси, сообщения об ошибках, утилита-зонд | +| [VTun protocol](docs/protocol.md) | рукопожатие, ответ на challenge, флаги сессии, кадры, keepalive, особенности сервера, важные для клиента, UDP | +| [Architecture](docs/architecture.md) | слои, `tunnel_ops_t`, клиент VTun, стек lwIP, прокси и управление потоком, структура репозитория | +| [Embedding](docs/embedding.md) | использование библиотек в другом приложении, интеграция с циклом событий, пример | +| [Security](docs/security.md) | слабые места аутентификации VTun, открытый трафик, доступ к локальному прокси | +| [VTun server](server/README.md) | сборки vtund с патчами, бинарники в релизах, список патчей | +| [Testing](docs/testing.md) | юнит-тесты, санитайзеры, big-endian MIPS, тестовый стенд в Docker и приёмочные тесты | ## План работ Этапы и задачи ведутся в [GitHub Issues](https://github.com/compot-dev/vtesse/issues): -| Этап | Статус | Задачи | -|---|---|---| -| 0. Тестовый стенд (VTun 3.0.2 в Docker, мост, DHCP с опцией 121) | ✅ Готово | [#1](https://github.com/compot-dev/vtesse/issues/1) ✅ | -| 1. Прототип CLI для Linux: TCP + `type ether` + DHCP поверх lwIP | ✅ Готово | [#2](https://github.com/compot-dev/vtesse/issues/2) ✅ [#3](https://github.com/compot-dev/vtesse/issues/3) ✅ [#4](https://github.com/compot-dev/vtesse/issues/4) ✅ [#5](https://github.com/compot-dev/vtesse/issues/5) ✅ [#6](https://github.com/compot-dev/vtesse/issues/6) ✅ [#7](https://github.com/compot-dev/vtesse/issues/7) ✅ [#8](https://github.com/compot-dev/vtesse/issues/8) ✅ | -| 2. Локальный прокси: SOCKS5 и проброс портов | ✅ Готово | [#10](https://github.com/compot-dev/vtesse/issues/10) ✅ [#11](https://github.com/compot-dev/vtesse/issues/11) ✅ | -| 3. Встраиваемый Linux: кросс-сборка ARM/MIPS, размер и память, CI | ✅ Готово | [#12](https://github.com/compot-dev/vtesse/issues/12) ✅ [#20](https://github.com/compot-dev/vtesse/issues/20) ✅ | -| 3. Режим TAP/TUN (интерфейс ядра вместо lwIP, Linux) | ✅ Готово | [#19](https://github.com/compot-dev/vtesse/issues/19) ✅ | -| 4. Приложение для Android (без VpnService) | ✅ Готово | [#13](https://github.com/compot-dev/vtesse/issues/13) ✅ | -| 5. Опционально: транспорт UDP, обёртка TLS, аутентификация Blowfish | ⏸ Отложено | [#14](https://github.com/compot-dev/vtesse/issues/14) [#15](https://github.com/compot-dev/vtesse/issues/15) [#16](https://github.com/compot-dev/vtesse/issues/16) | -| 6. Повторное использование верхних слоёв в camex | ⏸ Отложено | [#17](https://github.com/compot-dev/vtesse/issues/17) | -| Общее: тесты, лицензия | ✅ Готово | [#9](https://github.com/compot-dev/vtesse/issues/9) ✅ [#18](https://github.com/compot-dev/vtesse/issues/18) ✅ | +| Этап | Статус | Задачи | +|---------------------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0. Тестовый стенд (VTun 3.0.2 в Docker, мост, DHCP с опцией 121) | ✅ Готово | [#1](https://github.com/compot-dev/vtesse/issues/1) ✅ | +| 1. Прототип CLI для Linux: TCP + `type ether` + DHCP поверх lwIP | ✅ Готово | [#2](https://github.com/compot-dev/vtesse/issues/2) ✅ [#3](https://github.com/compot-dev/vtesse/issues/3) ✅ [#4](https://github.com/compot-dev/vtesse/issues/4) ✅ [#5](https://github.com/compot-dev/vtesse/issues/5) ✅ [#6](https://github.com/compot-dev/vtesse/issues/6) ✅ [#7](https://github.com/compot-dev/vtesse/issues/7) ✅ [#8](https://github.com/compot-dev/vtesse/issues/8) ✅ | +| 2. Локальный прокси: SOCKS5 и проброс портов | ✅ Готово | [#10](https://github.com/compot-dev/vtesse/issues/10) ✅ [#11](https://github.com/compot-dev/vtesse/issues/11) ✅ | +| 3. Встраиваемый Linux: кросс-сборка ARM/MIPS, размер и память, CI | ✅ Готово | [#12](https://github.com/compot-dev/vtesse/issues/12) ✅ [#20](https://github.com/compot-dev/vtesse/issues/20) ✅ | +| 3. Режим TAP/TUN (интерфейс ядра вместо lwIP, Linux) | ✅ Готово | [#19](https://github.com/compot-dev/vtesse/issues/19) ✅ | +| 4. Приложение для Android (без VpnService) | ✅ Готово | [#13](https://github.com/compot-dev/vtesse/issues/13) ✅ | +| 5. Опционально: транспорт UDP, обёртка TLS, аутентификация Blowfish | ⏸ Отложено | [#14](https://github.com/compot-dev/vtesse/issues/14) [#15](https://github.com/compot-dev/vtesse/issues/15) [#16](https://github.com/compot-dev/vtesse/issues/16) | +| 6. Повторное использование верхних слоёв в camex | ⏸ Отложено | [#17](https://github.com/compot-dev/vtesse/issues/17) | +| Общее: тесты, лицензия | ✅ Готово | [#9](https://github.com/compot-dev/vtesse/issues/9) ✅ [#18](https://github.com/compot-dev/vtesse/issues/18) ✅ | ✅ — задача закрыта. ⏸ — отложено. diff --git a/README.zh-CN.md b/README.zh-CN.md index 807ce22..c73da62 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -29,13 +29,13 @@ 静态二进制文件（无依赖）发布在 [Releases 页面](https://github.com/compot-dev/vtesse/releases)：[`latest`](https://github.com/compot-dev/vtesse/releases/tag/latest) 随 `main` 的每次推送重新构建（文件名固定，下文使用）。发布标题中注明 VTesse 版本；变更记录见 [CHANGELOG.md](CHANGELOG.md)。 -| 平台 | `ARCH` | -|---|---| -| OpenIPC 摄像机：海思、国科、SigmaStar 及其他 32 位 ARM；运行 32 位系统的树莓派 | `arm32` | -| OpenIPC 摄像机：君正（T31 等）；小端 MIPS 路由器（联发科 MT7621、MT7628） | `mipsel` | -| 大端 MIPS 路由器（高通 Atheros ath79 等） | `mips` | -| 64 位 ARM：运行 64 位系统的树莓派、瑞芯微及其他 ARM64 开发板 | `arm64` | -| PC 与服务器 | `x86_64` | +| 平台 | `ARCH` | +|--------------------------------------------------------------------------------|----------| +| OpenIPC 摄像机：海思、国科、SigmaStar 及其他 32 位 ARM；运行 32 位系统的树莓派 | `arm32` | +| OpenIPC 摄像机：君正（T31 等）；小端 MIPS 路由器（联发科 MT7621、MT7628） | `mipsel` | +| 大端 MIPS 路由器（高通 Atheros ath79 等） | `mips` | +| 64 位 ARM：运行 64 位系统的树莓派、瑞芯微及其他 ARM64 开发板 | `arm64` | +| PC 与服务器 | `x86_64` | 每个平台提供两个二进制文件：`vtesse-ARCH`（lwIP 与 TAP 两种后端：无需 root 的 SOCKS5 / 端口转发，或使用 `--tap` 的内核接口）和 `vtesse-tap-ARCH`（仅 TAP，体积约为一半）。TAP 后端需要 root、`tun` 驱动（`/dev/net/tun`）以及钩子脚本 `vtesse-hook.sh` 和 `vtesse-udhcpc.script`。 @@ -142,31 +142,31 @@ ffplay -rtsp_transport tcp rtsp://127.0.0.1:8554/stream 文档为英文。 -| 文档 | 内容 | -|---|---| -| [Usage](docs/usage.md) | 构建、`vtesse-cli` 选项、配置文件、设备 ID、DHCP 与路由、本地代理、错误信息、探测工具 | -| [VTun protocol](docs/protocol.md) | 握手、质询应答、会话标志、帧格式、keepalive、影响客户端的服务器行为、UDP | -| [Architecture](docs/architecture.md) | 分层、`tunnel_ops_t`、VTun 客户端、lwIP 协议栈、代理与流量控制、仓库结构 | -| [Embedding](docs/embedding.md) | 在其他应用中使用这些库、事件循环集成、示例 | -| [Security](docs/security.md) | VTun 认证的弱点、明文数据、本地代理的暴露面 | -| [VTun server](server/README.md) | 打补丁的 vtund 构建、发布的二进制文件、补丁列表 | -| [Testing](docs/testing.md) | 单元测试、sanitizer、大端序 MIPS、Docker 测试台与验收测试 | +| 文档 | 内容 | +|--------------------------------------|---------------------------------------------------------------------------------------| +| [Usage](docs/usage.md) | 构建、`vtesse-cli` 选项、配置文件、设备 ID、DHCP 与路由、本地代理、错误信息、探测工具 | +| [VTun protocol](docs/protocol.md) | 握手、质询应答、会话标志、帧格式、keepalive、影响客户端的服务器行为、UDP | +| [Architecture](docs/architecture.md) | 分层、`tunnel_ops_t`、VTun 客户端、lwIP 协议栈、代理与流量控制、仓库结构 | +| [Embedding](docs/embedding.md) | 在其他应用中使用这些库、事件循环集成、示例 | +| [Security](docs/security.md) | VTun 认证的弱点、明文数据、本地代理的暴露面 | +| [VTun server](server/README.md) | 打补丁的 vtund 构建、发布的二进制文件、补丁列表 | +| [Testing](docs/testing.md) | 单元测试、sanitizer、大端序 MIPS、Docker 测试台与验收测试 | ## 路线图 各阶段与任务记录在 [GitHub Issues](https://github.com/compot-dev/vtesse/issues) 中： -| 阶段 | 状态 | Issues | -|---|---|---| -| 0. 测试台（Docker 中的 VTun 3.0.2、网桥、带选项 121 的 DHCP） | ✅ 已完成 | [#1](https://github.com/compot-dev/vtesse/issues/1) ✅ | -| 1. Linux 命令行原型：TCP + `type ether` + 基于 lwIP 的 DHCP | ✅ 已完成 | [#2](https://github.com/compot-dev/vtesse/issues/2) ✅ [#3](https://github.com/compot-dev/vtesse/issues/3) ✅ [#4](https://github.com/compot-dev/vtesse/issues/4) ✅ [#5](https://github.com/compot-dev/vtesse/issues/5) ✅ [#6](https://github.com/compot-dev/vtesse/issues/6) ✅ [#7](https://github.com/compot-dev/vtesse/issues/7) ✅ [#8](https://github.com/compot-dev/vtesse/issues/8) ✅ | -| 2. 本地代理：SOCKS5 与端口转发 | ✅ 已完成 | [#10](https://github.com/compot-dev/vtesse/issues/10) ✅ [#11](https://github.com/compot-dev/vtesse/issues/11) ✅ | -| 3. 嵌入式 Linux：ARM/MIPS 交叉编译、体积与内存、CI | ✅ 已完成 | [#12](https://github.com/compot-dev/vtesse/issues/12) ✅ [#20](https://github.com/compot-dev/vtesse/issues/20) ✅ | -| 3. TAP/TUN 后端（用内核接口代替 lwIP，Linux 平台） | ✅ 已完成 | [#19](https://github.com/compot-dev/vtesse/issues/19) ✅ | -| 4. Android 应用（不使用 VpnService） | ✅ 已完成 | [#13](https://github.com/compot-dev/vtesse/issues/13) ✅ | -| 5. 可选：UDP 传输、TLS 封装、Blowfish 认证 | ⏸ 已推迟 | [#14](https://github.com/compot-dev/vtesse/issues/14) [#15](https://github.com/compot-dev/vtesse/issues/15) [#16](https://github.com/compot-dev/vtesse/issues/16) | -| 6. 在 camex 中复用上层模块 | ⏸ 已推迟 | [#17](https://github.com/compot-dev/vtesse/issues/17) | -| 通用：测试、许可证 | ✅ 已完成 | [#9](https://github.com/compot-dev/vtesse/issues/9) ✅ [#18](https://github.com/compot-dev/vtesse/issues/18) ✅ | +| 阶段 | 状态 | Issues | +|---------------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0. 测试台（Docker 中的 VTun 3.0.2、网桥、带选项 121 的 DHCP） | ✅ 已完成 | [#1](https://github.com/compot-dev/vtesse/issues/1) ✅ | +| 1. Linux 命令行原型：TCP + `type ether` + 基于 lwIP 的 DHCP | ✅ 已完成 | [#2](https://github.com/compot-dev/vtesse/issues/2) ✅ [#3](https://github.com/compot-dev/vtesse/issues/3) ✅ [#4](https://github.com/compot-dev/vtesse/issues/4) ✅ [#5](https://github.com/compot-dev/vtesse/issues/5) ✅ [#6](https://github.com/compot-dev/vtesse/issues/6) ✅ [#7](https://github.com/compot-dev/vtesse/issues/7) ✅ [#8](https://github.com/compot-dev/vtesse/issues/8) ✅ | +| 2. 本地代理：SOCKS5 与端口转发 | ✅ 已完成 | [#10](https://github.com/compot-dev/vtesse/issues/10) ✅ [#11](https://github.com/compot-dev/vtesse/issues/11) ✅ | +| 3. 嵌入式 Linux：ARM/MIPS 交叉编译、体积与内存、CI | ✅ 已完成 | [#12](https://github.com/compot-dev/vtesse/issues/12) ✅ [#20](https://github.com/compot-dev/vtesse/issues/20) ✅ | +| 3. TAP/TUN 后端（用内核接口代替 lwIP，Linux 平台） | ✅ 已完成 | [#19](https://github.com/compot-dev/vtesse/issues/19) ✅ | +| 4. Android 应用（不使用 VpnService） | ✅ 已完成 | [#13](https://github.com/compot-dev/vtesse/issues/13) ✅ | +| 5. 可选：UDP 传输、TLS 封装、Blowfish 认证 | ⏸ 已推迟 | [#14](https://github.com/compot-dev/vtesse/issues/14) [#15](https://github.com/compot-dev/vtesse/issues/15) [#16](https://github.com/compot-dev/vtesse/issues/16) | +| 6. 在 camex 中复用上层模块 | ⏸ 已推迟 | [#17](https://github.com/compot-dev/vtesse/issues/17) | +| 通用：测试、许可证 | ✅ 已完成 | [#9](https://github.com/compot-dev/vtesse/issues/9) ✅ [#18](https://github.com/compot-dev/vtesse/issues/18) ✅ | ✅ — 已关闭的 issue。 ⏸ — 已推迟。 diff --git a/bench/README.md b/bench/README.md index f2053f5..140b477 100644 --- a/bench/README.md +++ b/bench/README.md @@ -35,15 +35,15 @@ logged with the session name and the reason, e.g. ## Sessions (`vtund.conf`) -| Session | Purpose | Flags | -|---|---|---| -| `02BE0C000001` | main: `type ether`, bridge + DHCP, `keepalive 10:5`, `multi killold` | `` | -| `02BE0C000002` | second ether client | `` | -| `02BE0C000003` | inherits `speed 512:512` from `default` | `` | -| `02BE0C000004` | `compress zlib:9` (client must refuse) | `` | -| `02BE0C000005` | `multi no` (second login → `ERR`) | `` | -| `02BE0C000006` | `type tun`, manual addressing (`10.76.0.1` ↔ `10.76.0.2`) | `` | -| `02BE0C000007`, `02BE0C000008` | more ether clients for real devices on the LAN (`BENCH_BIND`) | `` | +| Session | Purpose | Flags | +|--------------------------------|----------------------------------------------------------------------|-------------| +| `02BE0C000001` | main: `type ether`, bridge + DHCP, `keepalive 10:5`, `multi killold` | `` | +| `02BE0C000002` | second ether client | `` | +| `02BE0C000003` | inherits `speed 512:512` from `default` | `` | +| `02BE0C000004` | `compress zlib:9` (client must refuse) | `` | +| `02BE0C000005` | `multi no` (second login → `ERR`) | `` | +| `02BE0C000006` | `type tun`, manual addressing (`10.76.0.1` ↔ `10.76.0.2`) | `` | +| `02BE0C000007`, `02BE0C000008` | more ether clients for real devices on the LAN (`BENCH_BIND`) | `` | Passwords are in `vtund.conf`. diff --git a/bench/vectors/README.md b/bench/vectors/README.md index 95d7199..e3abb48 100644 --- a/bench/vectors/README.md +++ b/bench/vectors/README.md @@ -7,13 +7,13 @@ session `02BE0C000001`, bench password `c79e01d2e49d80eafd192c043c5142bd5a65b5a9 ## Handshake (each message is exactly 50 bytes, NUL padded) -| Dir | Text | -|---|---| -| S→C | `VTUN server ver 3.X 10/13/2026\n` | -| C→S | `HOST: 02BE0C000001\n` | +| Dir | Text | +|-----|-------------------------------------------------| +| S→C | `VTUN server ver 3.X 10/13/2026\n` | +| C→S | `HOST: 02BE0C000001\n` | | S→C | `OK CHAL: \n` | -| C→S | `CHAL: \n` | -| S→C | `OK FLAGS: \n` | +| C→S | `CHAL: \n` | +| S→C | `OK FLAGS: \n` | XOR check: `cl2cs(cs2cl(chal) XOR password)` must equal the client `CHAL`. diff --git a/docs/architecture.md b/docs/architecture.md index f527181..5b22278 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -57,22 +57,22 @@ the tunnel; there is no system network interface. ## Repository layout -| Path | Contents | -|---|---| -| `include/netcore/`, `netcore/` | `tunnel_ops_t`, poll loop helper, route table, lwIP stack glue, proxy, TAP backend (protocol-agnostic) | -| `include/vtesse/`, `vtun/` | VTun wire format helpers and the VTun client | -| `cli/` | `vtesse-cli` | -| `port/lwip/` | lwIP configuration (`lwipopts.h`), `arch/cc.h`, hook prototypes | -| `third_party/lwip/` | vendored lwIP 2.2.1, unmodified subset | -| `tests/` | unit tests and client scenarios | -| `bench/` | Docker test bench | -| `android/` | Android app: Gradle project, JNI bridge, foreground service ([android/README.md](../android/README.md)) | -| `server/` | vtund build script and our VTun server patches (bench and release builds) | -| `ci/` | cross builds (`build-musl.sh`), build containers, big-endian MIPS tests under qemu | -| `.github/workflows/` | CI: tests, cross builds, test bench, releases | -| `tools/` | probe script | -| `scripts/` | hook and udhcpc scripts for the TAP backend, service scripts (`S99vtesse`, `vtesse.init`) | -| `docs/` | documentation | +| Path | Contents | +|--------------------------------|---------------------------------------------------------------------------------------------------------| +| `include/netcore/`, `netcore/` | `tunnel_ops_t`, poll loop helper, route table, lwIP stack glue, proxy, TAP backend (protocol-agnostic) | +| `include/vtesse/`, `vtun/` | VTun wire format helpers and the VTun client | +| `cli/` | `vtesse-cli` | +| `port/lwip/` | lwIP configuration (`lwipopts.h`), `arch/cc.h`, hook prototypes | +| `third_party/lwip/` | vendored lwIP 2.2.1, unmodified subset | +| `tests/` | unit tests and client scenarios | +| `bench/` | Docker test bench | +| `android/` | Android app: Gradle project, JNI bridge, foreground service ([android/README.md](../android/README.md)) | +| `server/` | vtund build script and our VTun server patches (bench and release builds) | +| `ci/` | cross builds (`build-musl.sh`), build containers, big-endian MIPS tests under qemu | +| `.github/workflows/` | CI: tests, cross builds, test bench, releases | +| `tools/` | probe script | +| `scripts/` | hook and udhcpc scripts for the TAP backend, service scripts (`S99vtesse`, `vtesse.init`) | +| `docs/` | documentation | ## Tunnel interface @@ -178,15 +178,15 @@ device), for RTP pushed by cameras. User-facing: [usage](usage.md#udp-relay-rtp- Two consumers of `tunnel_ops_t`: -| | lwIP (default) | TAP ([`tapdev.h`](../include/netcore/tapdev.h)) | -|---|---|---| -| Interface in the system | none | `vtesse0` (TAP for `type ether`, TUN for `type tun`) | -| Who can use the tunnel | the application, programs using its proxy | every program | -| Inbound connections | no | yes | -| Addressing | built-in DHCP client (lwIP) | system DHCP client via the hook script | -| Privileges | none | root or `CAP_NET_ADMIN`, `tun` driver | -| Platforms | Linux, Android | Linux | -| Code size (x86_64, `-Os`) | ~107 KiB code + lwIP pools | ~23 KiB (`make LWIP=0`) | +| | lwIP (default) | TAP ([`tapdev.h`](../include/netcore/tapdev.h)) | +|---------------------------|-------------------------------------------|------------------------------------------------------| +| Interface in the system | none | `vtesse0` (TAP for `type ether`, TUN for `type tun`) | +| Who can use the tunnel | the application, programs using its proxy | every program | +| Inbound connections | no | yes | +| Addressing | built-in DHCP client (lwIP) | system DHCP client via the hook script | +| Privileges | none | root or `CAP_NET_ADMIN`, `tun` driver | +| Platforms | Linux, Android | Linux | +| Code size (x86_64, `-Os`) | ~107 KiB code + lwIP pools | ~23 KiB (`make LWIP=0`) | The TAP backend creates the interface on the first tunnel `UP`, keeps it across reconnects and switches the carrier off while the tunnel is down diff --git a/docs/protocol.md b/docs/protocol.md index 59b1df3..9709840 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -48,10 +48,10 @@ in `<` `>`. Exactly 32 characters. **Challenge response** (`encrypt_chal`) depends on how the server was built: -| Server build | Response | -|---|---| +| Server build | Response | +|-----------------------------------|------------------------------------------------------------------------------------------------------| | without OpenSSL (`--disable-ssl`) | `resp[i] = chal[i] ^ pwd[i % strlen(pwd)]`, i = 0..15 — only the first 16 password characters matter | -| with OpenSSL | Blowfish-ECB over two 8-byte blocks, key = `MD5(password)` (16 bytes) | +| with OpenSSL | Blowfish-ECB over two 8-byte blocks, key = `MD5(password)` (16 bytes) | The client cannot detect the variant in advance; the auth mode is a setting. VTesse implements XOR; Blowfish is planned @@ -73,16 +73,16 @@ login with `multi` other than `yes` gets `ERR`. `OK FLAGS: <...>` (`bf2cf` / `cf2bf`), server order: transport, type, `S`, `C`, `L`, `K`, `E`, `>`. Example: ``. -| Flag | Meaning | VTesse | -|---|---|---| -| `T` / `U` | TCP / UDP transport | TCP; `U` → error "UDP not supported" (deferred) | -| `u` / `e` | `type tun` / `type ether` | supported | -| `t` / `p` | `type tty` / `type pipe` | error | -| `K` | keepalive | must answer `ECHO_REQ` | -| `C` / `L` | zlib / LZO compression | error "compression enabled on server" | -| `E` / `E` | encryption (`E0`/`E` legacy, else cipher id) | error "encryption enabled on server" | -| `S` | shaper | ignored | -| `F` | reserved | ignored | +| Flag | Meaning | VTesse | +|-----------------|----------------------------------------------|-------------------------------------------------| +| `T` / `U` | TCP / UDP transport | TCP; `U` → error "UDP not supported" (deferred) | +| `u` / `e` | `type tun` / `type ether` | supported | +| `t` / `p` | `type tty` / `type pipe` | error | +| `K` | keepalive | must answer `ECHO_REQ` | +| `C` / `L` | zlib / LZO compression | error "compression enabled on server" | +| `E` / `E` | encryption (`E0`/`E` legacy, else cipher id) | error "encryption enabled on server" | +| `S` | shaper | ignored | +| `F` | reserved | ignored | An unknown flag character, a missing number after `C`/`L`/`S` or a missing `>` is an error (as in the reference `cf2bf`). A session `speed 0:0` removes a shaper inherited @@ -99,12 +99,12 @@ Right after `OK FLAGS` the same TCP connection carries frames: hdr, big-endian: bits 0..11 = length (VTUN_FSIZE_MASK 0x0fff), bits 12..15 = flags ``` -| Flag | Name | Meaning | -|---|---|---| +| Flag | Name | Meaning | +|----------|-------------------|--------------------------------------------------------------| | `0x1000` | `VTUN_CONN_CLOSE` | peer closes the session (also sent when kicked by `killold`) | -| `0x2000` | `VTUN_ECHO_REQ` | keepalive request | -| `0x4000` | `VTUN_ECHO_REP` | keepalive reply | -| `0x8000` | `VTUN_BAD_FRAME` | internal return code of `tcp_read`, never on the wire | +| `0x2000` | `VTUN_ECHO_REQ` | keepalive request | +| `0x4000` | `VTUN_ECHO_REP` | keepalive reply | +| `0x8000` | `VTUN_BAD_FRAME` | internal return code of `tcp_read`, never on the wire | - A flag frame is a bare header (length 0). - Max payload `VTUN_FRAME_SIZE` = 2048; the receiver accepts up to 2048 + 100 diff --git a/docs/testing.md b/docs/testing.md index 2c30fed..7906c6c 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,33 +1,33 @@ # Testing -| Check | Command | What it covers | -|---|---|---| -| Unit tests | `make test` | `test_proto` (wire format, stock-client reference vector), `test_route` (option 121/249 parser, lookup, device ID), `test_client` (client scenarios against a scripted server: happy path, `ERR`, compression, bad greeting, handshake and keepalive timeouts, reconnect after take-over) | -| Sanitizers | `make BUILD=build-asan CFLAGS="-O1 -g -fsanitize=address,undefined" LDFLAGS="-fsanitize=address,undefined" test` | memory errors, undefined behaviour, leaks | -| Big-endian | `ci/test-mips.sh` | static MIPS BE build in Docker, all unit tests under `qemu-mips` | -| Real devices | `BENCH_BIND= bench/bench.sh up` | the bench listens on a LAN address so cameras/routers can connect to it instead of a production server | -| Cross targets | `QEMU=1 ci/build-musl.sh ` | static musl build for a camera/router target (VTesse; the patched vtund for x86_64 or with `VTUND=1`), unit tests under qemu-user | -| Bench self-test | `bench/bench.sh selftest` | server behaviour VTesse relies on (greeting, flags, keepalive, DHCP through the tunnel, `killold`, `ERR` cases, `multi no`) | -| Stage 1 acceptance | `bench/bench.sh cli-test` | `vtesse-cli`: DHCP address and option 121 routes, option 3 ignored, HTTP through lwIP, ping of the client from the device, reconnect after a take-over with the same address | -| Stage 2 acceptance | `bench/bench.sh proxy-test` | SOCKS5 reply codes, `curl --socks5`, 20 MiB download and 8 MiB echo with integrity checks, RTSP through a forward, 8 parallel downloads, SOCKS5 authentication | -| type tun | `bench/bench.sh tun-test` | `type tun` session with manual IPv4 (`ip`/`gw`/`route`): lwIP — HTTP to the device and inbound ping of the client; `--tap` — TUN interface configured by the hook, ping/HTTP to the device, inbound ping, no default route | -| UDP relay | `bench/bench.sh udp-test` | the device behind the server sends 500 numbered 1200-byte datagrams and one 4000-byte (fragmented) datagram to the tunnel address; all arrive at `127.0.0.1:1559` in order and intact; relay statistics | -| Failures | `bench/bench.sh fault-test` | link loss (server frozen past the keepalive timeout): DOWN, reconnect, same address; server restart: reconnect, same address; no option 121: option 3 becomes the default route; 2-minute leases: renewed at T1, address kept after expiry; dnsmasq restored (~4 min) | -| TAP backend | `bench/bench.sh tap-test` | `vtesse-cli --tap` (`LWIP=0` build) in a container: DHCP via udhcpc, option 121 route, no default route, HTTP and a 20 MiB download from any process, **inbound** ping and TCP from the device, reconnect after a take-over keeps interface and address, clean exit | -| Reference client | `bench/bench.sh stock-test` | the stock `vtund` client + `dhclient` reach the device through the bench | +| Check | Command | What it covers | +|--------------------|------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Unit tests | `make test` | `test_proto` (wire format, stock-client reference vector), `test_route` (option 121/249 parser, lookup, device ID), `test_client` (client scenarios against a scripted server: happy path, `ERR`, compression, bad greeting, handshake and keepalive timeouts, reconnect after take-over) | +| Sanitizers | `make BUILD=build-asan CFLAGS="-O1 -g -fsanitize=address,undefined" LDFLAGS="-fsanitize=address,undefined" test` | memory errors, undefined behaviour, leaks | +| Big-endian | `ci/test-mips.sh` | static MIPS BE build in Docker, all unit tests under `qemu-mips` | +| Real devices | `BENCH_BIND= bench/bench.sh up` | the bench listens on a LAN address so cameras/routers can connect to it instead of a production server | +| Cross targets | `QEMU=1 ci/build-musl.sh ` | static musl build for a camera/router target (VTesse; the patched vtund for x86_64 or with `VTUND=1`), unit tests under qemu-user | +| Bench self-test | `bench/bench.sh selftest` | server behaviour VTesse relies on (greeting, flags, keepalive, DHCP through the tunnel, `killold`, `ERR` cases, `multi no`) | +| Stage 1 acceptance | `bench/bench.sh cli-test` | `vtesse-cli`: DHCP address and option 121 routes, option 3 ignored, HTTP through lwIP, ping of the client from the device, reconnect after a take-over with the same address | +| Stage 2 acceptance | `bench/bench.sh proxy-test` | SOCKS5 reply codes, `curl --socks5`, 20 MiB download and 8 MiB echo with integrity checks, RTSP through a forward, 8 parallel downloads, SOCKS5 authentication | +| type tun | `bench/bench.sh tun-test` | `type tun` session with manual IPv4 (`ip`/`gw`/`route`): lwIP — HTTP to the device and inbound ping of the client; `--tap` — TUN interface configured by the hook, ping/HTTP to the device, inbound ping, no default route | +| UDP relay | `bench/bench.sh udp-test` | the device behind the server sends 500 numbered 1200-byte datagrams and one 4000-byte (fragmented) datagram to the tunnel address; all arrive at `127.0.0.1:1559` in order and intact; relay statistics | +| Failures | `bench/bench.sh fault-test` | link loss (server frozen past the keepalive timeout): DOWN, reconnect, same address; server restart: reconnect, same address; no option 121: option 3 becomes the default route; 2-minute leases: renewed at T1, address kept after expiry; dnsmasq restored (~4 min) | +| TAP backend | `bench/bench.sh tap-test` | `vtesse-cli --tap` (`LWIP=0` build) in a container: DHCP via udhcpc, option 121 route, no default route, HTTP and a 20 MiB download from any process, **inbound** ping and TCP from the device, reconnect after a take-over keeps interface and address, clean exit | +| Reference client | `bench/bench.sh stock-test` | the stock `vtund` client + `dhclient` reach the device through the bench | ## CI [`.github/workflows/build.yml`](../.github/workflows/build.yml) runs on every push and pull request: -| Job | What it does | -|---|---| -| `tests` | `make test`, the same under ASan/UBSan, the `LWIP=0` build | +| Job | What it does | +|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `tests` | `make test`, the same under ASan/UBSan, the `LWIP=0` build | | `build` (arm32, mipsel, arm64, mips, x86_64) | static musl binaries with `ci/build-musl.sh` (`vtesse`, `vtesse-tap`; patched `vtund` in the x86_64 job), unit tests and a `vtund -h` smoke test under qemu-user, artifacts | -| `bench` | the Docker test bench (vtund built with our patches): `selftest`, `cli-test`, `proxy-test`, `tap-test`, `tun-test`, `udp-test`, `fault-test` | -| `android` | the APKs in Docker (`android/build.sh`, `ci/Dockerfile.android`); the release APK is signed with the key from the repository secrets | -| `release` | push to `main`: replaces the `latest` release; binaries, `vtund--x86_64`, hook scripts, service scripts, `SHA256SUMS` | +| `bench` | the Docker test bench (vtund built with our patches): `selftest`, `cli-test`, `proxy-test`, `tap-test`, `tun-test`, `udp-test`, `fault-test` | +| `android` | the APKs in Docker (`android/build.sh`, `ci/Dockerfile.android`); the release APK is signed with the key from the repository secrets | +| `release` | push to `main`: replaces the `latest` release; binaries, `vtund--x86_64`, hook scripts, service scripts, `SHA256SUMS` | ### Versions and releases @@ -89,13 +89,13 @@ Results of 2026-10-14 (v1.09–1.10, #19, #30), all against the bench over a ~47 Device configuration was not changed: binaries, scripts and configs ran from `/tmp` (service scripts as copies with their paths pointed there) and were removed afterwards. -| Device | Backend | Checked | -|---|---|---| -| 2 × OpenIPC camera, SigmaStar SSC337 (armv7, 27 MiB RAM), `vtesse-arm32` / `vtesse-tap-arm32` | TAP (`--tap`, hook + udhcpc) | interface with MAC = device ID, DHCP address, option 121 routes, no default route; ping/HTTP to the device; 20 MiB at ~10 Mbit/s on both at once; **inbound**: the device opens the cameras' own web UI over the tunnel; take-over (reconnect ~2 s, same address); `type tun` with `ip=`/`route=`; clean stop; `S99vtesse` start/status/restart/stop; peak RSS ~148 KiB | -| same cameras | lwIP (medium profile) | DHCP + 121; HTTP and RTSP forwards; SOCKS5 used from the LAN (`--listen 0.0.0.0`); UDP relay (all datagrams arrive); take-over; link loss (DOWN by keepalive, reconnect); peak RSS ~412 KiB | -| OpenWrt 15.05 router, MediaTek MT7620 (MIPS 24KEc, no FPU, 61 MiB RAM), `vtesse-mipsel` / `vtesse-tap-mipsel` (soft-float) | TAP | MAC = device ID, DHCP, option 121 routes, no default route, `resolv.conf` untouched; ping/HTTP to the device; 20 MiB at ~16 Mbit/s; **inbound**: the device opens the router's web UI over the tunnel; take-over (~2 s, same address); clean stop; `vtesse.init` under procd: start, respawn after `kill -9`, stop, output in the system log; peak RSS ~188 KiB | -| same router | lwIP (medium profile) | DHCP + 121; HTTP/RTSP forwards; 20 MiB at ~9 Mbit/s; SOCKS5 from the LAN; UDP relay; link loss 65 s (DOWN by keepalive, reconnect); peak RSS ~468 KiB | -| Android 10 TV box (Amlogic, armv7) | app (large profile) | server profile with a camera: RTSP/HTTP forwards on the scheme ports, SOCKS5, 20 MiB with sha256 check, UDP relay counters, link loss and server restart recovered by themselves, switching back to another server | +| Device | Backend | Checked | +|----------------------------------------------------------------------------------------------------------------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2 × OpenIPC camera, SigmaStar SSC337 (armv7, 27 MiB RAM), `vtesse-arm32` / `vtesse-tap-arm32` | TAP (`--tap`, hook + udhcpc) | interface with MAC = device ID, DHCP address, option 121 routes, no default route; ping/HTTP to the device; 20 MiB at ~10 Mbit/s on both at once; **inbound**: the device opens the cameras' own web UI over the tunnel; take-over (reconnect ~2 s, same address); `type tun` with `ip=`/`route=`; clean stop; `S99vtesse` start/status/restart/stop; peak RSS ~148 KiB | +| same cameras | lwIP (medium profile) | DHCP + 121; HTTP and RTSP forwards; SOCKS5 used from the LAN (`--listen 0.0.0.0`); UDP relay (all datagrams arrive); take-over; link loss (DOWN by keepalive, reconnect); peak RSS ~412 KiB | +| OpenWrt 15.05 router, MediaTek MT7620 (MIPS 24KEc, no FPU, 61 MiB RAM), `vtesse-mipsel` / `vtesse-tap-mipsel` (soft-float) | TAP | MAC = device ID, DHCP, option 121 routes, no default route, `resolv.conf` untouched; ping/HTTP to the device; 20 MiB at ~16 Mbit/s; **inbound**: the device opens the router's web UI over the tunnel; take-over (~2 s, same address); clean stop; `vtesse.init` under procd: start, respawn after `kill -9`, stop, output in the system log; peak RSS ~188 KiB | +| same router | lwIP (medium profile) | DHCP + 121; HTTP/RTSP forwards; 20 MiB at ~9 Mbit/s; SOCKS5 from the LAN; UDP relay; link loss 65 s (DOWN by keepalive, reconnect); peak RSS ~468 KiB | +| Android 10 TV box (Amlogic, armv7) | app (large profile) | server profile with a camera: RTSP/HTTP forwards on the scheme ports, SOCKS5, 20 MiB with sha256 check, UDP relay counters, link loss and server restart recovered by themselves, switching back to another server | The router run found that hard-float MIPS binaries die with `Illegal instruction` on router SoCs without an FPU (no FPU emulation in their kernels): since 1.10 the `mipsel` diff --git a/docs/usage.md b/docs/usage.md index 1b88b6c..2f02274 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -31,12 +31,12 @@ Static musl binaries for cameras and routers are built by QEMU=1 ci/build-musl.sh arm32 dist # downloads the toolchain, runs the tests under qemu ``` -| Target | Toolchain | Devices | -|---|---|---| -| `arm32` | OpenIPC `hisilicon-hi3516cv100` (arm musleabi) | 32-bit ARM cameras | +| Target | Toolchain | Devices | +|----------|--------------------------------------------------|-------------------------------------------------------------------------| +| `arm32` | OpenIPC `hisilicon-hi3516cv100` (arm musleabi) | 32-bit ARM cameras | | `mipsel` | OpenWrt 23.05 `ramips/mt7621` (musl, soft-float) | Ingenic cameras, little-endian MIPS routers (MediaTek MT7620/7621/7628) | -| `arm64` | Bootlin aarch64 musl | 64-bit ARM | -| `mips` | OpenWrt 23.05 `ath79/generic` (musl, soft-float) | big-endian MIPS routers (Atheros ath79 and others) | +| `arm64` | Bootlin aarch64 musl | 64-bit ARM | +| `mips` | OpenWrt 23.05 `ath79/generic` (musl, soft-float) | big-endian MIPS routers (Atheros ath79 and others) | MIPS builds are soft-float: router SoCs have no FPU and their kernels often lack FPU emulation, so hard-float binaries end with `Illegal instruction` there (found on an @@ -45,12 +45,12 @@ OpenWrt MT7620 router, #30). Optional modules (#29), `vtesse-cli --version` lists what a binary contains: -| Switch | Leaves out | arm32/x86_64 code saved | -|---|---|---| -| `LWIP=0` | lwIP stack, port forwards, SOCKS5, UDP relay (TAP/TUN backend only) | ~75 % | -| `SOCKS=0` | SOCKS5 server (port forwards stay) | ~1.7 KB | -| `UDP_RELAY=0` | UDP relay | ~2 KB | -| `TAP=0` | TAP/TUN backend (kernel interface) | ~5 KB | +| Switch | Leaves out | arm32/x86_64 code saved | +|---------------|---------------------------------------------------------------------|-------------------------| +| `LWIP=0` | lwIP stack, port forwards, SOCKS5, UDP relay (TAP/TUN backend only) | ~75 % | +| `SOCKS=0` | SOCKS5 server (port forwards stay) | ~1.7 KB | +| `UDP_RELAY=0` | UDP relay | ~2 KB | +| `TAP=0` | TAP/TUN backend (kernel interface) | ~5 KB | A disabled feature is refused with a clear message (`--socks: built without SOCKS5`). Release binaries contain everything; `vtesse-tap-` is the `LWIP=0` build. @@ -72,20 +72,20 @@ vtesse-cli [--config FILE] [--seconds N] [-v] vtesse-cli [--config FILE] [--seconds N] --tap [--ifname NAME] [--hook SCRIPT] ``` -| Option | Meaning | -|---|---| -| `--config FILE` | configuration file, default `~/.config/vtesse/probe.conf` | -| `--seconds N` | stop after N seconds (default: run until SIGINT/SIGTERM) | -| `--id-from IFACE` | [device ID](#device-id) = MAC of the local interface `IFACE` (overrides `session`/`id_from` of the file) | -| `--socks PORT` | SOCKS5 server on `LISTEN:PORT` | -| `--forward LPORT:IP:RPORT` | TCP forward `LISTEN:LPORT → IP:RPORT` through the tunnel (repeatable, up to 16) | -| `--listen ADDR` | address of the local listeners, default `127.0.0.1` | -| `--udp-relay PORT[:LOCAL_PORT]` | [UDP relay](#udp-relay-rtp-from-cameras): datagrams to the tunnel address on `PORT` go to `127.0.0.1:LOCAL_PORT` (default the same port); repeatable, up to 3 | -| `--fetch URL` | one HTTP GET through the stack once an address is bound (diagnostics) | -| `--ip A.B.C.D/P`, `--gw A.B.C.D` | [manual IPv4](#manual-ipv4-type-tun) instead of DHCP; override `ip`/`gw` of the file (`--debug-ip`/`--debug-gw` are accepted as old names) | -| `--tap` | [TAP backend](#tap-backend): kernel interface instead of lwIP (Linux, root) | -| `--ifname NAME` | interface name for `--tap`, default `vtesse%d` | -| `--hook SCRIPT` | script run on interface events for `--tap` | +| Option | Meaning | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--config FILE` | configuration file, default `~/.config/vtesse/probe.conf` | +| `--seconds N` | stop after N seconds (default: run until SIGINT/SIGTERM) | +| `--id-from IFACE` | [device ID](#device-id) = MAC of the local interface `IFACE` (overrides `session`/`id_from` of the file) | +| `--socks PORT` | SOCKS5 server on `LISTEN:PORT` | +| `--forward LPORT:IP:RPORT` | TCP forward `LISTEN:LPORT → IP:RPORT` through the tunnel (repeatable, up to 16) | +| `--listen ADDR` | address of the local listeners, default `127.0.0.1` | +| `--udp-relay PORT[:LOCAL_PORT]` | [UDP relay](#udp-relay-rtp-from-cameras): datagrams to the tunnel address on `PORT` go to `127.0.0.1:LOCAL_PORT` (default the same port); repeatable, up to 3 | +| `--fetch URL` | one HTTP GET through the stack once an address is bound (diagnostics) | +| `--ip A.B.C.D/P`, `--gw A.B.C.D` | [manual IPv4](#manual-ipv4-type-tun) instead of DHCP; override `ip`/`gw` of the file (`--debug-ip`/`--debug-gw` are accepted as old names) | +| `--tap` | [TAP backend](#tap-backend): kernel interface instead of lwIP (Linux, root) | +| `--ifname NAME` | interface name for `--tap`, default `vtesse%d` | +| `--hook SCRIPT` | script run on interface events for `--tap` | The CLI brings the tunnel and the userspace stack up, prints link events, the DHCP address and routes, runs the local proxy and prints proxy statistics on exit. Exit @@ -151,17 +151,17 @@ vtesse-cli --config /etc/vtesse.conf --tap --ifname vtesse0 --hook /usr/share/vt `key=value` lines, `#` starts a comment. Credentials are read only from this file, never from the command line; keep it outside the repository with mode 600. -| Key | Meaning | -|---|---| -| `host` | VTun server name or IPv4 address | -| `port` | VTun server TCP port | -| `session` | session name = [device ID](#device-id) | -| `id_from` | instead of `session`: take the device ID from the MAC of this interface, e.g. `eth0` | -| `udp_relay` | `PORT[:LOCAL_PORT]`, repeatable: [UDP relay](#udp-relay-rtp-from-cameras) (lwIP backend) | -| `ip`, `gw`, `route` | [manual IPv4](#manual-ipv4-type-tun): `ip=A.B.C.D/P`, optional `gw=A.B.C.D`, `route=NET/P` (repeatable, up to 16); required for `type tun` | -| `password` | session password | -| `auth` | challenge response, `xor` (default; servers built without OpenSSL) | -| `socks_user`, `socks_password` | optional SOCKS5 username/password (RFC 1929) | +| Key | Meaning | +|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `host` | VTun server name or IPv4 address | +| `port` | VTun server TCP port | +| `session` | session name = [device ID](#device-id) | +| `id_from` | instead of `session`: take the device ID from the MAC of this interface, e.g. `eth0` | +| `udp_relay` | `PORT[:LOCAL_PORT]`, repeatable: [UDP relay](#udp-relay-rtp-from-cameras) (lwIP backend) | +| `ip`, `gw`, `route` | [manual IPv4](#manual-ipv4-type-tun): `ip=A.B.C.D/P`, optional `gw=A.B.C.D`, `route=NET/P` (repeatable, up to 16); required for `type tun` | +| `password` | session password | +| `auth` | challenge response, `xor` (default; servers built without OpenSSL) | +| `socks_user`, `socks_password` | optional SOCKS5 username/password (RFC 1929) | ## Device ID @@ -303,18 +303,18 @@ via `--udp-relay 1559:5600`). Link events printed by the CLI (`down` = retried automatically with backoff 1–30 s, `failed` = final): -| Message | Kind | Meaning | -|---|---|---| -| wrong session name or password | failed | server replied `ERR` (unknown session, wrong password, wrong auth mode, or session locked with `multi no`) | -| compression is enabled on the server | failed | session flags contain `C`/`L` | -| encryption is enabled on the server | failed | session flags contain `E` | -| unsupported transport (UDP) | failed | session flags contain `U` | -| unsupported session type | failed | `type tty` / `type pipe` | -| protocol error (not a VTun server?) | failed | unexpected greeting or flags | -| closed by server (possibly taken over by another connection) | down | `CONN_CLOSE` or EOF, e.g. another client logged in with the same session and `multi killold` | -| no response from server (keepalive) | down | 5 keepalive intervals without any frame | -| timeout | down | a handshake step timed out | -| cannot resolve / cannot connect to server | down | DNS or TCP connect failure | +| Message | Kind | Meaning | +|--------------------------------------------------------------|--------|------------------------------------------------------------------------------------------------------------| +| wrong session name or password | failed | server replied `ERR` (unknown session, wrong password, wrong auth mode, or session locked with `multi no`) | +| compression is enabled on the server | failed | session flags contain `C`/`L` | +| encryption is enabled on the server | failed | session flags contain `E` | +| unsupported transport (UDP) | failed | session flags contain `U` | +| unsupported session type | failed | `type tty` / `type pipe` | +| protocol error (not a VTun server?) | failed | unexpected greeting or flags | +| closed by server (possibly taken over by another connection) | down | `CONN_CLOSE` or EOF, e.g. another client logged in with the same session and `multi killold` | +| no response from server (keepalive) | down | 5 keepalive intervals without any frame | +| timeout | down | a handshake step timed out | +| cannot resolve / cannot connect to server | down | DNS or TCP connect failure | ## Probe tool diff --git a/server/README.md b/server/README.md index 4e6144a..16eacd8 100644 --- a/server/README.md +++ b/server/README.md @@ -36,8 +36,8 @@ VTUND=1 ci/build-musl.sh arm32 # or together with VTesse, OpenIPC toolchain ## Patches -| Patch | What it does | -|---|---| +| Patch | What it does | +|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | [`vtun-3.0.2-denied-log.patch`](patches/vtun-3.0.2-denied-log.patch) | A refused login is logged with the session name the client sent and the reason instead of only `Denied connection from IP:PORT` (#22). | Log lines with `vtun-3.0.2-denied-log.patch`: