Yandex Metrika

CLI клиент

Описание

Общее описание функционала

CLI-клиент позволяет опубликовать локальный сервис по HTTP, HTTPS, TCP или UDP через туннель и получить для него публичный адрес. Он подходит для удалённого доступа, демонстраций и временного доступа к стенду. TCP и UDP требуют зарегистрированную учётную запись; бесплатного тарифа достаточно. Гостевой режим может применяться только к HTTP и HTTPS, если он разрешён на сервере. Для соединения используются WebSocket, QUIC или DTLS в зависимости от настроек и условий сети.

Как пользователь может использовать

  • Разработчик публикует локальный веб-сервер и получает URL туннеля для быстрого доступа извне.
  • Пользователь открывает доступ к локальной базе, сервису или тестовому стенду без отдельного проброса портов.
  • Пользователь выбирает WebSocket, если сеть пропускает только обычные HTTPS-соединения.
  • Пользователь переключается на QUIC или DTLS, когда нужен альтернативный транспорт для ограниченной сети.
  • Пользователь настраивает TCP- или UDP-туннель для сервисов, которые не работают как обычный веб-сайт.
  • Пользователь включает режим ожидания stay, чтобы туннель оставался активным во время демонстрации или тестирования.
  • Пользователь использует watch, когда нужно отслеживать изменения состояния туннеля без ручного перезапуска.
  • Пользователь передаёт секреты через флаги, файлы, стандартный ввод или переменные окружения, чтобы не хранить их в командной строке.
  • Явные параметры командной строки (в том числе -login и -pass) имеют приоритет над сохранённым в fortunnels.yml CLI-токеном.
  • При исчерпании общего месячного трафика клиент показывает одно сообщение, прекращает передачу и завершает работу с ошибкой. Автоматическое переподключение и создание нового туннеля в этом состоянии не выполняются.
  • Пользователь скачивает готовый бинарник со страницы загрузок продукта или ставит клиент через поддерживаемый пакетный менеджер.

Как это реализовано в сервисе

Пользователь запускает CLI с адресом локального сервиса и параметрами подключения. Клиент проходит аутентификацию или использует гостевой режим, создаёт туннель в сервисе и получает URL туннеля. Затем он открывает выбранный канал передачи данных и направляет через него внешний трафик к локальному сервису. Если режим работы не даёт отдельного сигнала о завершении, клиент периодически проверяет состояние туннеля и завершает работу, когда доступ больше не нужен или туннель больше не действует. Ошибки подключения, ограничений и недоступного транспорта выводятся в консоли понятным для пользователя сообщением.

Как использовать через CLI-клиент

Для HTTP, HTTPS и TCP можно передать только порт: например, fortunnels http 4321. В этом случае клиент обращается к localhost:4321, поэтому локальный сервис может слушать как IPv4, так и IPv6. Краткая форма UDP остаётся IPv4-вариантом: fortunnels udp 4321 использует 127.0.0.1:4321.

Если важна конкретная версия IP, укажите адрес полностью: host:port не меняется клиентом. Для сервиса, который доступен только по IPv6, можно сразу использовать ./bin/client http localhost:4321 или ./bin/client -protocol http -local '[::1]:4321'.

TCP и UDP запускайте с действующими учётными данными. Пароль безопаснее читать из стандартного ввода:

fortunnels tcp 5432 -login user@example.test -pass-stdin
fortunnels udp 9000 -login user@example.test -pass-stdin

Можно использовать действующий Bearer-токен через -token или -token-file. Если общий месячный лимит исчерпан, дождитесь следующего месяца по UTC или попросите администратора увеличить лимит. Перезапуск клиента, смена порта и пересоздание туннеля не обнуляют использование.

Для частного сервера с собственной доверенной CA укажите её PEM-файл только для QUIC или DTLS:

fortunnels udp 9000 -login user@example.test -pass-stdin -dp quic -transport-ca /path/to/ca.pem

Имя сервера и цепочка сертификата всё равно проверяются; этот флаг не отключает TLS-проверку и не добавляет CA в системное хранилище.

Справочник API

Создание туннеля (плоскость управления)

Клиент использует тот же REST API, что и дашборд: POST /api/tunnels с телом JSON (протокол, целевой адрес, опции авторизации туннеля и т.д.). Для TCP и UDP требуется заголовок Authorization: Bearer <token> или сессионная кука после входа. Бесплатного тарифа достаточно в пределах его лимитов.

Гостевое создание (если включено на сервере) относится только к HTTP и HTTPS: тот же маршрут без заголовка авторизации; в ответе — URL туннеля, срок жизни и лимиты.

Статус туннеля

GET /api/tunnels?id=<tunnel_id> — используется CLI для опроса жизненного цикла в режимах stay (HTTP/TCP expose-local/UDP), пока процесс удерживает туннель.

Удаление

DELETE /api/tunnels?id=<tunnel_id> — при поддержке сервером и политикой доступа.

Точные поля запроса и ответа совпадают с публичной справкой API сервера и типами в клиентском протоколе.

Транспорт данных

После создания туннеля клиент открывает WebSocket GET /ws (с параметрами режима и tunnel_id в строке запроса) или альтернативный транспорт (QUIC / DTLS) согласно флагам CLI и конфигурации сервера.

Ошибки

Ошибка аутентификации

Сообщение о неверном логине/пароле или просроченном токене; код выхода ненулевой. Нужно обновить учётные данные или получить новый токен.

Отказ в создании туннеля

Ответ API с телом JSON: поле error или message с человекочитаемым текстом (квота, запрещённый протокол, неверные параметры). Исправить параметры или тариф.

«Tunnel was removed. Exiting.»

Туннель удалён на сервере, истёк или доступ отозван; опрос GET /api/tunnels?id=... вернул признак отсутствия или 401. Запустить клиент заново и при необходимости создать новый туннель.

Ошибка сети / таймаут

Нет связи с сервисом ForTunnels. Проверить подключение к сети и DNS для fortunnels.ru.

«Backend unreachable» и недоступное локальное приложение

Сообщение появляется, когда клиент не может подключиться к локальному адресу туннеля. Если сервис открывается по localhost, но не открывается по 127.0.0.1, он, вероятно, слушает только IPv6. Для HTTP, HTTPS и TCP запустите туннель с localhost:<порт> или явно укажите [::1]:<порт>.

Туннель при этом остаётся активным. Публичный запрос может получить временный ответ 502, а следующий запрос снова проверит локальное приложение. После запуска или восстановления приложения перезапускать туннель не требуется.

Недостаточная длина PSK

При включённом шифровании потока PSK короче минимума — клиент завершится с ошибкой валидации до создания туннеля.

Ограничения

  • CLI зависит от версии сервера: новые поля API могут требовать обновления клиента.
  • Режим guest и лимиты гостевых туннелей задаются на сервере; пользователь не может продлить TTL или сбросить квоту из CLI.
  • QUIC/DTLS могут быть недоступны, если сервер или сеть их блокирует; тогда используйте WebSocket.
  • Опрос статуса в stay-режиме создаёт периодический трафик к API; при очень большом числе процессов учитывайте лимиты.
  • Сообщения об ошибках в консоли не локализованы вне дашборда; язык зависит от версии клиента и ответов сервиса.