Эта страница поможет, если на Mac не работает то, что делает агент Ринго: веб-терминал, политики, скрипты, установка пакетов, инвентаризация ПО, Self Service; если Mac показывает только базовые данные; если агент то подключается, то пропадает. Если не выполняются профили и MDM-команды, см. страницу Команды MDM и профили.
На macOS агент устанавливается автоматически после регистрации: сервер отправляет MDM-командами профиль агента и команду установки. Агент проходит авторизацию с сертификатом, выданным через MDM, поэтому зависит от канала MDM. Подробнее см. Как устроен Ринго → агент.
Если MDM-команды (например, включение Bluetooth) выполняются, а функции агента не работают, сервер и регистрация в порядке. Ищите причину только в агенте и его соединении.
Агент работает как системная служба com.ringo.agent. Проверьте её состояние:
launchctl print system/com.ringo.agent | grep -E 'state|pid =|last exit'
Ожидаемый результат: строки pid = <номер>, last exit code = (never exited) и job state = running.
Посмотрите, какие логи есть у агента:
ls -lt /Library/Logs/com.ringo.agent/
Основной лог агента ведётся по файлу в сутки: ringo.ГГГГ-ММ-ДД.0.log, время в нём указано в UTC.
| Результат | Что это значит | Что делать |
|---|---|---|
Команда выводит Bad request., файла /usr/local/bin/ringo/agent нет |
Агент не установлен. | Агент устанавливается MDM-командой после регистрации. Проверьте её статус на вкладке Управление → Команды и убедитесь, что MDM-команды выполняются (см. Команды MDM). |
Служба есть, state = not running, last exit code не равен 0 |
Агент завершается с ошибкой при запуске. | Прочитайте ringo.agent.err и конец основного лога. |
В логе Agent configuration not found, waiting for configuration profile.. |
На Mac нет профиля «RINGO Agent Configuration Profile». | Профиль доставляется MDM-командой. Проверьте канал MDM. |
В логе socket connected и Auth verified successfully |
Агент подключён и прошёл авторизацию. | Причина не в подключении. См. Политики и пакеты. |
Чтобы перезапустить агент, выполните sudo launchctl kickstart -k system/com.ringo.agent.
Чтобы удалить агент, выполните sudo zsh /usr/local/bin/ringo/uninstall.sh. После удаления политики, инвентаризация, терминал и Self Service на этом Mac не работают. Чтобы установить агент снова, отправьте Mac команду «Обновить профиль MDM»: сервер заново отправит профиль агента и команду установки агента. Подробнее о логе агента см. Диагностика на устройстве → агент.
Найдите в основном логе агента записи о подключении. Успешное подключение выглядит так:
2026-10-13 10:32:00 | LOG - socket status change [connecting, 2]
2026-10-13 10:32:01 | LOG - socket connected
2026-10-13 10:32:01 | LOG - Changing status: connected
2026-10-13 10:32:01 | LOG - Auth verified successfully
| Запись в логе агента | Что это значит | Что делать |
|---|---|---|
socket status change [connecting, …] без последующего connected |
Агент не может подключиться к /socket.io/. |
Проверьте адреса, websocket и сертификат на странице Связь агента с сервером. |
Частые socket disconnect и Changing status: disonnected |
Соединение разрывается по таймауту прокси или балансировщика. | Связь агента с сервером → шаг 2 |
Connection error, reason: … Authentication error и Changing status: authentication failed |
Сервер отказал агенту в авторизации. | См. шаг 3. |
Connection error, reason: […] с другим текстом (например, The Internet connection appears to be offline.) и Changing status: authentication failed |
Агент не подключился из-за ошибки сети. Строку authentication failed агент пишет при любой ошибке подключения. |
Проверьте сеть Mac и Связь агента с сервером. |
Если сервер отказывает агенту в авторизации, в логе агента появляются такие записи:
2026-10-20 07:55:02 | LOG - socket status change [connecting, 2]
2026-10-20 07:55:03 | ERROR - Connection error, reason: [{
data = "Authentication error";
message = "Authentication error";
}]
2026-10-20 07:55:03 | LOG - Changing status: authentication failed
Агент повторяет попытку через несколько десятков секунд с тем же результатом. Текст Authentication error одинаков для всех причин отказа, поэтому причину нужно искать на сервере и в карточке Mac.
Часть причин записывается в лог backend. Выполните на сервере:
docker logs roll-deploy-backend --since 2h 2>&1 | grep -E 'same udid|decrypt agent auth|auth middleware|sign agent auth'
| Запись в логе backend | Что это значит | Что делать |
|---|---|---|
Failed to decrypt agent auth message for udid '…' |
Агент использует сертификат, который сервер не выпускал для этого Mac при последней регистрации: например, на Mac остался прежний сертификат агента. | См. На Mac несколько сертификатов агента. |
Agent connected with same udid: …, disconnecting |
Подключён второй агент с тем же UDID: клон виртуальной машины или два процесса агента. | Каждому UDID должно соответствовать одно устройство. Клоны регистрируйте заново. |
Agent gateway auth middleware error: no auth message или invalid message |
Агент передал неверные данные авторизации. | Обратитесь в поддержку и приложите лог агента. |
Failed to sign agent auth token for '…' |
Сервер не смог подписать ответ агенту. В логе агента при этом есть socket connected, но нет Auth verified successfully. |
Обратитесь в поддержку и приложите эту запись. |
| Записей нет | Причина в одной из проверок ниже: они в лог не записываются. | Проверьте Mac по списку ниже. |
Если записей нет, проверьте по порядку:
Hardware UUID в выводе команды system_profiler SPHardwareDataType. Найдите Mac в разделе Компьютеры по серийному номеру и сравните UDID в карточке с Hardware UUID. Если Mac не найден или UDID отличается, Mac удалён из Ринго, а агент на нём остался. Зарегистрируйте Mac заново или удалите агент.profiles status -type enrollment на Mac выводит MDM enrollment: No или в карточке Mac указано «Пользователь удалил MDM профиль: Да», Mac снят с MDM: пришло сообщение CheckOut или Apple сообщила, что push-токен недействителен. Зарегистрируйте Mac заново.Build id в логе агента) не совпадает с версией сервера, обычно после обновления Ринго, сервер сам ставит Mac MDM-команду установки агента: на вкладке Управление → Команды появляется команда «Установка приложения». Если MDM-команды на Mac не доходят, сначала устраните это (см. Команды MDM).Обновление агента после обновления Ринго. Сервер ставит устройству MDM-команду установки новой версии агента. Срок действия этой команды — 24 часа: если за это время она не выполнена, команда отменяется, и попытка повторяется позже. Если агент не обновляется, как правило, на этом Mac не работает канал MDM.
Если в системной связке ключей Mac больше одного сертификата «Ringo Agent Device Identity», агент может взять не тот, который сервер выпустил при последней регистрации. Так бывает, если на Mac остался сертификат от прежней версии Ринго. Признаки: в логе агента Authentication error, в логе backend Failed to decrypt agent auth message, а команда «Обновить профиль MDM» и повторная регистрация не помогают, потому что заменяют только текущий сертификат.
Чтобы проверить, сколько сертификатов агента на Mac, выполните:
sudo security find-certificate -a -c "Ringo Agent Device Identity" -Z /Library/Keychains/System.keychain | grep -E 'SHA-1|"labl"|"snbr"'
Ожидаемый результат — один сертификат, то есть одна группа из трёх строк:
SHA-1 hash: AAEE30E0E62723237CFA24BA2CAD2E5F79EE4738
"labl"<blob>="Ringo Agent Device Identity"
"snbr"<blob>=0x2A4DA284C19C0E0FC2D3D6B5B15CBA98 "*M\242\204…"
Если групп несколько, определите текущий сертификат. В Ринго откройте Настройки → PKI → PKI сертификаты и найдите сертификат «Ringo Agent Device Identity», в карточке которого в поле «Связанные устройства» указан этот Mac. Список отсортирован по дате выпуска, начиная с новых, поэтому текущий сертификат обычно ближе к началу. Серийный номер текущего сертификата совпадает со значением snbr одного из сертификатов на Mac без префикса 0x, регистр букв не важен. Остальные сертификаты агента на Mac — прежние.
Не удаляйте текущий сертификат. Без него агент не пройдёт авторизацию, пока вы не отправите Mac команду «Обновить профиль MDM».
Удалите каждый прежний сертификат, подставив его значение SHA-1 hash:
sudo security delete-certificate -Z <SHA-1> /Library/Keychains/System.keychain
Ожидаемый результат — команда завершается без сообщений.
Агент читает сертификат только при запуске, поэтому перезапустите его:
sudo launchctl kickstart -k system/com.ringo.agent
Через минуту проверьте конец основного лога агента. Ожидаемый результат — записи socket connected и Auth verified successfully, ошибок Authentication error больше нет.
При удалении профиля MDM агент не удаляется: Ринго удаляет агент при удалении устройства из Ринго. Получив сообщение CheckOut, сервер закрывает агенту авторизацию, и терминал перестаёт работать. Если терминал продолжает работать, сообщение CheckOut не дошло до сервера (из-за сети или WAF на /mdm/checkin). Удалите устройство из Ринго.
SystemPolicyAllFiles) входят в профиль «RINGO Agent Configuration Profile». Если профиль отсутствует или установлен не полностью, у агента нет доступа. Проверьте профиль в разделе Системные настройки → Основные → Управление устройством.Обратитесь в техническую поддержку (см. Обращение в поддержку). Приложите папку логов агента /Library/Logs/com.ringo.agent/ с Mac, Hardware UUID Mac, записи лога backend (Agent connected, Disconnected, а также вывод команды из шага 3) и результаты проверок со страницы Связь агента с сервером, выполненных из сети Mac.
Проверено на Ринго 3.0.5, октябрь 2026. Тексты ошибок — Справочник ошибок, термины — Термины.