ospab
/
ostp
mirror of https://github.com/ospab/ostp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: update wiki for v0.2.0 — Management API (EN+RU), updated Home, Configuration, Sidebar

ospab 2026-05-17 21:06:49 +03:00
parent b5ab15bb8f
commit cd3d7d8dae
7 changed files with 891 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
Configuration.md

@ -4,70 +4,110 @@
[Russian / Русский](Configuration_ru) [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 ## Server Configuration
### Core Settings
| Field | Type | Default | Description | | Field | Type | Default | Description |
|---|---|---|---| |---|---|---|---|
| `mode` | string | required | Must be `"server"` | | `mode` | string | required | Must be `"server"` |
| `listen` | string | `"0.0.0.0:50000"` | Local address and UDP port to bind the server to | | `listen` | string \| string[] | `"0.0.0.0:50000"` | UDP bind address(es). Supports single string or array for multi-listener |
| `access_keys` | string[] | required | List of valid secure access keys. The config is monitored for live hot-reloading | | `access_keys` | string[] | required | Valid access keys. Hot-reloaded every 5 seconds |
| `turn_server` | string | `null` | Optional STUN/TURN server address to support UDP hole punching / NAT traversal | | `turn_server` | string | `null` | STUN/TURN server for NAT traversal |
| `debug` | bool | `false` | Enable verbose packet-level diagnostic logs | | `debug` | bool | `false` | Verbose packet-level logging |
| `log_level` | string | `"info"` | Logging level: `debug`, `info`, `warn`, `error` |
| `outbound` | object | `null` | Forwarding/routing rules to redirect server traffic to upstream proxies |
### 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 | | Field | Type | Description |
|---|---|---| |---|---|---|
| `enabled` | bool | Enable/disable server-side upstream proxy routing | | `outbound.enabled` | bool | Enable upstream proxy |
| `protocol` | string | Upstream proxy protocol (e.g., `"socks5"`) | | `outbound.protocol` | string | `"socks5"` or `"http"` |
| `address` | string | IP address or hostname of the upstream proxy | | `outbound.address` | string | Proxy address |
| `port` | u16 | Port of the upstream proxy | | `outbound.port` | u16 | Proxy port |
| `default_action` | string | Default routing action for unmatched requests: `"proxy"` (route everything through the proxy) or `"direct"` (bypass the proxy) | | `outbound.default_action` | string | `"proxy"` or `"direct"` |
| `rules` | array | List of routing rule objects | | `outbound.rules` | array | Routing rules (see below) |
### Outbound Rules #### Routing Rules
Each rule object in the `rules` array contains:
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `domain_suffix` | string[] | Domains that trigger this rule (e.g., `[".onion"]`) | | `domain_suffix` | string[] | Domains matching this suffix (e.g., `[".onion"]`) |
| `ip_cidr` | string[] | IP subnets that trigger this rule (e.g., `["10.0.0.0/8"]`) | | `ip_cidr` | string[] | IP subnets (e.g., `["10.0.0.0/8"]`) |
| `action` | string | Override action when a match occurs: `"proxy"` or `"direct"` | | `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", "mode": "server",
// Single address or array: ["0.0.0.0:50000", "[::]:50000"]
"listen": "0.0.0.0:50000", "listen": "0.0.0.0:50000",
"access_keys": [ "access_keys": [
"c8a6fde902b4e23910cde882b7cf1612" "c8a6fde902b4e23910cde882b7cf1612"
], ],
"turn_server": "stun.l.google.com:19302",
"log_level": "info", // Management REST API
"debug": false, "api": {
"outbound": {
"enabled": true, "enabled": true,
"bind": "127.0.0.1:9090",
"token": "your-secret-token"
},
// Upstream proxy routing
"outbound": {
"enabled": false,
"protocol": "socks5", "protocol": "socks5",
"address": "127.0.0.1", "address": "127.0.0.1",
"port": 9050, "port": 9050,
"default_action": "direct", "default_action": "direct",
"rules": [ "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 ## Client Configuration
### Core Settings
| Field | Type | Default | Description | | Field | Type | Default | Description |
|---|---|---|---| |---|---|---|---|
| `mode` | string | required | Must be `"client"` | | `mode` | string | required | Must be `"client"` |
| `server` | string | required | Address of the remote OSTP server (`host:port`) | | `server` | string | required | Remote OSTP server (`host:port`) |
| `access_key` | string | required | Access key matching one of the keys on the server | | `access_key` | string | required | Access key matching a server key |
| `socks5_bind` | string | `"127.0.0.1:1088"` | Local HTTP/SOCKS5 inbound proxy address | | `socks5_bind` | string | `"127.0.0.1:1088"` | Local SOCKS5/HTTP proxy address |
| `debug` | bool | `false` | Enable verbose client debugging logs | | `debug` | bool | `false` | Verbose client logging |
| `tun` | object | `null` | Virtual TUN tunnel configurations |
| `exclude` | object | `null` | Bypassing/exclusion lists for local routing |
| `mux` | object | `null` | Session multiplexing settings |
### TUN Configuration ### TUN Mode (Full-System VPN)
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `enable` | bool | Enable full-system virtual TUN mode | | `tun.enable` | bool | Enable TUN virtual adapter |
| `wintun_path` | string | Path to custom `wintun.dll` on Windows | | `tun.wintun_path` | string | Path to `wintun.dll` (Windows only) |
| `ipv4_address` | string | IP address assigned to the virtual network adapter (e.g., `"10.1.0.2/24"`) | | `tun.ipv4_address` | string | IP for the virtual adapter (e.g., `"10.1.0.2/24"`) |
| `dns` | string | Custom DNS server for virtual adapter | | `tun.dns` | string | DNS server for the tunnel |
### Exclusions ### Exclusions
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `domains` | string[] | Domain suffixes to bypass (e.g., `"google.com"`) | | `exclude.domains` | string[] | Domain suffixes to bypass |
| `ips` | string[] | IP addresses or CIDR subnets to bypass (e.g., `"192.168.0.0/16"`) | | `exclude.ips` | string[] | IP/CIDR subnets to bypass |
| `processes` | string[] | OS process names to bypass in proxy mode (e.g., `"chrome.exe"`) | | `exclude.processes` | string[] | Process names to bypass (Windows) |
### Multiplexing ### Multiplexing
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `enabled` | bool | Distribute streams across multiple parallel OSTP sessions | | `mux.enabled` | bool | Distribute streams across multiple sessions |
| `sessions` | int | Number of concurrent active OSTP 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 ### Full Client Example
```json ```jsonc
{ {
"mode": "client", "mode": "client",
"server": "example.com:50000", "server": "example.com:50000",
"access_key": "c8a6fde902b4e23910cde882b7cf1612", "access_key": "c8a6fde902b4e23910cde882b7cf1612",
"socks5_bind": "127.0.0.1:1088", "socks5_bind": "127.0.0.1:1088",
"debug": false,
"tun": { "tun": {
"enable": true, "enable": true,
"wintun_path": "./wintun.dll",
"ipv4_address": "10.1.0.2/24",
"dns": "1.1.1.1" "dns": "1.1.1.1"
}, },
"exclude": { "exclude": {
"domains": ["bank.com", "local.network"], "domains": ["bank.com"],
"ips": ["192.168.0.0/16", "10.0.0.0/8"], "ips": ["192.168.0.0/16"],
"processes": ["steam.exe"] "processes": ["steam.exe"]
}, },
"mux": { "mux": {
"enabled": false, "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 | | Variable | Description |
|---|---|---| |---|---|
| `turn.enabled` | bool | Enable client-side TURN relay wrapper | | `RUST_LOG` | Logging filter (e.g., `RUST_LOG=ostp_server=debug`) |
| `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 |
--- ---
[← Installation](Installation) | [Protocol Design →](Protocol-Design) [← Installation](Installation) | [Management API →](Management-API)

194
Configuration_ru.md

@ -2,152 +2,206 @@
![GitHub Release](https://img.shields.io/github/v/release/ospab/ostp?style=flat-square&color=blue) ![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"` | | `mode` | string | обязательно | Должно быть `"server"` |
| `listen` | string | `"0.0.0.0:50000"` | Локальный адрес и UDP-порт прослушивания | | `listen` | string \| string[] | `"0.0.0.0:50000"` | UDP-адрес(а) для привязки. Поддерживает строку или массив для multi-listener |
| `access_keys` | string[] | обязательно | Список ключей доступа для клиентов. Файл отслеживается для автоматического горячего обновления на лету | | `access_keys` | string[] | обязательно | Валидные ключи доступа. Автоматически перезагружаются каждые 5 секунд |
| `turn_server` | string | `null` | Опциональный адрес STUN/TURN-сервера для обхода ограничений NAT и UDP-блокировок | | `turn_server` | string | `null` | STUN/TURN-сервер для NAT traversal |
| `debug` | bool | `false` | Включить подробное диагностическое логирование на уровне пакетов | | `debug` | bool | `false` | Подробное логирование на уровне пакетов |
| `log_level` | string | `"info"` | Уровень логирования: `debug`, `info`, `warn`, `error` |
| `outbound` | object | `null` | Правила перенаправления исходящего трафика сервера через вышестоящие прокси |
### Исходящая маршрутизация (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 | Включить/выключить проксирование исходящего трафика сервера | | `outbound.enabled` | bool | Включить вышестоящий прокси |
| `protocol` | string | Протокол прокси-сервера (например, `"socks5"`) | | `outbound.protocol` | string | `"socks5"` или `"http"` |
| `address` | string | IP-адрес или хост вышестоящего прокси | | `outbound.address` | string | Адрес прокси |
| `port` | u16 | Порт вышестоящего прокси | | `outbound.port` | u16 | Порт прокси |
| `default_action` | string | Действие по умолчанию для несовпадающих запросов: `"proxy"` (направлять все через прокси) или `"direct"` (направлять напрямую) | | `outbound.default_action` | string | `"proxy"` или `"direct"` |
| `rules` | array | Список правил маршрутизации | | `outbound.rules` | array | Правила маршрутизации (см. ниже) |
### Исходящие правила (Outbound Rules) #### Правила маршрутизации
Каждое правило в массиве `rules` содержит следующие параметры:
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `domain_suffix` | string[] | Доменные суффиксы для срабатывания правила (например, `[".onion"]`) | | `domain_suffix` | string[] | Домены, срабатывающие на правило (напр. `[".onion"]`) |
| `ip_cidr` | string[] | Подсети IP для срабатывания правила (например, `["10.0.0.0/8"]`) | | `ip_cidr` | string[] | IP-подсети (напр. `["10.0.0.0/8"]`) |
| `action` | string | Переопределение действия при совпадении: `"proxy"` или `"direct"` | | `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", "mode": "server",
// Один адрес или массив: ["0.0.0.0:50000", "[::]:50000"]
"listen": "0.0.0.0:50000", "listen": "0.0.0.0:50000",
"access_keys": [ "access_keys": [
"c8a6fde902b4e23910cde882b7cf1612" "c8a6fde902b4e23910cde882b7cf1612"
], ],
"turn_server": "stun.l.google.com:19302",
"log_level": "info", // REST API управления
"debug": false, "api": {
"outbound": {
"enabled": true, "enabled": true,
"bind": "127.0.0.1:9090",
"token": "ваш-секретный-токен"
},
// Маршрутизация через вышестоящий прокси
"outbound": {
"enabled": false,
"protocol": "socks5", "protocol": "socks5",
"address": "127.0.0.1", "address": "127.0.0.1",
"port": 9050, "port": 9050,
"default_action": "direct", "default_action": "direct",
"rules": [ "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"` | | `mode` | string | обязательно | Должно быть `"client"` |
| `server` | string | обязательно | Адрес удалённого сервера OSTP (`host:port`) | | `server` | string | обязательно | Адрес удалённого OSTP-сервера (`host:port`) |
| `access_key` | string | обязательно | Ключ доступа, соответствующий одному из ключей на сервере | | `access_key` | string | обязательно | Ключ доступа, совпадающий с ключом на сервере |
| `socks5_bind` | string | `"127.0.0.1:1088"` | Локальный адрес входящего HTTP/SOCKS5 прокси | | `socks5_bind` | string | `"127.0.0.1:1088"` | Локальный адрес SOCKS5/HTTP прокси |
| `debug` | bool | `false` | Включить подробное клиентское логирование | | `debug` | bool | `false` | Подробное логирование клиента |
| `tun` | object | `null` | Настройки виртуального туннеля TUN |
| `exclude` | object | `null` | Списки исключений трафика из туннеля |
| `mux` | object | `null` | Настройки мультиплексирования |
### TUN-туннель ### TUN-режим (полносистемный VPN)
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `enable` | bool | Включить режим виртуальной сетевой карты TUN | | `tun.enable` | bool | Включить виртуальный TUN-адаптер |
| `wintun_path` | string | Путь к файлу `wintun.dll` в Windows | | `tun.wintun_path` | string | Путь к `wintun.dll` (только Windows) |
| `ipv4_address` | string | IP-адрес, назначаемый виртуальному адаптеру (например, `"10.1.0.2/24"`) | | `tun.ipv4_address` | string | IP виртуального адаптера (напр. `"10.1.0.2/24"`) |
| `dns` | string | Выделенный DNS-сервер для туннельного интерфейса | | `tun.dns` | string | DNS-сервер для туннеля |
### Исключения ### Исключения
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `domains` | string[] | Доменные суффиксы для обхода туннеля (например, `"google.com"`) | | `exclude.domains` | string[] | Суффиксы доменов для обхода |
| `ips` | string[] | IP-адреса или CIDR подсети для обхода (например, `"192.168.0.0/16"`) | | `exclude.ips` | string[] | IP/CIDR-подсети для обхода |
| `processes` | string[] | Имена процессов в ОС для обхода в режиме прокси (например, `"chrome.exe"`) | | `exclude.processes` | string[] | Имена процессов для обхода (Windows) |
### Мультиплексирование ### Мультиплексирование
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `enabled` | bool | Распределять сетевые потоки между несколькими параллельными OSTP-сессиями | | `mux.enabled` | bool | Распределение потоков по нескольким сессиям |
| `sessions` | int | Количество одновременно активных OSTP-сессий | | `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", "mode": "client",
"server": "example.com:50000", "server": "example.com:50000",
"access_key": "c8a6fde902b4e23910cde882b7cf1612", "access_key": "c8a6fde902b4e23910cde882b7cf1612",
"socks5_bind": "127.0.0.1:1088", "socks5_bind": "127.0.0.1:1088",
"debug": false,
"tun": { "tun": {
"enable": true, "enable": true,
"wintun_path": "./wintun.dll",
"ipv4_address": "10.1.0.2/24",
"dns": "1.1.1.1" "dns": "1.1.1.1"
}, },
"exclude": { "exclude": {
"domains": ["bank.ru", "local.network"], "domains": ["bank.com"],
"ips": ["192.168.0.0/16", "10.0.0.0/8"], "ips": ["192.168.0.0/16"],
"processes": ["steam.exe"] "processes": ["steam.exe"]
}, },
"mux": { "mux": {
"enabled": false, "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-сервер | | `RUST_LOG` | Фильтр логирования (напр. `RUST_LOG=ostp_server=debug`) |
| `turn.server_addr` | string | Адрес и порт TURN-сервера |
| `turn.username` | string | Логин для авторизации на TURN |
| `turn.access_key` | string | Пароль/ключ доступа для TURN |
--- ---
[← Установка](Installation_ru) | [Протокол →](Protocol-Design_ru) [← Установка](Installation_ru) | [API управления →](Management-API_ru)

87
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) ![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) ![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) ![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 | | Page | Description |
|---|---| |---|---|
| [Installation](Installation) | Server & client setup guide | | [Installation](Installation) | Server & client setup — one-line install scripts |
| [Configuration](Configuration) | Full configuration reference | | [Configuration](Configuration) | Full configuration reference for server & client |
| [Protocol Design](Protocol-Design) | Wire format, cryptography, DPI resistance | | [Management API](Management-API) | REST API for panels, dashboards, and automation |
| [GUI Client](GUI-Client) | Windows desktop application guide | | [Protocol Design](Protocol-Design) | Wire format, cryptography, obfuscation, DPI resistance |
| [Share Links](Share-Links) | `ostp://` URI format reference | | [Share Links](Share-Links) | `ostp://` URI format for one-click connection |
| [Building from Source](Building-from-Source) | Compilation guide for all platforms | | [GUI Client](GUI-Client) | Windows/macOS desktop application |
| [Building from Source](Building-from-Source) | Compilation guide for 14+ targets |
| [FAQ](FAQ) | Frequently asked questions | | [FAQ](FAQ) | Frequently asked questions |
---
## What is OSTP? ## 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 | | **Full Obfuscation** | Headers, payloads, and metadata — all encrypted. Kerckhoffs's principle. |
| **Noise_NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — Forward Secrecy | | **Noise NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — forward secrecy, no PKI required |
| **Reliable UDP (ARQ)** | Selective ACK, retransmission, reorder buffer | | **Reliable UDP** | Selective ACK, NACK, gap recovery, configurable reorder buffer |
| **Multiplexing** | Multiple TCP streams over a single UDP session | | **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 | | **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.

113
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) ![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) ![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) ![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) | Развёртывание сервера и клиента | | [Установка](Installation_ru) | Настройка сервера и клиента — установка в одну строку |
| [Конфигурация](Configuration_ru) | Полный справочник config.json | | [Конфигурация](Configuration_ru) | Полный справочник конфигурации сервера и клиента |
| [Протокол](Protocol-Design_ru) | Wire-формат, криптография, защита от DPI | | [API управления](Management-API_ru) | REST API для панелей, дашбордов и автоматизации |
| [GUI-клиент](GUI-Client_ru) | Приложение для Windows | | [Протокол](Protocol-Design_ru) | Wire format, криптография, обфускация, DPI-устойчивость |
| [Ссылки-приглашения](Share-Links_ru) | Формат `ostp://` URI | | [Ссылки-приглашения](Share-Links_ru) | Формат URI `ostp://` для подключения в один клик |
| [Сборка](Building-from-Source_ru) | Компиляция из исходников | | [GUI-клиент](GUI-Client_ru) | Десктопное приложение для Windows/macOS |
| [Сборка](Building-from-Source_ru) | Компиляция для 14+ целевых платформ |
| [FAQ](FAQ_ru) | Часто задаваемые вопросы | | [FAQ](FAQ_ru) | Часто задаваемые вопросы |
---
## Что такое OSTP? ## Что такое OSTP?
**Ospab Stealth Transport Protocol** — UDP-протокол зашифрованного туннелирования, разработанный для максимальной устойчивости к DPI и ТСПУ. Каждый байт на проводе криптографически неотличим от случайного шума. **Ospab Stealth Transport Protocol** — протокол туннелирования на основе UDP, спроектированный для максимальной устойчивости к DPI, ТСПУ и активному зондированию. Каждый байт на проводе криптографически неотличим от случайного шума.
### Ключевые особенности ### Ключевые возможности
| Возможность | Описание | | Возможность | Детали |
|---|---| |---|---|
| **Полная обфускация** | Принцип Керкгоффса — безопасность зависит только от ключа | | **Полная обфускация** | Заголовки, данные и метаданные — всё зашифровано. Принцип Керкгоффса. |
| **Noise_NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — Forward Secrecy | | **Noise NNpsk0** | X25519 + ChaChaPoly + BLAKE2s — forward secrecy, без PKI |
| **Надёжный UDP (ARQ)** | Selective ACK, ретрансмиссия, буфер переупорядочивания | | **Надёжный UDP** | Selective ACK, NACK, восстановление пропусков, настраиваемый буфер реордеринга |
| **Мультиплексирование** | Множество TCP-потоков в одной UDP-сессии | | **Congestion Control** | BBR-подобное адаптивное окно с оценкой bandwidth и RTT |
| **Кросс-платформа** | Windows, Linux, macOS, Android, FreeBSD, MIPS, RISC-V | | **Мультиплексирование** | Несколько TCP-потоков в одной зашифрованной UDP-сессии |
| **TUN-режим** | Полный VPN через виртуальный сетевой адаптер | | **Бесшовный роуминг** | 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 года.

241
Management-API.md Normal file

@ -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)

