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 (горячая перезагрузка поддерживается автоматически, перезапускать сервер после изменений не нужно).

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

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

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

По умолчанию команды работают с файлом clients.json в текущей директории. Если вы используете другой путь, задайте его через переменную окружения CLIENTS_FILE:

CLIENTS_FILE=/etc/free-turn-proxy/clients.json ./server clients list

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

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

# Добавить клиента
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.