fxtunnel up: все туннели в фоне по одному конфигу

Если туннелей несколько, держать под каждый отдельное окно терминала неудобно. Команда fxtunnel up читает все туннели из файла fxtunnel.yaml, поднимает их в фоне и сразу возвращает терминал. Дальше fxtunnel status показывает адреса, fxtunnel down всё останавливает, а с флагом --foreground тот же клиент работает как служба systemd и стартует вместе с системой.

Ниже по шагам: как устроен файл, что происходит при запуске, куда смотреть, если туннель не поднялся, и как настроить автозапуск.

Файл с туннелями

Проще всего создать файл мастером. Он работает после входа в аккаунт (fxtunnel login, установка и вход описаны ниже, в разделе «Запуск в фоне»); без входа мастер ответит You are not logged in.:

fxtunnel init

Он спросит тип туннеля, имя, локальный порт, для HTTP — поддомен, для TCP и UDP — удалённый порт, и сохранит fxtunnel.yaml в текущей папке. Если файл уже есть, туннели можно дописать к нему или перезаписать его.

Файл можно написать и руками. Типичный набор для разработки: фронтенд, API и база:

# fxtunnel.yaml
tunnels:
  - name: web
    type: http
    local_port: 3000
    subdomain: myapp

  - name: api
    type: http
    local_port: 8080
    subdomain: myapp-api
    basic_auth: "team:SharedPass123"

  - name: db
    type: tcp
    local_port: 5432
    remote_port: 15432
    allow_ips:
      - 203.0.113.0/24

Поля каждого туннеля:

Поля повторяют флаги команд fxtunnel http, tcp и udp. Пароль из basic_auth клиент не отправляет открытым текстом: на сервер уходит его bcrypt-хеш. Файл он всё равно хранит как есть, поэтому не коммитьте его с настоящими паролями.

Кроме tunnels, в файле бывают секции server, reconnect и inspect. Их полный список с умолчаниями есть в документации по конфигурационному файлу.

Сервис в контейнере или на другой машине

Команды fxtunnel http, tcp и udp принимают только номер порта и ведут на этот же компьютер. В файле можно указать и адрес: поле local_addr. Например, база в контейнере Docker с адресом 172.17.0.2 или NAS в домашней сети:

tunnels:
  - name: nas
    type: http
    local_addr: 192.168.1.20
    local_port: 5000

Клиент подключается к 192.168.1.20:5000 и отдаёт его наружу. Машина с клиентом должна видеть этот адрес, больше ничего не нужно. Это одна из причин держать туннели в файле, даже если туннель всего один.

Где клиент ищет файл

Без флага --config клиент берёт первый найденный:

1. fxtunnel.yaml в текущей папке;
2. client.yaml в текущей папке;
3. configs/client.yaml;
4. ~/.fxtunnel/client.yaml.

Отсюда два удобных сценария. Положили файл в папку проекта, и fxtunnel up из этой папки поднимает туннели проекта. Положили в ~/.fxtunnel/client.yaml, и те же туннели поднимаются из любой папки, где нет своего fxtunnel.yaml. Другой путь задаётся явно: fxtunnel up --config path/to/config.yaml.

Запуск в фоне

Перед первым запуском клиент нужно поставить и войти. Linux и macOS:

curl -fsSL https://fxtun.ru/install.sh | sh
fxtunnel login

Windows, PowerShell: irm https://fxtun.ru/install.ps1 | iex, затем fxtunnel login.

Теперь из папки с fxtunnel.yaml:

fxtunnel up

Daemon started (PID 12345)
  HTTP: http://myapp.fxtun.ru
  HTTP: http://myapp-api.fxtun.ru
  TCP: fxtun.ru:15432
  Uptime: 1s

HTTP-адреса открываются и по https://, сертификат для *.fxtun.ru уже есть. Терминал можно закрыть: туннели работают в фоновом процессе.

Что происходит внутри: fxtunnel up запускает сам себя ещё раз в фоне, ждёт до 10 секунд, пока фоновый процесс подключится и поднимет туннели, и печатает их адреса. Если второй демон уже работает, команда ответит Daemon is already running. и нового не запустит.

Статус и остановка

fxtunnel status

Daemon running (PID 12345)
Server: tunnel.fxtun.ru:443
  HTTP: http://myapp.fxtun.ru
  HTTP: http://myapp-api.fxtun.ru
  TCP: fxtun.ru:15432
  Uptime: 2h15m0s

fxtunnel down

Daemon stopped.

Демон закрывает все туннели и завершается. Если он не запущен, обе команды ответят Daemon is not running.

Туннель на ходу

Пока демон работает, fxtunnel http, tcp и udp не открывают отдельное подключение, а добавляют туннель в демон и сразу возвращают терминал:

fxtunnel http 5173

  Tunnel added: http://lemon.fxtun.ru -> localhost:5173

Такой туннель переживает обрыв связи и переподключение, но в файл не записывается и пропадает после перезапуска демона. То, что нужно постоянно, добавляйте в fxtunnel.yaml.

Флаги --no-inspect, --inspect-addr и --insecure действуют, когда вы запускаете сам демон: fxtunnel up --no-inspect. У команды, которая добавляет туннель в уже работающий демон, они не применяются: туннель уходит в демон раньше, чем клиент читает эти флаги, и живёт с настройками демона.

