Server-Agent-Bereitstellung per GPO

Der Kabeen Server-Agent kann über Gruppenrichtlinienobjekte (GPO) von Microsoft Active Directory zentral auf allen Ihren Windows-Servern bereitgestellt werden.

Die Bereitstellung erfolgt in zwei Schritten, beide vollständig GPO-nativ: die Installation des MSI-Pakets über Softwareinstallation und anschließend die Verteilung der Konfigurationsdatei über die Einstellung Dateien.

Neu in 3.0. Der Agent liest keinen Registrierungsschlüssel mehr. Seine gesamte Konfiguration steckt in einer einzigen Datei config.toml, die automatisch alle 10 Sekunden neu eingelesen wird. Ist ein älterer Kapsul-Agent auf dem Rechner vorhanden, werden dessen API-Schlüssel und Kennung beim ersten Start automatisch migriert (siehe Migration vom bisherigen Agenten).

Voraussetzungen

• Administratorrechte auf dem Domänencontroller
• Windows-Server, die der Domäne beigetreten sind (Windows Server 2016+, Windows 10/11)
• Signiertes MSI-Paket: kabeen-server-agent-<version>-x86_64.msi (Variante -aarch64.msi für ARM-Rechner)
• Kabeen-API-Schlüssel
• Ausgehende Verbindung zu intake.kabeen.io über Port 443/TCP

Das Paket erhalten Sie über Ihre Kabeen-Konsole (Infrastruktur > Server hinzufügen > Automatische Installation) oder direkt:

Schritt 1: Netzwerkfreigabe vorbereiten

1. Erstellen Sie einen freigegebenen Ordner, der für alle Zielserver zugänglich ist.
2. Kopieren Sie die MSI-Datei dorthin.
3. Prüfen Sie die Berechtigungen: Da die Installation im Computerkontext läuft, benötigen die Computerkonten Lesezugriff (über Authentifizierte Benutzer oder Domänencomputer) — nicht die Benutzerkonten.

\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi

Der Pfad muss zwingend ein UNC-Pfad sein: ein lokaler Pfad (C:\...) wäre von den Zielservern aus nicht auflösbar.

Schritt 2: Installations-GPO erstellen

1. Öffnen Sie die Gruppenrichtlinienverwaltungskonsole (GPMC).
2. Erstellen Sie ein neues GPO, das mit der OU Ihrer Server verknüpft ist.
3. Bearbeiten Sie das GPO und navigieren Sie zu:
   • Computerkonfiguration > Richtlinien > Softwareeinstellungen > Softwareinstallation
4. Rechtsklick > Neu > Paket.
5. Wählen Sie die MSI-Datei über den UNC-Netzwerkpfad aus.
6. Wählen Sie Zugewiesen als Bereitstellungsmethode.

Die Installation wird beim nächsten Neustart des Servers ausgelöst, im Computerkontext und vor der Anmeldung. Sie kopiert die Binärdatei nach C:\Program Files\Kabeen\Server Agent\, registriert den Windows-Dienst KabeenServerAgent (automatischer Start) und startet ihn.

Bis hierhin wurde kein API-Schlüssel übergeben — das ist so vorgesehen: Der Dienst startet trotzdem und wartet auf eine gültige Konfiguration, protokolliert dabei Configuration is incomplete (api_key is empty). Waiting.... Er stürzt nicht ab und verbraucht praktisch keine Ressourcen. Der Schlüssel wird im nächsten Schritt verteilt.

Schritt 3: Konfiguration verteilen

In 3.0 wird der API-Schlüssel nicht mehr über einen Registrierungsschlüssel konfiguriert, sondern aus C:\ProgramData\Kabeen\Server Agent\config.toml gelesen. Am einfachsten verteilen Sie eine zentrale Referenzdatei über die Gruppenrichtlinieneinstellungen.

Referenzdatei config.toml vorbereiten

Legen Sie auf Ihrer Freigabe eine Datei config.toml mit folgendem Inhalt ab:

# Konfiguration des Kabeen Server-Agenten
api_key = "IHR_KABEEN_API_SCHLÜSSEL"
 
# Nur bei Bedarf einkommentieren:
# proxy = "http://proxy.corp.example:8080"
# network_usage = false

Diese drei Schlüssel — zuzüglich endpoint, der nur auf Anweisung des Supports geändert werden sollte — sind sämtliche vom Agenten erkannten Parameter.

Kodierung. Die Datei muss als UTF-8 ohne BOM (nicht UTF-16) gespeichert werden: eine falsche Kodierung verhindert den Start des Agenten. Zuverlässige Methoden und Fehlerbehebung unter Diagnose › Kodierung der Konfigurationsdatei.

Schützen Sie diese Datei. Sie enthält den API-Schlüssel im Klartext: Beschränken Sie die Freigabe-ACLs auf Lesezugriff für Domänencomputer.

GPO-Einstellung anlegen

