¶ Агент на Linux
Эта страница поможет, если компьютер с Linux не появляется в Ринго после установки агента, не работают веб-терминал, политики, скрипты или установка пакетов, или компьютер в Ринго показан без связи. На Linux агент — единственный канал управления, поэтому любые проблемы с такими компьютерами начинаются здесь.
Файлы агента доступны только root. Выполняйте команды на этой странице с sudo или от имени root.
¶ Как устроен агент на Linux
Агент работает как служба systemd и связывается с сервером двумя способами. По постоянному соединению websocket (/socket.io/) сервер сообщает агенту, что для него есть задача, и через это же соединение работает веб-терминал. Сами задачи агент забирает и возвращает результаты запросами HTTPS к /agent/connect. Кроме того, примерно раз в 10 минут агент сам опрашивает сервер, даже если задач нет.
| Что | Где |
|---|---|
| Служба | ringo-agent (/etc/systemd/system/ringo-agent.service), включается при загрузке, при сбое перезапускается через 5 с. |
| Агент | /opt/ringo/agent/ringo |
| Модуль установки и обновления | /opt/ringo/updater/updater |
| Лог агента | /opt/ringo/logs/agent.ГГГГ-ММ-ДД.0.log, отдельный файл на каждые сутки, время в UTC. Те же записи — в журнале systemd. В версиях агента до 5ed51db лог вёлся в одном файле /opt/ringo/logs/agent.log с местным временем. |
| Лог установки и обновления | /opt/ringo/logs/updater.ГГГГ-ММ-ДД.0.log, время в UTC. Модуль обновления из прежней установки пишет в /opt/ringo/logs/updater.log с местным временем. |
| Загруженные пакеты | /opt/ringo/applications |
| Сертификаты и ключ | /var/lib/ringo/certificates/: device-identity.crt («Ringo Device Identity»), agent-device-identity.crt («Ringo Agent Device Identity»), device-identity.key, ca.crt («Ringo Built-in Certificate Authority»). |
| Идентификатор устройства | /var/lib/ringo/device_identity.cache |
| Служебные скрипты | bash |
Агент подключается к серверу напрямую. Переменные HTTPS_PROXY и HTTP_PROXY он не использует, в том числе заданные для службы. Если в сети компьютера нет прямого выхода на сервер Ринго по порту 443, откройте его.
¶ Установка агента
-
На компьютере с Linux откройте в браузере
https://<домен>/enrollи войдите с учётной записью Ринго. -
Нажмите У меня другая платформа, выберите Linux и нажмите Скачать установщик Linux.
-
Распакуйте архив
ringo-agent-linux.zip. В нём файлservice.shи модуль установки для двух архитектур:updater-amd64иupdater-arm64. -
В папке с распакованным архивом выполните
sudo ./service.shи введите1(Install Agent). Архитектуруservice.shопределяет сам.
В service.sh уже записаны адрес сервера и код регистрации, поэтому один архив подходит для любого числа компьютеров. Код регистрации действует от 7 до 90 дней с момента скачивания архива. Если архив скачан давно, скачайте новый.
Чтобы установить агент без вопросов, например из системы управления конфигурацией, выполните от имени root в папке с распакованным архивом:
./service.sh --non-interactive --action install
Результат установки записывается в /opt/ringo/logs/updater.<ГГГГ-ММ-ДД>.0.log и выводится в терминал. При успешной установке последняя запись — Ringo agent was installed successfully!. Запись systemctl reset-failed ringo-agent: … Unit ringo-agent.service not loaded. при первой установке ошибкой не является.
При установке модуль скачивает агент (/agent/manifest, /agent/bundle), регистрирует компьютер (/agent/checkin, /scep, /agent/certificate) и создаёт службу. Компьютер появляется в разделе Компьютеры сразу после регистрации, а сведения о нём — через 1–2 минуты, когда агент выполнит первую задачу.
¶ Частые причины
- Служба агента остановлена, например после обновления агента — см. шаг 1.
- Нет прямого выхода на сервер, прокси или сертификат — см. шаг 2.
- Компьютер удалён в Ринго, и агент удалил себя — см. шаг 3.
¶ Шаг 1. Служба агента установлена и запущена
Проверьте состояние агента:
sudo /opt/ringo/agent/ringo status
Ожидаемый результат:
Agent version: '5ed51db'
Device UUID: b5bc4d83-b196-4f50-9552-394515c1b657
Credential key provider: File
Credential key title: device-identity.key
Device identity certificate: found, expires at '2028-09-28 13:49:02 +0000 UTC'
Agent device identity certificate: found, expires at '2028-09-28 13:49:02 +0000 UTC'
Service status: Running
Device UUID — это UDID компьютера в Ринго. По нему ищите записи в логе backend.
| Результат | Что это значит | Что делать |
|---|---|---|
sudo: /opt/ringo/agent/ringo: command not found |
Агент не установлен или удалён. | Установите агент (см. Установка агента). Если агент удалился сам, см. шаг 3. |
Service status: Stopped |
Служба остановлена. | См. ниже. |
Device identity certificate: not found или Agent device identity certificate: not found |
Нет сертификата, с которым агент проходит авторизацию. | Переустановите агент (см. шаг 3). |
Service status: Running, сертификаты найдены |
Агент запущен. Running не означает, что агент подключён к серверу. |
Переходите к шагу 2. |
Служба остановлена. Посмотрите последние записи лога модуля обновления:
sudo tail -5 /opt/ringo/logs/updater.log
Если последние записи — Downloading agent manifest... и Stopping service..., служба остановилась во время обновления агента и не была запущена снова. Выполните обновление вручную:
sudo /opt/ringo/updater/updater update --url https://<домен>
Ожидаемый результат: последняя строка вывода — Ringo agent updated successfully!. Проверьте состояние агента снова: в Agent version должна быть новая версия, а в Service status — Running.
В остальных случаях запустите службу и посмотрите, почему она остановилась:
sudo systemctl start ringo-agent
sudo journalctl -u ringo-agent -b --no-pager -n 30
Чтобы перезапустить агент, выполните sudo systemctl restart ringo-agent.
¶ Шаг 2. Агент подключается к серверу
Посмотрите, какие логи есть у агента:
sudo ls -l /opt/ringo/logs
Покажите последние записи лога за сегодня, подставив дату по UTC:
sudo tail -30 /opt/ringo/logs/agent.<ГГГГ-ММ-ДД>.0.log
Успешный запуск и подключение выглядят так (записи identity пропущены):
2026-10-15 10:13:23 | agent-linux | service | info | agent version: 5ed51db, OS: linux
2026-10-15 10:13:44 | agent-linux | client | info | sync: got empty result, waiting for command
2026-10-15 10:13:44 | agent-linux | service | info | ringo agent started
2026-10-15 10:13:45 | agent-linux | client | info | socket: auth:verified
2026-10-15 10:13:45 | agent-linux | client | info | socket: connect
| Запись в логе агента | Что это значит | Что делать |
|---|---|---|
sync: initial sync failed: … dial tcp <адрес>:443: connect: connection refused |
Соединение отклонено: межсетевой экран на компьютере или в сети, либо на этом адресе не работает HTTPS. | Проверьте правила nftables или iptables на компьютере и межсетевой экран на пути. |
sync: initial sync failed: … dial tcp <адрес>:443: i/o timeout |
Сервер недоступен из сети компьютера. | Проверьте маршрут, межсетевой экран и VPN. Если выход в интернет возможен только через прокси, откройте прямой доступ к серверу Ринго: агент не использует прокси. |
… dial tcp: lookup <домен> on <адрес>:53: … network is unreachable сразу после загрузки |
Агент запустился раньше, чем поднялась сеть. | Действий не требуется: агент повторяет попытки и подключается, когда сеть готова. Если запись повторяется и позже, проверьте сеть и DNS компьютера. |
… tls: failed to verify certificate: x509: certificate is valid for …, not <домен> |
Агенту предъявлен сертификат другого сервера: запросы перехватывает SSL-inspection, или имя сервера указывает не на тот адрес (/etc/hosts, DNS). |
Исключите домен Ринго из инспекции. Проверьте, что getent hosts <домен> возвращает адрес сервера Ринго. |
sync: sending connect idle, но нет socket: connect; повторяются socket: connect error [timeout] или [fetch read error] |
Запросы HTTPS проходят, а соединение websocket — нет. | Проверьте путь /socket.io/ на прокси (см. Связь агента с сервером → шаги 1–2). |
sync: got 401, uninstalling |
Сервер не знает этот компьютер. | См. шаг 3. |
После того как связь восстановлена, перезапускать службу не нужно: агент повторяет попытки сам и подключается в течение минуты.
Чтобы проверить адреса сервера с этого компьютера, выполните проверки со страницы Связь агента с сервером.
¶ Шаг 3. Сервер принимает агента
Если сервер отвечает агенту кодом 401, агент удаляет себя: в логе агента появляется sync: got 401, uninstalling. Так бывает, если компьютер удалили в Ринго.
Чтобы вернуть агент, удалите данные прошлой установки и установите агент заново.
Проверьте, что службы агента нет:
systemctl status ringo-agent --no-pager
Ожидаемый результат: Unit ringo-agent.service could not be found. Если служба есть, сначала удалите агент командой sudo /opt/ringo/updater/updater uninstall.
Проверьте, остались ли данные прошлой установки:
sudo ls -la /var/lib/ringo
Если папка есть, удалите её:
sudo rm -r /var/lib/ringo
Затем установите агент заново (см. Установка агента).
Ошибки при регистрации. Если установка не завершилась, найдите причину в логе backend:
docker logs roll-deploy-backend --since 2h 2>&1 | grep -E 'Checkin:|PUT /agent/checkin'
| Запись в логе backend | Что это значит | Что делать |
|---|---|---|
Checkin: failed to verify enroll challenge for device with udid "…" |
Код регистрации в архиве недействителен: архив скачан давно. | Скачайте архив заново со страницы регистрации. |
Checkin: no enroll challenge provided for device with udid "…" |
Модуль установки запущен без кода регистрации. | Устанавливайте агент через service.sh из архива. |
PUT /agent/checkin с кодом 402 |
«Достигнуто максимальное количество компьютеров»: лицензия исчерпана. | Проверьте Настройки → Лицензия. |
¶ Редкие причины
- Пакет не устанавливается. Агент на Linux устанавливает пакеты
.debкомандойapt install,.rpm— командойdnf installилиrpm -Uvh, а архивы.tar.gzи.tgzраспаковывает в/opt/ringo. Для других форматов задача завершается ошибкойUnsupported package format: <расширение>. См. Политики и пакеты. - Подключены два агента с одним UDID. Сервер отключает второй агент с тем же UDID с записью
Agent connected with same udid: …, disconnecting. Так бывает с клоном виртуальной машины. На клоне удалите данные прошлой установки и установите агент заново (см. шаг 3). - Терминал отключён в настройках (Настройки → Терминал). Сервер отвечает «Терминал отключен».
¶ Если проблема не решена
Обратитесь в техническую поддержку (см. Обращение в поддержку). Приложите:
- папку
/opt/ringo/logsс компьютера; - вывод команды
sudo /opt/ringo/agent/ringo status; - вывод команды
sudo journalctl -u ringo-agent -b --no-pager; - записи лога backend по UDID устройства (
Agent connected,Disconnected,Checkin:,PUT /agent/connect); - результаты проверок со страницы Связь агента с сервером, выполненных с этого компьютера.
Проверено на Ринго 3.0.5 и Debian 13 (агент 5ed51db), октябрь 2026. Тексты ошибок — Справочник ошибок, термины — Термины.