Agent auf Windows bereitstellen

Diese Anleitung zeigt dir, wie du den octoja Agent auf einem Windows-System installierst und registrierst.

Voraussetzungen

• Ein octoja-Konto mit der Berechtigung Agent-Verwaltung — ohne sie erscheint Administration → Agent-Bereitstellung nicht in deiner Navigation
• Windows 10 / Windows Server 2016 oder neuer — Details und Legacy-Versionen siehe Tabelle unten
• Microsoft Visual C++ Redistributable (x64 oder ARM64), Version 14.51.36247.0 oder neuer, auf dem Gerät. Die Schnellinstallation prüft die installierte Version und installiert oder aktualisiert sie bei Bedarf; bei Manuelle Installation und Automatischer Rollout installierst du eine unterstützte Version vor der MSI selbst
• Microsoft .NET Framework 4.7.2 oder neuer. Die Schnellinstallation installiert Version 4.7.2, wenn die Voraussetzung nicht erfüllt ist, und behält neuere Versionen bei. Bei Manuelle Installation und Automatischer Rollout installierst du es selbst und führst einen erforderlichen Neustart vor der MSI aus
• Administratorkonto auf dem Gerät
• Internetzugang (ausgehend HTTPS auf Port 443)

Unterstützte Windows-Versionen

Installationsdownloads erlauben

Die Schnellinstallation benötigt ausgehenden HTTPS-Zugriff auf cdn.octoja.com und deine octoja-Instanz. Wenn sie das Visual C++ Redistributable installiert oder aktualisiert, erlaube außerdem aka.ms und dessen Download-Ziel download.visualstudio.microsoft.com. Für die Installation von .NET Framework erlaube go.microsoft.com und dessen Download-Ziel download.microsoft.com.

Für die laufende Agent-Kommunikation und funktionsabhängige Anforderungen siehe Firewall-Freigaben für den Agent konfigurieren.

Schritte

1. Navigiere in octoja zu Administration → Agent-Bereitstellung.
2. Überprüfe in Schritt 1 – Einstellungen den Bereitstellungsmodus (offenes Deployment oder Token-basiert).
3. Klicke in Schritt 2 – Plattform wählen auf Windows.
4. Wähle in Schritt 3 – Installationsmethode wählen die gewünschte Methode aus:
   • Schnellinstallation — ein einzelner PowerShell-Befehl, der die Architektur automatisch erkennt und lautlos installiert. Ideal für ein einzelnes Gerät.
   • Manuelle Installation — lade das ZIP-Archiv herunter, entpacke die MSI und installiere sie selbst mit einem Assistenten oder Silent-Flag.
   • Automatischer Rollout — generiere den Intune- oder Gruppenrichtlinien-Befehl (GPO), um auf vielen Geräten gleichzeitig bereitzustellen.
5. Kopiere den Befehl oder lade das Installationsprogramm aus dem angezeigten Bereich herunter. Lass das Fenster offen — der Befehl enthält deine individuelle Server-URL.
6. Führe den Befehl auf dem Windows-Gerät aus (siehe unten).
7. Navigiere in octoja zurück zu Geräte. Das Gerät erscheint innerhalb von Sekunden.

Schnellinstallation (empfohlen für ein einzelnes Gerät)

Kopiere den PowerShell-Befehl von der Bereitstellungsseite und füge ihn in eine PowerShell mit erhöhten Rechten auf dem Zielgerät ein.

Der PowerShell-Befehl sieht in etwa so aus:

