Start / Log / Exitcodes / Testsyntax

Kommandozeilenparameter

Der 'opsi-script' enthält unter Windows seit Version 4.11.3 ein Manifest mit der Option:
<requestedExecutionLevel level="highestAvailable" />. Dies bedeutet, dass unter NT6 als Administrator aufgerufen, versucht wird als 'elevated' Prozess zu arbeiten. Wird der 'opsi-script' mit User Rechten aufgerufen, so läuft er unter den Rechten dieses Users.

Wird der 'opsi-script' ohne Parameter aufgerufen, so startet er interaktiv.

'opsi-script' kann ja nach Kontext und Verwendungszweck mit unterschiedlichen Parametern gestartet werden.

Es existieren eine Vielzahl von Optionen welche teilweise nur in Kombination und dann in der richtigen Reihenfolge verwendet werden können.

Note

Unter Linux or macOS ist das Parameterzeichen nicht "/" sondern "-". Also statt unter Windows opsi-script /help unter Linux / macOS opsi-script -help.

Allgemeine Optionen:

  • /? oder /h[elp]
    Hilfe aufrufen

  • /silent
    opsi-script ohne GUI ausführen

Ausführung eines (oder mehrerer) Skriptes:
opsi-script <scriptfile>[;<scriptfile>]* [<logfile>]
Dabei ist:
<scriptfile> = Name der Scriptdatei inclusive Pfad
<logfile> = Name der Logdatei inclusive Pfad
Logpfade siehe auch: Logdatei und Pfade

  • /parameter <parameterstring>
    Einen String als (über die String-Funktion ParamStr) abfragbaren Parameter übergeben.
    Dabei ist <parameterstring> ein String der keine Leerzeichen enthält.

  • /logfile <logfile>
    Festlegen des Logfiles:
    Dabei ist:
    <logfile> = Name der Logdatei inclusive Pfad
    Logpfade siehe auch: Logdatei und Pfade

  • /lang <lang>
    Festlegen der Lokalisierung:
    Dabei ist:
    <lang> = Zwei Buchstaben Kurzbezeichnung der Sprache (de,en,fr,es,…​)

  • /batch
    Ausführen eines angegeben Skriptes mit Batchoberflache. Die Batch-Oberfläche bietet keine Möglichkeiten für Benutzereingaben.In Kombination mit der Option /silent wird auch die Batch-Oberfläche ausgeblendet. Beim Aufruf ohne den Parameter /batch erscheint die Dialog-Oberfläche. Mit ihr ist die interaktive Auswahl von Skript- und Protokolldatei möglich (in erster Linie für Testzwecke gedacht).

  • /testsyntax (seit 4.12.7.)
    Ausführen eines angegeben Skriptes im testsyntax-Modus. In der Regel in der Kombination mit der Option /batch.
    siehe auch: Start / Log / Exitcodes / Testsyntax

  • /productid <productId>
    Verwendung zusammen mit /servicebatch ; siehe dort.

  • /servicebatch
    Ausführen eines angegeben Scriptes mit Batchoberflache und mit opsi-service Verbindung, so als würde das auch angegebene /productid auf 'setup' stehen.
    Dabei muß die Scriptdatei als erster Parameter angegeben sein.
    Dabei muß auch der Parameter /opsiservice und seine Zusatzparameter angegeben sein.
    Dabei muß auch der Parameter /productid angegeben sein. Dieser Parameter wird verwendet um in der Kommunikation mit dem opsi-Service das angegeben Script so auzuführen als wäre es das 'setup-script' des mit <productId> angegebenen opsi-produktes.

  • /logproductid <productId>
    Bei der Erstellung der Logdatei soll <productId> als Quelle des Logs angegeben werden.
    Wird z.B. verwendet bei Scripten welche mit einem temporären user arbeiten und in dessem Kontext Scripte als Teil des Produktes <productId> ausgeführen.

  • /normalwindow
    Schaltet im nicht interaktiven Modus die Maximierung der Batchoberfläche aus.

  • /usercontext <[ domain\]username >
    Wenn der angegebene user angemeldet ist, wird versucht die Ermittlung von Konstanten wie %CurrentAppdataDir%, %CurrentStartmenuDir%, %CurrentDesktopDir%, %CurrentStartupDir%, %CurrentProgramsDir%, %CurrentSendToDir%, %CurrentProfileDir% im Kontext dieses Users auszuführen. Meist verwendet im Zusammenhang mit der 'User Profile Management' Erweiterung.

  • /opsiservice <opsiserviceurl>
    /clientid <clientname>
    /username <username>
    /password <password>
    [/sessionid <sessionid>]
    [/credentialfile <credentialfile>]
    Angabe der Verbindungsdaten zum opsi-service:
    Dabei müssen entweder /clientid und /username und /password sowie optional die /sessionid angegeben werden
    oder diese Daten werden in einem /credentialfile zur Verfügung gestellt.

