Agent auf Linux bereitstellen

Schritt-für-Schritt-Anleitung zur Installation und Bereitstellung des octoja Agent auf Linux.

Voraussetzungen

Ein octoja-Konto mit der Berechtigung Agent-Verwaltung — ohne sie erscheint Administration → Agent-Bereitstellung nicht in deiner Navigation
Ubuntu 22.04 LTS oder 24.04 LTS, Debian 12 oder 13 oder ein System der RHEL-Familie ab Version 8 (x64 oder arm64)
Root- oder sudo-Zugang
Internetzugang (ausgehend HTTPS auf Port 443)

Wichtige Begriffe

Diese Anleitung verwendet einige Linux-Befehle. Hier ist ihre Bedeutung:

Begriff	Erklärung
Terminal	Eine textbasierte Oberfläche zum Eingeben von Befehlen. Auf einem Linux-Desktop suchst du im Anwendungsmenü nach „Terminal“. Auf einem Server bist du in der Regel bereits in einem Terminal.
sudo	Ein Befehlspräfix, das den nachfolgenden Befehl mit Administrator-(Root-)Rechten ausführt. Möglicherweise wird das Passwort abgefragt.
curl	Ein Kommandozeilenwerkzeug zum Herunterladen von Dateien aus dem Internet.
systemctl	Ein Befehl zur Verwaltung von Hintergrunddiensten (Teil von systemd, dem Dienst-Manager aller modernen Linux-Distributionen).

Schritte

Navigiere in octoja zu Administration → Agent-Bereitstellung.
Wähle in Schritt 1 – Einstellungen den Registrierungsmodus aus. Wähle Offenes Deployment, damit sich jedes Gerät registrieren kann, oder Token-basiertes Deployment, um ein Enrollment-Token zu verlangen. Der in Schritt 4 erzeugte Installationsbefehl ändert sich abhängig von dieser Auswahl.
Klicke in Schritt 2 – Plattform wählen auf Linux.
Wähle in Schritt 3 – Installationsmethode wählen die Schnellinstallation für ein einzelnes Gerät oder Manuelle Installation, wenn du ein eigenes Paket benötigst.
Kopiere in Schritt 4 – Installieren den Befehl aus dem Bereich und führe ihn auf dem Linux-Gerät aus (siehe unten).
Bestätige in Schritt 5 – Verifizierung, dass das neue Gerät auftaucht. Du kannst auch zu Geräte navigieren. Das Gerät erscheint in der Regel innerhalb von Sekunden, nachdem die Installation abgeschlossen ist.

Schnellinstallation (empfohlen)

Die octoja Agent-Bereitstellungsseite mit Linux ausgewählt, Schnellinstallation als Methode und dem sichtbaren Befehl in Schritt 4 – Installieren.

Kopiere den Schnellinstallations-Befehl von der Bereitstellungsseite. Er sieht in etwa so aus:

curl -fsSL 'https://cdn.octoja.com/installer/install.sh' | sudo bash -s -- 'https://YOUR-OCTOJA-URL'

Falls Token-basiertes Deployment aktiviert ist, enthält der Befehl das Token als zweites positionelles Argument:

curl -fsSL 'https://cdn.octoja.com/installer/install.sh' | sudo bash -s -- 'https://YOUR-OCTOJA-URL' 'YOUR-TOKEN'

Den Befehl direkt aus octoja kopieren. Er enthält bereits die Server-URL (und ggf. das Token). Das obige Beispiel funktioniert nicht ohne Anpassung.

Das Skript erkennt die Architektur, lädt das passende Paket herunter, installiert es und startet die Dienste octoja-launcher und octoja-agent. Fehlen die ICU-Laufzeit oder jq, installiert das Skript sie vorher und weist darauf hin — der Agent braucht ICU zum Starten, und die Linux-Skripte für Überwachung und Automatisierung brauchen jq.

Zum Schluss prüft das Skript, ob beide Dienste wirklich laufen. Ist einer davon nicht gestartet, bricht das Skript mit einer Fehlermeldung ab und gibt die letzten 20 Logzeilen dieses Dienstes aus, damit du siehst, was schiefgelaufen ist. Die vollständigen Logs liegen unter /opt/octoja/logs/agent/ und /opt/octoja/logs/launcher/.

Manuelle Installation

Wähle auf der Bereitstellungsseite Manuelle Installation, um das Agent-ZIP-Archiv direkt herunterzuladen. Entpacke es und führe dann aus dem entpackten Verzeichnis heraus das mitgelieferte install.sh mit deiner Server-URL aus:

sudo bash install.sh https://YOUR-OCTOJA-URL

Falls ein Token erforderlich ist, übergib es als zweites Argument:

sudo bash install.sh https://YOUR-OCTOJA-URL YOUR-TOKEN

Das Archiv enthält .deb- und .rpm-Pakete. Das Skript wählt auf Debian-basierten Systemen .deb mit dpkg, auf RHEL-basierten Systemen .rpm mit dnf/rpm. Es legt den Agenten unter /opt/octoja ab und startet die Dienste octoja-launcher und octoja-agent. Lass die Paketdateien beim Ausführen neben install.sh liegen.

So funktioniert die Sidecar-Einstellungsdatei

Wenn du install.sh mit einer Server-URL (und optional einem Token) ausführst, schreibt das Skript diese Werte in eine Einstellungsdatei unter /etc/octoja/installer.settings.json. Der Post-Install-Schritt des Pakets liest dann diese Datei zur Konfiguration des Agenten — er liest nicht die Befehlszeilenargumente direkt aus.

Falls die Sidecar-Datei beim Installieren des Pakets fehlt, gibt der Post-Install-Schritt einen Hinweis aus, dass du launcherconfig.xml manuell bearbeiten sollst. Du kannst die Sidecar-Datei auch selbst vor der Paketinstallation anlegen, etwa beim Vorbereiten eines Images:

sudo mkdir -p /etc/octoja
sudo tee /etc/octoja/installer.settings.json <<'EOF'
{
  "octojaUrl": "https://YOUR-OCTOJA-URL",
  "token": "YOUR-TOKEN"
}
EOF

Agent-Status überprüfen

Der octoja Agent läuft als zwei systemd-Dienste — Hintergrundprogramme, die beim Systemstart automatisch gestartet werden:

octoja-launcher — verwaltet Updates und überwacht den Agent-Prozess.
octoja-agent — der eigentliche Agent, der sich mit deinem octoja-Server verbindet.

Prüfe den Status beider Dienste mit folgenden Befehlen:

systemctl status octoja-launcher
systemctl status octoja-agent

Beide sollten active (running) anzeigen. Falls einer inactive oder failed anzeigt, starte ihn neu:

sudo systemctl restart octoja-launcher
sudo systemctl restart octoja-agent

Agent-Dienste verwalten

Befehl	Beschreibung
systemctl status octoja-launcher	Prüfen, ob der Launcher läuft
systemctl status octoja-agent	Prüfen, ob der Agent selbst läuft
sudo systemctl restart octoja-launcher octoja-agent	Beide Dienste stoppen und neu starten
sudo systemctl stop octoja-launcher octoja-agent	Beide Dienste stoppen (starten beim nächsten Neustart wieder)
sudo systemctl start octoja-launcher octoja-agent	Beide Dienste starten, wenn sie gestoppt sind
journalctl -u octoja-agent -f	Agent-Logausgabe in Echtzeit verfolgen (Strg+C zum Beenden)

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