diff --git a/Configuration.md b/Configuration.md index 7e71bf2..12efd82 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,66 +1,114 @@ - # Configuration +# Configuration ![GitHub Release](https://img.shields.io/github/v/release/ospab/ostp?style=flat-square&color=blue) [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. + +--- + ## Server Configuration | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | required | Must be `"server"` | -| `listen` | string | `"0.0.0.0:50000"` | Listen address and port | -| `access_keys` | string[] | required | List of access keys for client authentication | +| `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 | -### Example +### Outbound Routing (Server Outbound) + +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 | 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 Rules + +Each rule object in the `rules` array contains: + +| 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"` | + +### Full Server Configuration Example ```json { "mode": "server", "listen": "0.0.0.0:50000", "access_keys": [ - "key-for-user-1", - "key-for-user-2" + "c8a6fde902b4e23910cde882b7cf1612" ], - "log_level": "info" + "turn_server": "stun.l.google.com:19302", + "log_level": "info", + "debug": false, + "outbound": { + "enabled": true, + "protocol": "socks5", + "address": "127.0.0.1", + "port": 9050, + "default_action": "direct", + "rules": [ + { + "domain_suffix": [".onion"], + "action": "proxy" + } + ] + } } ``` +--- + ## Client Configuration | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | required | Must be `"client"` | -| `server` | string | required | Server address (`host:port`) | -| `access_key` | string | required | Access key matching server config | -| `socks5_bind` | string | `"127.0.0.1:1088"` | Local HTTP/SOCKS5 proxy address | -| `debug` | bool | `false` | Enable verbose logging | -| `tun` | object | `null` | TUN tunnel configuration | -| `exclude` | object | `null` | Traffic exclusion rules | -| `mux` | object | `null` | Multiplexing configuration | +| `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 | ### TUN Configuration | Field | Type | Description | |---|---|---| -| `enable` | bool | Enable TUN tunnel mode (routes all traffic) | -| `dns` | string | Custom DNS server for the tunnel interface | +| `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 | ### Exclusions | Field | Type | Description | |---|---|---| | `domains` | string[] | Domain suffixes to bypass (e.g., `"google.com"`) | -| `ips` | string[] | IP addresses or CIDR ranges to bypass (e.g., `"192.168.0.0/16"`) | -| `processes` | string[] | Process names to bypass in proxy mode (e.g., `"chrome.exe"`) | +| `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"`) | ### Multiplexing | Field | Type | Description | |---|---|---| -| `enabled` | bool | Enable session multiplexing | -| `sessions` | int | Number of concurrent OSTP sessions | +| `enabled` | bool | Distribute streams across multiple parallel OSTP sessions | +| `sessions` | int | Number of concurrent active OSTP sessions | ### Full Client Example @@ -68,11 +116,13 @@ { "mode": "client", "server": "example.com:50000", - "access_key": "my-secret-key", + "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": { @@ -87,16 +137,16 @@ } ``` -### TURN Relay (Optional) +### TURN Relay (Optional Client-Side) -For networks that block direct UDP: +For clients operating behind highly restrictive firewalls blocking direct UDP: | 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 | +| `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 | --- diff --git a/Configuration_ru.md b/Configuration_ru.md index fc3bbd5..079e372 100644 --- a/Configuration_ru.md +++ b/Configuration_ru.md @@ -4,63 +4,111 @@ [English / Английский](Configuration) | [← Главная](Home_ru) +OSTP (Ospab Stealth Transport Protocol) настраивается с помощью одного конфигурационного файла JSON, обычно имеющего имя `config.json`. Приложение определяет свою роль исполнения (клиент или сервер) по значению ключа `"mode"`. + +--- + ## Серверная конфигурация | Поле | Тип | По умолчанию | Описание | |---|---|---|---| | `mode` | string | обязательно | Должно быть `"server"` | -| `listen` | string | `"0.0.0.0:50000"` | Адрес и порт прослушивания | -| `access_keys` | string[] | обязательно | Список ключей доступа для клиентов | +| `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` | Правила перенаправления исходящего трафика сервера через вышестоящие прокси | -### Пример +### Исходящая маршрутизация (Server Outbound) + +С помощью блока `outbound` сервер OSTP может перенаправлять весь или определённый трафик клиентов через вышестоящие прокси (например, SOCKS5 или Tor). + +| Поле | Тип | Описание | +|---|---|---| +| `enabled` | bool | Включить/выключить проксирование исходящего трафика сервера | +| `protocol` | string | Протокол прокси-сервера (например, `"socks5"`) | +| `address` | string | IP-адрес или хост вышестоящего прокси | +| `port` | u16 | Порт вышестоящего прокси | +| `default_action` | string | Действие по умолчанию для несовпадающих запросов: `"proxy"` (направлять все через прокси) или `"direct"` (направлять напрямую) | +| `rules` | array | Список правил маршрутизации | + +### Исходящие правила (Outbound Rules) + +Каждое правило в массиве `rules` содержит следующие параметры: + +| Поле | Тип | Описание | +|---|---|---| +| `domain_suffix` | string[] | Доменные суффиксы для срабатывания правила (например, `[".onion"]`) | +| `ip_cidr` | string[] | Подсети IP для срабатывания правила (например, `["10.0.0.0/8"]`) | +| `action` | string | Переопределение действия при совпадении: `"proxy"` или `"direct"` | + +### Полный пример серверного конфига ```json { "mode": "server", "listen": "0.0.0.0:50000", "access_keys": [ - "ключ-пользователя-1", - "ключ-пользователя-2" + "c8a6fde902b4e23910cde882b7cf1612" ], - "log_level": "info" + "turn_server": "stun.l.google.com:19302", + "log_level": "info", + "debug": false, + "outbound": { + "enabled": true, + "protocol": "socks5", + "address": "127.0.0.1", + "port": 9050, + "default_action": "direct", + "rules": [ + { + "domain_suffix": [".onion"], + "action": "proxy" + } + ] + } } ``` +--- + ## Клиентская конфигурация | Поле | Тип | По умолчанию | Описание | |---|---|---|---| | `mode` | string | обязательно | Должно быть `"client"` | -| `server` | string | обязательно | Адрес сервера (`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` | Правила исключения трафика | +| `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` | Настройки мультиплексирования | ### TUN-туннель | Поле | Тип | Описание | |---|---|---| -| `enable` | bool | Включить TUN-режим (маршрутизирует весь трафик) | -| `dns` | string | DNS-сервер для туннельного интерфейса | +| `enable` | bool | Включить режим виртуальной сетевой карты TUN | +| `wintun_path` | string | Путь к файлу `wintun.dll` в Windows | +| `ipv4_address` | string | IP-адрес, назначаемый виртуальному адаптеру (например, `"10.1.0.2/24"`) | +| `dns` | string | Выделенный DNS-сервер для туннельного интерфейса | ### Исключения | Поле | Тип | Описание | |---|---|---| -| `domains` | string[] | Суффиксы доменов для обхода (`"google.com"`) | -| `ips` | string[] | IP-адреса или CIDR-диапазоны для обхода (`"192.168.0.0/16"`) | -| `processes` | string[] | Имена процессов для обхода в прокси-режиме (`"chrome.exe"`) | +| `domains` | string[] | Доменные суффиксы для обхода туннеля (например, `"google.com"`) | +| `ips` | string[] | IP-адреса или CIDR подсети для обхода (например, `"192.168.0.0/16"`) | +| `processes` | string[] | Имена процессов в ОС для обхода в режиме прокси (например, `"chrome.exe"`) | ### Мультиплексирование | Поле | Тип | Описание | |---|---|---| -| `enabled` | bool | Включить мультиплексирование сессий | -| `sessions` | int | Количество параллельных OSTP-сессий | +| `enabled` | bool | Распределять сетевые потоки между несколькими параллельными OSTP-сессиями | +| `sessions` | int | Количество одновременно активных OSTP-сессий | ### Полный пример клиентского конфига @@ -68,11 +116,13 @@ { "mode": "client", "server": "example.com:50000", - "access_key": "мой-ключ", + "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": { @@ -87,16 +137,16 @@ } ``` -### TURN-реле (опционально) +### TURN-реле (Опционально на стороне клиента) -Для сетей, блокирующих прямой UDP: +Для клиентов, находящихся за строгими брандмауэрами, блокирующими прямой UDP-трафик: | Поле | Тип | Описание | |---|---|---| -| `turn.enabled` | bool | Включить TURN-реле | -| `turn.server_addr` | string | Адрес TURN-сервера | -| `turn.username` | string | Имя пользователя TURN | -| `turn.access_key` | string | Пароль TURN | +| `turn.enabled` | bool | Включить проксирование через TURN-сервер | +| `turn.server_addr` | string | Адрес и порт TURN-сервера | +| `turn.username` | string | Логин для авторизации на TURN | +| `turn.access_key` | string | Пароль/ключ доступа для TURN | ---