Client-Agent: Betrieb und Rollout

Für Administratoren. Stand September 2026 (Server 1.0.31, Agent 1.0.36). Verwandte Anleitungen: Administrationshandbuch (Kapitel „Clients anbinden"), Quick-Admin-Guide (Schritt für Schritt mit Bildschirmfotos), Geräte ohne Domäne (API-Key), Bekannte Fehlerbilder, MSIX-Pakete verteilen, Richtlinien und Vorlagen.

1. Was ist das?

Der ZeroPortal Client-Agent läuft auf dem Endgerät. Er fragt das Portal, was dem Computer und dem angemeldeten Benutzer zugewiesen ist, und setzt das lokal um: MSIX-Pakete (auch als App Attach), App-V-Pakete und Verbindungsgruppen sowie ZeroPortal-Richtlinien. Er meldet dem Portal, dass Gerät und Benutzer aktiv sind (Lizenzquittung), und zeigt dem Benutzer über ein Tray-Symbol, was gerade passiert.

Anmeldung am Portal. In einer Domäne braucht der Agent keine Konfiguration: der Dienst meldet sich mit dem Computerkonto (Kerberos) an, der Benutzer-Sync mit dem Ticket des Benutzers. Geräte ohne Domäne holen sich über ein Registrierungstoken einen eigenen Schlüssel (geschützt unter HKLM\SOFTWARE\NickIT\ZPAgent\Auth); liegt ein Schlüssel vor, wird er benutzt, sonst Kerberos. Siehe Geräte ohne Domäne (API-Key).

2. Wozu ist das gut?

• Arbeitsplätze in der Domäne. MSI per Gruppenrichtlinie oder Softwareverteilung, alle Einstellungen aus einer GPO. Nach der ersten Anmeldung erscheinen die zugewiesenen Anwendungen; neue Zuweisungen kommen mit dem nächsten Abgleich.
• Terminalserver und Sitzungshosts. Der Computer-Sync stellt Pakete maschinenweit bereit, der Benutzer-Sync registriert sie bei jeder Anmeldung. App Attach hält die Paketinhalte auf einem zentralen Image statt in jedem Profil.
• Notebooks. Ohne Portalkontakt arbeitet der Agent mit seinem Zwischenspeicher weiter und entfernt nichts. Lokal installierte MSIX- und vollständig geladene App-V-Pakete laufen offline; App Attach braucht die Freigabe.
• Mehrere Standorte. Ein standortlokaler Pfad für die Paketquelle (MSIX/MSIXPackageRoot) hält den Paketverkehr im Standortnetz.
• Cluster. Mehrere Portal-Server in der Serverliste bilden eine Prioritätskette; bei Ausfall wechselt der Agent zum nächsten.
• Geräte ohne Active Directory. Pilotgeräte oder Einzelplätze melden sich mit einem Schlüssel an, den sie sich mit einem Registrierungstoken selbst holen.

3. Wie nutze ich das?

3.1 Agent-MSI beziehen

Die zum Server passende Agent-MSI liegt im Portal in der Seitenleiste unter Downloads (Voll-Administratoren und Gruppen mit Stufe Lesen für den Bereich Downloads auf der Seite Berechtigungen). Neue Agent-Versionen kommen mit dem Server-Update.

Edge und SmartScreen warnen bei einer selten heruntergeladenen Datei: Beibehalten und Trotzdem beibehalten. Für den regelmäßigen Bezug nehmen Sie die Portal-Domäne per Richtlinie aus (Abschnitt 3.2).

3.2 Browser vorbereiten: Intranetzone und SmartScreen

Intranetzone. Damit sich Browser und Agent ohne Anmeldefenster per Kerberos anmelden, gehört die Portal-URL in die Zone Lokales Intranet. Ein Anmeldefenster trotz korrekter Berechtigung ist fast immer dieses fehlende Zonen-Mapping (fehlende Berechtigung erscheint als „kein Zugriff"). Per GPO: Benutzerkonfiguration → Administrative Vorlagen → Windows-Komponenten → Internet Explorer → Internetsystemsteuerung → Sicherheitsseite → Site-zu-Zone-Zuweisungsliste, Portal-FQDN mit Wert 1; gilt auch für Edge und Chrome. Einen SPN braucht es nur, wenn das Portal unter einem Aliasnamen erreichbar ist (Bekannte Fehlerbilder).

SmartScreen. GPO Computerkonfiguration → Administrative Vorlagen → Microsoft Edge → SmartScreen-Einstellungen → Liste der Domänen, für die Microsoft Defender SmartScreen keine Warnungen auslöst (Registry: HKLM\SOFTWARE\Policies\Microsoft\Edge\SmartScreenAllowListDomains, Wert 1 = Portal-FQDN). Meldet Edge „unsicherer Download blockiert", wurde das Portal über HTTP statt HTTPS aufgerufen.

3.3 Gruppenrichtlinie vorbereiten (ADMX)

Wo finde ich die ADMX-Vorlage? Sie wird mit dem Agenten installiert und liegt auf jedem Gerät mit Agent unter

C:\Program Files\NickIT\ZeroPortalAgent\admx

Der Ordner enthält ZeroPortalAgent.admx und die Sprachordner de-DE und en-US mit den zugehörigen .adml-Dateien. Es gibt keinen getrennten Download: Installieren Sie den Agenten einmal auf einem beliebigen Rechner (auch auf dem Portal-Server) und holen Sie die Dateien von dort.

Kopieren Sie die Dateien in den Central Store Ihrer Domäne (\\<Domäne>\SYSVOL\<Domäne>\Policies\PolicyDefinitions). Die Einstellungen erscheinen unter Computerkonfiguration → Administrative Vorlagen → NickIT → ZeroPortal Agent.

Vier Einstellungen entscheiden über alles Weitere. Sie stehen direkt im Ordner ZeroPortal Agent, alle übrigen liegen in den Unterordnern.

Nach der Installation sind alle drei Abgleichbereiche aus: der Agent verbindet sich mit dem Portal, stellt aber nichts bereit. Schalten Sie nur ein, was Sie wirklich brauchen.

App-V-Abgleich ausgeschaltet lassen, wenn der Microsoft-App-V-Client die Pakete holt. Für App-V gibt es zwei Wege, und auf einem Gerät darf immer nur einer aktiv sein. Entweder der Microsoft-App-V-Client fragt das Portal selbst als Publishing-Server ab, dann bleibt Sync App-V einschalten aus. Oder der ZeroPortal-Agent übernimmt die App-V-Pakete, dann tragen Sie im Microsoft-Client keinen Publishing-Server ein. Laufen beide, veröffentlichen und entfernen sie dieselben Pakete abwechselnd: Verknüpfungen verschwinden und tauchen wieder auf, und in den Protokollen jagen sich die Einträge. MSIX und Richtlinien sind davon nicht betroffen, die dürfen parallel laufen.

Bei eigener PKI verteilen Sie das Serverzertifikat des Portals mit derselben GPO in den Speicher Vertrauenswürdige Stammzertifizierungsstellen des Computers; der Dienst läuft als System und sieht keine Benutzerzertifikate.

3.4 Agent installieren

msiexec /i ZeroPortalAgent-<Version>.msi /qn

Der Dienst startet sofort, der erste Computer-Sync läuft etwa 30 Sekunden später, das Tray-Symbol erscheint in jeder angemeldeten Sitzung. Ein Neustart ist nicht nötig.

MSI-Parameter braucht nur, wer ohne Gruppenrichtlinie arbeitet (Test, Workgroup):

Upgrade. Eine neuere MSI lässt sich über die vorhandene Version installieren; Dienst und Tray werden dabei neu gestartet. Bei einem großen Versionssprung oder wenn ein Upgrade mit Fehler 1603 zurückgerollt wird: alte Version deinstallieren, neue MSI installieren. Vermeiden Sie Serien von Installationen und Dienstneustarts im Minutentakt (Abschnitt 5.2).

3.5 Erste Prüfung

Auf dem Client in einer administrativen PowerShell:

Get-ZPAgentStatus                 # Dienst erreichbar, Version, Serverliste
Get-ZPAgentSync                   # Welche Bereiche aktiv sind und woher der Wert stammt
Sync-ZPAgentPublishingServer      # Abgleich sofort anstoßen
Get-ZPAgentPackage                # Vom Agenten verwaltete Pakete

Der Benutzer sieht dasselbe im Tray-Symbol: Jetzt synchronisieren, Pakete anzeigen…, Logs öffnen, Bereitstellungszeiten… und Einstellungen… (zentrale Vorgaben haben Vorrang).

Im Portal erscheint das Gerät nach dem ersten Abgleich auf der Seite Globale Konfiguration → Agent-Registrierung in der Karte Bekannte Clients.

3.6 Einstellungen ändern

Die Faustregel: Was der Agent zum Starten braucht, kommt aus der Gruppenrichtlinie. Wie er sich im Betrieb verhält, kommt aus einer Richtlinie im Portal.

Die Gruppenrichtlinie bietet 25 Einstellungen an, die Portal-Richtlinie erreicht alle 57 Schalter. Nur in der Gruppenrichtlinie gibt es die Publishing-Server und das Registrierungstoken — beide braucht der Agent, bevor er ein Portal erreichen kann. Umgekehrt haben 34 Schalter keinen Eintrag in der Vorlage, darunter der App-Attach-Mount-Pfad, die Regeln fürs Entfernen, Downgrade und Selbstheilung sowie das Tray-Verhalten; die setzen Sie über die Portal-Richtlinie oder lokal. Anhang 6.1: steht in der Spalte ADMX ein Name, geht es auch per Gruppenrichtlinie.

1. Gruppenrichtlinie (ADMX) für Serverliste, Failover, Zeitverhalten, die drei Sync-Schalter und Protokollierung. Gewinnt immer.
2. ZeroPortal-Richtlinie vom Typ Agent-Konfiguration im Portal (Vorlage Agent-Konfiguration, siehe Richtlinien und Vorlagen): erreicht jeden Schalter des Katalogs. Wird mit dem nächsten Abgleich wirksam; ein später aus der Richtlinie entfernter Wert wird auf dem Gerät zurückgesetzt.
3. PowerShell lokal mit Set-ZPAgentConfiguration -<Schalter> <Wert>; jeder Schalter ist ein eigener Parameter, die Tab-Vervollständigung zeigt alle:

Get-ZPAgentConfiguration                                 # alle Schalter: Name, Wert, SetByGroupPolicy, Bereich
Get-ZPAgentConfiguration -SyncIntervalMinutes            # nur dieser Schalter
Set-ZPAgentConfiguration -SyncIntervalMinutes 30
Set-ZPAgentConfiguration -LogLevel Debug
Enable-ZPAgentSync -Msix -Policy                         # Abgleichbereiche lokal einschalten

3.7 Publishing-Server ohne Gruppenrichtlinie

Add-ZPAgentPublishingServer -Name 'ZeroPortal' -Url 'https://portal:8443'
Get-ZPAgentPublishingServer
Remove-ZPAgentPublishingServer -Name 'ZeroPortal'

Die lokale Liste gilt nur, solange keine GPO-Liste konfiguriert ist; greift die GPO, wird die lokale Liste ignoriert (nicht gelöscht).

3.8 App-Attach-Mount-Pfad ändern

MSIX/AppAttachMountRoot bestimmt, wohin App-Attach-Images (VHDX/CIM) eingehängt werden; leer bedeutet C:\ProgramData\NickIT\AppAttach. Ist der Pfad nicht nutzbar (Laufwerk fehlt), fällt der Agent auf den Standard zurück (Ereignis 3535). Eine Änderung hängt beim nächsten Abgleich alle App-Attach-Pakete am neuen Pfad ein und registriert sie neu — daher im Wartungsfenster: Set-ZPAgentConfiguration -AppAttachMountRoot 'D:\AppAttach' (oder Richtlinie Agent-Konfiguration), Stop-Service ZeroPortalAgent, Neustart. Mounts überleben keinen Neustart; leere Verzeichnisse des alten Pfads räumt der Agent beim Start weg.

3.9 Standortlokale Paketquelle

MSIX/MSIXPackageRoot (ADMX: Paketquellen-Stammpfad überschreiben) ersetzt den Präfix \\Server\Freigabe der Katalog-URL durch einen lokalen Pfad oder DFS-Pfad; der restliche Pfad bleibt. Gilt für MSIX-Bits und App-Attach-Images. Fehlt ein Paket dort, lädt der Agent von der ursprünglichen Quelle.

4. Regeln: wann wirkt was

4.1 Rangfolge der Einstellungen

Beim Lesen gilt: Gruppenrichtlinie vor Richtlinie Agent-Konfiguration vor lokalem Wert (PowerShell, MSI-Parameter) vor Standard im Code. Ist ein Schalter per GPO gesetzt, haben Set-ZPAgentConfiguration und Enable-ZPAgentSync keine sichtbare Wirkung; Get-ZPAgentConfiguration zeigt das in der Spalte SetByGroupPolicy.

4.2 Zeitverhalten

Ein neues Intervall greift nach dem nächsten Lauf; Periodischer Benutzer-Sync, Protokollierungsstufe und Protokollpfad beim nächsten Dienststart bzw. Benutzer-Sync.

4.3 Serverliste und Failover

• Die GPO-Liste ist maßgeblich. Nach einer Änderung: gpupdate /force am Client; der Agent liest die Liste beim nächsten Abgleich (oder sofort mit Sync-ZPAgentPublishingServer).
• Failover (Standard): Die Liste ist eine Prioritätskette identischer Replikate. Der erste Server, der innerhalb des Failover-Timeouts antwortet, gilt als vollständige Sicht; der Aufräumlauf richtet sich nach seinem Katalog. Nur Server mit demselben Katalog gehören in eine Liste.
• Merge-All (Failover aus): Jeder Server wird kontaktiert, die Inhalte werden zusammengeführt. Nur für unabhängige Portale. Antwortet einer nicht, wird der Aufräumlauf übersprungen (Ereignis 3500), damit kein Paket eines ausgefallenen Servers entfernt wird.
• Zufällige Serverauswahl verteilt die Last: pro Lauf startet der Agent bei einem zufälligen Server der Liste.
• Ein Server, der mit einem Fehler antwortet (403, 500), gilt als erreichbar und landet nicht auf der Sperrliste; der Agent versucht den nächsten.

4.4 Entfernen, Downgrade, Formatwechsel

• Ohne Serverkontakt wird nichts entfernt. Schlägt ein Abruf fehl, bleibt alles wie es ist.
• Ein Paket, das im Katalog fehlt, wird beim nächsten Abgleich entfernt (MSIX/AutoUninstallOnUnpublish; MSIX/ManagedPackageMissThreshold = Anzahl Abgleiche, die es fehlen muss). MSIX/GlobalRemovalPolicy: Immediate sofort, WhenIdle und OnReboot vormerken und später bzw. beim nächsten Dienststart entfernen, Disabled nur beobachten. Läuft die Anwendung, wird aufgeschoben (MSIX/DeferRemovalWhileInUse), spätestens nach MSIX/RemovalIdleTimeoutHours (24) entfernt.
• Downgrade ist aus (MSIX/AllowDowngrade): eine lokal neuere Version gilt als erfüllt (Ereignis 2538 bzw. 3510). Eine Richtlinie Package Downgrade Control je Paketfamilie geht vor (MSIX-Pakete verteilen).
• Formatwechsel MSIX ↔ App Attach: Der Agent beendet die laufende Anwendung und registriert das Paket neu (MSIX/TerminateAppsForFormatSwitch); aus = Wechsel wartet, solange sie läuft (Ereignis 3544).
• Abgleichbereich abschalten (MSIX, App-V, Richtlinien) lässt bereits Bereitgestelltes unverändert.
• Sweep verwaister Verknüpfungen: Agent/ShortcutSweepMode Off (Standard), ZeroPortal (nur eigene Pakete), All (alle lokalen).

4.5 Offline: Notebooks und mobile Geräte

Praxisregel: Mobile Geräte bekommen MSIX oder vollständig geladenes App-V, kein App Attach.

• Richtlinien bleiben auf dem zuletzt angewendeten Stand (Offline-Cache, Ereignis 3600); zurückgenommen wird ein Eintrag nur, wenn ein erreichbarer Server meldet, dass er entfallen ist.
• Lizenz: Die Quittung läuft 90 Tage und wird ab 28 Tagen Restlaufzeit erneuert. Hinweise wie „keine Lizenz frei" kommen nur nach einer echten Serverantwort, höchstens alle 4 Stunden. Erst wenn die Quittung abgelaufen und das Portal weiter unerreichbar ist, sieht der Benutzer einen Hinweis; die Anwendungen laufen in jedem Fall weiter.
• Wieder online holt der erste erfolgreiche Abgleich alles nach: Pakete, Richtlinien, Lizenzerneuerung.

5. Betrieb und Fehlersuche

5.1 Protokolle

Der Agent schreibt nur in diese Textdateien, nicht in das Windows-Ereignisprotokoll. Jede Zeile trägt Zeitstempel, Stufe (INF, WRN, ERR) und in eckigen Klammern die Ereignis-ID (Anhang 6.4); am Ende jedes Abgleichs steht eine Zusammenfassung mit Zählern und den Namen fehlgeschlagener Pakete.

• Feindiagnose: Set-ZPAgentConfiguration -LogLevel Debug (oder GPO Protokollierungsstufe), wirkt beim nächsten Dienststart bzw. Benutzer-Sync; danach zurück auf Information.
• Anderer Ablageort: Agent/LogPath (GPO Alternativer Protokollpfad). Dienst und Benutzer müssen dort schreiben dürfen, sonst entfällt das jeweilige Protokoll still.
• Clear-ZPAgentLog löscht alle Agent-Protokolle; eine automatische Rotation gibt es nicht.
• Der Benutzer erreicht den Ordner über das Tray-Menü Logs öffnen; Bereitstellungszeiten… zeigt, wie lange Pakete und Richtlinien gebraucht haben (Agent/DeploymentReport).
• Die ADMX-Einstellung Keine Benutzernamen ins Agentenprotokoll schreiben (Bereich Datenschutz) wird in dieser Version noch nicht ausgewertet.

5.2 Stabil betreiben und Fehler finden

Jeder Dienststart remountet alle App-Attach-Images und fährt einen vollständigen Abgleich. Installation, Deinstallation oder Dienstneustart im Minutentakt erzeugen einen Mount-/Unmount-Wechsel, bei dem moderne Apps (Task-Manager, Startmenü) beim Start abstürzen können — vorübergehend, keine bleibende Beschädigung. Daher: nach einer Installation den ersten Abgleich abwarten; beim Testen den Dienst zwischen Änderungen stoppen (Stop-Service ZeroPortalAgent) statt ihn schnell neu zu starten; auf Testgeräten mit vielen App-Attach-Paketen den periodischen Abgleich drosseln (Agent/MachineSyncPeriodicEnabled=0 oder größeres MSIX/SyncIntervalMinutes). Tritt der Zustand ein: Dienst stoppen, Gerät neu starten.

6. Anhang: Technische Referenz

6.1 Schalter

Die Schalter, die ein Administrator üblicherweise ändert. Setzbar per GPO (Spalte „ADMX"), per Richtlinie Agent-Konfiguration oder lokal mit Set-ZPAgentConfiguration -<Schalter> <Wert>. Die vollständige Liste mit den aktuellen Werten liefert Get-ZPAgentConfiguration auf dem Gerät; jeder Schalter ist ein Parameter von Set-ZPAgentConfiguration.

6.2 Registry

Drei Stämme: GPO = HKLM\SOFTWARE\Policies\NickIT\ZPAgent (gewinnt beim Lesen; der Agent liest hier jeden Katalogschlüssel, auch ohne ADMX-Eintrag), Lokal = HKLM\SOFTWARE\NickIT\ZPAgent (PowerShell, MSI-Parameter, Richtlinie Agent-Konfiguration), Benutzer = HKCU\SOFTWARE\NickIT\ZPAgent.

Das Tray-Symbol hat keinen Autostart-Eintrag unter Run; der Dienst startet es (Agent/TrayAutostart). Von ZeroPortal-Richtlinien gesetzte Werte (Laufwerke, Registry, Verknüpfungen …) liegen an ihrem jeweiligen Ziel, nicht unter ZPAgent.

6.3 Cmdlets des Moduls ZeroPortalAgent

6.4 Ereignis-IDs im Agent-Protokoll (Auswahl)