Клиент LSUS (Windows)

На Windows работают две службы LSUS (каждая — отдельный .exe / служба Windows):

Разделение повторяет архитектуру Linux, где обновлениями занимается lsus-client, а конфигурациями — отдельный пакет lsus-config-agent. Раньше на Windows обе функции были совмещены в одном LsusAgent.exe; теперь конфигурации вынесены в самостоятельную службу, что упрощает её независимое обновление и не связывает долгие прогоны скриптов с циклом обновлений.

Обе службы — это C#/.NET-приложения (.NET Framework 4.6.2+). Для управления Linux-хостами используется другой агент. Эта страница — только про Windows.

Архитектура#

• Рантайм: .NET Framework 4.6.2+ (для Windows Server 2012 R2 / Windows 8.1 и новее).
• Формат: Windows-службы (LsusAgent и LsusConfigAgent, тип запуска «Автоматически»).
• Поставка: один MSI-пакет (обе службы) и ZIP-архив со скриптами установки. Если служба LsusConfigAgent зарегистрирована, патч-служба не запускает второй in-process цикл конфигураций; если службы нет (например, -SkipConfigAgent) — прогонами занимается встроенный воркер внутри LsusAgent.

Главный цикл патч-службы (LsusAgent)#

Несколько параллельных процессов:

Главный цикл службы конфигураций (LsusConfigAgent)#

Один воркер — pull-цикл прогонов конфигураций (полный аналог Linux lsus-config-agent):

Функциональность#

Windows Update API#

Используется COM Microsoft.Update.Session:

• Поиск доступных обновлений — Search("IsInstalled=0").
• Установка — CreateUpdateDownloader + IUpdateInstaller.Install.
• Offline-скан — регистрация scan-package-сервиса из wsusscn2.cab через ServiceManager.AddScanPackageService, поиск по whitelist классификаций (Security/Critical/UpdateRollups/SSU), исключая Defender/MSRT.

Работа через сайт#

Артефакты агента (MSI/ZIP), каталог сканирования wsusscn2.cab и MSU хост получает только с сайта хоста. При обязательном сайте подсети (или выключенном failover) агент не переходит на адрес из ServerUrl, даже если тот задан; на ответ сайта «повторите позже» ждёт указанный срок и докачивает файл с места обрыва. Мастер прямые запросы таких хостов отклоняет.

Установка на новую машину по WinRM — из Центра отладки: активный MSI нужной архитектуры машина скачивает по одноразовой ссылке с сайта своей подсети (вне подсетей с сайтом — с мастера) с проверкой контрольной суммы и ставит с адресом сервера в параметрах.

Установка обновлений KB (wusa.exe)#

Дедлайн wusa — wusa_timeout_minutes (по умолчанию 60, env LSUS_WUSA_TIMEOUT_MIN).

Коды возврата wusa:

Коды из категорий not_applicable/prerequisite_missing/manual_intervention не переводят весь батч в failed, а помечаются как Skipped (auto-skip) — сервер продолжает установку остальных KB.

Конфигурации (PowerShell/DSC) — служба LsusConfigAgent#

Исполнение политик конфигурации выполняет отдельная служба LsusConfigAgent.exe — зеркало lsus-config-agent, но исполняет PowerShell вместо Ansible.

• Проверка Ed25519-подписи контента.
• Скачивание ассетов/дистрибутивов с sha256+Ed25519.
• Запуск: powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File <wrapper> -Mode <check|apply>.
• Скрипты пишутся UTF-8 с BOM (для совместимости с PowerShell 4/5).
• extra_vars через env LSUS_EXTRA_VARS (JSON).
• Сбор артефактов из $env:LSUS_ARTIFACTS_DIR.
• Команды [DEBUG_EXEC] из центра отладки также исполняются службой конфигураций (через /clients/ansible/commands/pending).

Дистрибутивы ПО (.exe/.msi)#

Код 3010 (требуется перезагрузка) трактуется как успех с требованием ребута.

Установка#

Готовый MSI или ZIP, уже лежащий на Master как источник автообновления, можно скачать в Управление обновлениями → Версии агента с карточки Windows-агента или из истории — тот же файл, который получают хосты.

MSI (рекомендуется)#

Один MSI ставит обе службы (LsusAgent и LsusConfigAgent). В комплекте MSI есть publish-config/LsusConfigAgent.exe.