& ([scriptblock]::Create((irm https://cdn.octoja.com/installer/install.ps1))) -OctojaUrl 'https://YOUR-OCTOJA-URL'

Falls Token-basiertes Deployment aktiviert ist, enthält der Befehl ein -Token-Argument — übernimm dieses vollständig:

& ([scriptblock]::Create((irm https://cdn.octoja.com/installer/install.ps1))) -OctojaUrl 'https://YOUR-OCTOJA-URL' -Token 'YOUR-TOKEN'

Das Skript prüft die Voraussetzungen und installiert fehlende Komponenten von Microsoft Visual C++ Redistributable und .NET Framework automatisch. Es erkennt die Gerätearchitektur (x64 oder ARM64), lädt das korrekte Paket herunter, entpackt die enthaltene MSI und führt sie lautlos aus. Es erfordert eine PowerShell-Sitzung mit Administratorrechten.

Windows Server 2016 (und ältere Windows): zuerst TLS 1.2 aktivieren. Auf diesen Systemen nutzt Windows PowerShell noch eine ältere TLS-Version, daher kann der Befehl bereits am Download-Schritt (irm https://cdn.octoja.com/installer/install.ps1) mit einem Verbindungsfehler wie „Die zugrunde liegende Verbindung wurde geschlossen: Unbekannter Fehler beim Empfangen.“ scheitern — bevor die eingebaute TLS-Anhebung des Installationsprogramms greifen kann. Aktiviere in derselben PowerShell-Sitzung mit erhöhten Rechten TLS 1.2 und führe den octoja-Befehl dann erneut aus:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Ein Zertifikatsvertrauensfehler ist etwas anderes. Endet Resolve installer URL mit „Für den geschützten SSL/TLS-Kanal konnte keine Vertrauensstellung hergestellt werden“, hilft ein Wechsel auf TLS 1.2 nicht. Der Startbefehl lädt das Skript von cdn.octoja.com; nach dem Start fragt das Skript deine octoja-Instanz nach der Installer-URL und lädt das Paket anschließend aus dem CDN. Eine Firewall oder ein Proxy mit SSL-/TLS-Deep-Inspection kann das Zertifikat beider Ziele durch ein Zertifikat der eigenen Zertifizierungsstelle ersetzen. Windows lehnt dieses Zertifikat ab, wenn es der Zertifizierungsstelle auf dem Gerät nicht vertraut.

Bitte deinen Netzwerkadministrator, sowohl die URL deiner octoja-Instanz als auch cdn.octoja.com von SSL-/TLS-Deep-Inspection auszunehmen. Öffne auf dem betroffenen Gerät beide Adressen im Browser und prüfe im Zertifikat den Aussteller. Gehört der Aussteller zu deiner Firewall, deinem Proxy oder deiner Organisation statt zur öffentlichen Zertifizierungsstelle der Website, wird die Verbindung per Deep Inspection untersucht.

Prüfe für grundlegende DNS- und Porttests beide Ziele. Ersetze https://YOUR-OCTOJA-URL durch die vollständige URL deiner Instanz. Diese Tests prüfen nicht die Zertifikatsvertrauensstellung:

$instanceHost = ([Uri]'https://YOUR-OCTOJA-URL').Host
Test-NetConnection $instanceHost -Port 443
Resolve-DnsName $instanceHost
Test-NetConnection cdn.octoja.com -Port 443
Resolve-DnsName cdn.octoja.com

Manuelle Installation (MSI)

Vor dem Ausführen der MSI: Stelle sicher, dass Microsoft Visual C++ Redistributable (x64 oder ARM64) und .NET Framework die oben genannten Voraussetzungen erfüllen, und führe einen erforderlichen Neustart durch. Die Schnellinstallation ergänzt fehlende Voraussetzungen für dich; die MSI setzt voraus, dass sie bereits vorhanden sind.

Wähle auf der Bereitstellungsseite Manuelle Installation aus, um die Schaltfläche Download x64 / Download ARM64 zu sehen. Der Download ist ein ZIP-Archiv — entpacke es zuerst und führe dann die enthaltene MSI (octoja.Launcher.<version>.<arch>.msi) mit msiexec aus:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL"

Hänge /qn für lautlose Installation ohne Benutzeroberfläche an:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL" /qn

Falls ein Enrollment-Token erforderlich ist, füge TOKEN="..." hinzu:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL" TOKEN="YOUR-TOKEN" /qn

Automatischer Rollout (Intune / Gruppenrichtlinie)

Die Karte Automatischer Rollout führt dich durch jedes Bereitstellungstool. Die MSI selbst stammt aus dem Download der Manuellen Installation — entpacke sie zuerst aus dem ZIP-Archiv.

Per Gruppenrichtlinie ausrollen

Die Softwareinstallation per Gruppenrichtlinie kann selbst keine MSI-Eigenschaften übergeben. Deshalb bekommst du von octoja eine fertige Transform-Datei (octoja.Launcher.<version>.mst), in der deine Server-URL und das Enrollment-Token schon enthalten sind. Sie setzt dieselben Eigenschaften OCTOJA_URL und TOKEN wie der manuelle msiexec-Befehl.

1. Wähle auf der Karte Automatischer Rollout die Registerkarte Gruppenrichtlinie (GPO) und klicke auf Transform (.mst) herunterladen. Wenn du das Enrollment-Token später änderst, lade die Datei einfach erneut herunter.

2. Kopiere die MSI und die .mst-Datei auf eine Netzwerkfreigabe und verwende UNC-Pfade wie \\Server\Freigabe\…. Die Installation läuft unter dem Computerkonto. Die Zielcomputer brauchen deshalb Leserechte auf die Freigabe und auf die Dateien (NTFS).

3. Navigiere in einer GPO zu Computerkonfiguration → Richtlinien → Softwareeinstellungen → Softwareinstallation und füge die MSI als neues Paket hinzu. Wähle als Bereitstellungsmethode Erweitert – nur so kannst du die Transform-Datei anhängen.

   

4. Klicke auf der Registerkarte Änderungen des Pakets auf Hinzufügen und wähle die .mst-Datei über denselben UNC-Pfad aus.

   

5. Verknüpfe die GPO mit der OU, in der die Zielcomputer liegen. Der Agent wird beim nächsten Start des jeweiligen Computers installiert. Mehr Details zu den Konsolenschritten findest du in Microsofts Anleitung zur Softwareinstallation per Gruppenrichtlinie.

Du filterst nach einer Gruppe? Wenn du die Sicherheitsfilterung der GPO auf eine Gruppe wie Domänencomputer einschränkst, denk daran, dass Domänencontroller nicht darin enthalten sind (Microsofts Gruppenreferenz). Sollen auch deine Domänencontroller den Agent bekommen, nimm sie zusätzlich in den Filter und in die Freigabeberechtigungen auf.

So bleibt der Agent installiert: Die Gruppenrichtlinie entfernt Software nur beim Computerstart. Eine ungewollte Deinstallation fällt deshalb oft erst Tage oder Wochen später auf, nach einem ganz normalen Neustart. Auf zwei Einstellungen kommt es an:

• „Uninstall this application when it falls out of the scope of management“ deaktiviert lassen. Du findest die Option auf der Registerkarte Bereitstellung des Pakets (im deutschen Windows sinngemäß „Anwendung deinstallieren, wenn sie außerhalb des Verwaltungsbereichs liegt“). Ist sie aktiv, entfernt Windows den Agent von jedem Computer, für den die GPO nicht mehr gilt – zum Beispiel, nachdem du den Filter änderst oder einen Computer in eine andere OU verschiebst.

  

• Beim Entfernen des Pakets die Software behalten. Um eine neue MSI oder Transform-Datei zu verteilen, entfernst du das Paket und fügst es neu hinzu. Im Dialog Software entfernen ist Immediately uninstall the software from users and computers vorausgewählt. Damit wird der Agent beim nächsten Start deinstalliert – und klappt die Installation des neuen Pakets nicht, bleibt das Gerät ohne Agent. Wähle stattdessen Allow users to continue to use the software, but prevent new installations (sinngemäß: Software weiter nutzen, aber keine neuen Installationen). Installierte Agents bleiben registriert; ein neues Token gilt nur für neue Installationen.

  

Windows 10 und 11: Diese Systeme warten beim Start standardmäßig nicht auf das Netzwerk und überspringen dadurch oft die Softwareinstallation. Aktiviere deshalb in derselben oder einer eigenen GPO Computerkonfiguration → Richtlinien → Administrative Vorlagen → System → Anmelden → Beim Neustart des Computers und bei der Anmeldung immer auf das Netzwerk warten.

Vorkonfigurierte Einstellungsdatei verwenden

Klicke auf der Seite zur Agent-Bereitstellung unter Manuelle Installation auf installer.settings.json, um die vorkonfigurierte Datei herunterzuladen, und lege sie neben der MSI ab. So musst du die Server-URL und den Enrollment-Token nicht per Kommandozeile übergeben.

Führe dann msiexec /i octoja.Launcher.<version>.<arch>.msi /qn aus — das Installationsprogramm liest die Einstellungsdatei automatisch.

Parameterreferenz

Installation überprüfen

1. Stelle in der Windows-Konsole Dienste sicher, dass beide Agent-Dienste Wird ausgeführt sind: Octoja Agent (Octoja.Agent) und Octoja Launcher (Octoja.Launcher).
2. Navigiere in octoja zu Geräte — das Gerät erscheint innerhalb von Sekunden nach Abschluss der Installation.

Enrollment-Token benötigt? Siehe Enrollment-Tokens konfigurieren.

FAQ