241
Management-API_ru.md Normal file

@ -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)

6
_Sidebar.md

@ -1,19 +1,25 @@
**OSTP Wiki** **OSTP Wiki**
---
**English** **English**
- [Home](Home) - [Home](Home)
- [Installation](Installation) - [Installation](Installation)
- [Configuration](Configuration) - [Configuration](Configuration)
- [Management API](Management-API)
- [Protocol Design](Protocol-Design) - [Protocol Design](Protocol-Design)
- [Share Links](Share-Links) - [Share Links](Share-Links)
- [GUI Client](GUI-Client) - [GUI Client](GUI-Client)
- [Building from Source](Building-from-Source) - [Building from Source](Building-from-Source)
- [FAQ](FAQ) - [FAQ](FAQ)
---
**Русский** **Русский**
- [Главная](Home_ru) - [Главная](Home_ru)
- [Установка](Installation_ru) - [Установка](Installation_ru)
- [Конфигурация](Configuration_ru) - [Конфигурация](Configuration_ru)
- [API управления](Management-API_ru)
- [Протокол](Protocol-Design_ru) - [Протокол](Protocol-Design_ru)
- [Ссылки-приглашения](Share-Links_ru) - [Ссылки-приглашения](Share-Links_ru)
- [GUI-клиент](GUI-Client_ru) - [GUI-клиент](GUI-Client_ru)