Перейти к содержанию

Агенты

Агент — программа Alatyr на рабочей машине сотрудника. Она заводит ключ в чипе устройства, подаёт заявку на сертификат, устанавливает выданный сертификат и профиль сети.

Эта страница — про то, как агент ведёт себя после установки: какие процессы работают постоянно, где живёт ключевой материал, что происходит по истечении срока сертификата и какие команды пригодятся при разборе. Про сборку пакетов и шаги установки — Установка → Агент.

Что работает на машине и кто это запускает

Работа агента устроена циклами: зарегистрироваться → дождаться одобрения → поставить сертификат → следить за сроком. На Windows и Linux этот цикл повторяет постоянно работающая служба; на macOS его запускает планировщик системы раз в минуту. Рядом в любом случае работает отдельный процесс в контексте вошедшего пользователя — он обслуживает то, до чего у системной учётной записи нет доступа.

Платформа Кто запускает основной цикл От кого Постоянные процессы рядом
Windows служба AlatyrAgent SYSTEM задача планировщика AlatyrAgentUser — по одному экземпляру на вошедшего пользователя
Linux служба alatyr-agent.service root alatyr-agent-secretd.service (системная) и alatyr-agent-user.service (для каждого вошедшего пользователя)
macOS LaunchAgent каждый вошедший пользователь отдельный всегда работающий LaunchAgent пользовательского процесса

Как часто агент приходит на сервер

Не с одной и той же частотой, и это сделано намеренно.

Когда Как часто
в покое, машинная половина раз в 10 минут
в покое, пользовательская половина раз в минуту
пока агент чего-то ждёт — одобрения заявки либо включения политики выдачи для назначенной цели раз в 30 секунд

Десять минут — разумный такт для парка в покое: сотня машин чаще нагружает сервер без пользы. Но ровно в тот промежуток, когда вы одобряете заявку, эти десять минут наблюдает человек, глядя в неизменившееся окно агента, — и читает это не как «медленно», а как «зависло». Поэтому пока агент ждёт, он опрашивает чаще; учащение держится ограниченное время, иначе парк с назначенной целью и выключенной политикой ушёл бы на частый опрос навсегда.

Такт можно задать самому: Настройки → Обновление агента → «Такт агента, секунд». 0 означает «агент решает сам» по таблице выше. Заданное вами значение старше собственной догадки агента — в том числе если вы намеренно поставили большее. Меньше пяти секунд агент не примет: такт ходит по сети.

На Linux таймера больше нет

Раньше агент запускался по alatyr-agent.timer. Сейчас это резидентная служба, которая повторяет цикл сама, а интервал задаёт переменная ALATYR_AGENT_INTERVAL в юните (по умолчанию 10m). Причина не в опросе: этот же процесс держит служебный сокет, через который непривилегированная пользовательская половина получает enrollment_token. Как разовый запуск раз в десять минут он жил секунду-две, и передача токена срабатывала только при случайном совпадении — а от неё зависят user_mtls, ad_logon и ssh целиком.

Команды systemctl … alatyr-agent.timer из старых инструкций ответят «юнит не найден». Правильная проверка:

systemctl status alatyr-agent.service

Команды, которые пригодятся администратору

Один и тот же исполняемый файл alatyr-agent (alatyr-agent.exe на Windows) обслуживает и планировщик, и человека. Команды, не поддержанные на платформе, всё равно зарегистрированы и отвечают внятной ошибкой, а не «неизвестная команда».

Посмотреть и починить:

Команда Платформы Что делает
status все Печатает текущее состояние: стадия, идентификатор устройства и заявки, серийный номер и срок сертификата.
purposes все Показывает, какие цели назначены этому устройству и в каком они состоянии.
request-purpose <цель> все Просит у сервера назначить цель. Запрос попадает в раздел Запросы назначений админки.
reissue <цель> все Перевыпуск. Снимает защёлку прежней заявки, и ближайший цикл подаёт новую. Нужен, когда администратор отклонил выдачу или сертификат отозван: без этого устройство остаётся без сертификата навсегда — заявка одна и сама повторно не подаётся. Ключ при этом не пересоздаётся.
reset все Сбрасывает состояние в исходное: следующий цикл начнёт регистрацию заново. На Linux дополнительно освобождает объект в TPM и хранилище PKCS#11, чтобы не оставлять осиротевших слотов.
version все Версия сборки агента.
rdp --target <fqdn> все Печатает список препятствий ко входу по карте через RDP: адрес, политика, карта, клиент, PIN, служба считывателей, защита LSA.
ssh-key-rotate все Явный выход из состояния «ключ отозван»: заводит новый SSH-ключ вместо отозванного.
language ru\|en все Язык окна агента и уведомлений.

Процессы, которые запускает система, а не человек:

Команда Платформы Роль
run все Основной цикл. Его запускает планировщик или служба.
service только Windows Точка входа службы Windows. Её вызывает менеджер служб; в обычной консоли она не работает и честно об этом говорит.
user-agent все Постоянный процесс в контексте вошедшего пользователя: выпуск user_mtls, работа со смарт-картой, канал окна агента, аппаратный ssh-agent. На macOS у него есть устаревшее имя-псевдоним ssh-agent — его называют уже установленные LaunchAgent, поэтому убрать его нельзя.
secretd только Linux Служба, которая отдаёт NetworkManager PIN токена TPM при подключении к сети 802.1X. Работает отдельно от основного цикла, потому что PIN может понадобиться в любой момент.
tray все Значок в системной панели. На Linux запускается сам через файл автозапуска, который кладёт пакет.
print-active-session-user только Linux Внутренняя утилита пакета: определяет логин активной сессии, чтобы подставить CORP_EMAIL при установке.

Есть также команды для работы со смарт-картой (card-prepare, card-unlock, card-set-pin, card-change-pin, card-rebind), для доступа к Kubernetes (k8s credential, k8s kubeconfig), для VPN (vpn) и полной очистки клиента (wipe-client). Они описаны в разделах по своим целям: Вход в домен по смарт-карте, Доступ к Kubernetes, Доступ по VPN.

Окно агента — то, что видит сотрудник на своей машине

У агента есть окно (отдельное приложение alatyr-agent-gui). Это единственная поверхность продукта, с которой имеет дело не администратор, а сам сотрудник, — и единственное место, где он может увидеть причину, по которой на его машине чего-то не происходит.

Что в нём есть. Слева — список целей, справа — состояние выбранной и пояснение, что агент делает дальше. У каждой цели своё состояние: цель может быть разрешена и выпускаться, уже выдана или ещё не запрошена. Внизу — переключатель языка и время последнего обмена с сервером.

Что сотрудник может сделать сам. Для цели, которая ему не назначена, в окне есть кнопка «Запросить»: запрос попадает в раздел Запросы назначений админки, и решение по-прежнему принимает администратор. Права окно не выдаёт.

Если состояние прочитать не удалось, окно говорит об этом текстом, а не показывает бесконечную заставку. Сообщения вида «Сервер отказал в регистрации ключа» приходят туда же вместе с причиной.

Окно стартует скрытым, и это не поломка

Процесс окна живёт, но на экране ничего нет: сотрудник открывает окно сам — из значка агента в системной панели. Значок окно не заменяет.

Скрытые цели: о чём окно вообще заводит разговор

Список целей, о которых окно молчит, задаётся централизованно, на весь парк: Настройки → Окно агента → «Скрытые цели».

Скрытая цель исчезает из окна целиком — раздела просто нет. Это сделано намеренно: скрытая цель не должна выглядеть как «не куплена» или «запрещена вам».

Три механизма легко перепутать, а они разные:

Механизм Что решает Что видит сотрудник
Лицензионные места сколько устройств может получить цель «мест нет» — это к администратору
Назначение цели устройству положена ли цель этой машине «нужно назначение администратора», есть кнопка «Запросить»
Скрытые цели о чём вообще заводить разговор ничего: раздела нет