Beeinflussung was im Kontext des /opsiservice getan werden soll:

  • Default (keine weiteren der folgenden Parameter):
    Abarbeitung der Aktionsanforderungen welche für den client auf dem opsi-server gespeichert sind.

  • /allloginscripts oder /loginscripts
    Abarbeitung der Loginscripts der opsi-produkte. Dabei werden bei /allloginscripts alle dem opsi-server bekannten login-scripte ausgeführt und bei /loginscripts nur die Login-Scripte von Produkten welche auf dem Client installiert sind oder waren (es existiert für das Produkt ein productOnClient Objekt).

  • /productlist <productid>[,<productid>]*
    Bearbeite die angegebene /productlist so, als würden für diese Produkte die Aktionsanforderung auf dem opsi-server auf 'setup' stehen.
    Üblicherweise verwendet vom event_silent_install.

  • /processproducts <productid>[,<productid>]*
    Abarbeitung der Aktionsanforderungen welche für den Client auf dem opsi-Server gespeichert sind, aber beschränkt auf die Produkte welche mit /processproducts übergeben wurden.

Logdatei und Pfade

Die Default Logdatei heist opsi-script.log. Es werden per default bis zu 8 Sicherungskopien angelegt: opsi-script_0.log bis opsi-script_8.log.
Die Anzahl der Sicherungskopien kann per config Weitere Konfigurationsoptionen geändert werden.

Die Logdateien werden im Encoding UTF-8 angelegt.

Die default Protokolldateien werden unter Windows in das Verzeichnis 'c:\opsi.org\log' geschrieben, welches der 'opsi-script' zu erstellen versucht. Wenn der 'opsi-script' nicht erfolgreich bei der Erstellung diese Protokollverzeichnisses ist, wird das Benutzer TEMP-Verzeichnis zum Speichern der Protokolldatei genutzt.

Logdateien unter Linux:
Ausgeführt als root (default): /var/log/opsi-script Ausgeführt als user: /tmp

Der Name der Protokolldatei und der Speicherort können durch eine spezifizierte Kommandozeile überschrieben werden.

In dem Fall, dass der opsi-script ein Skript im /batch mode und mit einem spezifizierten (und funktionierenden) User Kontext aufgerufen wird, ist der voreingestellte Protokollpfad opsi/tmp in dem Anwendungsverzeichnis des Benutzers. Dieses wird überschreiben, wenn eine anderer Protokollpfad angegeben ist.

Zu weiteren Möglichkeiten das Logging zu beeinflussen:
siehe auch: opsi-script-manual:configuration-options.adoc#opsi-script-configs_writeProductLogFile
siehe auch: opsi-script-manual:configuration-options.adoc#opsi-script-configs_default_loglevel
siehe auch: opsi-script-manual:configuration-options.adoc#opsi-script-configs_force_min_loglevel
siehe auch: Weitere Konfigurationsoptionen
siehe auch: Weitere Konfigurationsoptionen

Neben dem normalen Logfile wird auch eine opsi-script.history Logdatei geschrieben. Diese enthält für jeden Produktlauf seit der Installation eine Zeile nach dem Muster:
<timestamp> handled: <productid> Version: <version> Request: <request> Result: <result>
Beispiel:
2022-01-18 00:09 handled : gimp Version: 2.10.30-1 Request: setup Result: success

