Развёртывание моста и агентов на своей инфраструктуре

01Обзор#

Серверная часть парка состоит из двух компонентов, которые разворачиваются на вашей инфраструктуре:

Мост раздаёт по HTTP (порт 7480) публичный каталог: установщики install.sh / install.ps1, дистрибутивы агента и свой корневой сертификат ca.crt. Агенты, установленные с этого моста, доверяют именно его CA — у каждого моста собственная изолированная PKI.

Установщик install-bridge.sh выполняет всю работу идемпотентно: первый запуск создаёт PKI, секреты и службу, повторный — обновляет бинарник моста и файлы раздачи, сохраняя сертификаты, токен, коды и журнал.

02Требования#

• Linux x86_64 (amd64) — также поддерживается arm64; рекомендуемые ОС: Ubuntu/Debian, Rocky/Alma, CentOS Stream, openSUSE;
• права root или sudo;
• система инициализации systemd (установщик создаёт службу office-admin-bridge);
• утилиты curl, openssl, awk, sed;
• открытые входящие порты: 7443/tcp (mTLS агентов) и 7480/tcp (раздача установщиков);
• желательно постоянное DNS-имя или стабильный IP — агенты запоминают адрес моста при установке.

Отдельный сервер не нужен: мост — один небольшой статический бинарник без внешних зависимостей (БД — встроенная bbolt). Подойдёт минимальная VPS на 1 vCPU / 512 МБ.

03Установка одной командой#

Установщик скачивается с официального источника дистрибутивов; файлы для агентов берутся с того же зеркала (переменная OA_MIRROR, глава 04):

curl -fsSL http://sa-projects.ru:7480/install-bridge.sh \
  | sudo OA_MIRROR=http://sa-projects.ru:7480 bashКопировать

Если OA_MIRROR не задан, используется официальное зеркало по умолчанию (тот же источник, откуда скачан установщик).

Что делает скрипт

1. создаёт системного пользователя office-admin и каталог /etc/office-admin (права 0700);
2. если PKI ещё не создана — генерирует собственный центр сертификации (CA) и сертификат моста через openssl со случайным CN и SAN (localhost, 127.0.0.1, hostname, плюс заданные OA_DNS/OA_IP);
3. создаёт bridge.yaml: случайный admin_token и pairing-код enroll (оба печатаются в конце);
4. скачивает бинарник моста с зеркала и сверяет его по sha256sums.txt;
5. копирует установочные файлы агентов в публичный каталог /etc/office-admin/install/ и кладёт туда свой ca.crt;
6. ставит и запускает службу systemd office-admin-bridge;
7. проверяет API (GET /api/admin/agents с токеном) и печатает итог: токен, pairing-код, команды добавления агентов и firewall.

04Параметры установки#

Все параметры — переменные окружения перед bash, все необязательные:

Пример — мост на других портах, со своим кодом и DNS-именем:

sudo OA_LISTEN=0.0.0.0:8443 OA_PUBLIC=0.0.0.0:8480 \
     OA_CODE=office-2026:servers OA_DNS=bridge.mycompany.ru \
     bash -c "$(curl -fsSL http://sa-projects.ru:7480/install-bridge.sh)"Копировать

Обратите внимание: адрес моста, который будет указан в команде установки агентов, обязан присутствовать в SAN сертификата (глава 10).

05Структура на сервере#

Всё, что создаёт мост, лежит в /etc/office-admin/ (владелец office-admin):

06Подключение агентов#

Агент ставится одной командой с любого хоста, которому доступен публичный каталог вашего моста. Установщику передаются две переменные:

