diff --git a/Configuration.md b/Configuration.md index 12efd82..c0f71ba 100644 --- a/Configuration.md +++ b/Configuration.md @@ -4,70 +4,110 @@ [Russian / Русский](Configuration_ru) -OSTP (Ospab Stealth Transport Protocol) is configured via a single JSON configuration file, typically named `config.json`. The application detects its execution role (client or server) via the top-level `"mode"` key. +OSTP is configured via a single JSON file (supports `//` comments). The `"mode"` field determines whether it runs as a server or client. + +```bash +# Generate a default config with a random access key: +./ostp --init server # VPS +./ostp --init client # Local machine + +# Validate without running: +./ostp --check +``` --- ## Server Configuration +### Core Settings + | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | required | Must be `"server"` | -| `listen` | string | `"0.0.0.0:50000"` | Local address and UDP port to bind the server to | -| `access_keys` | string[] | required | List of valid secure access keys. The config is monitored for live hot-reloading | -| `turn_server` | string | `null` | Optional STUN/TURN server address to support UDP hole punching / NAT traversal | -| `debug` | bool | `false` | Enable verbose packet-level diagnostic logs | -| `log_level` | string | `"info"` | Logging level: `debug`, `info`, `warn`, `error` | -| `outbound` | object | `null` | Forwarding/routing rules to redirect server traffic to upstream proxies | +| `listen` | string \| string[] | `"0.0.0.0:50000"` | UDP bind address(es). Supports single string or array for multi-listener | +| `access_keys` | string[] | required | Valid access keys. Hot-reloaded every 5 seconds | +| `turn_server` | string | `null` | STUN/TURN server for NAT traversal | +| `debug` | bool | `false` | Verbose packet-level logging | -### Outbound Routing (Server Outbound) +### Management API -By configuring the `outbound` block, the OSTP server can route all or specific parts of the traffic passing through it via an upstream proxy (e.g. SOCKS5, Tor). +| Field | Type | Default | Description | +|---|---|---|---| +| `api.enabled` | bool | `false` | Enable the REST Management API | +| `api.bind` | string | `"127.0.0.1:9090"` | API listen address | +| `api.token` | string | `""` | Bearer token for authentication | + +See **[Management API](Management-API)** for full endpoint reference. + +### Outbound Routing + +Route server traffic through an upstream proxy (SOCKS5, HTTP CONNECT). | Field | Type | Description | |---|---|---| -| `enabled` | bool | Enable/disable server-side upstream proxy routing | -| `protocol` | string | Upstream proxy protocol (e.g., `"socks5"`) | -| `address` | string | IP address or hostname of the upstream proxy | -| `port` | u16 | Port of the upstream proxy | -| `default_action` | string | Default routing action for unmatched requests: `"proxy"` (route everything through the proxy) or `"direct"` (bypass the proxy) | -| `rules` | array | List of routing rule objects | +| `outbound.enabled` | bool | Enable upstream proxy | +| `outbound.protocol` | string | `"socks5"` or `"http"` | +| `outbound.address` | string | Proxy address | +| `outbound.port` | u16 | Proxy port | +| `outbound.default_action` | string | `"proxy"` or `"direct"` | +| `outbound.rules` | array | Routing rules (see below) | -### Outbound Rules - -Each rule object in the `rules` array contains: +#### Routing Rules | Field | Type | Description | |---|---|---| -| `domain_suffix` | string[] | Domains that trigger this rule (e.g., `[".onion"]`) | -| `ip_cidr` | string[] | IP subnets that trigger this rule (e.g., `["10.0.0.0/8"]`) | -| `action` | string | Override action when a match occurs: `"proxy"` or `"direct"` | +| `domain_suffix` | string[] | Domains matching this suffix (e.g., `[".onion"]`) | +| `ip_cidr` | string[] | IP subnets (e.g., `["10.0.0.0/8"]`) | +| `action` | string | `"proxy"` or `"direct"` | -### Full Server Configuration Example +### Fallback Server (Anti-DPI) -```json +Proxy unrecognized TCP connections to a web server, making OSTP look like a regular website during active probing. + +| Field | Type | Default | Description | +|---|---|---|---| +| `fallback.enabled` | bool | `false` | Enable TCP fallback proxy | +| `fallback.listen` | string | `"0.0.0.0:443"` | TCP listen address | +| `fallback.target` | string | `"127.0.0.1:8080"` | Target web server (nginx, caddy) | + +### Full Server Example + +```jsonc { "mode": "server", + // Single address or array: ["0.0.0.0:50000", "[::]:50000"] "listen": "0.0.0.0:50000", "access_keys": [ "c8a6fde902b4e23910cde882b7cf1612" ], - "turn_server": "stun.l.google.com:19302", - "log_level": "info", - "debug": false, - "outbound": { + + // Management REST API + "api": { "enabled": true, + "bind": "127.0.0.1:9090", + "token": "your-secret-token" + }, + + // Upstream proxy routing + "outbound": { + "enabled": false, "protocol": "socks5", "address": "127.0.0.1", "port": 9050, "default_action": "direct", "rules": [ - { - "domain_suffix": [".onion"], - "action": "proxy" - } + { "domain_suffix": [".onion"], "action": "proxy" } ] - } + }, + + // TCP fallback for anti-DPI camouflage + "fallback": { + "enabled": false, + "listen": "0.0.0.0:443", + "target": "127.0.0.1:8080" + }, + + "debug": false } ``` @@ -75,79 +115,93 @@ Each rule object in the `rules` array contains: ## Client Configuration +### Core Settings + | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | required | Must be `"client"` | -| `server` | string | required | Address of the remote OSTP server (`host:port`) | -| `access_key` | string | required | Access key matching one of the keys on the server | -| `socks5_bind` | string | `"127.0.0.1:1088"` | Local HTTP/SOCKS5 inbound proxy address | -| `debug` | bool | `false` | Enable verbose client debugging logs | -| `tun` | object | `null` | Virtual TUN tunnel configurations | -| `exclude` | object | `null` | Bypassing/exclusion lists for local routing | -| `mux` | object | `null` | Session multiplexing settings | +| `server` | string | required | Remote OSTP server (`host:port`) | +| `access_key` | string | required | Access key matching a server key | +| `socks5_bind` | string | `"127.0.0.1:1088"` | Local SOCKS5/HTTP proxy address | +| `debug` | bool | `false` | Verbose client logging | -### TUN Configuration +### TUN Mode (Full-System VPN) | Field | Type | Description | |---|---|---| -| `enable` | bool | Enable full-system virtual TUN mode | -| `wintun_path` | string | Path to custom `wintun.dll` on Windows | -| `ipv4_address` | string | IP address assigned to the virtual network adapter (e.g., `"10.1.0.2/24"`) | -| `dns` | string | Custom DNS server for virtual adapter | +| `tun.enable` | bool | Enable TUN virtual adapter | +| `tun.wintun_path` | string | Path to `wintun.dll` (Windows only) | +| `tun.ipv4_address` | string | IP for the virtual adapter (e.g., `"10.1.0.2/24"`) | +| `tun.dns` | string | DNS server for the tunnel | ### Exclusions | Field | Type | Description | |---|---|---| -| `domains` | string[] | Domain suffixes to bypass (e.g., `"google.com"`) | -| `ips` | string[] | IP addresses or CIDR subnets to bypass (e.g., `"192.168.0.0/16"`) | -| `processes` | string[] | OS process names to bypass in proxy mode (e.g., `"chrome.exe"`) | +| `exclude.domains` | string[] | Domain suffixes to bypass | +| `exclude.ips` | string[] | IP/CIDR subnets to bypass | +| `exclude.processes` | string[] | Process names to bypass (Windows) | ### Multiplexing | Field | Type | Description | |---|---|---| -| `enabled` | bool | Distribute streams across multiple parallel OSTP sessions | -| `sessions` | int | Number of concurrent active OSTP sessions | +| `mux.enabled` | bool | Distribute streams across multiple sessions | +| `mux.sessions` | int | Number of parallel OSTP sessions | + +### TURN Relay + +| Field | Type | Description | +|---|---|---| +| `turn.enabled` | bool | Enable TURN relay | +| `turn.server_addr` | string | TURN server address | +| `turn.username` | string | TURN username | +| `turn.access_key` | string | TURN password | ### Full Client Example -```json +```jsonc { "mode": "client", "server": "example.com:50000", "access_key": "c8a6fde902b4e23910cde882b7cf1612", "socks5_bind": "127.0.0.1:1088", - "debug": false, + "tun": { "enable": true, - "wintun_path": "./wintun.dll", - "ipv4_address": "10.1.0.2/24", "dns": "1.1.1.1" }, + "exclude": { - "domains": ["bank.com", "local.network"], - "ips": ["192.168.0.0/16", "10.0.0.0/8"], + "domains": ["bank.com"], + "ips": ["192.168.0.0/16"], "processes": ["steam.exe"] }, + "mux": { "enabled": false, - "sessions": 1 - } + "sessions": 2 + }, + + "turn": { + "enabled": false, + "server_addr": "turn.example.com:3478", + "username": "user", + "access_key": "pass" + }, + + "debug": false } ``` -### TURN Relay (Optional Client-Side) +--- -For clients operating behind highly restrictive firewalls blocking direct UDP: +## Environment Variables -| Field | Type | Description | -|---|---|---| -| `turn.enabled` | bool | Enable client-side TURN relay wrapper | -| `turn.server_addr` | string | TURN relay server IP/Host and port | -| `turn.username` | string | Authentication username for TURN | -| `turn.access_key` | string | Authentication key/password for TURN | +| Variable | Description | +|---|---| +| `RUST_LOG` | Logging filter (e.g., `RUST_LOG=ostp_server=debug`) | --- -[← Installation](Installation) | [Protocol Design →](Protocol-Design) +[← Installation](Installation) | [Management API →](Management-API) diff --git a/Configuration_ru.md b/Configuration_ru.md index 079e372..d1dc292 100644 --- a/Configuration_ru.md +++ b/Configuration_ru.md @@ -2,152 +2,206 @@ ![GitHub Release](https://img.shields.io/github/v/release/ospab/ostp?style=flat-square&color=blue) -[English / Английский](Configuration) | [← Главная](Home_ru) +[English version](Configuration) -OSTP (Ospab Stealth Transport Protocol) настраивается с помощью одного конфигурационного файла JSON, обычно имеющего имя `config.json`. Приложение определяет свою роль исполнения (клиент или сервер) по значению ключа `"mode"`. +OSTP настраивается через единый JSON-файл (поддерживает `//` комментарии). Поле `"mode"` определяет режим работы — сервер или клиент. + +```bash +# Генерация конфига с случайным ключом доступа: +./ostp --init server # VPS +./ostp --init client # Локальная машина + +# Проверка конфига без запуска: +./ostp --check +``` --- -## Серверная конфигурация +## Конфигурация сервера + +### Основные настройки | Поле | Тип | По умолчанию | Описание | |---|---|---|---| | `mode` | string | обязательно | Должно быть `"server"` | -| `listen` | string | `"0.0.0.0:50000"` | Локальный адрес и UDP-порт прослушивания | -| `access_keys` | string[] | обязательно | Список ключей доступа для клиентов. Файл отслеживается для автоматического горячего обновления на лету | -| `turn_server` | string | `null` | Опциональный адрес STUN/TURN-сервера для обхода ограничений NAT и UDP-блокировок | -| `debug` | bool | `false` | Включить подробное диагностическое логирование на уровне пакетов | -| `log_level` | string | `"info"` | Уровень логирования: `debug`, `info`, `warn`, `error` | -| `outbound` | object | `null` | Правила перенаправления исходящего трафика сервера через вышестоящие прокси | +| `listen` | string \| string[] | `"0.0.0.0:50000"` | UDP-адрес(а) для привязки. Поддерживает строку или массив для multi-listener | +| `access_keys` | string[] | обязательно | Валидные ключи доступа. Автоматически перезагружаются каждые 5 секунд | +| `turn_server` | string | `null` | STUN/TURN-сервер для NAT traversal | +| `debug` | bool | `false` | Подробное логирование на уровне пакетов | -### Исходящая маршрутизация (Server Outbound) +### API управления -С помощью блока `outbound` сервер OSTP может перенаправлять весь или определённый трафик клиентов через вышестоящие прокси (например, SOCKS5 или Tor). +| Поле | Тип | По умолчанию | Описание | +|---|---|---|---| +| `api.enabled` | bool | `false` | Включить REST API управления | +| `api.bind` | string | `"127.0.0.1:9090"` | Адрес для API | +| `api.token` | string | `""` | Bearer-токен для аутентификации | + +Полный справочник: **[API управления](Management-API_ru)**. + +### Маршрутизация исходящего трафика + +Направление серверного трафика через вышестоящий прокси (SOCKS5, HTTP CONNECT). | Поле | Тип | Описание | |---|---|---| -| `enabled` | bool | Включить/выключить проксирование исходящего трафика сервера | -| `protocol` | string | Протокол прокси-сервера (например, `"socks5"`) | -| `address` | string | IP-адрес или хост вышестоящего прокси | -| `port` | u16 | Порт вышестоящего прокси | -| `default_action` | string | Действие по умолчанию для несовпадающих запросов: `"proxy"` (направлять все через прокси) или `"direct"` (направлять напрямую) | -| `rules` | array | Список правил маршрутизации | +| `outbound.enabled` | bool | Включить вышестоящий прокси | +| `outbound.protocol` | string | `"socks5"` или `"http"` | +| `outbound.address` | string | Адрес прокси | +| `outbound.port` | u16 | Порт прокси | +| `outbound.default_action` | string | `"proxy"` или `"direct"` | +| `outbound.rules` | array | Правила маршрутизации (см. ниже) | -### Исходящие правила (Outbound Rules) - -Каждое правило в массиве `rules` содержит следующие параметры: +#### Правила маршрутизации | Поле | Тип | Описание | |---|---|---| -| `domain_suffix` | string[] | Доменные суффиксы для срабатывания правила (например, `[".onion"]`) | -| `ip_cidr` | string[] | Подсети IP для срабатывания правила (например, `["10.0.0.0/8"]`) | -| `action` | string | Переопределение действия при совпадении: `"proxy"` или `"direct"` | +| `domain_suffix` | string[] | Домены, срабатывающие на правило (напр. `[".onion"]`) | +| `ip_cidr` | string[] | IP-подсети (напр. `["10.0.0.0/8"]`) | +| `action` | string | `"proxy"` или `"direct"` | -### Полный пример серверного конфига +### Fallback-сервер (анти-DPI) -```json +Проксирование нераспознанных TCP-соединений на веб-сервер, что делает OSTP неотличимым от обычного сайта при активном зондировании. + +| Поле | Тип | По умолчанию | Описание | +|---|---|---|---| +| `fallback.enabled` | bool | `false` | Включить TCP fallback proxy | +| `fallback.listen` | string | `"0.0.0.0:443"` | TCP-адрес для прослушивания | +| `fallback.target` | string | `"127.0.0.1:8080"` | Целевой веб-сервер (nginx, caddy) | + +### Полный пример сервера + +```jsonc { "mode": "server", + // Один адрес или массив: ["0.0.0.0:50000", "[::]:50000"] "listen": "0.0.0.0:50000", "access_keys": [ "c8a6fde902b4e23910cde882b7cf1612" ], - "turn_server": "stun.l.google.com:19302", - "log_level": "info", - "debug": false, - "outbound": { + + // REST API управления + "api": { "enabled": true, + "bind": "127.0.0.1:9090", + "token": "ваш-секретный-токен" + }, + + // Маршрутизация через вышестоящий прокси + "outbound": { + "enabled": false, "protocol": "socks5", "address": "127.0.0.1", "port": 9050, "default_action": "direct", "rules": [ - { - "domain_suffix": [".onion"], - "action": "proxy" - } + { "domain_suffix": [".onion"], "action": "proxy" } ] - } + }, + + // TCP fallback для камуфляжа от DPI + "fallback": { + "enabled": false, + "listen": "0.0.0.0:443", + "target": "127.0.0.1:8080" + }, + + "debug": false } ``` --- -## Клиентская конфигурация +## Конфигурация клиента + +### Основные настройки | Поле | Тип | По умолчанию | Описание | |---|---|---|---| | `mode` | string | обязательно | Должно быть `"client"` | -| `server` | string | обязательно | Адрес удалённого сервера OSTP (`host:port`) | -| `access_key` | string | обязательно | Ключ доступа, соответствующий одному из ключей на сервере | -| `socks5_bind` | string | `"127.0.0.1:1088"` | Локальный адрес входящего HTTP/SOCKS5 прокси | -| `debug` | bool | `false` | Включить подробное клиентское логирование | -| `tun` | object | `null` | Настройки виртуального туннеля TUN | -| `exclude` | object | `null` | Списки исключений трафика из туннеля | -| `mux` | object | `null` | Настройки мультиплексирования | +| `server` | string | обязательно | Адрес удалённого OSTP-сервера (`host:port`) | +| `access_key` | string | обязательно | Ключ доступа, совпадающий с ключом на сервере | +| `socks5_bind` | string | `"127.0.0.1:1088"` | Локальный адрес SOCKS5/HTTP прокси | +| `debug` | bool | `false` | Подробное логирование клиента | -### TUN-туннель +### TUN-режим (полносистемный VPN) | Поле | Тип | Описание | |---|---|---| -| `enable` | bool | Включить режим виртуальной сетевой карты TUN | -| `wintun_path` | string | Путь к файлу `wintun.dll` в Windows | -| `ipv4_address` | string | IP-адрес, назначаемый виртуальному адаптеру (например, `"10.1.0.2/24"`) | -| `dns` | string | Выделенный DNS-сервер для туннельного интерфейса | +| `tun.enable` | bool | Включить виртуальный TUN-адаптер | +| `tun.wintun_path` | string | Путь к `wintun.dll` (только Windows) | +| `tun.ipv4_address` | string | IP виртуального адаптера (напр. `"10.1.0.2/24"`) | +| `tun.dns` | string | DNS-сервер для туннеля | ### Исключения | Поле | Тип | Описание | |---|---|---| -| `domains` | string[] | Доменные суффиксы для обхода туннеля (например, `"google.com"`) | -| `ips` | string[] | IP-адреса или CIDR подсети для обхода (например, `"192.168.0.0/16"`) | -| `processes` | string[] | Имена процессов в ОС для обхода в режиме прокси (например, `"chrome.exe"`) | +| `exclude.domains` | string[] | Суффиксы доменов для обхода | +| `exclude.ips` | string[] | IP/CIDR-подсети для обхода | +| `exclude.processes` | string[] | Имена процессов для обхода (Windows) | ### Мультиплексирование | Поле | Тип | Описание | |---|---|---| -| `enabled` | bool | Распределять сетевые потоки между несколькими параллельными OSTP-сессиями | -| `sessions` | int | Количество одновременно активных OSTP-сессий | +| `mux.enabled` | bool | Распределение потоков по нескольким сессиям | +| `mux.sessions` | int | Количество параллельных OSTP-сессий | -### Полный пример клиентского конфига +### TURN-релей -```json +| Поле | Тип | Описание | +|---|---|---| +| `turn.enabled` | bool | Включить TURN-релей | +| `turn.server_addr` | string | Адрес TURN-сервера | +| `turn.username` | string | Имя пользователя TURN | +| `turn.access_key` | string | Пароль TURN | + +### Полный пример клиента + +```jsonc { "mode": "client", "server": "example.com:50000", "access_key": "c8a6fde902b4e23910cde882b7cf1612", "socks5_bind": "127.0.0.1:1088", - "debug": false, + "tun": { "enable": true, - "wintun_path": "./wintun.dll", - "ipv4_address": "10.1.0.2/24", "dns": "1.1.1.1" }, + "exclude": { - "domains": ["bank.ru", "local.network"], - "ips": ["192.168.0.0/16", "10.0.0.0/8"], + "domains": ["bank.com"], + "ips": ["192.168.0.0/16"], "processes": ["steam.exe"] }, + "mux": { "enabled": false, - "sessions": 1 - } + "sessions": 2 + }, + + "turn": { + "enabled": false, + "server_addr": "turn.example.com:3478", + "username": "user", + "access_key": "pass" + }, + + "debug": false } ``` -### TURN-реле (Опционально на стороне клиента) +--- -Для клиентов, находящихся за строгими брандмауэрами, блокирующими прямой UDP-трафик: +## Переменные окружения -| Поле | Тип | Описание | -|---|---|---| -| `turn.enabled` | bool | Включить проксирование через TURN-сервер | -| `turn.server_addr` | string | Адрес и порт TURN-сервера | -| `turn.username` | string | Логин для авторизации на TURN | -| `turn.access_key` | string | Пароль/ключ доступа для TURN | +| Переменная | Описание | +|---|---| +| `RUST_LOG` | Фильтр логирования (напр. `RUST_LOG=ostp_server=debug`) | --- -[← Установка](Installation_ru) | [Протокол →](Protocol-Design_ru) +[← Установка](Installation_ru) | [API управления →](Management-API_ru) diff --git a/Home.md b/Home.md index f044340..307ae5d 100644 --- a/Home.md +++ b/Home.md @@ -5,38 +5,85 @@ ![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20Android-green.svg?style=flat-square) ![Build](https://img.shields.io/github/actions/workflow/status/ospab/ostp/release.yml?style=flat-square&label=CI%2FCD) ![Crypto](https://img.shields.io/badge/Crypto-Noise__NNpsk0-blueviolet?style=flat-square) -![Transport](https://img.shields.io/badge/Transport-UDP-informational?style=flat-square) +![Transport](https://img.shields.io/badge/Transport-UDP%20ARQ-informational?style=flat-square) -Welcome to the OSTP Wiki. | [Russian version / Русская версия](Home_ru) +Welcome to the **OSTP Wiki** — the official documentation for the Ospab Stealth Transport Protocol. -## Quick Navigation +[Русская версия / Russian version](Home_ru) + +--- + +## Documentation | Page | Description | |---|---| -| [Installation](Installation) | Server & client setup guide | -| [Configuration](Configuration) | Full configuration reference | -| [Protocol Design](Protocol-Design) | Wire format, cryptography, DPI resistance | -| [GUI Client](GUI-Client) | Windows desktop application guide | -| [Share Links](Share-Links) | `ostp://` URI format reference | -| [Building from Source](Building-from-Source) | Compilation guide for all platforms | +| [Installation](Installation) | Server & client setup — one-line install scripts | +| [Configuration](Configuration) | Full configuration reference for server & client | +| [Management API](Management-API) | REST API for panels, dashboards, and automation | +| [Protocol Design](Protocol-Design) | Wire format, cryptography, obfuscation, DPI resistance | +| [Share Links](Share-Links) | `ostp://` URI format for one-click connection | +| [GUI Client](GUI-Client) | Windows/macOS desktop application | +| [Building from Source](Building-from-Source) | Compilation guide for 14+ targets | | [FAQ](FAQ) | Frequently asked questions | +--- + ## What is OSTP? -**Ospab Stealth Transport Protocol** is a UDP-based encrypted tunneling protocol designed for maximum DPI/TSPU resistance. Every byte on the wire is cryptographically indistinguishable from random noise. +**Ospab Stealth Transport Protocol** is a UDP-based encrypted tunneling protocol designed for maximum resistance to DPI, TSPU, and active probing. Every byte on the wire is cryptographically indistinguishable from random noise. -### Key Features +### Core Features -| Feature | Description | +| Feature | Details | |---|---| -| **Full Obfuscation** | Kerckhoffs's principle — security depends solely on the key | -| **Noise_NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — Forward Secrecy | -| **Reliable UDP (ARQ)** | Selective ACK, retransmission, reorder buffer | -| **Multiplexing** | Multiple TCP streams over a single UDP session | +| **Full Obfuscation** | Headers, payloads, and metadata — all encrypted. Kerckhoffs's principle. | +| **Noise NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — forward secrecy, no PKI required | +| **Reliable UDP** | Selective ACK, NACK, gap recovery, configurable reorder buffer | +| **Congestion Control** | BBR-inspired adaptive window with bandwidth/RTT estimation | +| **Multiplexing** | Multiple TCP streams over a single encrypted UDP session | +| **Seamless Roaming** | WiFi to LTE without session drop — tracked by session ID, not IP | +| **Management API** | REST API with per-user traffic stats, limits, and key management | +| **Fallback Server** | TCP proxy to nginx/caddy — looks like a regular website to DPI | +| **Multi-Listener** | Bind to multiple addresses/ports simultaneously | +| **Structured Logging** | `tracing` with `RUST_LOG` filtering — debug/info/warn/error | | **Cross-Platform** | Windows, Linux, macOS, Android, FreeBSD, MIPS, RISC-V | -| **TUN Mode** | Full VPN via virtual network adapter | -| **Seamless Roaming** | Network switch without session interruption | -### Releases +--- -Download the latest release: [GitHub Releases](https://github.com/ospab/ostp/releases) +## Quick Install + +### Linux +```bash +bash <(curl -Ls https://raw.githubusercontent.com/ospab/ostp/master/scripts/install.sh) +``` + +### Windows (PowerShell, Administrator) +```powershell +irm https://raw.githubusercontent.com/ospab/ostp/master/scripts/install.ps1 | iex +``` + +### Manual +Download from **[GitHub Releases](https://github.com/ospab/ostp/releases)**. + +--- + +## Comparison + +| Capability | sing-box | xray-core | Hysteria2 | **OSTP** | +|---|---|---|---|---| +| Management API | Yes | Yes (gRPC) | Yes | Yes (REST) | +| Per-user traffic stats | Yes | Yes | Yes | Yes | +| Traffic limits | Yes | Yes | Yes | Yes | +| Congestion control | BBR | N/A | Brutal/BBR | BBR-inspired | +| Fallback web server | Yes | Yes | Yes | Yes | +| Structured logging | Yes | Yes | Yes | Yes | +| Config validation CLI | Yes | Yes | — | Yes | +| Full traffic obfuscation | Partial | Partial | — | Yes | +| Native DPI resistance | — | — | — | Yes | + +--- + +## License + +Business Source License 1.1 — free for personal and non-commercial use. +Automatically converts to MIT License on May 14, 2030. diff --git a/Home_ru.md b/Home_ru.md index e12c705..e8c4368 100644 --- a/Home_ru.md +++ b/Home_ru.md @@ -5,38 +5,109 @@ ![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20Android-green.svg?style=flat-square) ![Build](https://img.shields.io/github/actions/workflow/status/ospab/ostp/release.yml?style=flat-square&label=CI%2FCD) ![Crypto](https://img.shields.io/badge/Crypto-Noise__NNpsk0-blueviolet?style=flat-square) -![Transport](https://img.shields.io/badge/Transport-UDP-informational?style=flat-square) +![Transport](https://img.shields.io/badge/Transport-UDP%20ARQ-informational?style=flat-square) -Добро пожаловать в Wiki проекта OSTP. | [English version / Английская версия](Home) +Добро пожаловать в **OSTP Wiki** — официальную документацию протокола Ospab Stealth Transport Protocol. -## Навигация +[English version](Home) + +--- + +## Документация | Страница | Описание | |---|---| -| [Установка](Installation_ru) | Развёртывание сервера и клиента | -| [Конфигурация](Configuration_ru) | Полный справочник config.json | -| [Протокол](Protocol-Design_ru) | Wire-формат, криптография, защита от DPI | -| [GUI-клиент](GUI-Client_ru) | Приложение для Windows | -| [Ссылки-приглашения](Share-Links_ru) | Формат `ostp://` URI | -| [Сборка](Building-from-Source_ru) | Компиляция из исходников | +| [Установка](Installation_ru) | Настройка сервера и клиента — установка в одну строку | +| [Конфигурация](Configuration_ru) | Полный справочник конфигурации сервера и клиента | +| [API управления](Management-API_ru) | REST API для панелей, дашбордов и автоматизации | +| [Протокол](Protocol-Design_ru) | Wire format, криптография, обфускация, DPI-устойчивость | +| [Ссылки-приглашения](Share-Links_ru) | Формат URI `ostp://` для подключения в один клик | +| [GUI-клиент](GUI-Client_ru) | Десктопное приложение для Windows/macOS | +| [Сборка](Building-from-Source_ru) | Компиляция для 14+ целевых платформ | | [FAQ](FAQ_ru) | Часто задаваемые вопросы | +--- + ## Что такое OSTP? -**Ospab Stealth Transport Protocol** — UDP-протокол зашифрованного туннелирования, разработанный для максимальной устойчивости к DPI и ТСПУ. Каждый байт на проводе криптографически неотличим от случайного шума. +**Ospab Stealth Transport Protocol** — протокол туннелирования на основе UDP, спроектированный для максимальной устойчивости к DPI, ТСПУ и активному зондированию. Каждый байт на проводе криптографически неотличим от случайного шума. -### Ключевые особенности +### Ключевые возможности -| Возможность | Описание | +| Возможность | Детали | |---|---| -| **Полная обфускация** | Принцип Керкгоффса — безопасность зависит только от ключа | -| **Noise_NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — Forward Secrecy | -| **Надёжный UDP (ARQ)** | Selective ACK, ретрансмиссия, буфер переупорядочивания | -| **Мультиплексирование** | Множество TCP-потоков в одной UDP-сессии | -| **Кросс-платформа** | Windows, Linux, macOS, Android, FreeBSD, MIPS, RISC-V | -| **TUN-режим** | Полный VPN через виртуальный сетевой адаптер | -| **Бесшовный роуминг** | Смена сети без разрыва сессии | +| **Полная обфускация** | Заголовки, данные и метаданные — всё зашифровано. Принцип Керкгоффса. | +| **Noise NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — forward secrecy, без PKI | +| **Надёжный UDP** | Selective ACK, NACK, восстановление пропусков, настраиваемый буфер реордеринга | +| **Congestion Control** | BBR-подобное адаптивное окно с оценкой bandwidth и RTT | +| **Мультиплексирование** | Несколько TCP-потоков в одной зашифрованной UDP-сессии | +| **Бесшовный роуминг** | WiFi в LTE без разрыва сессии — отслеживание по session ID, а не IP | +| **API управления** | REST API с per-user статистикой, лимитами и управлением ключами | +| **Fallback-сервер** | TCP-прокси на nginx/caddy — выглядит как обычный сайт для DPI | +| **Multi-Listener** | Привязка к нескольким адресам/портам одновременно | +| **Структурное логирование** | `tracing` с `RUST_LOG` фильтрацией — debug/info/warn/error | +| **Кроссплатформенность** | Windows, Linux, macOS, Android, FreeBSD, MIPS, RISC-V | -### Скачать +--- -Последний релиз: [GitHub Releases](https://github.com/ospab/ostp/releases) +## Быстрая установка + +### Linux +```bash +bash <(curl -Ls https://raw.githubusercontent.com/ospab/ostp/master/scripts/install.sh) +``` + +### Windows (PowerShell, от имени Администратора) +```powershell +irm https://raw.githubusercontent.com/ospab/ostp/master/scripts/install.ps1 | iex +``` + +### Вручную +Скачайте с **[GitHub Releases](https://github.com/ospab/ostp/releases)**. + +--- + +## Быстрый старт + +```bash +# Генерация конфига сервера +./ostp --init server + +# Генерация конфига клиента +./ostp --init client + +# Проверка конфига +./ostp --check + +# Запуск +./ostp + +# Подключение по ссылке +./ostp ostp://ACCESS_KEY@server.com:50000 + +# Генерация ключей +./ostp --generate-key -c 5 +``` + +--- + +## Сравнение + +| Возможность | sing-box | xray-core | Hysteria2 | **OSTP** | +|---|---|---|---|---| +| API управления | Да | Да (gRPC) | Да | Да (REST) | +| Per-user статистика | Да | Да | Да | Да | +| Лимиты трафика | Да | Да | Да | Да | +| Congestion control | BBR | N/A | Brutal/BBR | BBR-inspired | +| Fallback веб-сервер | Да | Да | Да | Да | +| Структурное логирование | Да | Да | Да | Да | +| CLI валидация конфига | Да | Да | — | Да | +| Полная обфускация трафика | Частично | Частично | — | Да | +| Нативная DPI-устойчивость | — | — | — | Да | + +--- + +## Лицензия + +Business Source License 1.1 — бесплатно для личного и некоммерческого использования. +Автоматически конвертируется в MIT License 14 мая 2030 года. diff --git a/Management-API.md b/Management-API.md new file mode 100644 index 0000000..ac06997 --- /dev/null +++ b/Management-API.md @@ -0,0 +1,241 @@ +# Management API + +[Russian / Русский](Management-API_ru) + +OSTP includes a built-in REST API for remote server management. This API enables third-party panels (like 3x-ui), Telegram bots, and custom dashboards to manage users, monitor traffic, and control the server. + +--- + +## Enabling the API + +Add the `api` block to your server `config.json`: + +```jsonc +{ + "mode": "server", + "listen": "0.0.0.0:50000", + "access_keys": ["..."], + "api": { + "enabled": true, + "bind": "127.0.0.1:9090", + "token": "your-secret-api-token" + } +} +``` + +| Field | Type | Default | Description | +|---|---|---|---| +| `enabled` | bool | `false` | Enable/disable the API server | +| `bind` | string | `"127.0.0.1:9090"` | Address and port for the API to listen on | +| `token` | string | `""` | Bearer token for authentication. **Required for production.** | + +> ⚠️ **Security**: Always set a strong `token` in production. If empty, the API assumes a trusted local environment. + +> 💡 **Tip**: Bind to `127.0.0.1` and use a reverse proxy (nginx/caddy) with TLS for remote access. + +--- + +## Authentication + +All requests require the `Authorization` header: + +``` +Authorization: Bearer your-secret-api-token +``` + +Requests without a valid token receive `401 Unauthorized`. + +--- + +## Endpoints + +### Server Status + +``` +GET /api/server/status +``` + +Returns server version, uptime, and user count. + +**Response:** +```json +{ + "version": "0.1.70", + "uptime_seconds": 3600, + "total_users": 5, + "status": "running" +} +``` + +--- + +### List Users + +``` +GET /api/users +``` + +Returns all users with traffic statistics. + +**Response:** +```json +{ + "users": [ + { + "key": "c8a6fde902b4e23910cde882b7cf1612", + "bytes_up": 1048576, + "bytes_down": 52428800, + "connections": 3, + "limit_bytes": 10737418240 + } + ] +} +``` + +--- + +### Get User Stats + +``` +GET /api/users/{key} +``` + +Returns statistics for a specific user. + +--- + +### Create User + +``` +POST /api/users +``` + +**Request body (optional):** +```json +{ + "key": "custom-key-or-leave-empty-for-auto", + "limit_bytes": 10737418240 +} +``` + +If `key` is omitted, a secure random key is generated automatically. + +**Response:** +```json +{ + "key": "a1b2c3d4e5f6...", + "created": true +} +``` + +--- + +### Delete User + +``` +DELETE /api/users/{key} +``` + +Removes the user and their access key. + +--- + +### Set Traffic Limit + +``` +PUT /api/users/{key}/limit +``` + +**Request body:** +```json +{ + "limit_bytes": 5368709120 +} +``` + +Set to `null` to remove the limit. + +--- + +### Reset Traffic Counters + +``` +POST /api/users/{key}/reset +``` + +Resets `bytes_up`, `bytes_down`, and `connections` to zero. + +--- + +## Examples + +### cURL + +```bash +# Server status +curl -s -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/server/status | jq + +# List all users +curl -s -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/users | jq + +# Create user with 10 GB limit +curl -s -X POST \ + -H "Authorization: Bearer mytoken" \ + -H "Content-Type: application/json" \ + -d '{"limit_bytes": 10737418240}' \ + http://127.0.0.1:9090/api/users | jq + +# Delete user +curl -s -X DELETE \ + -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/users/c8a6fde902b4e23910cde882b7cf1612 + +# Set 5 GB limit +curl -s -X PUT \ + -H "Authorization: Bearer mytoken" \ + -H "Content-Type: application/json" \ + -d '{"limit_bytes": 5368709120}' \ + http://127.0.0.1:9090/api/users/c8a6fde902b4e23910cde882b7cf1612/limit + +# Reset counters +curl -s -X POST \ + -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/users/c8a6fde902b4e23910cde882b7cf1612/reset +``` + +### Python + +```python +import requests + +API = "http://127.0.0.1:9090" +TOKEN = "your-secret-api-token" +HEADERS = {"Authorization": f"Bearer {TOKEN}"} + +# List users +users = requests.get(f"{API}/api/users", headers=HEADERS).json() +for user in users["users"]: + print(f"Key: {user['key'][:8]}... | ↑{user['bytes_up']} ↓{user['bytes_down']}") + +# Create user +resp = requests.post(f"{API}/api/users", headers=HEADERS, + json={"limit_bytes": 10 * 1024**3}) +print(f"New key: {resp.json()['key']}") +``` + +--- + +## Integration with Panels + +The API is designed to be compatible with panel architectures like **3x-ui** and **RemnaWave**. A panel integration typically: + +1. Calls `POST /api/users` to create access keys for new subscribers +2. Periodically polls `GET /api/users` for traffic consumption +3. Uses `PUT /api/users/{key}/limit` to enforce data caps +4. Calls `DELETE /api/users/{key}` when a subscription expires + +--- + +[← Configuration](Configuration) | [Protocol Design →](Protocol-Design) diff --git a/Management-API_ru.md b/Management-API_ru.md new file mode 100644 index 0000000..3d9d48d --- /dev/null +++ b/Management-API_ru.md @@ -0,0 +1,241 @@ +# API управления + +[English version](Management-API) + +OSTP включает встроенный REST API для удалённого управления сервером. Этот API позволяет сторонним панелям (3x-ui, RemnaWave), Telegram-ботам и пользовательским дашбордам управлять пользователями, отслеживать трафик и контролировать сервер. + +--- + +## Включение API + +Добавьте блок `api` в серверный `config.json`: + +```jsonc +{ + "mode": "server", + "listen": "0.0.0.0:50000", + "access_keys": ["..."], + "api": { + "enabled": true, + "bind": "127.0.0.1:9090", + "token": "ваш-секретный-токен" + } +} +``` + +| Поле | Тип | По умолчанию | Описание | +|---|---|---|---| +| `enabled` | bool | `false` | Включить/выключить API-сервер | +| `bind` | string | `"127.0.0.1:9090"` | Адрес и порт для API | +| `token` | string | `""` | Bearer-токен для аутентификации. **Обязателен для продакшена.** | + +> **Безопасность**: всегда устанавливайте надёжный `token` в продакшене. Если пустой, API считает окружение доверенным. + +> **Совет**: привяжите к `127.0.0.1` и используйте реверс-прокси (nginx/caddy) с TLS для удалённого доступа. + +--- + +## Аутентификация + +Все запросы требуют заголовок `Authorization`: + +``` +Authorization: Bearer ваш-секретный-токен +``` + +Запросы без валидного токена получают `401 Unauthorized`. + +--- + +## Эндпоинты + +### Статус сервера + +``` +GET /api/server/status +``` + +Возвращает версию сервера, аптайм и количество пользователей. + +**Ответ:** +```json +{ + "version": "0.1.70", + "uptime_seconds": 3600, + "total_users": 5, + "status": "running" +} +``` + +--- + +### Список пользователей + +``` +GET /api/users +``` + +Возвращает всех пользователей со статистикой трафика. + +**Ответ:** +```json +{ + "users": [ + { + "key": "c8a6fde902b4e23910cde882b7cf1612", + "bytes_up": 1048576, + "bytes_down": 52428800, + "connections": 3, + "limit_bytes": 10737418240 + } + ] +} +``` + +--- + +### Статистика пользователя + +``` +GET /api/users/{key} +``` + +Возвращает статистику конкретного пользователя. + +--- + +### Создание пользователя + +``` +POST /api/users +``` + +**Тело запроса (опционально):** +```json +{ + "key": "свой-ключ-или-оставьте-пустым", + "limit_bytes": 10737418240 +} +``` + +Если `key` не указан, генерируется случайный ключ. + +**Ответ:** +```json +{ + "key": "a1b2c3d4e5f6...", + "created": true +} +``` + +--- + +### Удаление пользователя + +``` +DELETE /api/users/{key} +``` + +Удаляет пользователя и его ключ доступа. + +--- + +### Установка лимита трафика + +``` +PUT /api/users/{key}/limit +``` + +**Тело запроса:** +```json +{ + "limit_bytes": 5368709120 +} +``` + +Установите `null` для снятия лимита. + +--- + +### Сброс счётчиков + +``` +POST /api/users/{key}/reset +``` + +Обнуляет `bytes_up`, `bytes_down` и `connections`. + +--- + +## Примеры + +### cURL + +```bash +# Статус сервера +curl -s -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/server/status | jq + +# Список пользователей +curl -s -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/users | jq + +# Создать пользователя с лимитом 10 ГБ +curl -s -X POST \ + -H "Authorization: Bearer mytoken" \ + -H "Content-Type: application/json" \ + -d '{"limit_bytes": 10737418240}' \ + http://127.0.0.1:9090/api/users | jq + +# Удалить пользователя +curl -s -X DELETE \ + -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/users/c8a6fde902b4e23910cde882b7cf1612 + +# Установить лимит 5 ГБ +curl -s -X PUT \ + -H "Authorization: Bearer mytoken" \ + -H "Content-Type: application/json" \ + -d '{"limit_bytes": 5368709120}' \ + http://127.0.0.1:9090/api/users/c8a6fde902b4e23910cde882b7cf1612/limit + +# Сброс счётчиков +curl -s -X POST \ + -H "Authorization: Bearer mytoken" \ + http://127.0.0.1:9090/api/users/c8a6fde902b4e23910cde882b7cf1612/reset +``` + +### Python + +```python +import requests + +API = "http://127.0.0.1:9090" +TOKEN = "ваш-секретный-токен" +HEADERS = {"Authorization": f"Bearer {TOKEN}"} + +# Список пользователей +users = requests.get(f"{API}/api/users", headers=HEADERS).json() +for user in users["users"]: + print(f"Ключ: {user['key'][:8]}... | Вх.{user['bytes_up']} Исх.{user['bytes_down']}") + +# Создать пользователя +resp = requests.post(f"{API}/api/users", headers=HEADERS, + json={"limit_bytes": 10 * 1024**3}) +print(f"Новый ключ: {resp.json()['key']}") +``` + +--- + +## Интеграция с панелями + +API спроектирован для совместимости с архитектурой панелей типа **3x-ui** и **RemnaWave**. Типичная интеграция: + +1. Вызывает `POST /api/users` для создания ключей новым подписчикам +2. Периодически опрашивает `GET /api/users` для мониторинга потребления трафика +3. Использует `PUT /api/users/{key}/limit` для установки квот +4. Вызывает `DELETE /api/users/{key}` при истечении подписки + +--- + +[← Конфигурация](Configuration_ru) | [Протокол →](Protocol-Design_ru) diff --git a/_Sidebar.md b/_Sidebar.md index ea755f5..b4ce001 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,19 +1,25 @@ **OSTP Wiki** +--- + **English** - [Home](Home) - [Installation](Installation) - [Configuration](Configuration) +- [Management API](Management-API) - [Protocol Design](Protocol-Design) - [Share Links](Share-Links) - [GUI Client](GUI-Client) - [Building from Source](Building-from-Source) - [FAQ](FAQ) +--- + **Русский** - [Главная](Home_ru) - [Установка](Installation_ru) - [Конфигурация](Configuration_ru) +- [API управления](Management-API_ru) - [Протокол](Protocol-Design_ru) - [Ссылки-приглашения](Share-Links_ru) - [GUI-клиент](GUI-Client_ru)