Две подробности, из-за которых настройку легко счесть неработающей:

  • Пустой список означает «показывать всё», а не «скрыть всё». Сервер отказывается скрыть все цели разом, и неудачное чтение настроек на сервере даёт агенту пустой список скрытых, а не полный.
  • Изменение доезжает опросом, тем же, которым до устройства доезжают назначения целей, — то есть не мгновенно.

Где живёт ключ и что из этого следует

macOS — Secure Enclave, отдельно у каждого пользователя

Ключ подписи создаётся в Secure Enclave и живёт в связке ключей вошедшего пользователя. Поэтому агент на macOS ставится и работает как LaunchAgent пользователя, а не как системный LaunchDaemon: под системной учётной записью такого ключа не существует. Каждый пользователь одной машины регистрируется отдельно и получает свой сертификат.

Следствие, которое стоит знать заранее: на машине без активной графической сессии сертификат не выпустится вообще. Ключ Secure Enclave держит системный процесс secd, а он работает только внутри графической сессии. Это свойство платформы, а не недоработка.

После выпуска агент сам привязывает сертификат к каждой настроенной сети в связке ключей пользователя; в системную связку — дополнительно и только если работает с правами root. Без этого macOS спрашивала бы «Выберите сертификат для сети» при каждом подключении.

Подтверждение владельца при подписи SSH. По умолчанию окно доверия выключено: каждая подпись проходит обычную проверку присутствия (Touch ID или пароль), которую обеспечивает сам Secure Enclave. Администратор может включить окно длиной от 1 до 5 минут в настройках — верхнюю границу задаёт сама macOS. Когда окно включено, перед подписью, не покрытой действующим разрешением, агент показывает уведомление с выбором «1 минута» / «5 минут» / «Отказать»; выбор подтверждается биометрией или паролем, а не одним фактом касания уведомления. Отказ, закрытие уведомления и истечение ожидания означают «разрешения нет» — текущая подпись всё равно проходит обычную проверку присутствия.

Windows — TPM 2.0, один ключ на машину

Ключ создаётся в TPM 2.0. На Windows это хранилище выполняет ту же роль, что Secure Enclave на macOS, и дополнительно даёт аттестацию через ключ аттестации (AK). Хранится он на уровне машины, а не пользователя: основной цикл работает от SYSTEM, а доступ к TPM требует повышенных прав.

Пользовательскую часть — выпуск user_mtls и работу с картой для входа в домен — выполняет отдельный процесс user-agent, потому что процесс SYSTEM структурно не имеет доступа к сессии пользователя. Токен регистрации передаётся между ними через защищённый DPAPI файл с повторными попытками.

В том же процессе user-agent работает и Windows-реализация аппаратного ssh-agent (именованный канал). Отдельной команды ssh-agent на Windows нет намеренно — она возвращает ошибку с объяснением, где ssh-agent живёт на самом деле. Подробности о регистрации SSH-ключей — Реестр ключей и Keyholder API.

Вход в домен по смарт-карте (ad_logon) использует отдельную карту, которая создаётся только когда эта цель назначена устройству. Машины, у которых есть только user_mtls, остаются на обычном ключе CNG с PIN. Что для этого настраивается в домене, в админке и на устройстве — Вход в домен по смарт-карте.

Linux — TPM 2.0 через tpm2-pkcs11

Ключ создаётся в TPM 2.0 через модуль tpm2-pkcs11. Без него агент использует программный ключ на диске — см. предупреждение в Установка → Linux о том, чего это стоит.

Пользовательский контекст обслуживает постоянный процесс user-agent, зарегистрированный как пользовательский юнит systemd с перезапуском. Он же поднимает сокет аппаратного ssh-agent (отдельной команды ssh-agent, как на macOS, здесь нет).

Дополнительно всегда работает системная служба secretd: без неё NetworkManager не получит PIN токена TPM при подключении к сети 802.1X, независимо от того, отработал ли основной цикл.