• OA_BASE — адрес раздачи моста (например http://bridge.mycompany.ru:7480); установщик сам выведет адрес mTLS-API (тот же хост, порт 7443);
• OA_CODE — pairing-код, который мост напечатал при установке (после первого подключения агент получает собственный клиентский сертификат, код больше не нужен).

Linux

OA_BASE=http://bridge.mycompany.ru:7480 OA_CODE=ваш-код \
  curl -fsSL http://bridge.mycompany.ru:7480/install.sh | bashКопировать

Windows (PowerShell от администратора)

$env:OA_BASE = "http://bridge.mycompany.ru:7480"
$env:OA_CODE = "ваш-код"
irm http://bridge.mycompany.ru:7480/install.ps1 | iexКопировать

После установки машина появляется в журнале моста (группа — из pairing-кода, имя агента — hostname машины). Посмотреть подключённых агентов:

curl -sk https://127.0.0.1:7443/api/admin/agents \
  -H "Authorization: Bearer ВАШ_ТОКЕН"Копировать

07Проверка и журнал#

Статус службы

systemctl status office-admin-bridge
systemctl restart office-admin-bridge     # при необходимостиКопировать

Журнал (что делает мост: enroll, задачи, ошибки)

journalctl -u office-admin-bridge -f       # следить
journalctl -u office-admin-bridge -n 50    # последние 50 строкКопировать

Проверка API и раздачи

# mTLS-API отвечает (200) с admin_token
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:7443/api/admin/agents \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

# публичный каталог отдаёт файлы
curl -s http://127.0.0.1:7480/versions.json | head
curl -s http://127.0.0.1:7480/ca.crt | openssl x509 -noout -subjectКопировать

Итоговая диагностика «всё сразу»:

journalctl -u office-admin-bridge -n 30 --no-pager && \
  ss -ltnp | grep -E '7443|7480'Копировать

08Сеть и firewall#

UFW (Ubuntu/Debian):

sudo ufw allow 7443/tcp comment 'mTLS агентов'
sudo ufw allow 7480/tcp comment 'раздача установщиков'
sudo ufw reloadКопировать

firewalld (Rocky/CentOS):

sudo firewall-cmd --permanent --add-port=7443/tcp --add-port=7480/tcp
sudo firewall-cmd --reloadКопировать

В облаке (VPS) дополнительно откройте порты в security group. Порт 7480 — только установочные файлы и ca.crt: после того как парк развёрнут, его можно закрыть совсем и открывать по мере необходимости.

09Обновление и перенос#

Обновление моста

Повторно запустите ту же команду установки (глава 03): скрипт переиспользует PKI, токен, коды и журнал, обновит бинарник и файлы раздачи. Агенты продолжат работать без переустановки.

Перенос на другой сервер

1. остановите службу: sudo systemctl stop office-admin-bridge;
2. упакуйте состояние: sudo tar -C /etc -czf office-admin-backup.tgz office-admin;
3. на новом сервере распакуйте архив в /etc/ (при необходимости chown -R office-admin:office-admin /etc/office-admin);
4. запустите установщик — он подхватит существующий конфиг и PKI, пересоздаст бинарник, службу и права (глава 03).

Резервное копирование

Достаточно архивировать один каталог /etc/office-admin (конфиг + PKI + журнал). Восстановление = распаковка + повторный запуск установщика.

10Сертификаты и имена (SAN)#

Как устроена PKI моста

• при первой установке мост генерирует собственный CA (ca.crt/ca.key, срок 10 лет) и сертификат моста server.crt, подписанный этим CA;
• в SAN сертификата попадают: localhost, 127.0.0.1, hostname сервера и всё, что передано в OA_DNS/OA_IP;
• агент при enroll получает клиентский сертификат от CA моста (срок — cert_days, по умолчанию 365 дней);
• агенты доверяют мосту через ca.crt, который мост кладёт в свой публичный каталог.

Правило имён

Адрес, по которому агенты ходят на мост (https://<имя>:7443), обязан присутствовать в SAN server.crt — иначе агент отвергнет сертификат. Поэтому DNS-имя (или внешний IP) задаётся при первой установке через OA_DNS/OA_IP.

Перевыпуск сертификата моста без смены CA

Если нужно добавить имя уже после установки (агенты не пострадают — CA тот же):

# сгенерируйте новый ключ и запрос
sudo openssl req -newkey rsa:2048 -nodes \
  -keyout /etc/office-admin/server.key \
  -out /tmp/server.csr -subj "/CN=office-bridge"

# подпишите своим CA с нужным SAN (перечислите все имена!)
sudo openssl x509 -req -in /tmp/server.csr \
  -CA /etc/office-admin/ca.crt -CAkey /etc/office-admin/ca.key \
  -days 825 -sha256 \
  -extfile <(printf 'subjectAltName=DNS:localhost,DNS:bridge.mycompany.ru,DNS:%s,IP:127.0.0.1\n' "$(hostname)") \
  -out /etc/office-admin/server.crt

sudo rm -f /tmp/server.csr
sudo chown office-admin:office-admin /etc/office-admin/server.key /etc/office-admin/server.crt
sudo systemctl restart office-admin-bridgeКопировать

11Безопасность#

• admin_token — ключ доступа к API моста. Храните в менеджере паролей; не передавайте в открытом виде. При утечке замените его в bridge.yaml и перезапустите службу;
• pairing-код нужен агенту один раз при enroll. После подключения агент работает по собственному клиентскому сертификату; код можно менять/добавлять в enroll_codes конфига;
• порт 7480 — ограничьте его доверенными подсетями или открывайте только на время установки (глава 08);
• ключ CA (ca.key) — никогда не покидает сервер и не раздаётся;
• служба работает под непривилегированным пользователем office-admin с ProtectSystem=strict, ProtectHome=true, NoNewPrivileges=true;
• регулярно обновляйте мост повторным запуском установщика (глава 09);
• наблюдайте за журналом journalctl -u office-admin-bridge — там видны enroll новых машин и ошибки.

12Агент на Linux и Windows#

Linux

Без прав root установка выполняется в пользовательском режиме; с sudo — как системная служба (sudo не обязателен, но нужен для системного режима и самообновления). Имя агента по умолчанию — hostname машины, при желании задаётся явно:

OA_NAME=web-01 OA_CODE=ваш-код \
  curl -fsSL http://bridge.mycompany.ru:7480/install.sh | sudo bashКопировать

Windows

Запустите PowerShell от имени администратора (правый клик по ярлыку → «Запуск от имени администратора») — установка регистрирует службу Windows и требует прав администратора, из обычного окна UAC откажет:

$env:OA_NAME = "web-01"
$env:OA_CODE = "ваш-код"
irm http://bridge.mycompany.ru:7480/install.ps1 | iexКопировать

Запуск службы под учётной записью

После установки службу можно перевести на другую учётную запись: services.msc → служба агента → «Вход в систему» → «С учётом: домен\пользователь». Это удобно, когда команды на машине должны выполняться в контексте доменной учётки (сетевые ресурсы, доступ к другим серверам по WinRM/Invoke-Command).

Самообновление

Агенты периодически сверяются с каталогом раздачи моста (versions.json) и обновляют себя сами, когда появляются новые версии (флот переходит на новую версию после подтверждения версии-гейта). Для обновления каталога раздачи перезапустите установщик моста (глава 09).

13Устранение неполадок#

Мост не запускается

Смотрите причину: journalctl -u office-admin-bridge -n 50 --no-pager. Частое — порт занят (проверьте ss -ltnp | grep 7443 и смените OA_LISTEN) или неверные права на файлы PKI (должны принадлежать office-admin).

Агент не подключается

• порт 7443 не открыт на мосту (глава 08) — проверьте ss -ltnp и firewall;
• адрес в команде агента не совпадает с SAN сертификата (глава 10) — используйте имя/IP из SAN или перевыпустите сертификат;
• на машине агента неверное время (NTP) — mTLS чувствителен к расхождению часов;
• неверный или уже использованный pairing-код — получите свежий: он в выводе установщика или в bridge.yaml.

API отвечает 401

Неверный admin_token в заголовке Authorization: Bearer …. Возьмите актуальный из /etc/office-admin/bridge.yaml.

Публичный каталог пуст или устарел

Повторно запустите установщик — он заново скопирует файлы агентов с зеркала и положит свой ca.crt. Права каталога /etc/office-admin/install: владелец office-admin, 0755.

Агент старый / не обновляется

Проверьте versions.json в каталоге раздачи и журнал моста. Если в раздаче нет новых версий — обновите каталог перезапуском установщика моста (глава 09).

14Что дальше#

1. Установите мост (глава 03) и сохраните admin_token и pairing-код;
2. добавьте первые машины командами из главы 06;
3. проверьте подключение: API-запрос из главы 06 и журнал службы (глава 07);
4. настройте обновления (глава 09) и регулярные резервные копии каталога /etc/office-admin.