Пилот: с чего начать¶

Короткий маршрут для администратора, который разворачивает пилот Alatyr на выпуске v1.5.6: сервер одной командой, агент на Windows и macOS, одобрение устройств мышью в админке, выдача трёх целей — ssh, user_mtls и vpn. Подробности каждого шага — на страницах, на которые ведут ссылки; здесь только порядок и то, что проверить.

Что нового в v1.5.6¶

Установка сервера стала проще: админка открывается по HTTPS сразу после первого запуска, адрес списков отзыва подставляется автоматически, а установщик заранее предупреждает о занятых портах.
Vault для SSH-сертификатов готов сразу; профиль издателя и список разрешённых учётных имён администратор по-прежнему включает вручную (шаг 3).
В окне агента на Mac и Windows появились кнопки повторного запроса цели — сотруднику не нужно ждать администратора, если заявку отклонили.
Агент на Windows сам формирует профиль VPN для OpenVPN GUI — администратору достаточно один раз задать основу профиля в админке.
Обновление агента на Mac и Windows сохраняет его настройки и не требует от сотрудника повторного входа.
Админка стала удобнее: таблицы помещаются на экран, добавлены подсказки к колонкам и переключатель языка.

1. Что в комплекте и что нужно заранее¶

Файлы выпуска¶

Всё берётся со страницы выпуска v1.5.6:

Файл	Что это
`alatyr-deploy-1.5.6.tar.gz`	набор развёртывания сервера: Docker Compose, сценарий `first-up.sh`, `.env.example` с уже вписанной версией образов, `README.md`
`alatyr-agent-1.5.6-x64.msi`	агент для Windows (x64): служба, окно агента, драйвер считывателя
`alatyr-agent-1.5.6.pkg`	агент для macOS: подписан и нотаризован Apple, окно агента внутри
`alatyr-agent_1.5.6_amd64.deb`, `alatyr-agent_1.5.6_arm64.deb`	агент для Debian и Ubuntu
`alatyr-agent-1.5.6-1.x86_64.rpm`, `alatyr-agent-1.5.6-1.aarch64.rpm`	агент для Fedora, RHEL и совместимых
`alatyr-1.5.6.tgz`	Helm-чарт для установки сервера в Kubernetes

Образы сервера и админки (s3m4rgl/alatyr-server и s3m4rgl/alatyr-frontend) скачиваются сами при первом запуске: их версия уже вписана в набор. Номер версии образов отличается от номера выпуска — так и должно быть, берите их парой из одного выпуска.

Linux-агент и установка в Kubernetes поддерживаются, но в этом пилоте не в фокусе: маршрут ниже — про Windows и macOS.

Что нужно заранее¶

Что	Требование
Машина под сервер	Linux с Docker 24.0+ (`docker compose` подкомандой), 2 ядра, 2–4 ГБ памяти, 20 ГБ диска — подробнее в Установке
Порты сервера	`8443` — админка по HTTPS, `8090` — API для агентов, `8200` — списки отзыва и сертификаты УЦ для агентов (`3000` — HTTP, перенаправляет на `8443`). `8090` и `8200` должны быть открыты из сети, где стоят машины сотрудников
Вход в админку	сервер сам поднимает HTTPS на `8443` и выпускает сертификат на имя и IP-адреса машины; адрес и отпечаток корня `first-up.sh` печатает в конце установки. Браузеру нужно один раз доверить корень `Alatyr Root CA` — подробности в шаге 2. Свой сертификат от корпоративного УЦ вместо этого — тоже шаг 2
Время	синхронизировано на сервере и на машинах сотрудников
Windows	проверены Windows 10 LTSC и Windows 11, x64, TPM 2.0. На Windows без интернета (LTSC) для окна агента нужен WebView2 Runtime: положите офлайн-установщик `MicrosoftEdgeWebView2RuntimeInstallerX64.exe` рядом с MSI — пакет поставит его сам
macOS	macOS 12 или новее. Пакет подписан и нотаризован Apple
VPN-клиент	Windows — community OpenVPN GUI 2.6 (openvpn.net); macOS — `openvpn` 2.5+ из командной строки (`brew install openvpn`)
Свой сервер для проверки	Linux-машина с `sshd` для проверки `ssh`; веб-приложение за nginx или haproxy для `user_mtls`; OpenVPN-сервер для `vpn`

