free-turn-proxy/docs/flags.md

# Флаги

## Клиент

| Флаг                | По умолчанию                                      | Описание                                                                                                                                                                                                                                                  |
|---------------------|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-listen`           | `127.0.0.1:9000`                                  | локальный адрес `ip:port`, куда подключается WireGuard (UDP) или Xray/sing-box (TCP) клиент                                                                                                                                                               |
| `-peer`             | **обязательный**                                  | адрес сервера на VPS, `host:port`                                                                                                                                                                                                                         |
| `-provider`         | `vk`                                              | источник потоков: `vk` (TURN-реле сервиса звонков) \| `direct` (напрямую на `-peer`), см. `docs/providers.md`                                                                                                                                                    |
| `-link`             | пусто                                             | (устарел) одна ссылка на звонок; используйте `-links`. Игнорируется, если задан `-links`                                                                                                                                     |
| `-links`            | **обязательный для `-provider vk`** (или `-link`) | ссылки на звонки через запятую; каждая даёт свой пул из `-n` стримов                                                                                                                                 |
| `-n`                | `12` (`direct`: `1`)                              | параллельных потоков; в `-mode tcp` это число сессий пула, по которым round-robin раскладываются локальные TCP-соединения                                                                                                                                 |
| `-transport`        | `tcp`                                             | транспорт до TURN-реле: `tcp` (TCP/TLS) \| `udp`                                                                                                                                                                                                          |
| `-mode`             | `udp`                                             | режим туннеля: `udp` (UDP-релей для WireGuard) \| `tcp` (TCP-форвардер для Xray/sing-box)                                                                                                                                                                 |
| `-bond` | `false` | объединять сессии для одного TCP-соединения; только `-mode tcp`, до 256 сессий суммарно; нужен обновлённый сервер |
| `-turn`             | из creds                                          | переопределить IP TURN-сервера                                                                                                                                                                                                                            |
| `-port`             | из creds                                          | переопределить порт TURN-сервера                                                                                                                                                                                                                          |
| `-obf-profile`      | `none`                                            | wire-профиль обфускации payload: `none` \| `rtpopus` (RTP/opus + ChaCha20-Poly1305 AEAD) \| `rtpopus2` (+ RTP header extension, ближе к WebRTC) \| `rtpopus3` (+ abs-send-time, VAD, имитация потерь, вариативный timestamp); должен совпадать с сервером |
| `-obf-key`          | пусто                                             | общий ключ для `-obf-profile != none`, 32 байта hex (64 символа)                                                                                                                                                                                          |
| `-obf-timing`       | `0`                                               | межпакетная задержка для RTP-мимикрии (напр. `20ms`); только с `-obf-profile != none`; `0` = выкл. В `-mode tcp` особенно уместна: KCP гонит бёрсты полноразмерных пакетов, без выравнивания профиль на Opus не похож                                     |
| `-gen-obf-key`      | `false`                                           | напечатать новый ключ и выйти                                                                                                                                                                                                                             |
| `-manual-captcha`   | `false`                                           | сразу ручной режим captcha (только `-provider vk`)                                                                                                                                                                                                        |
| `-streams-per-cred` | `12`                                              | потоков на один кеш учёток (только `-provider vk`)                                                                                                                                                                                                     |
| `-platform`         | `desktop`                                         | класс устройства персоны авторизации (мобильность UA/device/client hints): `desktop` \| `mobile` (только `-provider vk`)                                                                                                                                      |
| `-dns-mode`         | `auto`                                            | `plain` (UDP/53) \| `doh` \| `auto`                                                                                                                                                                                                                       |
| `-dns-servers`      | пусто                                             | свои UDP/53 резолверы, `ip[:port][,ip[:port]...]`                                                                                                                                                                                                         |
| `-client-id`        | авто                                              | уникальный ID клиента (автогенерация если не задан)                                                                                                                                                                                                       |
| `-sub`              | пусто                                             | URL подписки (sub.md) для получения списка серверов                                                                                                                                                                                                       |
| `-debug`            | `false`                                           | debug-логи                                                                                                                                                                                                                                                |

## KCP (только `-mode tcp`, клиент и сервер)

Флаги настраивают ARQ-слой, который держит TCP-поток поверх датаграмм TURN. Задаются на каждой стороне отдельно; в `-mode udp` любое отличие от дефолта - ошибка запуска. В share-ссылке профиль едет полем `kcp`, так что гость получает тот же ARQ, что настроил владелец.

| Флаг | По умолчанию | Описание |
| --- | --- | --- |
| `-kcp-nodelay` | `1` | `0` (обычный) \| `1` (быстрый режим) |
| `-kcp-interval` | `20` | интервал внутреннего цикла KCP, мс; больше = меньше служебного трафика |
| `-kcp-resend` | `2` | быстрая повторная отправка после N дубликатов ACK; `0` = выкл |
| `-kcp-nc` | `1` | congestion control: `0` (вкл) \| `1` (выкл) |
| `-kcp-sndwnd` | `512` | окно отправки в пакетах |
| `-kcp-rcvwnd` | `512` | окно приёма в пакетах |
| `-kcp-mtu` | `1200` | MTU сегмента KCP, байты; допустимо `300..1350` |
| `-kcp-acknodelay` | `true` | отправлять ACK сразу: ниже задержка, выше служебный трафик |

На мобильной сети дефолт заметно шумит; щадящий вариант - `-kcp-interval 40 -kcp-sndwnd 256 -kcp-rcvwnd 256 -kcp-acknodelay=false`.

## Сервер

| Флаг | По умолчанию | Описание |
| --- | --- | --- |
| `-listen` | `0.0.0.0:56000` | адрес прослушивания `ip:port` |
| `-connect` | **обязательный** | локальный backend `host:port` (WG `127.0.0.1:51820` / Xray `127.0.0.1:443`) |
| `-mode` | `udp` | режим туннеля: `udp` \| `tcp`; должен совпадать с клиентом |
| `-obf-profile` | `none` | wire-профиль обфускации payload: `none` \| `rtpopus` \| `rtpopus2` \| `rtpopus3`; должен совпадать с клиентом (описание профилей - в таблице клиента) |
| `-obf-timing` | `0` | межпакетная задержка для RTP-мимикрии (напр. `10ms`); только с `-obf-profile != none`; `0` = выкл |
| `-obf-key` | пусто | общий ключ для `-obf-profile != none`, 32 байта hex |
| `-gen-obf-key` | `false` | напечатать новый ключ и выйти |
| `-clients-file` | пусто | путь к JSON-файлу (`clients.json`) для включения авторизации по Client ID |
| `-debug` | `false` | debug-логи |

## Управление Client ID (Команды Сервера)

> [!NOTE]
> **Про авторизацию:** клиент **всегда** отправляет свой Client ID первой записью после DTLS-handshake, сервер **всегда** его читает - wire-контракт симметричен. Флаг `-clients-file` на сервере включает **проверку** ID по allowlist (`clients.json`). Без `-clients-file` ID читается и игнорируется.

Сервер содержит встроенные команды для управления файлом `clients.json` (горячая перезагрузка поддерживается автоматически, перезапускать сервер после изменений не нужно).

```bash
# Добавить или обновить клиента
./server clients add <client_id> ["Комментарий"]