1. Navigieren Sie im selben GPO zu:
   • Computerkonfiguration > Einstellungen > Windows-Einstellungen > Dateien
2. Rechtsklick > Neu > Datei.
3. Tragen Sie ein:
   • Aktion: Ersetzen (oder Aktualisieren, wenn eine lokale Anpassung nicht überschrieben werden soll)
   • Quelldatei(en): \\fileserver.corp\software$\Kabeen\config.toml
   • Zieldatei: C:\ProgramData\Kabeen\Server Agent\config.toml

Ein Neustart des Dienstes ist nicht erforderlich. Der Agent liest config.toml alle 10 Sekunden neu: Die Konfiguration greift beim nächsten Durchlauf — auch dann, wenn Sie den Schlüssel später wechseln.

Berechtigungen der abgelegten Datei einschränken

Die Einstellung Dateien übernimmt die von C:\ProgramData geerbten ACLs. Um die Datei abzusichern, fügen Sie dem GPO eine Sofortaufgabe hinzu (siehe Variante B), die Folgendes ausführt:

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

Dieselbe Dateien-Einstellung eignet sich auch dazu, den API-Schlüssel auf einem bereits ausgestatteten Serverbestand zu aktualisieren, ganz ohne Neuinstallation.

Schritt 4: Anwenden und überprüfen

1. Erzwingen Sie die Richtlinienaktualisierung auf einem Testserver und starten Sie ihn anschließend neu, um die Installation auszulösen:

gpupdate /force
Restart-Computer

2. Prüfen Sie nach dem Neustart, ob der Dienst läuft:

Get-Service -Name KabeenServerAgent

3. Sehen Sie sich die Protokolle des Agenten an:

Get-Content "C:\ProgramData\Kabeen\Server Agent\logs\$(Get-Date -Format 'yyyy-MM-dd').log" -Tail 30

Sobald ein gültiger API-Schlüssel übernommen wurde, sollten die Protokolle All tasks running. Agent is operational. anzeigen und der Rechner mit einem aktuellen Heartbeat (weniger als 2 Minuten) in Ihrer Kabeen-Konsole erscheinen.

Varianten

Variante A: MST-Transformation mit dem API-Schlüssel

Das MSI stellt die öffentliche Eigenschaft APIKEY bereit, die sich über die Kommandozeile setzen lässt:

msiexec /i "kabeen-server-agent-x86_64.msi" /qn /norestart APIKEY="IHR_KABEEN_API_SCHLÜSSEL"

Da die GPO Softwareinstallation kein Feld für Argumente bietet, lässt sich diese Eigenschaft nur über eine Transformationsdatei .mst einschleusen, die auf der Registerkarte Änderungen des Pakets deklariert wird (diese Registerkarte erscheint nur, wenn Sie beim Anlegen des Pakets Erweitert statt Zugewiesen wählen).

Erzeugen Sie die MST-Datei mit Orca (Windows SDK): Transform > New Transform, Tabelle Property, Zeile APIKEY mit Ihrem Schlüssel hinzufügen, dann Transform > Generate Transform.

Zwei wichtige Einschränkungen, bevor Sie sich für diese Variante entscheiden:

• Der API-Schlüssel liegt im Klartext in der .mst-Datei auf der Freigabe. Wenden Sie dieselben restriktiven ACLs an wie auf config.toml.
• Bei der Installation überschreibt das MSI config.toml vollständig und trägt nur den API-Schlüssel ein. Bei einem späteren Upgrade des Pakets mit derselben MST-Datei gehen daher ein zuvor ergänzter proxy oder network_usage verloren. Diese Variante ist nicht empfehlenswert, wenn Sie einen Proxy einsetzen.

Variante B: Sofortaufgabe und PowerShell-Skript

Dieser Weg installiert und konfiguriert in einem Durchgang, ohne vorherigen Neustart, und setzt die ACLs korrekt.

Legen Sie im GPO eine Sofortaufgabe an:

• Computerkonfiguration > Einstellungen > Systemsteuerungseinstellungen > Geplante Aufgaben > Neu > Sofortaufgabe (mindestens Windows 7)
• Benutzer: NT AUTHORITY\System
• Mit höchsten Privilegien ausführen: aktiviert
• Aktion: Programm starten
  • Programm: powershell.exe
  • Argumente: -NoProfile -ExecutionPolicy Bypass -File "\\fileserver.corp\software$\Kabeen\install.ps1"

Inhalt von install.ps1 (anzupassen und zu signieren, falls Ihre Richtlinien dies verlangen):

$ErrorActionPreference = 'Stop'
$msi    = '\\fileserver.corp\software$\Kabeen\kabeen-server-agent-x86_64.msi'
$marker = 'C:\ProgramData\Kabeen\Server Agent\.gpo-installed'
$apiKey = '<AUS_IHREM_TRESOR_GELESENER_SCHLÜSSEL>'
 
