Актуально для v2.5.0 и выше.
Быстрый путь:
./install.shделает всё, что описано ниже, одной командой (сертификаты,.env.prod, ключ подписи релизов, стек, сборка и публикация агентов). Обновление —./update.sh. См. self-hosted-deploy.md. Этот документ — те же шаги вручную, для понимания и нестандартных случаев, плюс исчерпывающий справочник по переменным, портам и типичным проблемам.
| Парк устройств | CPU | RAM | Диск |
|---|---|---|---|
| до 50 устройств | 1 vCPU | 2 ГБ | 20 ГБ SSD |
| до 500 устройств | 2 vCPU | 4 ГБ | 40 ГБ SSD |
| 500+ устройств | 4+ vCPU | 8+ ГБ | 80+ ГБ SSD |
Диск нужен под базу данных PostgreSQL и бинарные релизы агентов. Рекомендуется SSD — PostgreSQL чувствителен к задержке I/O.
- Linux-сервер (Ubuntu 22.04+, Debian 12+)
- Docker + Docker Compose v2 (обязательно, см. ниже)
- Открытые порты:
80/443(веб + enrollment + загрузки),50051(gRPC для агентов) - Домен или статический IP
Требуется Docker Compose v2. На Ubuntu 22.04 по умолчанию установлен
docker-composev1.29.2, который несовместим с Docker Engine 25+ и падает с ошибкойKeyError: 'ContainerConfig'при пересоздании контейнеров. Все команды ниже используют синтаксис v2 (docker composeбез дефиса).Установка Compose v2:
sudo mkdir -p /usr/local/lib/docker/cli-plugins sudo curl -SL https://github.com/docker/compose/releases/download/v2.27.1/docker-compose-linux-x86_64 \ -o /usr/local/lib/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose docker compose version # должно вывести Docker Compose version v2.x.x
Ставьте и обновляйте MDM от обычного пользователя, входящего в группу docker:
sudo usermod -aG docker "$USER"
# перелогиньтесь (новая группа применяется только к новой сессии)
id -nG # в списке должен появиться dockerВажно: никогда не запускайте
sudo ./install.shилиsudo ./update.sh. Под root каталог.git,.env.prodиrelease_ed25519.pemстанут root-owned, и следующийgit pullот обычного пользователя сломается на правах. Репозиторий, ключи и.env.prodдолжны принадлежать тому пользователю, который запускает скрипты. Сами скрипты вызываютdockerбезsudo— именно поэтому нужна группа.
Скопируйте шаблон, заполните и запустите — так все параметры уходят в установку сразу и наверняка (ничего не забудется в инлайновых переменных):
cp install.env.example install.env
nano install.env # заполните PUBLIC_ADDR и ADMIN_EMAIL / ADMIN_PASSWORD
./install.shinstall.env лежит в .gitignore (в нём пароль администратора) — коммитить его
нельзя. Инлайновые переменные при запуске (VAR=… ./install.sh) переопределяют файл.
install.sh сгенерирует сертификаты (подставив в SAN нужные адреса), создаст
.env.prod со случайными секретами, сгенерирует per-deployer ключ подписи релизов,
поднимет стек, соберёт и опубликует агентов, а также разложит установщики
(releases/RoutineOps-agent.msi, releases/RoutineOps-agent.pkg).
Обновление установщиков MSI/PKG в
/downloads/. Кнопки «Скачать MSI/PKG» в UI отдаютreleases/RoutineOps-agent.{msi,pkg}. Эти файлы обновляют иinstall.sh, иupdate.sh: оба копируют их изbuild/msi/RoutineOps-agent.msiиbuild/pkg/RoutineOps-agent.pkgвнутри build-контейнера (releases/становится root-owned после публикации, поэтому host-sidecpот деплойера падал быPermission denied, аumask 077дал бы 600 — в контейнере root +umask 022→ 644, читаемо сервером). Поэтому чтобы выложить новый установщик, достаточно положить свежесобранный файл вbuild/msi/RoutineOps-agent.msi/build/pkg/RoutineOps-agent.pkg(MSI — на Windows черезbuild/msi/build-msi.ps1, PKG — на macOS) и подтянуть его в репо на сервере (git pullделает самupdate.sh): следующий./update.shили./install.shскопирует его вreleases/. Ручнойsudo cp build/msi/RoutineOps-agent.msi releases/RoutineOps-agent.msi && sudo chmod 644 releases/RoutineOps-agent.*нужен только на сервере со старыми скриптами (до июля 2026, когдаupdate.shустановщики не обновлял). На уже установленные агенты выкладка нового установщика не влияет — они обновляются через self-update.
Ключевые поля install.env:
PUBLIC_ADDR— внешний адрес (IP или домен), по которому к серверу ходят агенты и браузеры. За NAT/VPNhostname -Iдаёт ВНУТРЕННИЙ IP — задайте внешний адрес ЯВНО, иначе enroll по внешнему адресу упадёт на TLS: адрес обязан быть в SAN сертификата. Внутренний IP хоста добавляется в SAN автоматически.ADMIN_PASSWORDобязателен — без негоinstall.shотказывается работать. Пароль обязан пройти политику сложности (≥8 символов, минимум 3 из 4 классов: строчные / прописные / цифры / спецсимволы). Слабый пароль сервер отвергнет: админ не создастся, а в логе будетseed admin failed— войти будет некем.- Опционально:
SERVER_HOST(доп. DNS-имя в SAN), SMTP-поля (почта инвайтов/сброса),TELEGRAM_BOT_TOKEN(алерты),COOKIE_SECURE, retention — см. комментарии в шаблоне.
Без
install.envможно и инлайном (всё то же самое переменными окружения):PUBLIC_ADDR=mdm.example.com ADMIN_EMAIL=you@example.com ADMIN_PASSWORD=… ./install.sh
Дальше — раздел «Проверка». Остальное в этом разделе — ручной путь.
git clone <URL-этого-репозитория>
cd RoutineOpsКаталог называется
RoutineOps(по имени репозитория), а не как-либо иначе.
Серверный сертификат обязан покрывать адрес, по которому к серверу обращаются
агенты. Базовый набор SAN (DNS:localhost, DNS:routineops-server, IP:127.0.0.1)
скрипт проставляет сам; внешний адрес добавляется через переменную SERVER_SANS:
SERVER_SANS="IP:203.0.113.10,DNS:mdm.example.com" bash scripts/gen-certs.shСоздаст certs/ca.crt, ca.key, server.crt, server.key.
Важно: редактировать
scripts/gen-certs.shне нужно — SAN задаётся только черезSERVER_SANS(install.shподставляет туда публичный IP хоста автоматически). Скрипт идемпотентен: еслиcerts/server.keyуже есть, он пропускает генерацию. Чтобы перевыпустить сертификат с новым SAN, сначала уберите старую пару (mv certs/server.crt certs/server.crt.bakи то же сserver.key) — CA при этом не пострадает.
Все переменные живут в одном файле .env.prod (его читают и сервер, и postgres,
и migrate-сервис). Скопируйте шаблон и заполните:
cp .env.prod.example .env.prod
chmod 600 .env.prodМинимум, который нужно заполнить:
POSTGRES_PASSWORD=<придумайте_пароль>
# Сервер ходит ролью приложения (без права обходить RLS), миграции — владельцем базы.
DATABASE_DSN=postgres://mdm_app:<пароль_приложения>@postgres:5432/mdm?sslmode=disable
MIGRATION_DSN=postgres://mdm:<тот_же_пароль>@postgres:5432/mdm?sslmode=disable
REDIS_ADDR=redis:6379
SERVER_CERT=certs/server.crt
SERVER_KEY=certs/server.key
CA_CERT=certs/ca.crt
CA_KEY=certs/ca.key
JWT_SECRET=<openssl rand -hex 32>
SEED_ADMIN_EMAIL=admin@example.com
SEED_ADMIN_PASSWORD=<пароль_администратора>
PUBLIC_WEB_URL=https://mdm.example.com
COOKIE_SECURE=trueВажно: не используйте в паролях спецсимвол
$— он интерпретируется как начало переменной в env-файлах и приведёт к ошибке аутентификации.Хост в
DATABASE_DSN—postgres(имя сервиса в compose), а неlocalhost.Две роли, а не одна.
DATABASE_DSN— роль приложенияmdm_app(NOSUPERUSER NOBYPASSRLS),MIGRATION_DSN— владелец базы. Изоляция тенантов держится наROW LEVEL SECURITY, а владелец базы её обходит: один DSN под владельцем означает, что изоляция существует на бумаге. При этом миграции обязан катить именно владелец — роль без прав DDL не выполнит. Обе строки заполняетinstall.shсам; парольmdm_appставится после наката миграции049, потому что пароль в SQL-файле = утечка. Гейт:migrateотказывается катить DDL, еслиMIGRATION_DSNне задан, а сервер уже переведён на роль приложения. Подробно — self-hosted-deploy.md.
PUBLIC_WEB_URL— сhttps://: nginx редиректит 80 → 443. Это значение используется в генерируемых installer-скриптах и ссылках на загрузку агентов.
RELEASE_PUBKEYне заполняйте вручную —install.shгенерирует per-deployer ключ подписи релизов и дописывает его сам (см. self-hosted-deploy.md).
export VERSION=$(cat VERSION) # версия релиза — build-arg для образа сервера
docker compose -f docker-compose.prod.yml up -d --buildВажно:
export VERSIONобязателен. Compose интерполирует build-argVERSIONтолько из окружения запуска (env_fileна сборку не влияет), и без него образ соберётся с версиейdev. Агент версииdevпропускает самообновление, а сравнение версий на сервере ломается../install.shи./update.shделают это сами.
Миграции БД накатывает автоматически compose-сервис migrate (таблица
schema_migrations, fail-closed: сервер не стартует, пока миграции не применены).
Ручной psql для миграций не нужен.
На существующей инсталляции, где миграции когда-то накатывались вручную (до появления
schema_migrations), перед первым./update.shнужен одноразовый backfill — иначеmigrateоткажется стартовать. Процедура: self-hosted-deploy.md.
Всё читается из .env.prod. Значения в файле всегда перекрывают дефолты из
кода (см. «Ловушка перекрытых дефолтов»).
| Переменная | Дефолт | Назначение |
|---|---|---|
POSTGRES_PASSWORD |
— | Пароль суперпользователя postgres-контейнера. Без него postgres не стартует. Без $ в значении |
DATABASE_DSN |
postgres://mdm:mdm_dev_password@localhost:5432/mdm?sslmode=prefer |
DSN сервера — роль приложения mdm_app без права обходить RLS. В проде задавать явно, хост — postgres |
MIGRATION_DSN |
— (fallback на DATABASE_DSN) |
DSN владельца базы: под ним катятся миграции (DDL). Заполняется install.sh; при переводе сервера на mdm_app обязателен |
REDIS_ADDR |
localhost:6379 |
Адрес Redis. В compose — redis:6379 |
JWT_SECRET |
dev-secret-change-in-production |
Корень доверия админ-сессий. openssl rand -hex 32. Ротация — jwt-secret-rotation.md |
PUBLIC_WEB_URL |
https://localhost:8081 |
Внешний URL сервера. Подставляется в installer-скрипты, ссылки на загрузку и инвайты |
| Переменная | Дефолт | Назначение |
|---|---|---|
SERVER_CERT |
certs/server.crt |
Серверный сертификат (TLS для REST и gRPC) |
SERVER_KEY |
certs/server.key |
Приватный ключ сервера |
CA_CERT |
certs/ca.crt |
Корневой CA: проверка клиентских сертификатов агентов |
CA_KEY |
certs/ca.key |
Ключ CA: подпись сертификатов при enrollment. Нет ключа — enrollment выключен |
| Переменная | Дефолт | Назначение |
|---|---|---|
SEED_ADMIN_EMAIL |
пусто | Email первого админа. Пусто = seed не выполняется |
SEED_ADMIN_PASSWORD |
пусто | Пароль первого админа. Обязан пройти политику сложности (≥8 символов, 3 из 4 классов), иначе seed admin failed |
| Переменная | Дефолт | Назначение |
|---|---|---|
HTTP_ADDR |
:8081 |
Адрес REST/HTTPS-сервера внутри контейнера. Наружу его проксирует nginx |
GRPC_ADDR |
:50051 |
Адрес gRPC-сервера для агентов |
RELEASES_DIR |
./releases |
Каталог с опубликованными бинарями агентов; раздаётся как /downloads/* |
COOKIE_SECURE |
false |
true → на cookie админ-сессии ставится флаг Secure (уходит только по HTTPS). Ставьте true на любом деплое за HTTPS; любое другое значение = выключено |
TRUSTED_PROXIES |
приватные и loopback-диапазоны | С каких адресов верить заголовку X-Real-IP / X-Forwarded-For при определении адреса клиента. Список CIDR или голых адресов через запятую |
TRUSTED_PROXIESнужен, только если ваш обратный прокси стоит на публичном адресе (отдельный хост, облачный балансер). В штатной установке nginx живёт рядом в compose-сети, его адрес приватный, и дефолта достаточно.Зачем это вообще: лимиты на попытки входа считаются по адресу клиента, а из-за прокси сервер видит адрес прокси. Без восстановления настоящего адреса все клиенты попадают в один общий счётчик — перебор с одной машины съедает лимит и роняет вход остальным. Если прокси публичный и не перечислен здесь, будет ровно это.
Заголовку верят только от перечисленных адресов. Запрос с любого другого адреса со своим
X-Real-IPзаголовок не обманет — иначе лимит обходился бы новым значением на каждый запрос.
COOKIE_SECUREне прописывается автоматически.install.shего в.env.prodне пишет, то есть по умолчанию флагSecureна cookie сессии не ставится. ДобавьтеCOOKIE_SECURE=trueвручную и перезапустите сервер.
| Переменная | Дефолт | Назначение |
|---|---|---|
DATA_RETENTION_DAYS |
7 |
Срок хранения операционных данных (алерты, результаты скриптов). 0 = бессрочно |
AUDIT_RETENTION_DAYS |
365 |
Отдельный, длинный срок хранения audit_log. 0 = бессрочно |
AGENT_UNREACHABLE_MINUTES |
10080 (7 суток) |
Сколько минут без heartbeat до алерта agent_unreachable |
AGENT_UNREACHABLE_COOLDOWN_MINUTES |
360 (6 часов) |
Окно подавления повторных agent_unreachable по одному устройству |
AUDIT_ARCHIVE_DIR |
— (пусто) | [Enterprise] Каталог архива журнала: записи выгружаются в JSONL.gz перед удалением по сроку. Пусто = архива нет; тогда AUDIT_RETENTION_DAYS уничтожает записи безвозвратно вместе с цепочкой, ради которой журнал и заведён |
ALERT_ESCALATE_AFTER_MINUTES |
30 |
[Enterprise] Через сколько минут неподтверждённый алерт эскалируется |
ALERT_ESCALATE_REPEAT_MINUTES |
60 |
[Enterprise] Период повторной эскалации, пока алерт не подтверждён |
ALERT_ESCALATE_MIN_SEVERITY |
critical |
[Enterprise] С какого уровня критичности включается эскалация |
SCREEN_DIR |
./screen-recordings |
[Enterprise] Каталог записей сеансов удалённого стола. Отдельный том: записи невосстановимы, в отличие от releases/, который пересоздаётся из БД. Ретеншен — 30 дней |
| Переменная | Дефолт | Назначение |
|---|---|---|
SMTP_HOST |
пусто | Хост SMTP. Пусто = почта отключена (в логе mailer disabled) |
SMTP_PORT |
587 |
587 = STARTTLS, 465 = implicit TLS |
SMTP_USER |
пусто | Логин SMTP |
SMTP_PASS |
пусто | Пароль SMTP — как правило, app password, а не пароль от ящика |
SMTP_FROM |
noreply@mdm.local |
Адрес отправителя. Дефолтный домен отвергнет любой реальный релей — задавайте явно |
SMTP_TLS |
false |
true → implicit TLS (порт 465). Любое значение кроме true = STARTTLS |
TELEGRAM_BOT_TOKEN |
пусто | Токен своего бота от @BotFather. Пусто = Telegram-уведомления отключены |
| Переменная | Дефолт | Назначение |
|---|---|---|
RELEASE_PUBKEY |
пусто | Публичный ed25519-ключ подписи релизов. Заполняется install.sh автоматически, вручную не трогать |
Enterprise-переменные (ESCROW_RECIPIENT, ESCROW_RECIPIENT_FPR) free-сборкой
игнорируются — см. .env.prod.example и ROADMAP.md.
Переменная, физически присутствующая в .env.prod, перекрывает дефолт из кода
навсегда. Если в новом релизе дефолт изменился, до вашей инсталляции он не доедет —
там продолжит действовать старое значение из файла. Перед обновлением сверьте:
grep -nE '^[A-Z_]+=' .env.prodи сравните с дефолтами в internal/server/config/config.go. Чаще всего расходятся
DATA_RETENTION_DAYS, AUDIT_RETENTION_DAYS, AGENT_UNREACHABLE_MINUTES
(текущий дефолт 10080 = 7 суток; старые инсталляции нередко держат минуты и
получают шквал ложных алертов) и AGENT_UNREACHABLE_COOLDOWN_MINUTES.
| Порт | Наружу | Протокол | Назначение |
|---|---|---|---|
80 |
да | HTTP | Редирект на 443; исключение — /downloads/ раздаётся прямо по HTTP (бинари публичны, установщик сверяет sha256-пин) |
443 |
да | HTTPS | Веб-интерфейс, REST API, enrollment, /ca.crt, /downloads/ (nginx) |
50051 |
да | gRPC/TLS | Постоянное соединение агентов (mTLS) |
8081 |
нет — bind 127.0.0.1 |
HTTPS | REST API напрямую, минуя nginx. /healthz живёт только здесь — nginx его не проксирует |
5432 |
нет — bind 127.0.0.1 |
PostgreSQL | База данных |
| Redis | нет — только внутри compose-сети | — | Очередь доставки задач (asynq) |
Агенты подключаются к 443 (enrollment, скачивание CA и бинарей — адрес берётся
из PUBLIC_WEB_URL) и 50051 (основной канал). Схема компонентов —
ARCHITECTURE.md.
Перед добавлением первого устройства бинарь агента должен быть собран, подписан и зарегистрирован в БД. Без этого installer-скрипт генерируется без строки загрузки агента.
./install.sh (и каждый ./update.sh) делает это автоматически: собирает агентов
(windows/amd64, linux/amd64, а также prebuilt darwin/arm64 из build/darwin/),
подписывает их per-deployer ключом release_ed25519.pem и публикует через
cmd/publish-release (повтор той же версии с тем же sha256 идемпотентен и меняет лишь канал; с другим sha256 — отказ, версии неизменяемы).
linux/arm64штатные скрипты НЕ публикуют. В UI архитектуруarm64выбрать можно, но installer-скрипт придёт без строки загрузки, пока вы не опубликуете бинарь вручную (команда ниже,-os linux -arch arm64).
Вручную (например, для одной платформы) — то же самое в golang-контейнере на compose-сети:
set -a; . ./.env.prod; set +a
PG=$(docker compose -f docker-compose.prod.yml ps -q postgres)
NET=$(docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' "$PG" | awk '{print $1}')
docker run --rm --network "$NET" -v "$(pwd)":/app -w /app \
-e DATABASE_DSN="$DATABASE_DSN" \
golang:1.26-alpine sh -c '
V=$(cat AGENT_VERSION) # версия АГЕНТА (отдельно от продукта/сервера)
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -trimpath \
-ldflags "-s -w -X main.version=${V}" \
-o /tmp/agent_linux_arm64 ./cmd/agent
go run ./cmd/publish-release -binary /tmp/agent_linux_arm64 \
-version "v${V}" -os linux -arch arm64 -key release_ed25519.pem
'Ручной
INSERTвagent_releasesс пустой подписью не работает: self-update требует валидную ed25519-подпись манифеста (канонversion+os+arch+sha256; пустая или невалидная подпись = fail-closed отказ) плюс сверку sha256 бинаря, а даунгрейд блокируется high-water mark версии — публикуйте только черезcmd/publish-release. Детали — self-update.md.
Windows-агент нельзя собирать «как есть». Без
.sysoс манифестом Common Controls и без-H windowsguiвы получите агента, у которого падает трей и лок-оверлей. Точные флаги — вupdate.sh; лучше просто вызвать./update.sh. Аналогично macOS-агент требует cgo и собирается только на маке (make release-darwin), поэтому в репо лежит prebuiltbuild/darwin/agent_darwin_arm64.
Устройство появляется в интерфейсе только после того, как агент установлен и выполнил enrollment — не в момент создания токена.
В веб-интерфейсе откройте «Устройства» → «Добавить устройство» и выберите ОС (hostname подставится автоматически при enrollment).
- Windows: UI выдаст готовую команду
msiexec(со всеми пятью свойствами) и кнопку «Скачать MSI» (/downloads/RoutineOps-agent.msi). - Linux / macOS: выберите архитектуру и нажмите «Скачать установщик» —
это shell-скрипт
install-mdm.shс уже подставленными токеном,-ca-url,-ca-sha256-пином и адресом gRPC.
Этот токен действует 24 часа и одноразовый — он привязан к конкретному устройству. Если истёк или сгорел — нажмите «Перерегистрировать» на странице устройства. Подробнее — enrollment.md.
Для парка машин этот путь не нужен. Заводить устройства заранее по одному не требуется: есть массовый токен — один на всю партию, срок по умолчанию 7 дней, устройство создаётся само при первом подключении. См. «Массовая установка на парк».
msiexec /i RoutineOps-agent.msi /qn `
ENROLL_URL="https://mdm.example.com/api/v1/enroll" `
ENROLL_TOKEN="<токен>" `
CA_URL="https://mdm.example.com/ca.crt" `
CA_SHA256="<hex sha256 от ca.crt>" `
SERVER_ADDR="mdm.example.com:50051"Все пять свойств обязательны. MSI универсален — он не содержит
ca.crt. Агент качает CA поCA_URLи сверяет его сCA_SHA256(скачивание CA без пина отклоняется: TOFU = MITM). Пропустите любое из пяти — установка прервётся на Launch-condition. Готовую команду с подставленными токеном и пином показывает UI; вручную пин берётся так:sha256sum certs/ca.crt.
MSI кладёт агента в C:\Program Files\RoutineOps, выполняет enrollment, ставит, запускает
и хардерит службу RoutineOps-agent, поднимает трей — без ребута. Детали, повторная
установка и сборка MSI: build/msi/README.md.
Пакет лежит на сервере: https://mdm.example.com/downloads/RoutineOps-agent.pkg
(кладётся туда install.sh из build/pkg/RoutineOps-agent.pkg). Кнопки в UI для него нет —
качайте по прямой ссылке.
# на деплое с самоподписанным сертификатом передайте CA явно (--cacert ca.crt),
# а не отключайте проверку через -k
curl -fsSL --cacert /path/to/ca.crt \
"https://mdm.example.com/downloads/RoutineOps-agent.pkg" -o /tmp/RoutineOps-agent.pkg
sudo installer -pkg /tmp/RoutineOps-agent.pkg -target /Ставьте пакет из терминала, а не двойным кликом.
.pkgне подписан Developer ID и не нотаризован — Gatekeeper заблокирует установку из Finder.sudo installerэтот путь обходит.
Пакет кладёт только бинарь /usr/local/bin/RoutineOps-agent; enrollment он сам не делает
(если только root заранее не положил /tmp/mdm-enroll.env). Допишите вручную —
postinstall печатает ту же команду:
sudo /usr/local/bin/RoutineOps-agent enroll -install-service \
-enroll-url https://mdm.example.com/api/v1/enroll -server mdm.example.com:50051 \
-token <токен> \
-ca /usr/local/etc/mdm/ca.crt \
-ca-url https://mdm.example.com/ca.crt -ca-sha256 <hex sha256 от ca.crt>После обновления пакета поверх работающего агента перезапустите службы вручную.
.pkgзаменяет бинарь на диске, но LaunchDaemon продолжает крутить старый процесс:sudo launchctl kickstart -k system/RoutineOps-agent sudo launchctl kickstart -k "gui/$(id -u)/RoutineOps-agent.tray" # трей, при наличии
Раскладка на macOS: демон /Library/LaunchDaemons/RoutineOps-agent.plist, трей
/Library/LaunchAgents/RoutineOps-agent.tray.plist, данные и серты /var/lib/RoutineOps-agent/,
логи /Library/Logs/RoutineOps/.
Скачайте install-mdm.sh кнопкой в UI (или GET /api/v1/installer?os=linux&arch=amd64&token=<токен>) и запустите:
chmod +x install-mdm.sh
sudo bash install-mdm.shСкрипт скачает бинарь, сверит его sha256, положит в /usr/local/bin/RoutineOps-agent
и выполнит enroll -install-service.
Что ставится на Linux:
| Что | Где |
|---|---|
| Бинарь | /usr/local/bin/RoutineOps-agent |
| systemd-юнит | /etc/systemd/system/RoutineOps-agent.service (Restart=always) |
Состояние (outbox, *.seen) |
/var/lib/RoutineOps-agent/ |
| Сертификаты | /var/lib/RoutineOps-agent/certs/ |
| Лог | /var/log/RoutineOps-agent/agent.log |
Инвентаризация ПО на Linux работает через первый найденный пакетный менеджер:
dpkg-query → rpm → pacman → apk. Ни одного не нашлось — не ошибка: железо и
ОС всё равно отправятся, список ПО будет пуст. Серийный номер читается из
/sys/class/dmi/id/product_serial, а если там пусто или вендорский плейсхолдер
(Default string и т.п.) — из dmidecode -s system-serial-number (нужен root и
установленный пакет dmidecode).
Собранные архитектуры — amd64 и arm64 (make build-linux, make build-linux-arm64),
но штатные install.sh/update.sh публикуют только amd64; см.
«Публикация релиза агента».
Чего на Linux нет (сервер это учитывает, устройство остаётся управляемым):
- полноэкранного оверлея блокировки — команда
lockпринимается, состояние персистится и переживает перезапуск, но окна с паролем не рисуется;- хранилища ключей ОС (
-cert-source keystore) — на Linux только файловые сертификаты, это штатный путь;- трея — подкоманда
trayзавершится с кодом 2;- tamper-protection — на Linux защиты от удаления нет; она есть на Windows (SafeBoot + реестр) и macOS (
schg), см. tamper-protection.md.tamper-disarmна Linux вернёт ошибку «не реализована».
Раскатка через групповые политики AD, KSC, Ansible или любой другой инструмент доставки. Заранее заводить устройства в интерфейсе не нужно — сервер создаёт запись сам, когда агент впервые придёт с массовым токеном.
| Одноразовый | Массовый (bulk) | |
|---|---|---|
| Привязан к устройству | да, device_id назначен заранее |
нет |
| Число установок | одна | лимит max_uses либо без ограничения |
| Срок жизни | 24 часа | 7 дней по умолчанию, задаётся при выпуске |
| Устройство в списке | до энроллмента, как pending |
создаётся в момент подключения |
| Очередь одобрения | нет | есть, включена по умолчанию |
| Целевая группа | назначается вручную потом | вшивается в токен |
Обе разновидности — в свободной редакции.
Интерфейс → «Энроллмент» → «Массовые токены» → «Выпустить токен». Поля: группа, лимит использований (пусто — без ограничения), срок жизни в часах (пусто — 168, то есть неделя) и «Требовать одобрения».
Панель сразу отдаёт готовую команду установки со всеми свойствами, включая
ca_sha256 — отдельно считать хеш CA не нужно.
Для автоматизации есть REST:
POST /api/v1/enrollment-tokens/bulk
{
"group_id": "<uuid или пусто>",
"max_uses": 200, // отсутствует или null — без ограничения
"ttl_hours": 336, // 0 или отсутствует — 168 (7 дней)
"require_approval": true // отсутствует — true
}
→ 201 { "enrollment_token": "...", "expires_at": "...", "ca_sha256": "...", "require_approval": true }
Выпуск токена — операция под
requireHuman: она даёт машинам вход в парк, поэтому сервисным API-токеном её не выполнить, только живым администратором из панели или под его сессией. Это осознанное ограничение, а не недоработка.
Токен один и тот же на всю партию — меняется только способ доставки.
MSI универсален и ставится тихо:
msiexec /i RoutineOps-agent.msi /qn ^
ENROLL_URL="https://mdm.example.com/api/v1/enroll" ^
ENROLL_TOKEN="<массовый токен>" ^
CA_URL="https://mdm.example.com/ca.crt" ^
CA_SHA256="<ca_sha256 из ответа>" ^
SERVER_ADDR="mdm.example.com:50051"
🔴 Назначение MSI через «Установка программ» в GPO свойства не передаёт. Политика умеет ставить пакет, но не умеет прокидывать
ENROLL_TOKENи остальные четыре свойства, а без них установка прервётся на Launch-условии. Рабочих путей два:
- скрипт запуска компьютера (Computer Configuration → Windows Settings → Scripts → Startup) с приведённой выше строкой
msiexec— самый прямой;- трансформ
.mstс прописанными свойствами, приложенный к пакету в политике установки, — если раскатка обязана идти именно через «Установку программ».
KSC задаёт параметры установки штатно — вставьте те же пять свойств в параметры инсталляционного пакета. То же касается SCCM/Intune и самописных раскаток: требуется лишь возможность передать msiexec аргументы.
Тот же токен, обычная команда энроллмента — она не различает виды токенов:
sudo /usr/local/bin/RoutineOps-agent enroll -install-service \
-enroll-url https://mdm.example.com/api/v1/enroll -server mdm.example.com:50051 \
-token <массовый токен> \
-ca-url https://mdm.example.com/ca.crt -ca-sha256 <ca_sha256 из ответа>При require_approval (по умолчанию) машины не получают доступ сразу: они встают в
«Энроллмент» → «Очередь одобрения» со статусом «Ожидает одобрения». Сертификат
им уже выдан, но полномочий нет, пока администратор не одобрит — поштучно или кнопкой
«Одобрить все».
Одобрение снимает ограничение целиком, включая выполнение скриптов, и применяется ко всем, кто стоит в очереди на момент подтверждения, — в том числе к тем, кто подключился, пока вы читали список.
Отклонение терминально: вернуть машину через одобрение нельзя, её придётся энролить заново.
Выключать одобрение (require_approval: false) осмысленно только там, где сам канал
доставки уже доверенный — например, GPO в закрытом домене. Тогда машины подключаются
сразу.
- Отзыв токена — кнопка «Отозвать» или
DELETE /api/v1/enrollment-tokens/{id}. Срабатывает мгновенно; уже заэнролленных устройств отзыв не касается. - «Не подключились» — раздел показывает одобренные устройства, от которых не пришло ни одного heartbeat. По нему и видно, до кого раскатка не доехала.
Логи сервера:
docker compose -f docker-compose.prod.yml logs --tail=30 serverОжидаемый вывод при успешном старте:
INFO config loaded
INFO database connected
INFO CA signer loaded, enrollment enabled
INFO asynq worker started redis=redis:6379
INFO gRPC server listening addr=:50051
INFO HTTPS server listening addr=:8081
Веб-интерфейс: откройте https://<IP_или_домен> и войдите с учётными данными из
SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD.
Статус службы агента на устройстве:
systemctl status RoutineOps-agent # Linux
sudo launchctl list | grep mdm # macOS
Get-Service RoutineOps-agent # Windows (PowerShell)Логи агента:
journalctl -u RoutineOps-agent -f # Linux (плюс /var/log/RoutineOps-agent/agent.log)
tail -f /Library/Logs/RoutineOps/agent.err.log # macOS
# Windows: %ProgramData%\RoutineOps\logs\agent.logПосле успешного enrollment устройство появится в разделе «Устройства».
Если агент не выходит на связь — field-troubleshooting.md
(agent diag -probe за минуту показывает причину).
SMTP нужен для приглашений пользователей и сброса пароля. Приглашение отправляется
из UI (роли: it_admin — полный доступ, viewer — только чтение); письмо содержит
ссылку /accept-invite?token=.... Добавьте в .env.prod:
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=<app password>
SMTP_FROM=noreply@example.com
# SMTP_TLS=true # раскомментировать для порта 465 (implicit TLS)Правила, на которых спотыкаются чаще всего:
- Порт 587 = STARTTLS (
SMTP_TLS=false), порт 465 = implicit TLS (SMTP_TLS=true). - Многие провайдеры требуют, чтобы
SMTP_FROMсовпадал сSMTP_USER(логином), иначе отправка отклоняется. - Используйте app password (пароль приложения), а не пароль от почтового ящика.
- Пустой
SMTP_HOST= почта выключена, в логеmailer disabled. - Успешная отправка не пишет ничего в лог — отсутствие строки об ошибке и есть признак успеха.
Диагностика:
docker compose -f docker-compose.prod.yml logs server | grep "send invite"Важно: ошибка SMTP не блокирует создание приглашения — оно сохраняется в БД, а ссылка возвращается в ответе API (
invite_url). Если письмо не дошло, ссылку можно скопировать оттуда и передать пользователю вручную.
Одной командой (от того же непривилегированного пользователя, без sudo):
./update.shupdate.sh делает всё по порядку: бэкап БД (backups/db-*.dump, custom format) →
git pull --ff-only → пересборка контейнеров (сервис migrate накатит новые
миграции до старта сервера) → пересборка, подпись и публикация агентов новой
версии. Парк подтянет агентов self-update'ом (проверка раз в 6 часов,
ROUTINEOPS_UPDATE_INTERVAL). Детали и откат — self-hosted-deploy.md.
Чек-лист вокруг обновления:
- Сверьте
.env.prodс новыми дефолтами — см. «Ловушка перекрытых дефолтов». - Запустите
./update.sh. - Обновите установщики вручную, если в релизе приехал новый MSI/.pkg.
update.shпубликует только голые бинари для self-update и не трогаетreleases/— туда файлы копирует лишьinstall.sh:Без этого кнопка «Скачать MSI» в UI продолжит отдавать старый установщик. На уже установленные агенты это не влияет — они обновляются сами.cp build/msi/RoutineOps-agent.msi releases/RoutineOps-agent.msi cp build/pkg/RoutineOps-agent.pkg releases/RoutineOps-agent.pkg
- Убедитесь, что всё поднялось:
docker compose -f docker-compose.prod.yml logs --tail=20 server
Версию агента каждого устройства видно в UI и в БД (devices.agent_version).
Агенты, собранные без
-ldflags "-X main.version=..."(версияdev), самообновление пропускают. Для тестового окружения проще переустановить агент вручную через новый installer-скрипт из UI.
# Перезапуск
docker compose -f docker-compose.prod.yml restart
# Логи
docker compose -f docker-compose.prod.yml logs -f server
# Остановка
docker compose -f docker-compose.prod.yml down
# Резервное копирование БД (custom format — восстанавливается pg_restore --clean)
mkdir -p backups
docker compose -f docker-compose.prod.yml exec -T postgres pg_dump -U mdm -Fc mdm > backups/db-$(date +%Y%m%d).dumpПолный список критичных активов, процедуры восстановления и мониторинг — operations.md.
Структура каталога:
certs/
ca.crt — корневой CA (нужен агентам для проверки сервера)
ca.key — приватный ключ CA (храните в безопасном месте)
server.crt — серверный сертификат
server.key — приватный ключ сервера
agents/
<device_id>/
agent.crt — клиентский сертификат агента
agent.key — приватный ключ агента
ca.crt — копия CA для агента
Сроки жизни и отсутствие автопродления:
| Сертификат | Срок | Что делать до истечения |
|---|---|---|
| Root CA | 10 лет | Перевыпуск = переустановка/перерегистрация всех агентов. ca.key бэкапить обязательно |
| Серверный | 1 год | Перевыпустить (gen-certs.sh после удаления старой пары, не забыв SERVER_SANS). Парк замену не заметит: агенты доверяют CA, а не серту |
| Агентский (выдаётся при enrollment) | 1 год | Автопродления нет. По истечении агент теряет mTLS-канал → «Перерегистрировать» в UI и повторный enrollment |
Проверить срок:
openssl x509 -enddate -noout -in certs/ca.crt
openssl x509 -enddate -noout -in certs/server.crtПроцедуры ротации — operations.md.
| Симптом | Причина | Что делать |
|---|---|---|
KeyError: 'ContainerConfig' при docker-compose up |
docker-compose v1.29.2 несовместим с Docker Engine 25+ |
Установить Compose v2 (раздел «Требования») и использовать docker compose без дефиса |
docker: unknown command: docker compose |
Плагин Compose v2 не установлен | Установить его (раздел «Требования») |
Postgres: superuser password is not specified |
В .env.prod не задан POSTGRES_PASSWORD |
Задать; файл должен лежать в корне проекта рядом с docker-compose.prod.yml |
password authentication failed for user "mdm" |
POSTGRES_PASSWORD и пароль в DATABASE_DSN разошлись, либо в пароле есть $ |
Исправить и пересоздать volume: docker compose -f docker-compose.prod.yml down -v && … up -d |
redis eval error: dial tcp [::1]:6379 |
В .env.prod не задан REDIS_ADDR |
Добавить REDIS_ADDR=redis:6379 |
migrate отказывается стартовать: есть таблицы, нет schema_migrations |
Старая инсталляция с ручными миграциями | Одноразовый backfill — self-hosted-deploy.md |
Собранный образ рапортует версию dev |
Забыт export VERSION=$(cat VERSION) перед up -d --build |
Пересобрать с переменной; self-update сравнивает именно её |
| Симптом | Причина | Что делать |
|---|---|---|
В логе seed admin failed, войти нечем |
SEED_ADMIN_PASSWORD не прошёл политику (≥8 символов, 3 из 4 классов) |
Задать сильный пароль. Учтите: seed выполняется на старте, для существующей БД пользователь уже мог не создаться |
git pull падает на правах после обновления |
Запускали sudo ./update.sh — .git, .env.prod, ключи стали root-owned |
sudo chown -R "$USER:$USER" . в каталоге установки; добавить пользователя в группу docker и больше не использовать sudo |
Cookie сессии уходит без флага Secure |
COOKIE_SECURE не задан (install.sh его не пишет) |
Добавить COOKIE_SECURE=true в .env.prod и перезапустить сервер |
| Симптом | Причина | Что делать |
|---|---|---|
В логе mailer disabled |
Пустой SMTP_HOST |
Заполнить SMTP-переменные |
no such host / SERVFAIL на внешние домены из контейнера server |
Петля встроенного Docker-DNS: dns: [127.0.0.11] заворачивает резолвер на самого себя. postgres/redis при этом резолвятся, а SMTP молча умирает |
В актуальном docker-compose.prod.yml у server заданы внешние форвардеры (dns: 8.8.8.8, 1.1.1.1) — сделать git pull и пересоздать контейнер. Диагностика ниже |
| SMTP: отказ при отправке, письма не уходят | SMTP_FROM ≠ SMTP_USER (многие провайдеры это запрещают), либо используется пароль от ящика вместо app password, либо SMTP_TLS не соответствует порту |
Выровнять From с логином; завести app password; 465 → SMTP_TLS=true, 587 → false |
Диагностика DNS-петли:
docker compose -f docker-compose.prod.yml exec server cat /etc/resolv.conf
# в строке ExtServers: не должно быть 127.0.0.11 — там должны стоять внешние резолверы
docker compose -f docker-compose.prod.yml exec server nslookup smtp.example.com
docker compose -f docker-compose.prod.yml exec server nslookup smtp.example.com 8.8.8.8
# резолвится только со вторым (явным сервером) → петля резолвера| Симптом | Причина | Что делать |
|---|---|---|
Installer-скрипт содержит # Поместите бинарь RoutineOps-agent в /usr/local/bin вручную (или # Поместите RoutineOps-agent.exe в $InstallDir вручную) |
Релиз агента для этой пары os/arch не зарегистрирован в БД | Выполнить «Публикация релиза агента» или просто ./update.sh. Для linux/arm64 — только вручную |
msiexec мгновенно прерывается с текстом про ENROLL_URL … CA_SHA256 … |
Не переданы все пять свойств (Launch-condition) | Скопировать команду из UI: CA_SHA256 пропускать нельзя, MSI не содержит CA |
msiexec прерывается с текстом «уже зарегистрирован» |
Продукт числится установленным, и энроллмент в этом прогоне не выполнится (режим обслуживания) | Повторить ту же команду с REINSTALL=ALL REINSTALLMODE=vomus. Если агента на диске нет — сперва снять запись: msiexec /x {ProductCode} /qn |
msiexec вернул 0, а службы и сертификатов нет |
Сиротская регистрация установщика: агента снимали процедурой, которая не дёргала msiexec /x |
field-troubleshooting.md — снять запись msiexec /x {ProductCode} /qn и поставить заново. Установщик с гейтом на этот случай такой прогон не пропускает молча, а прерывается |
| Кнопка «Скачать MSI» отдаёт старый установщик | update.sh не обновляет releases/ |
cp build/msi/RoutineOps-agent.msi releases/RoutineOps-agent.msi |
macOS: двойной клик по .pkg блокируется Gatekeeper |
Пакет не подписан Developer ID и не нотаризован | sudo installer -pkg <файл>.pkg -target / |
macOS: после установки нового .pkg агент рапортует старую версию |
.pkg не перезапускает LaunchDaemon — старый процесс продолжает работать |
sudo launchctl kickstart -k system/RoutineOps-agent |
| PowerShell: «файл не имеет цифровой подписи» | Запуск .ps1-установщика с политикой по умолчанию |
powershell -ExecutionPolicy Bypass -File <скрипт>.ps1 (для Windows штатный путь — MSI) |
| Симптом | Причина | Что делать |
|---|---|---|
В логе client cert ещё не действителен |
not_before в будущем: часы устройства убежали назад |
Синхронизировать время (NTP) на устройстве. Сертификаты выпускаются на 1 год, автопродления нет |
certificate signed by unknown authority |
Неверный ca.crt или серт от другого CA |
Сверить CA; при расхождении — «Перерегистрировать» и повторный enrollment |
Linux: systemctl status RoutineOps-agent → Unit … not found |
Enroll выполнялся без -install-service, либо не от root |
sudo /usr/local/bin/RoutineOps-agent enroll … -install-service |
Linux: юнит есть, но activating/failed в цикле |
Restart=always перезапускает падающий процесс. Причина — в логах |
journalctl -u RoutineOps-agent -n 50 --no-pager и /var/log/RoutineOps-agent/agent.log |
| Linux: устройство приехало без серийного номера | В /sys/class/dmi/id/product_serial пусто/плейсхолдер, а dmidecode не установлен |
Поставить dmidecode; служба и так работает от root. В ВМ серийника может не быть в принципе |
| Linux: список ПО пуст | Не найден ни один из dpkg-query/rpm/pacman/apk |
Ожидаемое поведение, не ошибка: остальная инвентаризация работает |
| macOS: launchd-служба не стартует (exit 1) | Нет лог-каталога, либо агент не может создать agent_outbox/ в рабочем каталоге |
sudo mkdir -p /Library/Logs/RoutineOps; переустановить текущим установщиком — он раскладывает /var/lib/RoutineOps-agent/ сам |
| macOS: агент перестал работать после ребута | Признак старой ручной установки из /tmp (macOS чистит его при перезагрузке) |
Переустановить: бинарь — /usr/local/bin/RoutineOps-agent, данные и серты — /var/lib/RoutineOps-agent/ |
Windows: служба RoutineOps-agent не запускается |
Разное; нужен ручной прогон с явными путями | Запустить агента руками (команда ниже) и прочитать ошибку |
Ручной прогон агента на Windows (mTLS-материал MSI кладёт в подкаталог certs
рядом с бинарём):
& "C:\Program Files\RoutineOps\RoutineOps-agent.exe" run `
-server "mdm.example.com:50051" `
-cert "C:\Program Files\RoutineOps\certs\agent.crt" `
-key "C:\Program Files\RoutineOps\certs\agent.key" `
-ca "C:\Program Files\RoutineOps\certs\ca.crt"Подробная полевая диагностика (agent diag, чтение вывода, re-enroll) —
field-troubleshooting.md. Справочник по флагам агента —
agent-cli.md.