Подтверждение присутствия для подписи SSH на Linux зависит от гейта присутствия цели (задаётся сервером). Когда гейт включён — а в демо-составе и по умолчанию он включён, — каждая подпись поднимает системное окно подтверждения (polkit) на рабочем столе пользователя: «Authentication is required to sign with the hardware-backed SSH key». Пока окно не подтверждено, подпись ждёт; без ответа примерно через минуту она отменяется, и вход завершается ошибкой. Когда гейт выключен, окна нет — доступ к значению авторизации токена TPM неинтерактивен, и подпись проходит без вопроса. Из-за этого ssh с гейтом имеет смысл запускать там, где виден рабочий стол сотрудника; в сценарии без экрана подтвердить присутствие некому.

Сроки жизни сертификатов по целям

Цель Срок Продлевается сам
wifi 3 года да
ad_logon 1 год да
user_mtls 1 год нет
k8s (личность) 1 год нет
vpn 1 год нет
ssh 24 часа нет

Это значения по умолчанию. Срок каждой цели задаётся в её профиле издателя (Настройки → Удостоверяющие центры) и тогда имеет приоритет. У цели wifi есть ещё один, более старый источник — переменная VAULT_CERT_TTL_HOURS (Конфигурация); она действует, только пока срок не задан в профиле.

Отдельно стоит цель k8s: год живёт личность, которую администратор одобряет один раз, а кластеру показывается совсем другой, эфемерный сертификат длиной десять минут. Почему так — Доступ к Kubernetes → Два режима доставки credential.

Продление сертификата

Продление — не отдельный режим, а тот же цикл регистрации, что и при первой выдаче. Он одинаков на всех трёх системах.

  • Перед каждым циклом агент проверяет срок установленного сертификата.
  • Перевыпуск запускается, если сертификат отсутствует, уже истёк, не читается либо до истечения осталось меньше 30 суток. Порог одинаков на macOS, Windows и Linux.
  • Тридцать суток выбраны не случайно: перевыпуск требует одобрения администратором, и запас должен пережить отпуск, праздники и выходные.
  • Перевыпуск — не обновление прежней заявки. Агент удаляет файл локального состояния, стартует с нуля (как после команды reset) и подаёт новую заявку. Терминальные состояния прежней заявки — отклонена или сертификат отозван — тоже сбрасывают состояние, чтобы агент не опрашивал бесконечно уже мёртвую заявку.
  • Рабочий сертификат при плановом продлении с диска не снимается: связь устройства не рвётся раньше срока. Удаляется только мёртвый — истёкший или нечитаемый.

Что это значит для вас. Новая заявка проходит ту же проверку одобрения, что и первичная. При ручном одобрении это даёт периодическую волну заявок по мере того, как у устройств парка подходит срок, — см. Эксплуатация → Продление сертификатов и волна одобрений. При настроенном автоодобрении (Управление и роли → Одобрение, отклонение и отзыв) дополнительных действий не требуется.

Сами продлеваются только wifi и ad_logon

По сроку перевыпускаются машинный сертификат (wifi) и сертификат для входа в домен (ad_logon). Цели user_mtls, k8s, vpn и ssh по истечении срока автоматически не перевыпускаются — верните их командой alatyr-agent reissue <цель> на устройстве либо переустановкой агента.

Срок этих сертификатов виден в окне агента и в команде alatyr-agent status, а на стороне сервера — в разделе Сертификаты админки. Отслеживайте его заранее: у user_mtls, k8s и vpn это год, у ssh — сутки.

Отключение установки сетевых профилей агентом

Профили 802.1X по умолчанию ставит сам агент. Там, где их раскатывает MDM, групповая политика или система управления конфигурацией, это отключается — отдельно на каждую сеть и систему, плюс одна настройка на весь парк для macOS (ALATYR_MACOS_AGENT_PROFILE_DISABLED, см. Конфигурация).

Что именно перестаёт делать агент на каждой системе, какой конфликт с групповой политикой это закрывает и почему ZIP-бандл при этом не фильтруется — Wi-Fi и проводной 802.1X → Кто ставит профиль.

Что дальше