if (Test-Path $marker) { exit 0 }   # bereits per GPO installiert
 
# 1. Unbeaufsichtigte Installation
Start-Process msiexec.exe -ArgumentList @(
    '/i', "`"$msi`"", '/qn', '/norestart',
    '/l*v', 'C:\Windows\Temp\kabeen-server-agent-install.log'
) -Wait -NoNewWindow
 
# 2. Konfiguration
$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 ohne BOM
icacls $cfg /inheritance:r `
    /grant 'SYSTEM:(F)' `
    /grant 'Administrators:(F)' `
    /grant 'NT SERVICE\KabeenServerAgent:(R)' | Out-Null
 
# 3. Idempotenz-Marker
New-Item -ItemType File -Path $marker -Force | Out-Null

Speichern Sie den Schlüssel niemals im Klartext im Skript. Lesen Sie ihn zur Laufzeit aus einem internen Tresor (Azure Key Vault, HashiCorp Vault).

Beachten Sie außerdem: Die Eigenschaft APIKEY erscheint im Klartext in einem ausführlichen Protokoll /l*v — schützen oder löschen Sie diese Dateien.

Filterung nach Sicherheitsgruppe

Für eine schrittweise Einführung:

1. Erstellen Sie eine Sicherheitsgruppe mit den Computerkonten der Zielserver (z. B. „Kabeen-Agent-Server“).
2. Im GPO: Registerkarte Delegierung > Erweitert.
3. Entfernen Sie „Authentifizierte Benutzer“ aus der Anwendung (Häkchen bei Gruppenrichtlinie übernehmen entfernen).
4. Fügen Sie Ihre Gruppe mit den Rechten „Lesen“ und „Gruppenrichtlinie übernehmen“ hinzu.

Serverbestand aktualisieren

Das MSI verwendet einen stabilen UpgradeCode und ein Major-Upgrade: Die neue Version wird über die alte installiert und behält sowohl die Konfiguration als auch die Identität des Hosts bei.

1. Legen Sie das neue MSI auf der Freigabe ab.
2. Erstellen Sie im GPO ein neues Paket und deklarieren Sie auf dessen Registerkarte Upgrades, dass es das vorherige Paket ersetzt.

Da der Ordner C:\ProgramData\Kabeen\Server Agent als permanent gekennzeichnet ist, übersteht config.toml auch eine Deinstallation. Siehe Server-Agent aktualisieren und Server-Agent deinstallieren.

Migration vom bisherigen Agenten

Ist auf den Zielservern bereits ein älterer Kapsul-Agent installiert, importiert der Server-Agent dessen Konfiguration automatisch beim allerersten Start:

Die Übernahme der agentUUID stellt sicher, dass der Rechner in der Kabeen-Konsole dieselbe Identität behält — er erscheint nicht als neuer Host.

Die Migration findet nur ein einziges Mal statt und überschreibt nie eine bereits ausgefüllte Konfiguration. Auf einem in Migration befindlichen Bestand können Sie das Installations-GPO daher ohne Verteilung einer config.toml ausrollen: Jeder Server übernimmt seinen eigenen vorhandenen Schlüssel. Empfohlenes Vorgehen: Server-Agent ausrollen, in der Konsole prüfen, dass die Rechner unter derselben Kennung melden, anschließend den bisherigen Agenten deinstallieren.

Fehlerbehebung

Die Installation startet nicht

• Prüfen Sie, ob der UNC-Pfad vom Computerkonto aus erreichbar ist (nicht aus Ihrer Administrationssitzung).
• Prüfen Sie die Leseberechtigungen auf der Freigabe und auf der MSI-Datei.
• Ein Neustart ist zwingend erforderlich, um eine zugewiesene Installation auszulösen: gpupdate /force allein genügt nicht.
• Prüfen Sie die Windows-Ereignisprotokolle (Anwendung und System) sowie die Ausgabe von gpresult /h bericht.html.

Der Dienst läuft, aber in der Konsole erscheint nichts

Fast immer liegt es an der Konfiguration:

• Prüfen Sie, ob C:\ProgramData\Kabeen\Server Agent\config.toml existiert und api_key enthält.
• Der Schlüssel muss mindestens 16 Zeichen lang sein und darf kein Platzhalterwert sein (changeme, placeholder …): andernfalls betrachtet der Agent die Konfiguration als unvollständig und wartet.
• Prüfen Sie die Kodierung der Datei: UTF-8 ohne BOM.
• Die Protokollmeldung Configuration is incomplete (api_key is empty). Waiting... bestätigt diese Diagnose.

Verbindungsfehler

• Testen Sie die ausgehende Verbindung: Test-NetConnection -ComputerName intake.kabeen.io -Port 443.
• Prüfen Sie die Firewall: Nur der ausgehende Port 443/TCP zu intake.kabeen.io wird benötigt.
• Hinter einem Unternehmens-Proxy siehe Proxy-Konfiguration für den Server-Agenten.