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

docs: document full server config options including turn_server, debug, and outbound rules in en and ru

ospab 2026-05-17 17:28:24 +03:00
parent c22dc10341
commit b5ab15bb8f
2 changed files with 153 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
Configuration.md

@ -1,66 +1,114 @@
# Configuration # Configuration
![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)
[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.
---
## Server Configuration ## Server Configuration
| 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"` | Listen address and port | | `listen` | string | `"0.0.0.0:50000"` | Local address and UDP port to bind the server to |
| `access_keys` | string[] | required | List of access keys for client authentication | | `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` | | `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 ```json
{ {
"mode": "server", "mode": "server",
"listen": "0.0.0.0:50000", "listen": "0.0.0.0:50000",
"access_keys": [ "access_keys": [
"key-for-user-1", "c8a6fde902b4e23910cde882b7cf1612"
"key-for-user-2"
], ],
"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 ## Client Configuration
| Field | Type | Default | Description | | Field | Type | Default | Description |
|---|---|---|---| |---|---|---|---|
| `mode` | string | required | Must be `"client"` | | `mode` | string | required | Must be `"client"` |
| `server` | string | required | Server address (`host:port`) | | `server` | string | required | Address of the remote OSTP server (`host:port`) |
| `access_key` | string | required | Access key matching server config | | `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 proxy address | | `socks5_bind` | string | `"127.0.0.1:1088"` | Local HTTP/SOCKS5 inbound proxy address |
| `debug` | bool | `false` | Enable verbose logging | | `debug` | bool | `false` | Enable verbose client debugging logs |
| `tun` | object | `null` | TUN tunnel configuration | | `tun` | object | `null` | Virtual TUN tunnel configurations |
| `exclude` | object | `null` | Traffic exclusion rules | | `exclude` | object | `null` | Bypassing/exclusion lists for local routing |
| `mux` | object | `null` | Multiplexing configuration | | `mux` | object | `null` | Session multiplexing settings |
### TUN Configuration ### TUN Configuration
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `enable` | bool | Enable TUN tunnel mode (routes all traffic) | | `enable` | bool | Enable full-system virtual TUN mode |
| `dns` | string | Custom DNS server for the tunnel interface | | `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 ### Exclusions
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `domains` | string[] | Domain suffixes to bypass (e.g., `"google.com"`) | | `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"`) | | `ips` | string[] | IP addresses or CIDR subnets to bypass (e.g., `"192.168.0.0/16"`) |
| `processes` | string[] | Process names to bypass in proxy mode (e.g., `"chrome.exe"`) | | `processes` | string[] | OS process names to bypass in proxy mode (e.g., `"chrome.exe"`) |
### Multiplexing ### Multiplexing
| Field | Type | Description | | Field | Type | Description |
|---|---|---| |---|---|---|
| `enabled` | bool | Enable session multiplexing | | `enabled` | bool | Distribute streams across multiple parallel OSTP sessions |
| `sessions` | int | Number of concurrent OSTP sessions | | `sessions` | int | Number of concurrent active OSTP sessions |
### Full Client Example ### Full Client Example
@ -68,11 +116,13 @@
{ {
"mode": "client", "mode": "client",
"server": "example.com:50000", "server": "example.com:50000",
"access_key": "my-secret-key", "access_key": "c8a6fde902b4e23910cde882b7cf1612",
"socks5_bind": "127.0.0.1:1088", "socks5_bind": "127.0.0.1:1088",
"debug": false, "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": {
@ -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 | | Field | Type | Description |
|---|---|---| |---|---|---|
| `turn.enabled` | bool | Enable TURN relay | | `turn.enabled` | bool | Enable client-side TURN relay wrapper |
| `turn.server_addr` | string | TURN server address | | `turn.server_addr` | string | TURN relay server IP/Host and port |
| `turn.username` | string | TURN username | | `turn.username` | string | Authentication username for TURN |
| `turn.access_key` | string | TURN password | | `turn.access_key` | string | Authentication key/password for TURN |
--- ---

102
Configuration_ru.md

@ -4,63 +4,111 @@
[English / Английский](Configuration) | [← Главная](Home_ru) [English / Английский](Configuration) | [← Главная](Home_ru)
OSTP (Ospab Stealth Transport Protocol) настраивается с помощью одного конфигурационного файла JSON, обычно имеющего имя `config.json`. Приложение определяет свою роль исполнения (клиент или сервер) по значению ключа `"mode"`.
---
## Серверная конфигурация ## Серверная конфигурация
| Поле | Тип | По умолчанию | Описание | | Поле | Тип | По умолчанию | Описание |
|---|---|---|---| |---|---|---|---|
| `mode` | string | обязательно | Должно быть `"server"` | | `mode` | string | обязательно | Должно быть `"server"` |
| `listen` | string | `"0.0.0.0:50000"` | Адрес и порт прослушивания | | `listen` | string | `"0.0.0.0:50000"` | Локальный адрес и UDP-порт прослушивания |
| `access_keys` | string[] | обязательно | Список ключей доступа для клиентов | | `access_keys` | string[] | обязательно | Список ключей доступа для клиентов. Файл отслеживается для автоматического горячего обновления на лету |
| `turn_server` | string | `null` | Опциональный адрес STUN/TURN-сервера для обхода ограничений NAT и UDP-блокировок |
| `debug` | bool | `false` | Включить подробное диагностическое логирование на уровне пакетов |
| `log_level` | string | `"info"` | Уровень логирования: `debug`, `info`, `warn`, `error` | | `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 ```json
{ {
"mode": "server", "mode": "server",
"listen": "0.0.0.0:50000", "listen": "0.0.0.0:50000",
"access_keys": [ "access_keys": [
"ключ-пользователя-1", "c8a6fde902b4e23910cde882b7cf1612"
"ключ-пользователя-2"
], ],
"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"` | | `mode` | string | обязательно | Должно быть `"client"` |
| `server` | string | обязательно | Адрес сервера (`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"` | Локальный адрес входящего HTTP/SOCKS5 прокси |
| `debug` | bool | `false` | Включить подробное логирование | | `debug` | bool | `false` | Включить подробное клиентское логирование |
| `tun` | object | `null` | Настройки TUN-туннеля | | `tun` | object | `null` | Настройки виртуального туннеля TUN |
| `exclude` | object | `null` | Правила исключения трафика | | `exclude` | object | `null` | Списки исключений трафика из туннеля |
| `mux` | object | `null` | Настройки мультиплексирования | | `mux` | object | `null` | Настройки мультиплексирования |
### TUN-туннель ### TUN-туннель
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `enable` | bool | Включить TUN-режим (маршрутизирует весь трафик) | | `enable` | bool | Включить режим виртуальной сетевой карты TUN |
| `dns` | string | DNS-сервер для туннельного интерфейса | | `wintun_path` | string | Путь к файлу `wintun.dll` в Windows |
| `ipv4_address` | string | IP-адрес, назначаемый виртуальному адаптеру (например, `"10.1.0.2/24"`) |
| `dns` | string | Выделенный DNS-сервер для туннельного интерфейса |
### Исключения ### Исключения
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `domains` | string[] | Суффиксы доменов для обхода (`"google.com"`) | | `domains` | string[] | Доменные суффиксы для обхода туннеля (например, `"google.com"`) |
| `ips` | string[] | IP-адреса или CIDR-диапазоны для обхода (`"192.168.0.0/16"`) | | `ips` | string[] | IP-адреса или CIDR подсети для обхода (например, `"192.168.0.0/16"`) |
| `processes` | string[] | Имена процессов для обхода в прокси-режиме (`"chrome.exe"`) | | `processes` | string[] | Имена процессов в ОС для обхода в режиме прокси (например, `"chrome.exe"`) |
### Мультиплексирование ### Мультиплексирование
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `enabled` | bool | Включить мультиплексирование сессий | | `enabled` | bool | Распределять сетевые потоки между несколькими параллельными OSTP-сессиями |
| `sessions` | int | Количество параллельных OSTP-сессий | | `sessions` | int | Количество одновременно активных OSTP-сессий |
### Полный пример клиентского конфига ### Полный пример клиентского конфига
@ -68,11 +116,13 @@
{ {
"mode": "client", "mode": "client",
"server": "example.com:50000", "server": "example.com:50000",
"access_key": "мой-ключ", "access_key": "c8a6fde902b4e23910cde882b7cf1612",
"socks5_bind": "127.0.0.1:1088", "socks5_bind": "127.0.0.1:1088",
"debug": false, "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": {
@ -87,16 +137,16 @@
} }
``` ```
### TURN-реле (опционально) ### TURN-реле (Опционально на стороне клиента)
Для сетей, блокирующих прямой UDP: Для клиентов, находящихся за строгими брандмауэрами, блокирующими прямой UDP-трафик:
| Поле | Тип | Описание | | Поле | Тип | Описание |
|---|---|---| |---|---|---|
| `turn.enabled` | bool | Включить TURN-реле | | `turn.enabled` | bool | Включить проксирование через TURN-сервер |
| `turn.server_addr` | string | Адрес TURN-сервера | | `turn.server_addr` | string | Адрес и порт TURN-сервера |
| `turn.username` | string | Имя пользователя TURN | | `turn.username` | string | Логин для авторизации на TURN |
| `turn.access_key` | string | Пароль TURN | | `turn.access_key` | string | Пароль/ключ доступа для TURN |
--- ---