Skript ausführen

Wie du mit der Aktion Skript ausführen eigene PowerShell- oder Bash-Skripte startest, Werte zurückgibst und wann der Schritt fehlschlägt.

Mit dieser Aktion startest du ein eigenes PowerShell- oder Bash-Skript auf dem Gerät und gibst Werte daraus an spätere Schritte weiter. Das Gerät muss dafür online sein.

Voraussetzungen

Auf dem Zielgerät muss ein octoja-Agent installiert und verbunden sein.
Für Angemeldeter Benutzer unter Ausführen als muss jemand am Gerät angemeldet sein. Unter Linux und macOS muss das ein anderes Konto als root sein.
Unter Linux braucht octoja jq auf dem Gerät, um Ausgabeparameter zu übernehmen. Ohne jq bleiben sie leer.

Konfigurationsfelder

Feld	Typ	Pflicht	Standard	Beschreibung
Windows (PowerShell)	Skript	Nein	—	Skript für Windows-Geräte. Läuft mit PowerShell 7, wenn es auf dem Gerät installiert ist, sonst mit Windows PowerShell 5.1. `#requires`-Direktiven funktionieren nicht. Variablen `${{ … }}` sind erlaubt
Linux (Bash)	Skript	Nein	—	Skript für Linux-Geräte, läuft mit `bash`. Variablen `${{ … }}` sind erlaubt
macOS (Bash)	Skript	Nein	—	Skript für macOS-Geräte, läuft mit der `bash` des Systems. Variablen `${{ … }}` sind erlaubt
Ausführen als	Auswahl	Nein	System (Agent-Identität)	Mit System (Agent-Identität) läuft das Skript unter Windows als `SYSTEM`, unter Linux und macOS als `root`. Mit Angemeldeter Benutzer läuft es in der Sitzung des angemeldeten Benutzers
Arbeitsverzeichnis (optional)	Text	Nein	—	Ordner, in dem das Skript startet. Gibt es den Ordner auf dem Gerät nicht, startet das Skript ohne Ordnerwechsel. Variablen `${{ … }}` im Feld werden aufgelöst
Skript-Zeitlimit in Sekunden (optional)	Zahl	Nein	`240`	So lange darf das Skript laufen, bevor der Agent es beendet. Erlaubt sind 10 bis 7.200 Sekunden (zwei Stunden). Andere Werte lassen sich nicht speichern
Ausgabeparameter	Liste aus Name und Typ	Nein	—	Variablen aus deinem Skript, die octoja nach dem Skriptende übernimmt. Neue Zeilen legst du mit Ausgabeparameter hinzufügen an. Als Typ wählst du Text (Standard), Zahl oder Boolean. Die Regeln stehen weiter unten

Die drei Skriptfelder sind Registerkarten im Eigenschaften-Panel. Jedes Gerät führt nur das Skript für sein eigenes Betriebssystem aus. Fülle also nur die Registerkarten aus, die du brauchst.

octoja setzt Variablen als reinen Text ins Skript ein, bevor es an das Gerät geht. Fehlt ein Wert im Lauf, etwa weil der Schritt, der ihn liefert, übersprungen wurde, bleibt der Platzhalter unverändert im Skript stehen.

Achtung: octoja maskiert Werte nicht für PowerShell oder Bash. Anführungszeichen, ; oder $( … ) in einem Wert werden Teil des Skripts und können ändern, was es tut. Setze nur Werte ein, die du selbst kontrollierst, etwa deine eigenen Felder. Freitext von Benutzern oder externen Systemen gehört nie in ein Skript.

Ausgabeparameter

Lege unter Ausgabeparameter einen Namen wie result an und setze im Skript eine Variable mit demselben Namen: $result = 'OK' in PowerShell oder result='OK' in Bash. Text, den du nur auf die Standardausgabe schreibst, setzt keinen Parameter.

Regel	Details
Erlaubte Namen	Nur Buchstaben, Ziffern und Unterstriche. Andere Namen ignoriert octoja. Unter Windows spielt Groß-/Kleinschreibung keine Rolle
Reservierte Namen unter Windows	Heißt ein Parameter wie eine eingebaute PowerShell-Variable, etwa `input`, `args`, `error` oder `host`, schlägt der Schritt fehl, bevor dein Skript startet
Eingebaute Namen	Verwende nicht `exitCode`, `success`, `stdout`, `stderr` oder `runtimeMs`. Die eingebaute Ausgabe hat immer Vorrang
Anzahl	Bis zu 100 Parameter pro Schritt
Typ	Alle Werte kommen als Text an. Der Typ legt nur fest, wie Variablenauswahl und Bedingungen den Wert behandeln. Er wandelt nichts um und prüft nichts