Exit-Codes

Es gibt (seit 4.12.7.0) folgende Exitcodes:

  • 0 :
    Das Programm opsi-script hat sich ohne internen Fehler beendet und alle ausgeführten Skripte waren erfolgreich.

  • 1 :
    Das Programm opsi-script hat sich ohne internen Fehler beendet aber ein (oder mehr) ausgeführte Skripte sind nicht erfolgreich durchgelaufen (failed).

  • >1 :
    Es ist ein interner Fehler im Programm opsi-script aufgetreten (das sollte nicht passieren). Die Skriptausführung ist vermutlich fehlgeschlagen.

Skript-Syntax prüfen

Verfügbar seit 4.12.7.

Wird opsi-script im testsyntax-Modus gestartet, so wird das gewählte Skript nicht komplett ausgeführt, sondern auf Syntaxfehler geprüft.
Ein solcher testsyntax-Lauf zeichnet sich durch folgende Eigenschaften aus:

  • Im Rahmen einer solchen Prüfung werden alle Zeilen des Skriptes durchlaufen. Also z.B. auch die Zweige einer if-else-endif Anweisung, welche normalerweise nie erreicht werden.

  • Alle Anweisungen, welche in irgendeiner Weise das System verändern würden, werden nicht ausgeführt.

  • Wird ein Syntaxfehler gefunden, so wird dies in der Logdatei vermerkt.
    Das Skript wird aber nicht beim ersten Syntaxfehler abgebrochen sondern bis zum Ende durchlaufen und so alle gefundenen Syntaxfehler im Log vermerkt.

  • Alle Anweisungen, welche den Skriptlauf in irgendeiner Form abbrechen (wie z.B. isFatalError), werden ignoriert.

  • In der Logdatei findet sich im Kopfteil die Warnung:
    Running in TestSyntax mode !!.

  • Wird ein Syntaxfehler gefunden, so wird das Skript als failed behandelt. Das hat die folgenden Auswirkungen:

    • In der Logdatei steht am Ende: script finished: failed.

    • Der opsi-script Prozess endet mit einem Exitcode = 1.

    • Ist opsi-script im 'Servicekontext' gestartet, also z.B. durch das Managementinterface per 'on_demand' und läuft im testsyntax-Modus, so wird das Produkt markiert als: Status: unknown und Report entweder ok: testsyntax oder failed: testsyntax

Testsyntax Ergebnis im opsi-configed: 1. Zeile: failed
Wenn Sie ein Script mit testsyntax prüfen, so sind zusätzliche Laufzeitfehlermeldungen in der Logdatei zu erwarten. Diese können zunächst ignoriert werden. Diese Laufzeitfehlermeldungen entstehen als Nebenwirkung des testsyntax-Laufs, da hier z.B. Variablen leer sind (oder andere unerwartete Werte haben).

Um ein Skript im testsyntax-Modus zu starten, gibt es folgende Möglichkeiten:

Screenshot: opsi-script im interaktiven Modus
Abbildung 1. opsi-script im interaktiven Modus

  • Interaktiv :
    Im interaktiven Modus das ausgewählte Skript über den Button Test Syntax (anstatt Start) starten.

  • Im Servicekontext :
    Über den config ('Hostparameter') opsi-script.global.testsyntax = true wird opsi-script dazu veranlasst, Scripte nur im testsyntax-Modus auszuführen.
    ACHTUNG: Stellen Sie diesen Config nur für einzelne Rechner auf true und vergessen Sie nicht, ihn wieder zurück auf false zu stellen!
    siehe auch: Weitere Konfigurationsoptionen

  • Kommandozeilenparameter :
    Beim Aufruf des opsi-script kann der Parameter /testsyntax mitgegeben werden. Dann wird das angegebene Skript im testsyntax-Modus ausgeführt.
    siehe auch: Kommandozeilenparameter