Despliegue por GPO del agente de servidor

Implemente el agente de servidor Kabeen en sus servidores Windows mediante directivas de grupo de Active Directory

Versión

El agente de servidor Kabeen puede implementarse de forma centralizada en todos sus servidores Windows mediante los objetos de directiva de grupo (GPO) de Microsoft Active Directory.

El despliegue se realiza en dos fases, ambas totalmente nativas de las GPO: la instalación del paquete MSI mediante Instalación de software y, a continuación, la distribución del archivo de configuración mediante la preferencia Archivos.

Novedad en 3.0. El agente ya no lee ninguna clave del Registro. Toda su configuración reside en un único archivo config.toml, releído automáticamente cada 10 segundos. Si hay un agente Kapsul anterior en la máquina, su clave API y su identificador se migran automáticamente en el primer arranque (consulte Migración desde el agente anterior).

Requisitos previos

  • Derechos de administración en el controlador de dominio
  • Servidores Windows unidos al dominio (Windows Server 2016+, Windows 10/11)
  • Paquete MSI firmado: kabeen-server-agent-<versión>-x86_64.msi (variante -aarch64.msi para máquinas ARM)
  • Clave API de Kabeen
  • Conexión saliente autorizada hacia intake.kabeen.io por el puerto 443/TCP

Descargue el paquete desde su consola Kabeen (Infraestructura > Añadir un servidor > Instalación automática) o directamente:

PlataformaEnlace de descarga
Windows x86_64 (MSI)Enlace
Windows arm64 (MSI)Enlace

Paso 1: Preparar el recurso compartido de red

  1. Cree una carpeta compartida accesible por todos los servidores de destino.
  2. Copie en ella el archivo MSI.
  3. Compruebe los permisos: como la instalación se ejecuta en contexto de equipo, son las cuentas de equipo las que necesitan acceso de lectura (a través de Usuarios autenticados o Equipos del dominio), no las cuentas de usuario.
\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi

La ruta debe ser obligatoriamente una ruta UNC: una ruta local (C:\...) no sería resoluble desde los servidores de destino.

Paso 2: Crear la GPO de instalación

  1. Abra la consola de Administración de directivas de grupo (GPMC).
  2. Cree una nueva GPO vinculada a la OU que contiene sus servidores.
  3. Edite la GPO y navegue a:
    • Configuración del equipo > Directivas > Configuración de software > Instalación de software
  4. Clic derecho > Nuevo > Paquete.
  5. Seleccione el archivo MSI desde la ruta de red UNC.
  6. Elija Asignado como método de implementación.

La instalación se activará en el próximo reinicio del servidor, en contexto de equipo y antes del inicio de sesión. Copia el binario en C:\Program Files\Kabeen\Server Agent\, registra el servicio de Windows KabeenServerAgent (inicio automático) y lo arranca.

En este punto no se ha proporcionado ninguna clave API, y es lo esperado: el servicio arranca igualmente y espera una configuración válida, registrando Configuration is incomplete (api_key is empty). Waiting.... No se bloquea y no consume prácticamente recursos. La clave se distribuye en el paso siguiente.

Paso 3: Distribuir la configuración

En la 3.0 la clave API ya no se configura mediante una clave del Registro: se lee del archivo C:\ProgramData\Kabeen\Server Agent\config.toml. Lo más sencillo es distribuir un archivo de referencia centralizado mediante las preferencias de directiva de grupo.

Preparar el archivo config.toml de referencia

Coloque en su recurso compartido un archivo config.toml con el siguiente contenido:

# Configuración del agente de servidor Kabeen
api_key = "SU_CLAVE_API_KABEEN"
 
# Descomente únicamente si es necesario:
# proxy = "http://proxy.corp.example:8080"
# network_usage = false

Estas tres claves —más endpoint, que solo debe modificarse por indicación del soporte— constituyen la totalidad de los parámetros reconocidos por el agente.

ClaveFunciónValor predeterminado
api_keyClave API de Kabeen. Obligatoria—
proxyProxy saliente, puerto explícito obligatorioninguno
network_usageCaptura del uso de redtrue
endpointPunto de recolección de Kabeenhttps://intake.kabeen.io

Codificación. El archivo debe guardarse en UTF-8 sin BOM (no UTF-16): una codificación incorrecta impide que el agente arranque. Métodos fiables y diagnóstico en Diagnóstico › Codificación del archivo de configuración.

Proteja este archivo. Contiene la clave API en texto plano: restrinja las ACL del recurso compartido a lectura únicamente para Equipos del dominio.

Crear la preferencia de GPO

  1. En la misma GPO, navegue a:
    • Configuración del equipo > Preferencias > Configuración de Windows > Archivos
  2. Clic derecho > Nuevo > Archivo.
  3. Rellene:
    • Acción: Reemplazar (o Actualizar si prefiere no sobrescribir una personalización local)
    • Archivo(s) de origen: \\fileserver.corp\software$\Kabeen\config.toml
    • Archivo de destino: C:\ProgramData\Kabeen\Server Agent\config.toml

No es necesario reiniciar el servicio. El agente relee config.toml cada 10 segundos: la configuración se aplica en el siguiente ciclo, incluso cuando rote la clave más adelante.

Restringir los permisos del archivo depositado

La preferencia Archivos copia las ACL heredadas de C:\ProgramData. Para bloquear el archivo, añada a la GPO una tarea inmediata (consulte la variante B) que ejecute:

icacls "C:\ProgramData\Kabeen\Server Agent\config.toml" /inheritance:r `
    /grant "SYSTEM:(F)" `
    /grant "Administrators:(F)" `
    /grant "NT SERVICE\KabeenServerAgent:(R)"

Esta misma preferencia Archivos también permite actualizar la clave API en un parque ya equipado, sin reinstalar nada.

Paso 4: Aplicar y verificar

  1. Fuerce la actualización de directivas en un servidor de prueba y reinícielo para activar la instalación:
gpupdate /force
Restart-Computer
  1. Tras el reinicio, compruebe que el servicio está en ejecución:
Get-Service -Name KabeenServerAgent
  1. Consulte los registros del agente:
Get-Content 'C:\ProgramData\Kabeen\Server Agent\logs\kabeen-server-agent.log' -Tail 30

Una vez aplicada una clave API válida, los registros deben mostrar All tasks running. Agent is operational. y la máquina debe aparecer en su consola Kabeen con un heartbeat reciente (menos de 2 minutos).

Variantes

Variante A: transformación MST con la clave API

El MSI expone una propiedad pública APIKEY, utilizable desde la línea de comandos:

msiexec /i "kabeen-server-agent-x86_64.msi" /qn /norestart APIKEY="SU_CLAVE_API_KABEEN"

Dado que la GPO Instalación de software no ofrece ningún campo de argumentos, la única forma de inyectar esta propiedad es un archivo de transformación .mst, declarado en la pestaña Modificaciones del paquete (pestaña disponible únicamente si elige Avanzado en lugar de Asignado al crear el paquete).

Genere el MST con Orca (SDK de Windows): Transform > New Transform, tabla Property, añada una fila APIKEY con su clave y, a continuación, Transform > Generate Transform.

Dos limitaciones importantes antes de elegir esta variante:

  • La clave API queda en texto plano dentro del .mst depositado en el recurso compartido. Aplíquele las mismas ACL restrictivas que a config.toml.
  • Durante la instalación, el MSI reescribe config.toml por completo con únicamente la clave API. En una actualización posterior del paquete con el mismo MST, un proxy o un network_usage que hubiera añadido se perderían. Esta variante no es recomendable si utiliza un proxy.

Variante B: tarea inmediata y script PowerShell

Este enfoque instala y configura en una sola pasada, sin reinicio previo, y gestiona correctamente las ACL.

Cree en la GPO una tarea inmediata:

  • Configuración del equipo > Preferencias > Configuración del Panel de control > Tareas programadas > Nuevo > Tarea inmediata (Windows 7 como mínimo)
  • Usuario: NT AUTHORITY\System
  • Ejecutar con los privilegios más altos: marcado
  • Acción: Iniciar un programa
    • Programa: powershell.exe
    • Argumentos: -NoProfile -ExecutionPolicy Bypass -File "\\fileserver.corp\software$\Kabeen\install.ps1"

Contenido de install.ps1 (adáptelo y fírmelo si sus directivas lo exigen):

$ErrorActionPreference = 'Stop'
$msi    = '\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi'
$marker = 'C:\ProgramData\Kabeen\Server Agent\.gpo-installed'
$apiKey = '<CLAVE_OBTENIDA_DE_SU_BÓVEDA>'
 
if (Test-Path $marker) { exit 0 }   # ya instalado por la GPO
 
# 1. Instalación silenciosa
Start-Process msiexec.exe -ArgumentList @(
    '/i', "`"$msi`"", '/qn', '/norestart',
    '/l*v', 'C:\Windows\Temp\kabeen-server-agent-install.log'
) -Wait -NoNewWindow
 
# 2. Configuración
$cfgDir = 'C:\ProgramData\Kabeen\Server Agent'
$cfg    = Join-Path $cfgDir 'config.toml'
[System.IO.File]::WriteAllText($cfg, "api_key = `"$apiKey`"`n", `
    (New-Object System.Text.UTF8Encoding $false))   # UTF-8 sin BOM
icacls $cfg /inheritance:r `
    /grant 'SYSTEM:(F)' `
    /grant 'Administrators:(F)' `
    /grant 'NT SERVICE\KabeenServerAgent:(R)' | Out-Null
 
# 3. Marcador de idempotencia
New-Item -ItemType File -Path $marker -Force | Out-Null

Nunca almacene la clave en texto plano en el script. Es preferible recuperarla en tiempo de ejecución desde una bóveda interna (Azure Key Vault, HashiCorp Vault).

Tenga en cuenta además que la propiedad APIKEY aparece en texto plano en un registro detallado /l*v: proteja o purgue esos archivos.

Filtrado por grupo de seguridad

Para un despliegue progresivo:

  1. Cree un grupo de seguridad que contenga las cuentas de equipo de destino (p. ej. «Servidores-Agente-Kabeen»).
  2. En la GPO, pestaña Delegación > Avanzado.
  3. Retire «Usuarios autenticados» de la aplicación (desmarque Aplicar directiva de grupo).
  4. Añada su grupo con los derechos «Leer» y «Aplicar directiva de grupo».

Actualización del parque

El MSI utiliza un UpgradeCode estable y una actualización mayor: la nueva versión se instala por encima de la anterior, conservando la configuración y la identidad del host.

  1. Deposite el nuevo MSI en el recurso compartido.
  2. En la GPO, cree un nuevo paquete y, en su pestaña Actualizaciones, declare que reemplaza al paquete anterior.

Como la carpeta C:\ProgramData\Kabeen\Server Agent está marcada como permanente, config.toml sobrevive incluso a una desinstalación. Consulte Actualizar el agente de servidor y Desinstalar el agente de servidor.

Migración desde el agente anterior

Si ya hay un agente Kapsul anterior instalado en los servidores de destino, el agente de servidor importa automáticamente su configuración en el primer arranque:

Elemento del agente anteriorRecuperado en el agente de servidor
kbine.apiKeyapi_key (clave API)
agentUUIDidentidad del agente (agent_id)

La recuperación del agentUUID garantiza que la máquina conserva la misma identidad en la consola Kabeen: no aparece como un host nuevo.

La migración se realiza una sola vez y nunca sobrescribe una configuración ya rellenada. En un parque en migración puede, por tanto, desplegar la GPO de instalación sin distribuir un config.toml: cada servidor recuperará su propia clave existente. Procedimiento recomendado: desplegar el agente de servidor, comprobar en la consola que las máquinas reportan con el mismo identificador y, después, desinstalar el agente anterior.

Solución de problemas

La instalación no se inicia

  • Compruebe que la ruta UNC es accesible desde la cuenta de equipo (no desde su sesión de administración).
  • Compruebe los permisos de lectura en el recurso compartido y en el archivo MSI.
  • Un reinicio es imprescindible para activar una instalación Asignada: gpupdate /force por sí solo no basta.
  • Consulte los registros de eventos de Windows (Aplicación y Sistema) y la salida de gpresult /h informe.html.

El servicio funciona pero no aparece nada en la consola

Casi siempre se trata de un problema de configuración:

  • Compruebe que C:\ProgramData\Kabeen\Server Agent\config.toml existe y contiene api_key.
  • La clave debe tener al menos 16 caracteres y no ser un valor de relleno (changeme, placeholder…): de lo contrario el agente considera la configuración incompleta y espera.
  • Compruebe la codificación del archivo: UTF-8 sin BOM.
  • El mensaje Configuration is incomplete (api_key is empty). Waiting... en los registros confirma este diagnóstico.

Error de conexión

  • Pruebe la conectividad saliente: Test-NetConnection -ComputerName intake.kabeen.io -Port 443.
  • Compruebe el firewall: solo se requiere el puerto 443/TCP saliente hacia intake.kabeen.io.
  • Detrás de un proxy corporativo, consulte Configuración del proxy en el agente de servidor.
AnteriorConfiguración del proxy en el agente de servidorSiguienteActualizar el agente de servidor