2. Порядок разворачивания¶

Сервер. Распакуйте набор и выполните ./first-up.sh — он сам поднимет стек (свой docker compose up -d внутри), впишет адрес списков отзыва ALATYR_PKI_PUBLIC_ADDR (при нескольких адресах машины — спросит, какой из них видят агенты) и в конце напечатает один блок: пароли, ключи, адрес админки по HTTPS и отпечаток корневого сертификата — сохраните этот блок сразу. Всё — в Установке → Сервер и в README.md набора (разделы «Запуск» и «Первые шаги после запуска»).
Вход в админку. Адрес по HTTPS (https://<адрес>:8443) и логин с паролем — из блока first-up.sh. Прежде чем входить, добавьте в доверенные корневые сертификаты браузера корень Alatyr Root CA, сверив отпечаток SHA-256 (тоже в блоке first-up.sh) — без этого браузер предупредит о сертификате. Смените пароль администратора.

Если для админки нужен сертификат от вашего корпоративного УЦ, а не от Alatyr Root CA — подложить готовый сертификат в набор нельзя, но можно выключить встроенный TLS (ALATYR_TLS=off) и поставить перед сервером свой обратный прокси с этим сертификатом — Установка → Свой сертификат для админки. 3. Издатели и цели. В «Настройки → Удостоверяющие центры» издатели user_mtls и vpn уже настроены набором; профиль SSH нужно включить самому и вписать, под какими учётными именами разрешён вход (README.md набора, шаг «Издатель для цели ssh»; подробно — SSH → Настройка). Для vpn на Windows добавьте ещё в «Профиль VPN» (меню админки) базовый профиль своего сервера доступа — без строки cryptoapicert и без данных сотрудника, это агент допишет сам (VPN → Windows). Затем «Настройки → Политика выдачи» — включите ssh, user_mtls и vpn: на свежей установке включён только Wi-Fi. Для Windows-машин без Windows Hello (например, LTSC без PIN и биометрии) переключите «Настройки → Безопасность по умолчанию → Аппаратное подтверждение использования SSH-ключа» на «Предпочтительно» — при умолчании «Обязательно» ssh на таких машинах не выдаётся. 4. Агент на Windows. Установите доверие к издателю пакета и поставьте MSI с адресом сервера и доменом — Установка → Windows. Адрес сервера — адрес API: https://… вашего TLS-прокси либо, для пилота в закрытой сети, http://<сервер>:8090. Для дальнейшей эксплуатации рекомендуем TLS-прокси перед сервером — без него трафик агента идёт по обычному HTTP. 5. Агент на macOS. Готовый .pkg из выпуска ставится вместе с файлом предварительных значений — блок для копирования в Установка → macOS. На Mac нужен вход сотрудника в графическую сессию: без неё сертификат не выпустится.

Если планируете выдавать user_mtls для входа в браузере, у macOS есть отдельное требование, никак не связанное со входом в саму админку (шаг 2): браузер предложит сотруднику его сертификат, только если Mac доверяет корню, которым он подписан. Оба сертификата — админки и user_mtls — подписывает один и тот же корень Alatyr Root CA, отсюда и путаница между этими двумя темами. Два варианта: - раздайте на Mac сотрудников корневой сертификат Alatyr как доверенный — через MDM либо вручную в «Связке ключей»; - либо выпускайте user_mtls через свой Vault, промежуточный УЦ которого подписан вашим корпоративным корнем (OWN-VAULT.md набора, раздел «Корень») — тогда Mac уже доверяет этому корню, и раздавать ничего не нужно. 6. Одобрение устройства. Зарегистрировавшаяся машина появляется в админке, а в «Запросах назначений» — её просьба о цели. «Разрешить» — и затем одобрите саму заявку в «Запросах». Роли и что проверяется при одобрении — Управление и роли. 7. Назначение целей. «Устройства» → раскрыть строку машины → «Разрешённые назначения сертификатов»: отметьте ssh, user_mtls, vpn и сохраните. Сотрудник может и сам попросить цель кнопкой «Запросить» в окне агента — просьба придёт в «Запросы назначений». Каждая выдача — отдельная заявка в «Запросах», её одобряете вы. Изменения доезжают до агента очередным тактом, в пределах десяти минут.

3. Что проверить в пилоте¶

Каждый сценарий — на Windows и на macOS.

Цель	Действие	Ожидаемый результат
—	Открыть окно агента из значка в системной панели (Windows) или строке меню (macOS)	Видны цели и их состояния; у выданных — «выдан»
—	Выполнить `alatyr-agent status` (путь — в разделе 5)	Устройство зарегистрировано, видны идентификатор и срок сертификата
`ssh`	Положить на свой Linux-сервер открытый ключ SSH-УЦ и строку `TrustedUserCAKeys` (SSH → Настройка); на машине сотрудника выполнить `ssh-add -l`, затем `ssh <логин>@<сервер>`	В `ssh-add -l` есть ключ с пометкой `alatyr-agent`; вход проходит без пароля, в журнале `sshd` — `Accepted publickey … ECDSA-CERT` (шаг 6)
`user_mtls`	Одобрить заявку `user_mtls`; на Windows открыть `certmgr.msc` → «Личное» → «Сертификаты», на macOS — «Связка ключей» → связка входа пользователя	Сертификат сотрудника в хранилище пользователя (не машины), издатель — `Alatyr User mTLS Issuing CA`
`user_mtls`	Открыть в браузере сотрудника приложение за приёмником mTLS (mTLS → Настройка)	Приложение пускает и видит личность сотрудника; сертификат `wifi` той же машины получает `403` (шаг 6)
`vpn` (Windows)	Одобрить заявку `vpn` (профиль VPN администратор задал в шаге 3) — агент сам положит готовый профиль в `C:\Program Files\OpenVPN\config\`; сотруднику остаётся открыть OpenVPN GUI и нажать «Подключить» (VPN → Windows)	Значок OpenVPN GUI зелёный, в журнале клиента `Initialization Sequence Completed`, на VPN-сервере — имя сотрудника; PIN не спрашивается
`vpn` (macOS)	Выполнить `alatyr-agent vpn`, вписать напечатанные строки в профиль, поднять `sudo openvpn --config <профиль>` и в сеансе сотрудника `alatyr-agent vpn serve-key` (VPN → macOS)	Туннель поднимается, ключ не покидает Secure Enclave
любая	Отклонить заявку, затем «Выписать цель» заново в окне агента (или `alatyr-agent reissue <цель>`)	Появляется новая заявка, после одобрения цель выдаётся

4. Обновление с предыдущей версии¶

Сервер. Возьмите новый набор развёртывания из выпуска v1.5.6 и обновитесь по инструкции UPGRADE.md внутри архива: резервная копия, замена файлов набора, затем ./first-up.sh поднимает новую версию. Данные, настройки и уже выданные сертификаты сохраняются, удостоверяющие центры не меняются.

Агенты. Поставьте новый пакет (.msi, .pkg, .deb или .rpm) поверх текущего — так же, как ставили в первый раз. Настройки агента сохраняются, повторная регистрация устройства и повторное одобрение уже выданных целей не нужны.

5. Как сообщить о проблеме¶

Соберите и приложите к сообщению:

Что делали и что увидели — шаг из этой страницы, время (UTC) и текст ошибки или снимок экрана админки / окна агента.

Состояние агента — вывод команды status (и purposes, если дело в целях):

# Windows, PowerShell
& "C:\Program Files\AlatyrAgent\alatyr-agent.exe" status

# macOS
/Applications/alatyr-agent.app/Contents/MacOS/alatyr-agent status

Журналы агента. Их два — машинный и пользовательский, и цель user_mtls/vpn/ssh чаще видна во втором (подробнее):

Система	Машинный журнал	Пользовательский журнал
Windows	`C:\ProgramData\AlatyrAgent\agent.log`	`%LOCALAPPDATA%\AlatyrAgent\user-agent.log`
macOS	— (агент целиком работает от пользователя)	`~/Library/Logs/AlatyrAgent/agent.log`, рядом `sshagent.log`

Журнал установки MSI — если ставили с /l*v C:\Windows\Temp\alatyr-msi.log; на macOS — /var/log/install.log.

Журнал сервера за время проблемы, из каталога набора:
```
docker compose logs --since 1h server > alatyr-server.log
```
и версию сервера: curl -s http://localhost:8090/api/v1/version.

Перед отправкой уберите из файлов пароли и токены, если вы вписывали их в команды.

Куда писать: контакт поддержки — укажет команда.

Порядок разбора типичных симптомов — Диагностика.