# Установка с указанием сервера
msiexec /i lsus-agent-net-<версия>.msi /qn /norestart SERVERURL="https://lsus.example.com:8443"

# Или только DNS-обнаружение (TXT _lsus.<домен>, запас — SRV)
msiexec /i lsus-agent-net-<версия>.msi /qn /norestart DISCOVERYDOMAIN=corp.example.com

# Или через Install-LsusAgent.ps1 (MSI/ZIP; без -SkipConfigAgent — обе службы)
.\Install-LsusAgent.ps1 -ServerUrl "https://lsus.example.com:8443"

ZIP (через PowerShell-скрипт)#

# Требует права администратора
.\Install-LsusAgent.ps1 -SourceDir .\publish -ServerUrl "https://lsus.example.com:8443"

Install-LsusAgent.ps1 автоматически:
1. останавливает службы и процессы LsusAgent.exe / LsusConfigAgent.exe;
2. копирует бинарники патч-службы в %ProgramFiles%\LSUS\LsusAgent\ и службы конфигураций в %ProgramFiles%\LSUS\LsusConfigAgent\;
3. создаёт %ProgramData%\LSUS\ (конфиг, логи, токен);
4. создаёт службы LsusAgent и LsusConfigAgent (тип «Автоматически», recovery — 3 рестарта через 60 с);
5. запускает обе службы.

-SkipConfigAgent — аварийный выключатель: не копирует и не регистрирует LsusConfigAgent.

Пути установки#

Удаление#

.\Uninstall-LsusAgent.ps1          # сохраняет %ProgramData%\LSUS (токен, логи)
.\Uninstall-LsusAgent.ps1 -Purge   # удаляет полностью

Конфигурация#

Файл: %ProgramData%\LSUS\lsus-client.conf (INI-формат, не JSON).

[server]
ServerUrl = https://lsus.example.com:8443
ServerDiscoveryDomain =
# dns_discovery = true
HeartbeatIntervalSeconds = 120
verify_ssl = false

[system]
DataDir =
scan_timeout_minutes = 45
wusa_timeout_minutes = 60

Ключи#

Env-переопределения: LSUS_SCAN_TIMEOUT_MIN, LSUS_WUSA_TIMEOUT_MIN.

Приоритет источников адреса сервера#

1. assigned_server_url с сервера (после /assignment);
2. DNS: TXT _lsus.<зона>, иначе SRV _lsus._tcp.<зона>. Какие зоны запрашиваются, зависит от конфига (см. «Режимы DNS-поиска»); найденный адрес перекрывает ServerUrl в памяти;
3. ServerUrl из конфига, если DNS ничего не вернул или поиск не запускался.

Найденный по DNS адрес хранится только в памяти службы, lsus-client.conf не меняется.

Режимы DNS-поиска#

Режим определяется конфигом, патч-служба и служба конфигураций выбирают его одинаково:

• dns_discovery = false — поиск выключен полностью: ни DNS-запросов, ни повторов. Работает ServerUrl.
• Задан ServerDiscoveryDomain — запрашивается только эта зона. Другие зоны не пробуются, чтобы закреплённый домен не подменялся догадкой.
• ServerDiscoveryDomain пуст, ServerUrl задан — запрашивается только домен AD (если хост в домене). Вне AD DNS не запрашивается, адрес из конфига не подменяется.
• Пусты оба ключа — поиск по зонам по порядку: домен AD, суффикс FQDN хоста, первичный DNS-суффикс, суффиксы активных сетевых адаптеров (адаптер со шлюзом по умолчанию первым). Хост вне домена находит сервер так же, как Linux-клиент: достаточно TXT _lsus.<зона> в зоне, которую выдал DHCP или которая указана в суффиксе. Однокомпонентные зоны (corp, lan) допускаются.

В каждой зоне сначала запрашивается TXT, затем SRV (если TXT нет или его cidr не подошёл). Ответ «записей нет» ведёт к следующей зоне; ответ с ошибкой от DNS-сервера для зоны (SERVFAIL, REFUSED) тоже, но итог считается неполным; если DNS недоступен (таймаут, нет сети), проход прерывается.

Пока адреса нет, поиск повторяется: сразу после старта пауза 15 с, затем 30 с, 1 мин, 2 мин и далее раз в 5 минут. Перед каждым проходом служба перечитывает ServerUrl, ServerDiscoveryDomain и dns_discovery из lsus-client.conf: адрес, дописанный вручную или через LsusAgent.exe set-server, подхватывается без перезапуска службы. Когда адрес появился, служба один раз запрашивает назначение сайта и регистрируется.

Пока мастер недоступен, агент не уходит с сайта на основной адрес: ответы площадки об обрыве мастера не считаются отказом сайта. Последняя политика берётся из settings-cache.json. Ответ площадки «назначение неизвестно, вот мой адрес» не затирает уже сохранённое назначение.

Регистрация и связь с сервером#

Тот же механизм и endpoint /api/v1/clients/*, что у Linux-агента.

• Регистрация: POST /clients/register (без Bearer, до получения токена). В ответе: api_token, host_id, new_client_uuid.
• Auth: Bearer-токен в заголовке для всех вызовов после регистрации. Сохраняется в %ProgramData%\LSUS\api-token.
• Heartbeat: POST /clients/heartbeat — статус, версия, флаг pending_reboot, boot_time, активные пользователи.

Что шлёт в heartbeat#

• hostname, client_uuid, os_install_id (MachineGuid, меняется при переустановке Windows);
• client_version, boot_time, uptime_seconds;
• pending_reboot (детектор CBS/WU реестра);
• windows_wu_scan_compliance (готовность WUA для wsusscn2);
• interactive_users (активные консоль/RDP);
• update_in_progress (флаг на время INSTALL_KB).

Диагностика#

Проверка работоспособности#

# статус служб (патч-служба + служба конфигураций)
Get-Service LsusAgent, LsusConfigAgent

# лог патч-службы (последние 50 строк)
Get-Content -Tail 50 "$env:ProgramData\LSUS\logs\lsus-agent.log"

# лог службы конфигураций
Get-Content -Tail 50 "$env:ProgramData\LSUS\Config\logs\lsus-config-agent.log"

На сервере: хост появится во вкладке «Хосты», инвентарь — в «Инвентаризации», активный пользователь — в карточке хоста. Прогоны политик конфигурации — в разделе «Запуски сценариев».

Логи#

• Патч-служба: %ProgramData%\LSUS\logs\lsus-agent.log (ротация 2 МБ × 5 копий, уровень INFO).
• Служба конфигураций: %ProgramData%\LSUS\Config\logs\lsus-config-agent.log.
• Логи ZIP-updater: %ProgramData%\LSUS\update\zip-updater-<ts>.log.
• Event Viewer: не используется (только файловые логи).

CLI#

Патч-служба запускается из "%ProgramFiles%\LSUS\LsusAgent\LsusAgent.exe". Флаги --version и --console сохранены: --version печатает версию, --console запускает службу в консоли для отладки. У службы конфигураций по-прежнему только --version и --console.

Проверка и установка обновлений выполняются уже запущенной службой LsusAgent. Если служба остановлена, эти команды сообщают об ошибке. status при этом всё равно печатает адрес сервера и наличие файлов.

Типовые сценарии:

& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" test-connection
& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" set-server https://site.example.com
& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" updates
& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" update --yes
& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" log --lines 50
& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" inventory --send
& "$env:ProgramFiles\LSUS\LsusAgent\LsusAgent.exe" diagnose-archive --output $env:TEMP

LsusConfigAgent.exe --version и LsusConfigAgent.exe --console остаются командами службы конфигураций.

Сбор диагностики (команда с сервера)#

Команда kind=COLLECT_DIAGNOSTICS собирает ZIP с логами LSUS, WindowsUpdateLogs, %WINDIR%\Logs\CBS, %WINDIR%\Logs\DISM, EventLog System/Application и загружает на сервер.

Кеш Windows Update (автопочинка)#

Агент сам следит за каталогом %WINDIR%\SoftwareDistribution и чинит его от имени службы, без политики. Проверка идёт раз в 6 часов и не запускается, пока идёт установка KB, скан или установка обновлений, работает wusa.exe или обслуживание Windows, либо хост ждёт перезагрузки. Состояние уходит на сервер отдельным запросом и видно значком в строке хоста:

Как проходит починка: агент останавливает службы обновления (UsoSvc, dosvc, wuauserv, bits; служб, которых нет на этой версии Windows, например UsoSvc и dosvc на 8.1 и Server 2012 R2, он пропускает), убирает мусор, при необходимости переименовывает DataStore в DataStore.bak-<время> (служба создаёт базу заново) и возвращает службы, которые были запущены. Установленные обновления не снимаются, но история установки в журнале Windows Update пропадает; первый скан после пересоздания базы идёт дольше обычного. Размер базы сам по себе пересоздание не запускает.

Автоматическая починка выполняется не чаще раза в сутки и не более трёх раз за 7 суток; после этого состояние остаётся repair_failed до ручного запуска. Отключить только автоматическую часть можно ключом wu_cache_auto_repair = false в [system]. Ручной запуск — пункт «Починить кеш Windows Update…» в меню строки хоста; он доступен агентам, которые умеют эту команду (пункт неактивен у более старых версий). Пункт «Очистить мусор Windows Update…» (обновлённый агент) убирает копии offline-скана и прочий мусор, но базу Windows Update не пересоздаёт и историю установки не сбрасывает.

Копии offline-скана (ScanFile)#

Для каждого offline-скана Windows распаковывает wsusscn2.cab в %WINDIR%\SoftwareDistribution\ScanFile\<id> (около 700 МБ) и регистрирует службу скана «LSUS Offline Scan». Если скан закончился, агент снимает службу, и Windows удаляет каталог сама. Если скан оборвался — агент остановился или обновился посреди него, служба Windows Update остановилась во время поиска, скан не уложился в scan_timeout_minutes — служба остаётся зарегистрированной, и копия лежит на диске, в том числе после перезагрузки. Каталог Download при этом может быть почти пустым.

Обновлённый агент снимает такие службы сам, одинаково на всех версиях от Windows 8.1 / Server 2012 R2 до Windows 11 и Server 2025:

• при старте службы агента, перед каждым offline-сканом и после обрыва скана;
• службы другого имени (сканеры других программ) не трогает — в отчёте указаны их имя и объём;
• каталог без службы старше суток удаляет сам, останавливая для этого только wuauserv.

Для этого службы обновления не останавливаются. Свободное место, которое заняли копии, возвращается до проверки места перед сканом.

Зависший скан. Если COM-поиск не уложился в scan_timeout_minutes, агент помечает его брошенным: пока он не вернулся, новый offline-скан и поиск обновлений не стартуют. Плановый скан после обрыва повторяется по интервалу расписания, поиск обновлений после 10-минутного таймаута — тоже по интервалу, а не через минуту. Поиск обновлений, брошенный по таймауту, агент ждёт до scan_timeout_minutes от его начала: долгий поиск ещё не зависание. Не вернулся за это время — та же самопочинка, что после зависшего скана, а в комментарии сказано, что завис поиск. Любая остановка службы Windows Update при починке, в том числе автоматической, снимает брошенные вызовы, и скан после неё не ждёт их возврата. Самопочинка агента:

1. перезапускает wuauserv — это прерывает зависший поиск. Процесс svchost не завершается: на Windows 8.1 / 2012 R2, Server 2016 и машинах с малой памятью в нём работают планировщик, WMI и другие службы. Если UsoSvc или WaaSMedicSvc снова запускают wuauserv, агент проверяет это перед каждым шагом;
2. снимает свои службы скана;
3. через 20 минут запускает проверочный скан, если места хватает.

Итог уходит на сервер с комментарием. Скан снова прошёл — значка в строке хоста нет. Не вышло — состояние «кеш WU: не починен», первая фраза причины видна под именем хоста, полный текст — по наведению: служба Windows Update не останавливается (нужна перезагрузка), каталог или служба не снимаются (путь и причина), проверочный скан снова завис или упал, места всё равно мало. Базу Windows Update из-за зависания агент не пересоздаёт. Ограничения автопочинки (раз в сутки, три раза за 7 суток) действуют и здесь.

Чем отличаются версии Windows

• Windows 8.1 / Server 2012 R2. Служб UsoSvc, dosvc и WaaSMedicSvc нет. Перед сканом агент ставит prerequisite (KB3173424, KB3138615, KB3172614, KB4566425). Если wusa для prerequisite остановлен по таймауту или вернул 0x652 («уже идёт другая установка»), следующая попытка — через сутки или после перезагрузки, а не перед каждым сканом; в комментарии самопочинки указано, какой KB не встал и почему. Журнал Windows Update — текстовый %WINDIR%\WindowsUpdate.log.
• Server 2016 и Windows 10 1607. Есть UsoSvc, нет WaaSMedicSvc. Скан по большому cab идёт долго — поэтому scan_timeout_minutes по умолчанию 45.
• Windows 10 1703+ и 11, Server 2019–2025. UsoSvc и WaaSMedicSvc могут снова запустить wuauserv; dosvc на клиентских версиях работает постоянно. Отказ остановки UsoSvc или dosvc не отменяет уборку копий скана. Журнал Windows Update — файлы .etl в %WINDIR%\Logs\WindowsUpdate, текст из них даёт Get-WindowsUpdateLog.

В архив диагностики (COLLECT_DIAGNOSTICS) входят windows_update/software_distribution.txt с размерами каталогов SoftwareDistribution, каждой копией ScanFile и списком служб Windows Update, а также ReportingEvents.log; на 8.1 / 2012 R2 — WindowsUpdate.log, на 10+ — свежие .etl в пределах бюджета.

Команды сервера и перезагрузка#

Поддерживаемые команды#

Перезагрузка#

• REBOOT_NOW — shutdown.exe /r /t 60 (окно 60 секунд для пользователя). Агент отправляет completed ДО начала перезагрузки; сервер переводит батч в waiting_reboot и ждёт смены boot_time в следующем heartbeat.
• Авто-reboot при INSTALL_KB — если wusa вернул 3010 или системный PendingRebootDetector сработал, агент сообщает reboot_required=true; сервер решает, инициировать ли перезагрузку (в auto_continue-режиме).
• Агент не ждёт ребут сам — только сообщает потребность или исполняет REBOOT_NOW по команде сервера.
• REBOOT_NOW не прерывает установку: пока идёт INSTALL_KB/UNINSTALL_KB, команда перезагрузки откладывается (остаётся pending) и забирается следующим опросом после завершения установки.
• Отмена чужого таймерного ребута: если на хосте запланирован shutdown /r /t N, а у агента ещё идёт установка KB, агент раз в 2 секунды отменяет таймер системным API, чтобы установка успела завершиться. Перезагрузка через меню «Пуск» (ExitWindowsEx) этим API не отменяется — в этом случае агент дозавершает остановку службы с предупреждением в журнале.

Self-update#

Команда [UPDATE_AGENT] запускает обновление патч-службы LsusAgent:

1. GET /clients/agent-package?os=windows&architecture=<arch>&package_type=zip&component=patch (fallback на msi);
2. скачивание в %ProgramData%\LSUS\update\<sha8>-<filename> с проверкой sha256; на слабом канале агент докачивает файл по Range, а сайт отдаёт уже скачанный пакет из своего кэша;
3. ZIP → Update-FromZip.ps1 (backup → распаковка → overlay → restart); если PowerShell не стартовал (нет в PATH) — агент ставит MSI. MSI → msiexec /i ... /qn /norestart из %SystemRoot%\System32;
4. после рестарта службы агент сверяет версию с маркером и отчитывается: success/failed.

Для уже установленных агентов старше 1.0.94 сервер сам отдаёт MSI вместо ZIP, чтобы обойти сломанный PATH без ручной установки.

Оба компонента поставляются одним пакетом lsus-agent-net-<версия> (MSI или ZIP): отдельного установщика или пакета обновлений для службы конфигураций нет. Self-update по ZIP (Update-FromZip.ps1 из скачанного архива) останавливает, обновляет и запускает обе службы; MSI также регистрирует обе. Установленный ранее патч-агент при self-update получает службу конфигураций без переустановки MSI.

Связанные страницы#

• Клиент LSUS — Linux-агент (heartbeat, обновления).
• Конфигурации — серверная часть: PowerShell-скрипты, дистрибутивы ПО.
• lsus-config-agent — Linux-аналог для Конфигураций (Ansible).
• Windows KB — управление обновлениями KB на стороне сервера.
• Антивирус и установка обновлений — исключения антивируса, диагностика зависшей установки.
• Полные инструкции по установке: docs/install.md в комплекте поставки агента.