¶ Как устроен Ринго
Эта страница описывает компоненты Ринго и то, как устройство обменивается данными с сервером. Зная это устройство, любую неполадку можно свести к двум вопросам: какой канал управления не работает и на каком шаге он прерывается.
¶ Обзор
Ринго управляет устройством по двум независимым каналам:
| Канал MDM | Канал агента | |
|---|---|---|
| Что это | Протокол Apple MDM, встроенный в macOS и iOS. | Программа Ринго, установленная на устройстве. |
| Платформы | macOS, iOS, iPadOS | macOS, Windows, Linux |
| Как сервер сообщает устройству о новой задаче | Push-уведомление через Apple (APNs). | Постоянное соединение websocket. |
| Адреса на сервере | /mdm/checkin, /mdm/connect, /scep, /mdm/enroll…, /enroll… |
/socket.io/, /agent/… |
| Что выполняется через канал | Профили конфигурации, MDM-команды (блокировка, стирание, обновление ОС, сведения о безопасности, FileVault, Activation Lock), установка приложений через MDM. | Политики, скрипты, пакеты (pkg, deb, rpm, msi, exe), инвентаризация ПО и дополнительные атрибуты, веб-терминал, Self Service. |
Если MDM-команды выполняются, а терминал не работает (или наоборот), причина находится в одном из каналов. Ищите её в том канале, который не работает.
¶ Компоненты
| Компонент | Контейнер | Назначение | Признаки неисправности |
|---|---|---|---|
| Reverse proxy | Встроенный nginx-proxy (с letsencrypt для выпуска сертификата) или ваш nginx либо HAProxy. |
TLS и сертификат сервера, маршрутизация путей, ограничение доступа к веб-интерфейсу. | Недоступен весь сервер или отдельные пути, ошибки сертификата. |
| Backend | roll-deploy-backend |
Всё приложение Ринго: веб-интерфейс и API, протокол Apple MDM (check-in, команды, SCEP), очередь MDM-команд, отправка push в APNs, канал агента, Self Service. | Интерфейс не открывается, /health не отвечает, регистрация и команды не работают. |
| PostgreSQL | roll-deploy-db |
Хранение всех данных Ринго. | Backend завершается с ошибкой или отвечает ошибками. |
Наружу через прокси публикуется только backend. Он же отправляет push в Apple, поэтому серверу нужен исходящий доступ к APNs (см. Сеть → от сервера до Apple).
При встроенном
nginx-proxyостановленный backend выглядит как проблема с сертификатом. Прокси перестаёт обслуживать сайт остановленного контейнера: по HTTPS отдаётся самоподписанный сертификат, по HTTP возвращается503. Если ошибка сертификата появилась сразу у всех, сначала выполнитеdocker ps -a(см. Сервер → контейнеры).
В старых версиях Ринго протокол MDM обрабатывал отдельный контейнер MicroMDM (
roll-deploy-micromdm). В версиях 2.4.4 и 3.0.5 его нет. Если этот контейнер есть в выводеdocker ps, у вас устаревшая версия.
Чтобы проверить состояние сервера, выполните:
curl -s https://<домен>/health
# {"status":"ok","details":{"db":{"status":"up"}}}
Если ответа нет, backend не запущен. Если у компонента указано down, неисправен этот компонент. Версия Ринго указана в разделе Настройки → Информация о системе:
¶ Сертификаты и их сроки
Многие внезапные сбои вызваны истёкшим сертификатом. В Ринго используются сертификаты четырёх видов:
| Сертификат | Где посмотреть | Срок действия | Последствия истечения |
|---|---|---|---|
| APNs (push-сертификат) | Настройки → Сертификат APNS, поле «Истекает» | 1 год | Push не уходят ни на одно устройство, все MDM-команды остаются в статусе «В очереди». |
| Сертификат устройства («Ringo Device Identity», выдаётся при регистрации) | Карточка устройства, поле «Сертификат энролл профиля истечет» | 1 год | Отправьте команду «Обновить профиль MDM» до истечения срока: устройство получит новый сертификат на год. |
| TLS-сертификат сервера | На reverse proxy | Задаёт удостоверяющий центр (у Let's Encrypt — 90 дней) | Устройства и агенты не могут подключиться. Прокси должен отдавать полную цепочку: сертификат сервера и промежуточный. |
| Сертификат агента («Ringo Agent Device Identity») | Системная связка ключей macOS; выдаётся MDM-командой | 5 лет, выдаётся заново при каждой регистрации и «Обновить профиль MDM» | Агент не проходит авторизацию: не работают политики, инвентаризация и терминал, хотя профили устанавливаются. |
Продлевайте APNs-сертификат кнопкой Renew, а не Create. Новый сертификат (Create) получает другой идентификатор (topic, поле «Идентификатор» на странице выше). Устройства, зарегистрированные со старым сертификатом, перестанут получать push, и их придётся регистрировать заново. Продление (Renew) сохраняет идентификатор.
¶ Жизненный цикл устройства Apple
¶ 1. Регистрация (enrollment)
Каждый шаг отражается в логе backend (см. Логи): mdm.Authenticate → mdm.TokenUpdate → device.enroll.mdm → Agent connected → device.enroll.agent. Шаг, на котором остановилась регистрация, определяется по первому отсутствующему событию. На Mac те же шаги видны в системном журнале (см. Диагностика на устройстве).
¶ 2. Доставка MDM-команды (профиль, команда, приложение)
Что важно для диагностики:
- Push не содержит команду. Он только сообщает устройству, что команды есть, и устройство само забирает их по HTTPS. Поэтому должны работать оба пути: от сервера до Apple (push) и от устройства до сервера.
- Пока устройство не обратилось к
/mdm/connect, команда остаётся в статусе «В очереди». Это означает, что push не дошёл или устройство не смогло подключиться к серверу (выключено, нет сети, нет доступа к серверу). - Статус «Отправлено» без результата означает, что сервер выдал команду, но ответ устройства не пришёл.
- Ответ
NotNow(статус «Отложено») означает, что устройство получило команду, но сейчас не может её выполнить. Чаще всего экран заблокирован, а команде нужен доступ к связке ключей. Это не ошибка: устройство запросит команду снова. - Ответ
Errorозначает, что устройство отказалось выполнить команду. Причина указана в тексте ошибки (значок «?»), и сеть здесь ни при чём. - Команды выполняются по одной: устройство отвечает на текущую команду и в том же соединении получает следующую.
¶ Статусы команды в Ринго
Статусы показаны в карточке устройства на вкладке Управление → Команды. Колонки: «Имя», «Статус», «Добавлена», «Отправлена». Недавние события отображаются в относительном виде, например «29 минут назад».
| Статус | Что произошло |
|---|---|
| В очереди | Команда ожидает. Устройство ещё ни разу её не забирало, колонка «Отправлена» пустая. |
| Отправлено | Сервер выдал команду устройству в ответе на /mdm/connect, ответа пока нет. В колонке «Отправлена» указано время выдачи. |
| Отложено | Устройство хотя бы раз ответило NotNow, команда ожидает повтора. Статус сохраняется и при повторной выдаче, пока команда не будет выполнена, отклонена или отменена. |
| Выполнено | Устройство ответило Acknowledged. |
| Ошибка | Устройство ответило Error. Текст ошибки доступен под значком «?». |
| Отменено | Команду отменил администратор или сервер: после 50 ответов NotNow, после того как Apple сообщила, что push-токен устройства недействителен (см. ниже), после повторной регистрации устройства профилем или когда агент сообщил, что профиля MDM на Mac нет. |
Как сервер обрабатывает очередь:
- Команды одного устройства выдаются по одной: сначала по приоритету, затем по времени создания.
- Команда в статусе «Отправлено», на которую устройство не ответило, выдаётся повторно при следующем подключении устройства.
- Push отправляется сразу после постановки команды в очередь. Кроме того, каждые 30 минут сервер повторно отправляет push всем устройствам с невыполненными командами. Поэтому если команда остаётся в статусе «В очереди» несколько часов, причина не в сервере: устройство не подключается.
- После ответа
NotNowповтор откладывается на нарастающий интервал: 5 с, 15 с, 30 с, 1 мин, 3 мин, 5 мин, затем каждые 10 мин. Другие команды в это время выдаются как обычно. После 50 ответовNotNowкоманды установки и удаления профилей и приложений, а также сбора сведений отменяются автоматически. Порог задаёт переменная окружения backendMDM_NOT_NOW_MAX_ATTEMPTS: по умолчанию 50, значение0отключает автоматическую отмену. В стандартномdocker-compose.ymlеё нет. Чтобы изменить порог, добавьте её в разделenvironmentсервисаbackendи выполнитеdocker compose up -d. - Если Apple сообщает, что push-токен устройства недействителен (
Unregistered: устройство стёрто или профиль MDM удалён), Ринго снимает устройство с MDM-учёта, отмечает в карточке «Пользователь удалил MDM профиль: Да» и отменяет все невыполненные команды этого устройства.
Как разбирать проблему по статусу команды, описано на странице Команды MDM и профили.
¶ Статусы в других разделах
MDM-команды, запуски политик, профили и массовые действия используют разные наборы статусов. Например, статус «Выполнено» у команды и «Успешно» у политики — это разные статусы.
| Где | Статусы | Подробнее |
|---|---|---|
| Карточка устройства → Управление → Команды | В очереди, Отправлено, Отложено, Выполнено, Ошибка, Отменено | Статусы команды |
| Политика → запуски; карточка устройства → Управление → Политики | Запланировано, В процессе, Успешно, Не удалось, Ожидает отмены, Отменен | Статусы запуска политики |
| Профили, колонка «Статус» | Добавлен, Ожидает удаления, Удалён | Статусы профиля |
| Профиль → Журналы | В ожидании, Выполнено, Не удалось, Ожидает удаления, Удалён, Ошибка удаления | Статусы профиля |
| Массовые действия | В ожидании, Отправлено, Выполнено, Ошибка, Отменяется, Отменено | Для каждого устройства массовое действие — это MDM-команда. Разбирайте проблему по статусу этой команды. |
¶ 3. Служебные сообщения на /mdm/checkin
Помимо ответов на команды, устройство само отправляет сообщения на /mdm/checkin:
| Сообщение | Когда отправляется | Если не дошло до сервера |
|---|---|---|
Authenticate |
При установке enroll-профиля. | Регистрация прерывается. |
TokenUpdate |
После регистрации и при смене push-токена. | Сервер не знает push-токен: push не доходят, команды остаются в статусе «В очереди». |
SetBootstrapToken |
macOS: после регистрации, если у пользователя есть Secure Token. | На сервере нет Bootstrap Token: не выдаётся Secure Token, не устанавливаются обновления на Apple silicon. |
GetBootstrapToken |
macOS: при запросе Bootstrap Token у сервера, например при создании пользователя. | Mac не получает Secure Token через MDM. |
CheckOut |
Пользователь удалил профиль MDM. | Ринго продолжает считать устройство управляемым, агент продолжает работать. |
Других сообщений check-in Ринго 3.0.5 не обрабатывает. Пользовательский канал macOS (UserAuthenticate) и декларативное управление (DeclarativeManagement) не поддерживаются.
¶ Как работает агент
- На macOS агент устанавливается автоматически после регистрации. Сервер отправляет профиль «RINGO Agent Configuration Profile» (настройки подключения, сертификат агента и разрешения PPPC) и команду установки агента. На Windows и Linux агент — единственный способ управления; его устанавливают вручную со страницы регистрации.
- На macOS агент работает как системная служба
com.ringo.agent(/Library/LaunchDaemons/com.ringo.agent.plist, исполняемый файл/usr/local/bin/ringo/agent). При сбое система перезапускает его автоматически. - Агент поддерживает постоянное соединение websocket с
/socket.io/. По нему сервер передаёт команды (по системным требованиям Ринго агент реагирует примерно за секунду), а агент возвращает результаты. Сервер отправляет ping каждые 25 с и ждёт ответа 20 с. Прокси должен пропускать заголовокUpgrade: websocketи не разрывать долгие соединения. - Пакет агента (около 800 КБ) и обновления загружаются с
/agent/bundle, версия сверяется по/agent/manifest. - Агент проходит авторизацию с сертификатом «Ringo Agent Device Identity», выданным Ринго. Сервер принимает агента, только если устройство зарегистрировано в MDM, другой агент с тем же UDID не подключён, а сборка агента совпадает с версией сервера. Поэтому на macOS агент зависит от канала MDM: после
CheckOutавторизация закрывается, а устаревший после обновления Ринго агент переустанавливается MDM-командой. Если MDM на устройстве не работает, агент не сможет обновиться и, как следствие, подключиться к серверу. - Пакеты агент загружает с точек распространения: сначала пробует HTTP-точки, затем SMB, пока загрузка не пройдёт успешно. Порядок точек внутри каждого типа не совпадает с порядком в списке настроек, поэтому пакет должен быть доступен на одной из точек. Загруженный пакет сохраняется в
/Library/Application Support/Ringo. - Пакеты устанавливаются от имени root командой
installer -pkg <файл> -target /. Доступ к файлам (SystemPolicyAllFiles) агенту даёт настройка PPPC в профиле агента. - Инвентаризацию ПО на macOS агент собирает через
system_profiler, который использует индекс Spotlight.
Логи агента на macOS находятся в /Library/Logs/com.ringo.agent/ (см. Диагностика на устройстве → агент).
¶ Выполнение задачи агентом (политика, скрипт, пакет)
Задачи агенту — шаги политик, скрипты, установка пакетов, сбор сведений — передаются по соединению websocket, без участия Apple. Так выполняется задача на Mac:
Как это проявляется в логах:
| Этап | Лог backend | Лог агента на Mac |
|---|---|---|
| Сервер отправил команду | Agent emit (command:create); Udid: …; Command id: … |
— |
| Агент принял команду | Agent event (command:queued); Udid: … |
command queued <id> |
| Выполнение началось | Agent event (command:started); Udid: … |
command started <id> |
| Выполнение завершено | Agent event (command:completed); Udid: …; Data: {"command_id":"…","exit_code":0} |
вывод между ### Command <id> stdout ### и ### Command <id> stderr END ###, затем command completed <id> |
Что важно для диагностики:
- Если агент не на связи, команда ожидает на сервере. При подключении и авторизации агента сервер сразу передаёт ему следующую команду и все команды, которые агент ещё не принял. Ожидающие команды хранятся 40 дней. Если агент не подключился к серверу, запуск политики остаётся в статусе «Запланировано».
- На устройстве выполняется одна задача за раз. Пока на устройстве выполняется запуск одной политики, запуски других политик ожидают в статусе «Запланировано» и начинаются по очереди. Шаги одной политики выполняются последовательно.
- Сервер проверяет выполнение каждые 5 минут. При проверке он повторно отправляет команды, которые агент не принял, завершает просроченные команды и запускает ожидающие запуски политик.
- Таймаут задаётся для каждой команды. Если агент не сообщил результат в течение таймаута плюс 2 минуты, сервер завершает команду с ошибкой, и запуск политики получает статус «Не удалось». Таймаут скриптов политик задаётся в разделе Настройки → Конфигурация скриптов.
- Если агент подключён, но не принял команду в течение таймаута плюс 2 минуты, сервер завершает её с ошибкой. Это признак того, что команда не доходит до агента, хотя соединение есть.
- Если агент переподключился во время выполнения и не сообщил о незавершённой команде, сервер завершает эту команду с ошибкой.
- Сеанс веб-терминала завершается при разрыве соединения агента.
На Windows и Linux порядок отличается в одном шаге: по соединению websocket сервер только сообщает агенту, что для него есть команды (command:check), а агент сам забирает команду и возвращает результат по HTTPS через /agent/connect. Поэтому на этих платформах путь /agent/ должен быть доступен так же, как /socket.io/.
Статусы запуска политики и порядок действий при сбоях описаны на странице Политики, пакеты, инвентаризация, Self Service.
¶ Задания по расписанию
Часть команд Ринго ставит в очередь автоматически. Расписание работает по часам контейнера backend, которые идут в UTC (00:00 UTC — это 03:00 по Москве). Интерфейс показывает время в часовом поясе браузера.
| Задание | Когда (UTC) |
|---|---|
| Повторный push устройствам с невыполненными командами | Каждые 30 мин |
| Повтор неудавшихся удалений профилей | Каждые 30 мин |
| Проверка интервальных политик | Каждые 5 мин |
SecurityInfo (FileVault, состояние безопасности) для всех зарегистрированных устройств. Push отправляется сразу. |
00:00 и 12:00 |
| Получение списка доступных обновлений ОС на Mac. Команда ставится в очередь без push и уходит при ближайшем 30-минутном повторе. | Проверка в 00:00 и 12:00. Команда ставится, если прошёл интервал из Настройки → Настройки устройств, поле «Интервал проверки доступных обновлений ОС (в днях)»; по умолчанию 1 день. |
| Пересчёт смарт-групп, синхронизация LDAP | Каждый час |
| Проверка связи с устройствами iOS (запрос имени устройства) | Проверка каждый час. Запрос уходит, если прошёл интервал из Настройки → Настройки устройств, поле «Интервал проверки подключения мобильных устройств (в часах)»; по умолчанию 1 час. |
| Обновление информации об устройствах iOS | По полям «Частота обновления информации о мобильных устройствах», «День недели для обновления» и «Время обновления» в Настройки → Настройки устройств; по умолчанию раз в неделю, в понедельник в 00:00 UTC. Сервер проверяет это каждые 30 мин. |
| Проверка приложений на устройствах | 14:00 |
Поэтому в списке команд устройства встречаются команды, которые администратор не отправлял. Каждая такая команда ставится в одном экземпляре: новая не создаётся, пока предыдущая того же типа не выполнена.
¶ Функции, каналы и первые проверки
| Не работает | Канал | Что проверить в первую очередь |
|---|---|---|
| Профили, MDM-команды, установка приложений через MDM | MDM | APNs-сертификат, доставку push, доступность /mdm/connect. |
| Регистрация macOS и iOS | MDM | Доступность /enroll, /mdm/enroll, /scep, /mdm/checkin; лицензию. |
| Политики, скрипты, пакеты, терминал, инвентаризация ПО | Агент | Запущен ли агент, соединение websocket с /socket.io/, полноту цепочки TLS-сертификата. |
| Любые функции на Windows и Linux | Агент | То же. |
| Self Service | Агент (вход по сертификату агента) | Работу агента, доступность /api/v1/self-service, опубликованы ли элементы для устройства. |
| Нет ключа восстановления FileVault | MDM | Команду SecurityInfo (00:00 и 12:00 UTC). |
| Не работает ничего | Сервер или сеть | /health, контейнеры, TLS-сертификат, DNS. |
Чтобы выбрать порядок действий по симптому, перейдите на страницу Начните здесь.
Проверено на Ринго 3.0.5, октябрь 2026. Тексты ошибок — Справочник ошибок, термины — Термины.