# Удалить клиента
./server clients remove <client_id>

# Вывести список всех клиентов
./server clients list
```

По умолчанию команды работают с файлом `clients.json` в текущей директории. Если вы используете другой путь, задайте его через переменную окружения `CLIENTS_FILE`:
```bash
CLIENTS_FILE=/etc/free-turn-proxy/clients.json ./server clients list
```

### Управление через Docker

Если сервер запущен в Docker-контейнере (например, с именем `free-turn-proxy`), вы можете использовать команду `docker exec` для управления клиентами без необходимости заходить внутрь контейнера или редактировать файл вручную:

```bash
# Добавить клиента
docker exec -it free-turn-proxy /app/server clients add "my-client" "Комментарий"

# Удалить клиента
docker exec -it free-turn-proxy /app/server clients remove "my-client"

# Посмотреть список
docker exec -it free-turn-proxy /app/server clients list
```

> **Важно:** команды `docker exec` берут путь к файлу из переменной окружения `CLIENTS_FILE` контейнера. Это работает, только если контейнер запущен с включённой авторизацией (т.е. `CLIENTS_FILE` задан в `docker-compose.yml` и файл проброшен через `volumes`). Если авторизация выключена, `clients` пишет в эфемерный `clients.json` внутри контейнера, который сервер не читает. Путь должен совпадать с тем, что смонтирован и передан в `-clients-file`.