Plattformunterstützung

Plattform	Unterstützt
Windows	Ja
Linux	Ja
macOS	Ja

Ausgaben

Ausgabe	Beschreibung
`exitCode`	Exit-Code des Skripts. `-1`, wenn das Skript das Zeitlimit überschritten hat oder nicht starten konnte
`stdout`	Standardausgabe des Skripts
`stderr`	Fehlerausgabe des Skripts
Deine Ausgabeparameter	Jeder deklarierte Parameter unter dem Namen, den du vergeben hast

Unter Variable einfügen findest du exitCode, stdout und stderr (als Exit-Code, Standardausgabe und Fehlerausgabe) sowie deine eigenen Parameter.

Ergebnisverhalten

Fall	Ergebnis
Exit-Code `0`	Erfolgreich.
Jeder andere Exit-Code	Fehlgeschlagen mit `Script exited with code <code>.` Ausgaben und Ausgabeparameter werden trotzdem übernommen.
Kein Skript für die Plattform des Geräts	Erfolgreich, ohne dass etwas läuft. `stderr` enthält `No script configured for this platform.`
Skript überschreitet das Zeitlimit	Fehlgeschlagen. Der Agent beendet das Skript, `exitCode` ist `-1` und `stderr` nennt die Zeitüberschreitung.
Angemeldeter Benutzer, aber niemand angemeldet	Fehlgeschlagen.
Gerät beim Start des Schritts offline	Gerät offline. Je nach Wenn Gerät offline endet der Lauf mit diesem Status oder der Schritt wird übersprungen.
Keine Antwort vom Gerät	Zeitüberschreitung.

Mit der Standardeinstellung unter Bei Fehler stoppt ein fehlgeschlagener Schritt den Workflow. Sollen spätere Schritte trotzdem laufen, wähle Mit nächstem Schritt fortfahren.

Standardausgabe, Fehlerausgabe und Ausgabeparameter werden nach 65.536 Zeichen abgeschnitten, und das Ergebnis weist nicht darauf hin. Auch ein erfolgreicher Schritt kann also eine unvollständige Ausgabe liefern. Gib deshalb kompakte Ergebnisse zurück statt ganzer Protokolle.

Mit System (Agent-Identität) läuft das Skript mit vollen Rechten und kann auf dem Gerät alles ändern oder löschen. Schritt testen und Testlauf führen es wirklich aus. Probiere neue Skripte zuerst auf einem geeigneten Gerät aus.

FAQ

Kann die Aktion über das Überwachungsgerät eines Netzwerkgeräts laufen?

Nein. Skript ausführen nutzt die Agentenverbindung des Zielgeräts. Bei einem agentenlosen Netzwerkgerät führt das zugewiesene Überwachungsgerät die Automatisierungsskripte nicht stellvertretend aus. Dass das Netzwerkgerät als online angezeigt wird, ersetzt keine Agentenverbindung.

Das unterscheidet die Aktion von Monitoring-Checks für Netzwerkgeräte, die über das Überwachungsgerät laufen können. Eigenes Feld schreiben läuft dagegen in octoja und benötigt keine Agentenverbindung; diese Aktion führt selbst kein PowerShell- oder Bash-Skript aus.

Warum bleibt die Fehlerausgabe leer, obwohl das Skript fehlgeschlagen ist?

Ein Exit-Code ungleich 0 kennzeichnet einen Fehler, erzeugt aber selbst keinen Text in stderr. In Bash schreibt echo "Example failure" in stdout, nicht in stderr. Prüfe deshalb beide Ausgaben; eine leere Fehlerausgabe bedeutet nicht, dass das Skript erfolgreich war.

Wenn dein Bash-Skript eine eigene Fehlermeldung zurückgeben soll, schreibe sie ausdrücklich in die Fehlerausgabe:

echo "Example failure" >&2
exit 1

Für eine nachfolgende Teams-Nachricht wähle am Skriptschritt unter Bei Fehler die Option Mit nächstem Schritt fortfahren. Setze im Benachrichtigungsschritt zwei Bedingungen für den Exit-Code des Skripts: ist nicht leer und ≠ 0, verknüpft mit Alle. So löst ein übersprungener Skriptschritt keine Fehlerbenachrichtigung aus.

Füge über Variable einfügen dessen Exit-Code, Standardausgabe und Fehlerausgabe in die Nachricht ein. Dafür musst du keine eigenen Ausgabeparameter anlegen.

Siehe auch: Eine Automatisierung erstellen

War dies hilfreich?

Brauchen Sie noch Hilfe? Team fragen