mirror of https://github.com/ospab/ostp.git
docs: document full server config options including turn_server, debug, and outbound rules in en and ru
ospab
parent
c22dc10341
commit
b5ab15bb8f
102
Configuration.md
102
Configuration.md
|
|
@ -4,63 +4,111 @@
|
|||
|
||||
[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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue