Déploiement par GPO de l'agent serveur

Déployez l'agent serveur Kabeen sur vos serveurs Windows via les stratégies de groupe Active Directory

Version

L'agent serveur Kabeen peut être déployé de manière centralisée sur l'ensemble de vos serveurs Windows grâce aux stratégies de groupe (GPO) de Microsoft Active Directory.

Le déploiement se fait en deux temps, tous deux entièrement natifs à la GPO : l'installation du package MSI via Installation de logiciel, puis la diffusion du fichier de configuration via les préférences Fichiers.

Nouveau en 3.0. L'agent ne lit plus aucune clé de registre. Toute sa configuration tient dans un unique fichier config.toml, relu automatiquement toutes les 10 secondes. Si un ancien agent Kapsul est présent sur la machine, sa clé d'API et son identifiant sont migrés automatiquement au premier démarrage (voir Migration depuis l'ancien agent).

Prérequis

  • Droits d'administration sur le contrôleur de domaine
  • Serveurs Windows joints au domaine (Windows Server 2016+, Windows 10/11)
  • Package MSI signé de l'agent serveur : kabeen-server-agent-<version>-x86_64.msi (variante -aarch64.msi pour les machines ARM)
  • Clé d'API Kabeen
  • Connexion sortante autorisée vers intake.kabeen.io sur le port 443/TCP

Le package se télécharge depuis votre console Kabeen (Infrastructure > Ajouter un serveur > Installation automatique) ou directement :

PlateformeLien de téléchargement
Windows x86_64 (MSI)Lien
Windows arm64 (MSI)Lien

Étape 1 : Préparer le partage réseau

  1. Créez un dossier partagé accessible par tous les serveurs cibles.
  2. Copiez-y le fichier MSI.
  3. Vérifiez les permissions : l'installation s'exécutant en contexte machine, ce sont les comptes d'ordinateurs qui doivent disposer d'un accès en lecture (via Utilisateurs authentifiés ou Ordinateurs du domaine), et non les comptes utilisateurs.
\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi

Le chemin doit impérativement être un chemin UNC : un chemin local (C:\...) ne serait pas résoluble depuis les serveurs cibles.

Étape 2 : Créer la GPO d'installation

  1. Ouvrez la console Gestion des stratégies de groupe (GPMC).
  2. Créez une nouvelle GPO liée à l'OU contenant vos serveurs.
  3. Éditez la GPO et naviguez vers :
    • Configuration ordinateur > Stratégies > Paramètres logiciels > Installation de logiciel
  4. Clic droit > Nouveau > Package.
  5. Sélectionnez le fichier MSI depuis le chemin réseau UNC.
  6. Choisissez Attribué comme méthode de déploiement.

L'installation se déclenchera au prochain redémarrage du serveur, en contexte machine, avant l'ouverture de session. Elle copie le binaire dans C:\Program Files\Kabeen\Server Agent\, enregistre le service Windows KabeenServerAgent (démarrage automatique) et le démarre.

À ce stade, aucune clé d'API n'a été fournie, et c'est normal : le service démarre malgré tout et attend patiemment une configuration valide, en journalisant Configuration is incomplete (api_key is empty). Waiting.... Il ne plante pas et ne consomme pratiquement aucune ressource. La clé est diffusée à l'étape suivante.

Étape 3 : Diffuser la configuration

En 3.0, la clé d'API ne se configure plus par une clé de registre : elle est lue dans le fichier C:\ProgramData\Kabeen\Server Agent\config.toml. Le plus simple est de diffuser un fichier de référence centralisé via les préférences de stratégie de groupe.

Préparer le fichier config.toml de référence

Déposez sur votre partage un fichier config.toml contenant :

# Configuration de l'agent serveur Kabeen
api_key = "VOTRE_CLÉ_API_KABEEN"
 
# Décommentez uniquement si nécessaire :
# proxy = "http://proxy.corp.example:8080"
# network_usage = false

Ces trois clés — plus endpoint, à ne modifier que sur instruction du support — constituent l'intégralité des paramètres reconnus par l'agent.

CléRôleValeur par défaut
api_keyClé d'API Kabeen. Obligatoire—
proxyProxy sortant, port explicite obligatoireaucun
network_usageCapture de l'usage réseautrue
endpointPoint de collecte Kabeenhttps://intake.kabeen.io

Encodage. Le fichier doit être enregistré en UTF-8 sans BOM (ni UTF-16) : un mauvais encodage empêche l'agent de démarrer. Méthodes fiables et diagnostic dans Diagnostic › Encodage du fichier de configuration.

Protégez ce fichier. Il contient la clé d'API en clair : restreignez les ACL du partage à une lecture par Ordinateurs du domaine uniquement.

Créer la préférence GPO

  1. Dans la même GPO, naviguez vers :
    • Configuration ordinateur > Préférences > Paramètres Windows > Fichiers
  2. Clic droit > Nouveau > Fichier.
  3. Renseignez :
    • Action : Remplacer (ou Mettre à jour si vous préférez ne pas écraser une personnalisation locale)
    • Fichier(s) source : \\fileserver.corp\software$\Kabeen\config.toml
    • Fichier de destination : C:\ProgramData\Kabeen\Server Agent\config.toml

Aucun redémarrage du service n'est nécessaire. L'agent relit config.toml toutes les 10 secondes : la configuration est prise en compte au tick suivant, y compris lorsque vous faites évoluer la clé plus tard.

Restreindre les permissions du fichier déposé

La préférence Fichiers recopie les ACL héritées de C:\ProgramData. Pour verrouiller le fichier, ajoutez dans la GPO une tâche immédiate (voir la variante B) exécutant :

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

Cette même préférence Fichiers permet aussi de mettre à jour la clé d'API sur un parc déjà équipé, sans réinstaller quoi que ce soit.

Étape 4 : Appliquer et vérifier

  1. Forcez la mise à jour des stratégies sur un serveur de test, puis redémarrez-le pour déclencher l'installation :
gpupdate /force
Restart-Computer
  1. Après redémarrage, vérifiez que le service est démarré :
Get-Service -Name KabeenServerAgent
  1. Consultez les journaux de l'agent :
Get-Content 'C:\ProgramData\Kabeen\Server Agent\logs\kabeen-server-agent.log' -Tail 30

Une fois la clé d'API valide prise en compte, les journaux doivent afficher All tasks running. Agent is operational. et la machine doit apparaître dans votre console Kabeen avec un heartbeat récent (moins de 2 minutes).

Variantes

Variante A : transformation MST portant la clé d'API

Le MSI expose une propriété publique APIKEY, exploitable en ligne de commande :

msiexec /i "kabeen-server-agent-x86_64.msi" /qn /norestart APIKEY="VOTRE_CLÉ_API_KABEEN"

La GPO Installation de logiciel n'offrant aucun champ « arguments », la seule façon d'y injecter cette propriété est un fichier de transformation .mst, à déclarer dans l'onglet Modifications du package (onglet accessible uniquement si vous choisissez Avancé au lieu d'Attribué lors de la création du package).

Générez le MST avec Orca (Windows SDK) : Transform > New Transform, table Property, ajout d'une ligne APIKEY = votre clé, puis Transform > Generate Transform.

Deux limites importantes avant de choisir cette variante :

  • La clé d'API se retrouve en clair dans le .mst déposé sur le partage. Appliquez-y les mêmes ACL restrictives que sur le config.toml.
  • À l'installation, le MSI réécrit intégralement config.toml avec la seule clé d'API. Lors d'une mise à niveau du package portant le même MST, un proxy ou un network_usage que vous auriez ajouté serait donc perdu. Cette variante est déconseillée si vous passez par un proxy.

Variante B : tâche immédiate et script PowerShell

Cette approche permet d'installer et de configurer en une seule passe, sans redémarrage préalable, et de gérer les ACL correctement.

Créez dans la GPO une tâche immédiate :

  • Configuration ordinateur > Préférences > Panneau de configuration > Tâches planifiées > Nouveau > Tâche immédiate (Windows 7 et versions ultérieures)
  • Utilisateur : NT AUTHORITY\System
  • Exécuter avec les autorisations maximales : coché
  • Action : Démarrer un programme
    • Programme : powershell.exe
    • Arguments : -NoProfile -ExecutionPolicy Bypass -File "\\fileserver.corp\software$\Kabeen\install.ps1"

Contenu de install.ps1 (à adapter, et à signer si vos stratégies l'exigent) :

$ErrorActionPreference = 'Stop'
$msi    = '\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi'
$marker = 'C:\ProgramData\Kabeen\Server Agent\.gpo-installed'
$apiKey = '<CLÉ_RÉCUPÉRÉE_DEPUIS_VOTRE_COFFRE>'
 
if (Test-Path $marker) { exit 0 }   # déjà installé par la GPO
 
# 1. Installation silencieuse
Start-Process msiexec.exe -ArgumentList @(
    '/i', "`"$msi`"", '/qn', '/norestart',
    '/l*v', 'C:\Windows\Temp\kabeen-server-agent-install.log'
) -Wait -NoNewWindow
 
# 2. Configuration
$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 sans BOM
icacls $cfg /inheritance:r `
    /grant 'SYSTEM:(F)' `
    /grant 'Administrators:(F)' `
    /grant 'NT SERVICE\KabeenServerAgent:(R)' | Out-Null
 
# 3. Marqueur d'idempotence
New-Item -ItemType File -Path $marker -Force | Out-Null

Ne stockez jamais la clé en clair dans le script. Privilégiez une récupération depuis un coffre interne (Azure Key Vault, HashiCorp Vault) au moment de l'exécution.

Notez également que la propriété APIKEY apparaît en clair dans un journal verbeux /l*v : protégez ou purgez ces fichiers.

Filtrage par groupe de sécurité

Pour un déploiement progressif :

  1. Créez un groupe de sécurité contenant les comptes d'ordinateurs cibles (ex. « Serveurs-Agent-Kabeen »).
  2. Dans la GPO, onglet Délégation > Avancé.
  3. Retirez « Utilisateurs authentifiés » de l'application (décochez Appliquer la stratégie de groupe).
  4. Ajoutez votre groupe avec les droits « Lire » et « Appliquer la stratégie de groupe ».

Mise à jour du parc

Le MSI utilise un UpgradeCode stable et une mise à niveau majeure : la nouvelle version s'installe par-dessus l'ancienne, en conservant la configuration et l'identité de l'hôte.

  1. Déposez le nouveau MSI sur le partage.
  2. Dans la GPO, créez un nouveau package et, dans son onglet Mises à niveau, déclarez qu'il remplace le package précédent.

Le dossier C:\ProgramData\Kabeen\Server Agent étant marqué comme permanent, config.toml survit également à une désinstallation. Voir Mettre à jour l'agent serveur et Désinstaller l'agent serveur.

Migration depuis l'ancien agent

Si un ancien agent Kapsul est déjà installé sur les serveurs cibles, l'agent serveur importe automatiquement sa configuration au tout premier démarrage :

Élément de l'ancien agentRepris dans l'agent serveur
kbine.apiKeyapi_key (clé d'API)
agentUUIDidentité de l'agent (agent_id)

La reprise de l'agentUUID garantit que la machine conserve la même identité côté console Kabeen — elle n'apparaît pas comme un nouvel hôte.

La migration ne s'effectue qu'une seule fois et n'écrase jamais une configuration déjà renseignée. Sur un parc en migration, vous pouvez donc déployer la GPO d'installation sans diffuser de config.toml : chaque serveur reprendra sa propre clé existante. Procédure recommandée : déployer l'agent serveur, vérifier dans la console que les machines remontent sous le même identifiant, puis désinstaller l'ancien agent.

Dépannage

L'installation ne démarre pas

  • Vérifiez que le chemin UNC est accessible depuis le compte d'ordinateur (et non depuis votre session d'administration).
  • Vérifiez les permissions de lecture sur le partage et sur le fichier MSI.
  • Un redémarrage est indispensable pour déclencher une installation Attribué : gpupdate /force seul ne suffit pas.
  • Consultez les journaux d'événements Windows (Application et Système) et la sortie de gpresult /h rapport.html.

Le service tourne mais rien ne remonte dans la console

C'est presque toujours un problème de configuration :

  • Vérifiez que C:\ProgramData\Kabeen\Server Agent\config.toml existe bien et contient api_key.
  • La clé doit faire au moins 16 caractères et ne pas être une valeur de remplissage (changeme, placeholder…) : sinon l'agent considère la configuration comme incomplète et attend.
  • Vérifiez l'encodage du fichier : UTF-8 sans BOM.
  • Le message Configuration is incomplete (api_key is empty). Waiting... dans les journaux confirme ce diagnostic.

Erreur de connexion

  • Testez la connectivité sortante : Test-NetConnection -ComputerName intake.kabeen.io -Port 443.
  • Vérifiez le pare-feu : seul le port 443/TCP sortant vers intake.kabeen.io est requis.
  • Derrière un proxy d'entreprise, reportez-vous à Configuration du proxy sur l'agent serveur.
PrécédentConfiguration du proxy sur l'agent serveurSuivantMettre à jour l'agent serveur