Сколько туннелей поднимется на вашем тарифе

Тут важная деталь. Демон запрашивает туннели по очереди, сверху вниз по файлу, и не падает, если часть из них сервер отклонил. Он падает, только если не поднялся ни один.

На бесплатном тарифе работает один HTTP-туннель; для TCP и UDP нужен Base или выше. С файлом из примера выше на Free произойдёт вот что:

• web поднимется;
• api и db сервер отклонит с причиной tunnel limit reached;
• fxtunnel up напечатает Daemon started и один адрес вместо трёх.

Ошибки не будет на экране, она будет в логе демона: строка Failed to request tunnel с причиной server rejected tunnel: tunnel limit reached. Если на бесплатном тарифе держите в файле несколько HTTP-туннелей, ставьте самый нужный первым.

С UDP похожая история: на бесплатном тарифе UDP-туннель сервер отклонит с UDP tunnels are not available on your plan. TCP, UDP, три туннеля из примера одновременно и инспектор HTTP-запросов — это тариф Base: там пять туннелей, на Pro — пятнадцать.

Поддомены из примера (myapp, myapp-api) на бесплатном тарифе работают, пока их никто не занял и не зарезервировал. Закрепить имя за собой можно с тарифа Base, подробности — в статье «Постоянный адрес туннеля».

Где лог демона

В фоне демон не пишет в терминал. Всё, что он выводит, уходит в файл daemon.log рядом с файлом состояния:

• Linux и macOS: ~/.fxtunnel/daemon.log;
• Windows: %USERPROFILE%\.fxtunnel\daemon.log.

Лог перезаписывается при каждом fxtunnel up, так что в нём всегда последний запуск. Посмотреть:

cat ~/.fxtunnel/daemon.log

Три ситуации, когда он нужен:

• Демон не стартовал вовсе — например, неверный токен или ни один туннель не поднялся. Тогда fxtunnel up сам напечатает daemon exited during startup: и следом содержимое лога.
• Демон не успел за 10 секунд. Команда напишет Daemon not ready after 10s и подскажет путь к логу. Подождите и проверьте fxtunnel status.
• Поднялись не все туннели. Адресов меньше, чем в файле. Ищите в логе Failed to request tunnel, рядом будет причина от сервера.

Для отладки удобнее запустить демон прямо в терминале:

fxtunnel up --foreground

Клиент не уходит в фон и печатает всё на экран. Остановка — Ctrl+C.

Автозапуск через systemd

Чтобы туннели поднимались вместе с машиной, например на домашнем сервере или Raspberry Pi, оформите клиент службой systemd. Флаг --foreground здесь обязателен: systemd сам следит за процессом и перезапускает его после сбоя, отдельный фоновый процесс ему мешает.

Токен передадим через файл окружения, доступный только вашему пользователю. Сам токен создаётся в личном кабинете на fxtun.ru:

mkdir -p ~/.fxtunnel
echo 'FXTUNNEL_TOKEN=sk_fxtunnel_ваш_токен' > ~/.fxtunnel/env
chmod 600 ~/.fxtunnel/env

Файл службы /etc/systemd/system/fxtunnel.service. Замените user на своё имя пользователя, а /home/user/project — на папку с fxtunnel.yaml. Путь /home/user/.local/bin/fxtunnel — туда клиент ставит install.sh:

[Unit]
Description=fxTunnel client
After=network-online.target
Wants=network-online.target

[Service]
User=user
WorkingDirectory=/home/user/project
EnvironmentFile=/home/user/.fxtunnel/env
ExecStart=/home/user/.local/bin/fxtunnel up --foreground
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Включите и запустите:

sudo systemctl daemon-reload
sudo systemctl enable --now fxtunnel

В режиме --foreground лог идёт не в daemon.log, а в журнал systemd:

journalctl -u fxtunnel -f

fxtunnel status и fxtunnel down работают и со службой, если запускать их от того же пользователя. Но down просто остановит процесс, а Restart=always поднимет его через пять секунд. Остановить службу надолго — sudo systemctl stop fxtunnel.

Что ещё стоит знать

• С настройками по умолчанию демон переподключается сам. Пропал интернет, перезагрузился сервер: демон вернётся и заново поднимет туннели, включая добавленные на ходу. Если в файле reconnect.enabled: false или исчерпаны попытки reconnect.max_attempts, демон при обрыве завершается с disconnected from server. Под systemd его снова поднимет Restart=always.
• Порты TCP и UDP без remote_port после перезапуска демона новые. При обрыве сети порт сохраняется, при перезапуске процесса — нет. Если адрес важен, задайте remote_port. Номер может оказаться занят: тогда в логе будет port 15432 is already in use, выберите другой.
• fxtunnel без up читает тот же файл, но работает на переднем плане, пока открыт терминал. Удобно, когда туннели нужны на время одной сессии.

Что дальше

• Как закрепить поддомены из конфига за собой и подключить свой домен — «Постоянный адрес туннеля».
• Несколько сервисов проекта через туннели — «Несколько туннелей для микросервисов».
• Все параметры файла и переменные окружения — документация по конфигурационному файлу и daemon-режиму.