Kommandozeilentools

Dieses Kapitel stellt wichtige Kommandozeilen-Werkzeuge zur opsi-Administration vor. Die Liste der Tools ist alphabetisch sortiert.

opsi-admin

Mit dem Kommandozeilentool opsi-admin können Sie auf die opsi-API zugreifen. Das Werkzeug bietet einen interaktiven Modus (-i) und einen nicht-interaktiven Modus. z. B. für den Einsatz in Skripten.

Lesen Sie auch den Abschnitt zu opsi-cli: opsi-cli ist deutlich moderner, leistungsfähiger und flexibler und bietet dabei ähnlich Funktionen wie opsi-admin. opsi-cli gehört seit Version 4.2.0.187 zum Paket opsi-utils und steht unter Linux, Windows und macOS zur Verfügung.

Um auf die opsi-API zuzugreifen, definieren Sie beim Aufruf die Service-URL (--address), einen Benutzernamen (--username) und das dazugehörige Passwort (--password). Wenn Sie keine Service-URL angeben, dann verwendet opsi-admin die in der Datei /etc/opsi/opsi.conf angegebene Service-URL. Lassen Sie den Benutzernamen/das Passwort im Aufruf weg, dann erfolgt die Authentifizierung über die Host-ID und den Kost-Key aus der Datei /etc/opsi/opsi.conf.

Die Zugangsdaten können Sie in einer persönlichen Konfigurationsdatei hinterlegen (siehe Abschnitt Konfigurationsdatei).

Abbildung 1. Rufen Sie opsi-admin -i auf, um das Tool im interaktiven Modus zu starten.

Wenn Sie beim Start zusätzlich den Parameter -c angeben, erhalten Sie eine farbige Anzeige; der vollständige Befehl lautet dann opsi-admin -ic. Im interaktiven Modus können Sie zur automatischen Vervollständigung von Befehlen die [Tab]-Taste drücken. Außerdem gibt es eine History, die bereits getippte Kommandos abspeichert. Sie die Pfeiltasten dazu verwenden, um durch die History zu blättern.

Die beiden Schalter -s (Shell-Ausgabe) und -S (einfache Ausgabe) erzeugen einen Output, der sich gut in Skripten weiterverarbeiten lässt.

Verwenden Sie das Kommando method <methodenname>, um RPC-Methoden der API auszuführen. Das Kommando task <taskname> eigenet sich für komplexere Administrations-Aufgaben. Weitere Beispiele für den Einsatz von opsi-admin finden Sie im Abschnitt Beispiele.

Konfigurationsdatei

Die Zugangsdaten zum opsi-Webservice können Sie in einer Konfigurationsdatei hinterlegen. Auf diese Weise ist es möglich, eine Verbindung zu starten, ohne Benutzername und Kennwort auf der Kommandozeile angeben zu müssen.

Die Datei heißt opsirc und liegt im versteckten Ordner ~/.opsi.org im Home-Verzeichnis des Benutzers. Sie hat den folgenden Aufbau:

address = https://<opsi-server>:4447/rpc
username = <opsi-user>
password = <secret>

Alle Angaben in der Datei sind optional. Falls die Datei leer oder nicht vorhanden ist, nutzt opsi-admin die oben beschriebenen Standardeinstellungen.

Mit dem Parameter --opsirc können Sie beim Aufruf den Pfad zu einer anderen Konfigurationsdatei angeben. Somit können Sie mehrere, unterschiedlich konfigurierte Verbindungen vorbereiten und nutzen.

Beispiele

Im Folgenden listen wir ein paar Beispiele für den Einsatz von opsi-admin auf:

Ein Produkt für alle Clients auf setup stellen, die das Produkt installiert haben:

opsi-admin task setupWhereInstalled <product-id>

Einfache Liste der IDs aller opsi-Clients ausgeben:

opsi-admin -S method host_getIdents str '{"type":"OpsiClient"}'

Einen opsi-Client löschen:

opsi-admin method host_delete <client-id>

Einen opsi-Client neu anlegen oder überschreiben (opsi-admin … <client-id> <opsi-host-key> <description>):

opsi-admin method host_createOpsiClient client1.opsi.internal null "Test client 1"

Action Request an ein Produkt senden (opsi-admin … <product-id> <client-id> <action-request>):

opsi-admin -d method setProductActionRequest opsi-client-agent client1.opsi.internal setup

Auflisten der auf Clients installierten Produkte:

opsi-admin method productOnClient_getObjects [] '{"installationStatus": "installed"}'

opsi-cli

Im Laufe der Jahre hat opsi einige Kommandozeilentools erhalten. Da die opsi-utils- und opsi-python-Skripte zu unterschiedlichen Zeiten entstanden sind, haben sie jeweils ihre eigene Struktur, eigene Kommandozeilenoptionen und Ausgabeformate.

Das Tool opsi-cli bietet Zugriff auf dieselben Funktionen (und mehr!). Darüber hinaus hat opsi-cli ein Plugin-System, welches es opsi-Anwendern ermöglicht, die Funktionalität durch eigene Plugins zu erweitern.

Installation

opsi-cli ist Teil des Pakets opsi-utils und wird damit automatisch auf den opsi-Servern installiert. Als Client-Komponente lässt sich opsi-cli auch außerhalb des opsi-Servers einsetzen. Daher steht opsi-cli als Paket für Linux-, Windows- und macOS-Clients zur Verfügung.

Wenn Sie opsi-cli außerhalb des opsi-Servers einsetzen möchten, dann müssen Sie Zugangsdaten zum opsi-Webservice übergeben — entweder beim Aufruf über --service, --username und --password, oder Sie speichern die Zugangsdaten lokal auf dem Client (opsi-cli config service add --help, siehe Abschnitt Service-Optionen).

Unter Arch Linux müssen Sie das Paket libxcrypt-compat installieren, damit opsi-cli richtig funktioniert.

Die ausführbare Datei opsi-cli ist sofort lauffähig und portabel einsetzbar. Wenn Sie auf einem opsi-Client das Binary in den Pfad aufnehmen möchten, können Sie opsi-cli selbst dafür nutzen, siehe opsi-cli self --help

Aufruf

opsi-cli ist ein Python-Binary, das Sie über Parameter und Kommandos steuern. Jedes Kommando kann eines oder mehrere Unterkommandos enthalten (Subkommandos). Die nächsten Abschnitte stellen erst die Grundfunktionalitäten und dann die verfügbaren Kommandos vor.

Es gibt zu jedem Kommando eine eigene Hilfe, die Sie über den Parameter --help einblenden, z. B. opsi-cli --help oder opsi-cli config --help.

Der allgemeine Aufruf von opsi-cli sieht folgendermaßen aus:

opsi-cli [OPTIONS] COMMAND [ARGS]...

Die Optionen direkt nach dem opsi-cli-Befehl gelten als globale Konfiguration und damit auch für alle Subkommandos. Es gibt drei Hauptkategorien bei den globalen Optionen.

Allgemeine Optionen

Mit den unter General options gelisteten Parametern beeinflussen Sie die Protokollierung, aktivieren eine farbige Ausgabe, die Konfiguration usw.

Ausgabeformat

Über die unter IO options gelisteten Optionen können Sie die Ausgabe aller Subkommandos vereinheitlichen, Ausgabeformate vorgeben und Filter einstellen.

Das nächste Beispiel zeigt, wie Sie die Ausgabe filtern und formatieren. Im ersten Befehl führt opsi-cli die JSON-RPC-Methode host_getObjects aus (execute), um Informationen zu opsi-Clients aus der Domäne domain.local anzuzeigen, deren Name mit client beginnt:

opsi-cli jsonrpc execute host_getObjects [] '{"id":"client*.domain.local"}'
[
  {
    "description": "",
    "notes": "Created by opsi-deploy-client-agent at Mon, 26 Sep 2022 17:19:29",
    "id": "client-linux.domain.local",
    "hardwareAddress": "08:00:27:f5:1d:8e",
    "ipAddress": "192.168.56.11",
    "inventoryNumber": "",
    "systemUUID": null,
    "opsiHostKey": null,
    "created": "2022-09-26 17:19:29",
    "lastSeen": "2023-03-08 12:13:10",
    "oneTimePassword": null,
    "type": "OpsiClient",
    "ident": "client-linux.domain.local"
  },
  […]
]

Der nächste Aufruf formatiert die Ausgabe als Tabelle im Terminal und filtert drei Attribute (id, type und lastSeen):

opsi-cli --output-format table --attributes id,type,lastSeen jsonrpc execute host_getObjects [] '{"id":"client*.domain.local"}'

Bevorzugen Sie das CSV-Format, dann schreiben Sie anstelle von table hinter --output-format einfach csv:

opsi-cli --output-format csv --attributes id,type,lastSeen jsonrpc execute host_getObjects [] '{"id":"client*.domain.local"}'
[…]
id;lastSeen;type
client-linux.domain.local;2023-03-08 12:13:10;OpsiClient
client-macos.domain.local;2023-03-15 14:55:37;OpsiClient
client-win10.domain.local;2023-03-15 15:13:46;OpsiClient

Verwenden Sie zusätzlich die Option --output-file, um die Ausgabe direkt in eine Datei zu schreiben.

Service-Optionen

Wenn Sie opsi-cli außerhalb des opsi-Servers verwenden möchten, dann müssen Sie Zugangsdaten für den opsi-Webservice angeben. Die dazugehörigen Parameter heißen --service, --username und --password:

Alternativ dazu speichern Sie die Zugangsdaten auf dem jeweiligen Client. Sie können sogar verschiedene Service-Konfigurationen als Profile hinterlegen, falls Sie auf verschiedene opsi-Server zugreifen wollen. Sie nutzen dazu das im folgenden Abschnitt vorgestellte Kommando opsi-cli config; geben Sie opsi-cli config service add --help ein, um die Onlinehilfe zu diesem Thema anzuzeigen.

Kommandos und Beispiele

Die nächsten Abschnitte erklären die derzeit verfügbaren Kommandos und geben Beispiele für deren Einsatz.

config

Mit diesem Kommando passen Sie die opsi-cli-Konfiguration an (siehe opsi-cli config --help).

Mit dem folgenden Befehl betrachten Sie die aktuelle Konfiguration und die Standardeinstellungen:

opsi-cli config list

Um einen Wert dauerhaft zu ändern, verwenden Sie den Befehl opsi-cli config set <name> <value>. Die neuen Einstellungen gelten dann für alle nachfolgenden opsi-cli-Aufrufe. Um einen Wert zu entfernen, geben Sie opsi-cli config unset <name> ein. Zur Verwaltung der Service-Zugänge steht opsi-cli config service mit den Subkommandos add, list und remove zur Verfügung.

jsonrpc

Mit dem Kommando jsonrpc greifen Sie auf JSON-RPC-Methoden zu und führen diese auf dem opsi-Server aus. Damit kann opsi-cli das Werkzeug opsi-admin komplett ersetzen. jsonrpc kennt zwei Subkommandos:

opsi-cli jsonrpc methods: Gibt eine Liste aller verfügbaren API-Methoden und ihrer Parameter aus.
opsi-cli jsonrpc execute <method>: Führt die angegebene Methode aus.

Die Ausgabe von opsi-cli jsonrpc methods zeigt in der Spalte deprecated ebenfalls an, ob eine Methode als veraltet gekennzeichnet ist. In der Spalte daneben (alternative_method) sehen Sie die empfohlene Alternative.

Um eine bestimmte Methode auszuführen, geben Sie ihren Namen nach dem Befehl opsi-cli jsonrpc execute an, zum Beispiel so:

opsi-cli jsonrpc execute authenticated

Die Syntax ähnelt der von opsi-admin, wie ein direkter Vergleich zeigt:

opsi-admin method authenticated

Die Angabe der Methoden-Parameter ist dabei absolut identisch, wie das nächste etwas komplexere Beispiel zeigt:

opsi-cli jsonrpc execute host_getObjects '["created","lastSeen"]' '{"id":"testclient01.uib.local"}'

Alte Variante:

opsi-admin method host_getObjects '["created","lastSeen"]' '{"id":"testclient01.uib.local"}'

Die beiden Beispiele verzichten bewusst auf den veralteten Parameter -d bei opsi-admin (umgeht opsiconfd). Die Umgehung des opsi-Webservices hat in der Vergangenheit zu Problemen innerhalb des opsi-Systems geführt. Deshalb ist der Weg zur API nur noch über den opsi-Webservice möglich — opsi-cli unterstützt diesen Modus erst gar nicht.

Wenn Sie direkt auf dem opsi-Server arbeiten, benötigen Sie keine Zugangsdaten; diese erhält das Tool automatisch aus der Server-Konfiguration. Möchten Sie opsi-cli jedoch in Skripten, Cronjobs o. Ä. einsetzen, müssen Sie die Zugangsdaten vorher hinterlegen.

Wie auch bei den anderen opsi-cli-Kommandos können Sie für jsonrpc das Ausgabeformat mit Parametern wie --output-format und --attributes beeinflussen (siehe Abschnitt Ausgabeformat).

opsi-cli --output-format table --attributes id,created,lastSeen jsonrpc execute host_getObjects '["created","lastSeen"]' '{"id":"testclient01.uib.local"}'

Beachten Sie, dass Sie unter Windows gegebenenfalls Escape-Sequenzen nutzen müssen, da die Eingabeaufforderung (cmd.exe) und die PowerShell einfache und doppelte Anführungszeichen anders interpretiert.

Die nächsten beiden Aufrufe zum Auflisten aller Depots in einer opsi-Umgebung verdeutlichen die Unterschiede. So sieht das Kommando unter Linux und macOS aus:

opsi-cli jsonrpc execute host_getObjects [] '{"type":"OpsiDepotserver"}'

In der Windows-Eingabeaufforderung sieht es so aus:

opsi-cli jsonrpc execute host_getObjects [] {\"type\":\"OpsiDepotserver\"}

In der PowerShell (vor Version 7) sieht das Kommando so aus:

opsi-cli jsonrpc execute host_getObjects [] '{\"type\":\"OpsiDepotserver\"}'

client-action

Mit dem Kommando client-action verwalten Sie opsi-Clients. Es bietet in erster Linie Optionen, um zu beeinflussen, auf welche Liste von Clients sich Aktionen auswirken (siehe opsi-cli client-action --help). Es hat die subkommandos set-action-request und und trigger-event.

Das Subkommando set-action-request kann verwendet werden, um Aktionen für Produkte auf opsi-Clients anzufordern. Es ist vergleichbar mit dem task-Kommando von opsi-admin (siehe Abschnitt Beispiele), arbeitet jedoch nach dem Ausschlussprinzip. Das heißt, ohne explizite Angabe von Clients und Produkten wirkt sich die Aktion auf alles aus. Daher bietet set-action-request weitere Optionen, um die Produkte zu filtern, auf die sich eine Aktion auswirken soll (siehe opsi-cli client-action set-action-request --help).

Beim Aufruf ohne explizite Angabe von Clients und Produkten wirkt sich der Befehl auf alle Clients und auf alle Produkte aus. Um Fehlern vorzubeugen, erlaubt opsi-cli kein Ausführen von set-action-request, ohne dass Sie mindestens eine der folgenden Angaben machen: --where-outdated, --where-failed, --products oder --product-groups.

So setzen Sie alle veralteten Produkte von Clients auf setup:

opsi-cli client-action set-action-request --where-outdated

Alternativ setzen Sie nur ein bestimmtes Produkt (hier: opsi-client-agent) auf einem bestimmten Client (hier test-98.domain.tld) setup:

opsi-cli -l5 client-action --clients test-98.domain.tld set-action-request --products opsi-client-agent

[5] [2022-10-28 12:54:59.998] [               ] Selected clients: ['test-98.domain.tld']   (client_action_worker.py:48)
[5] [2022-10-28 12:55:00.055] [               ] Handling products ['opsi-client-agent']   (set_action_request_worker.py:105)
[5] [2022-10-28 12:55:00.065] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-98.domain.tld   (set_action_request_worker.py:134)

Der Produktstatus setup ist dabei der Default. Wenn Sie dasselbe Produkt auf uninstall setzen möchten, lautet der Befehl so:

opsi-cli -l5 client-action --clients test-98.domain.tld set-action-request --products opsi-client-agent --request-type uninstall

[5] [2022-10-28 12:57:06.848] [               ] Selected clients: ['test-98.domain.tld']   (client_action_worker.py:48)
[5] [2022-10-28 12:57:06.904] [               ] Handling products ['opsi-client-agent']   (set_action_request_worker.py:105)
[5] [2022-10-28 12:57:06.914] [               ] Setting 'uninstall' ProductActionRequest: opsi-client-agent -> test-98.domain.tld   (set_action_request_worker.py:134)

Um einen Action Request für ein bestimmtes Produkt auf einem Client zurückzusetzen, verwenden Sie den Wert None (none ist ebenfalls erlaubt):

opsi-cli -l5 client-action --clients test-98.domain.tld set-action-request --products opsi-client-agent --request-type None

[5] [2022-10-28 14:12:50.538] [               ] Selected clients: ['test-98.domain.tld']   (client_action_worker.py:48)
[5] [2022-10-28 14:12:50.574] [               ] Handling products ['opsi-client-agent']   (set_action_request_worker.py:105)
[5] [2022-10-28 14:12:50.580] [               ] Setting 'None' ProductActionRequest: opsi-client-agent -> test-98.domain.tld   (set_action_request_worker.py:134)

Falls ein Fehler in einem Produkt auftaucht, sollte man alle Aktionen dafür auf den Clients temporär zurücknehmen können. So wird das fehlerhafte Produkt nicht weiter verteilt:

opsi-cli client-action set-action-request --products opsi-client-agent --request-type None

Sollte das Produkt irgendwann wieder fehlerfrei zur Verfügung stehen, können Sie alle veralteten oder fehlerhaften Statusinformationen wieder auf setup setzen:

opsi-cli client-action set-action-request --where-outdated --where-failed

So setzen Sie ein bestimmtes Produkt auf einer Gruppe von Clients (hier: testclients) auf setup:

opsi-cli -l5 client-action --client-groups testclients set-action-request --products opsi-client-agent

[5] [2022-10-28 13:03:24.100] [               ] Selected clients: ['test-1.domain.tld', 'test-2.domain.tld', 'test-3.domain.tld', 'test-4.domain.tld', 'test-5.domain.tld']   (client_action_worker.py:48)
[5] [2022-10-28 13:03:24.159] [               ] Handling products ['opsi-client-agent']   (set_action_request_worker.py:105)
[5] [2022-10-28 13:03:24.169] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-1.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:03:24.170] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-2.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:03:24.170] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-3.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:03:24.170] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-4.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:03:24.170] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-5.domain.tld   (set_action_request_worker.py:134)

Außer einer Gruppe von Clients können Sie hinter --product-groups auch eine Gruppe von Produkten (hier: testproducts) definieren:

opsi-cli -l5 client-action --client-groups testclients set-action-request --product-groups testproducts

[5] [2022-10-28 13:05:53.147] [               ] Selected clients: ['test-1.domain.tld', 'test-2.domain.tld', 'test-3.domain.tld', 'test-4.domain.tld', 'test-5.domain.tld']   (client_action_worker.py:48)
[5] [2022-10-28 13:05:53.225] [               ] Handling products ['hwaudit', 'opsi-client-agent', 'swaudit']   (set_action_request_worker.py:105)
[5] [2022-10-28 13:05:53.236] [               ] Setting 'setup' ProductActionRequest: hwaudit -> test-1.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.237] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-1.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.237] [               ] Setting 'setup' ProductActionRequest: swaudit -> test-1.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.237] [               ] Setting 'setup' ProductActionRequest: hwaudit -> test-2.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.237] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-2.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.238] [               ] Setting 'setup' ProductActionRequest: swaudit -> test-2.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.238] [               ] Setting 'setup' ProductActionRequest: hwaudit -> test-3.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.238] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-3.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.238] [               ] Setting 'setup' ProductActionRequest: swaudit -> test-3.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.239] [               ] Setting 'setup' ProductActionRequest: hwaudit -> test-4.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.239] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-4.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.239] [               ] Setting 'setup' ProductActionRequest: swaudit -> test-4.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.239] [               ] Setting 'setup' ProductActionRequest: hwaudit -> test-5.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.239] [               ] Setting 'setup' ProductActionRequest: opsi-client-agent -> test-5.domain.tld   (set_action_request_worker.py:134)
[5] [2022-10-28 13:05:53.240] [               ] Setting 'setup' ProductActionRequest: swaudit -> test-5.domain.tld   (set_action_request_worker.py:134)

opsi-cli schließt bei den beiden Parametern --where-outdated und --where-failed automatisch eine Liste bestimmter Pakete aus. Derzeit sind das opsi-winst, opsi-auto-update, opsi-script, shutdownwanted, windows10-upgrade, activate-win, opsi-script-test, opsi-bootimage-local, opsi-uefi-netboot, opsi-wan-config-on, opsi-wan-config-off, opsi-winpe, win10-sysprep-app-update-blocker und windomain.

Während es problemlos möglich ist, noch weitere Produkte oder Produktgruppen auszuschließen, ist es noch sicherer, eine eigene Produktgruppe zu pflegen und diese beim Aufruf anzugeben. So beschränken Sie Änderungen auf genau diese Gruppe.

Das Subkommando trigger-event startet auf der Menge ausgewählter clients ein Event. Um beispielsweise ein on_demand auf den clients der Gruppe testclients auszulösen, verwenden Sie:

opsi-cli -l5 client-action --client-groups testclients trigger-event

[5] [2022-10-28 13:05:53.147] [               ] Selected clients: ['test-1.domain.tld', 'test-2.domain.tld', 'test-3.domain.tld', 'test-4.domain.tld', 'test-5.domain.tld']   (client_action_worker.py:48)
[5] [2024-01-09 16:04:45.395] [               ] Triggering event 'on_demand' on clients ['test-1.domain.tld', 'test-2.domain.tld', 'test-3.domain.tld', 'test-4.domain.tld', 'test-5.domain.tld']   (trigger_event_worker.py:79)
[5] [2024-01-09 16:04:45.442] [               ] Successfully triggered event on all reachable clients   (trigger_event_worker.py:114)

Um ein bestimmtes anderes Event auszulösen anstelle des on_demand, kann es per --event Schalter spezifiziert werden. Z.B. opsi-cli client-action --clients test-1.domain.tld trigger-event --event timer.

Auf diese Weise können nur Events auf Clients ausgelöst werden, die per opsi-messagebus erreichbar sind. Möchte man zusätzlich die nicht erreichbaren Clients aufwecken/starten, geht das über den Schalter --wakeup. Voraussetzung dafür ist, dass die Clients im LAN sind (wake-on-lan Protokoll).

plugin

Alle opsi-cli-Kommandos sind als Plugins implementiert, einschließlich des Kommandos plugin selbst. Sie nutzen es, um Plugins zu verwalten, also neue externe Plugins zu installieren oder auch laufende Plugins aus dem System zu entfernen. Außerdem können Sie mit opsi-cli plugin Plugins auflisten oder exportieren. Siehe opsi-cli plugin --help

So generieren Sie ein Template für ein neues Plugin:

opsi-cli plugin new

Nachdem Sie Angaben zu Name, Version und Beschreibung gemacht haben, legt opsi-cli ein neues Verzeichnis mit dem gewählten Namen an. Darin befinden sich die Unterverzeichnisse python und data:

Im Verzeichnis python können Sie den Code für das neue Plugin hinterlegen. Das Verzeichnis repräsentiert ein Python-Paket und enthält eine init.py-Datei als Einstieg. Hier finden Sie ein Beispiel für einen Befehl, einen Unterbefehl und einige Optionen.
Das Verzeichnis data enthält statische Ressourcen für das Plugin; Sie können es normalerweise ignorieren.

Nachdem Sie das Template mit Inhalt gefüllt haben, fügen Sie das Plugin zur laufenden opsi-cli-Instanz hinzu:

opsi-cli plugin add <directory>

Falls das angegebene Verzeichnis validen Python-Code enthält, ist das enthaltene Kommando anschließend als Plugin in opsi-cli verfügbar.

Um alle registrierten Plugins anzuzeigen, geben Sie den Befehl opsi-cli plugin list ein.

Ein Plugin können Sie in ein Archiv exportieren und es anschließend in einer anderen opsi-cli-Instanz importieren:

opsi-cli plugin export <name>
opsi-cli plugin add <archive>

Zum Umwandeln eines Verzeichnisses in ein Archiv und vice versa verwenden Sie diese Kommandos:

opsi-cli plugin compress <directory>
opsi-cli plugin extract <archive>

Um ein importiertes Plugin nachträglich zu ändern, entpacken Sie es mit dem extract-Kommando, passen den Inhalt des Verzeichnisses an und rufen erneut `opsi-cli plugin add <directory> auf. Das vorhandene Plugin mit demselben Namen wird dadurch überschrieben.

Um ein Plugin aus einer opsi-cli-Instanz zu entfernen, rufen Sie den folgenden Befehl auf:

opsi-cli plugin remove <name>

self

Das Kommando self nutzen Sie, um die opsi-cli-Instanz zu verwalten. Dazu gehört die (De-)Installation von opsi-cli auf dem System, das Aktivieren der Autovervollständigung und das Anzeigen der Kommandostruktur (siehe opsi-cli self --help).

Sie können opsi-cli mit dem opsi-cli-Binary auf Ihrem System installieren. Führen Sie dazu den Befehl opsi-cli self install aus. Bei der Installation wird das Binärprogramm an einen global verfügbaren Ort kopiert (bzw. unter Windows in den PATH aufgenommen) und eine Konfigurationsdatei erstellt. Sie entscheiden, ob die opsi-cli-Installation benutzerspezifisch oder systemweit (Option --system) erfolgen soll. Für die Deinstallation verwenden Sie den Befehl opsi-cli self uninstall.

Wenn Sie das opsi-Paket opsi-cli bzw. die opsi-utils auf einem Client installieren, entfällt der Schritt opsi-cli self install.

Um die Kommandostruktur inklusive aller Kommandos, ihrer Versionsnummer und der Subkommandos anzuzeigen, geben Sie den Befehl opsi-cli self command-structure ein.

Die opsi-cli-Autovervollständigung funktioniert für Befehle, Unterbefehle und Optionen. Um sie einzurichten, geben Sie dieses Kommando ein:

opsi-cli self setup-shell-completion

Das Feature funktioniert momentan auf drei verschiedenen Shells: Bash, ZSH und Fish. Nach einem Neustart der aktiven Shell bzw. nach einer neuen Anmeldung können Sie die Tab-Completion genauso wie in herkömmlichen Unix-Shells nutzen. Drücken Sie [Tab] [Tab], um alle verfügbaren Optionen oder Kommandos einzublenden (abhängig vom Kontext). So verhält sich [Tab] [Tab] in unterschiedlichen Situationen:

Nach opsi-cli oder jedem Kommando, das mindestens ein Subkommando hat, sehen Sie eine Liste der verfügbaren (Unter-)Befehle.
Nach - sehen Sie verfügbare Optionen für das aktuelles Kommando oder opsi-cli selbst.
Nach einem Subkommando erscheinen die möglichen Werte für die Argumente:
- Für die Subkommandos set, show und unset von opsi-cli config zeigt [Tab] [Tab] eine Liste aller verfügbaren Konfigurationen, die betroffen sind.
- Für opsi-cli jsonrpc execute wird eine Liste der verfügbaren Methoden angezeigt (gefiltert durch ein angegebenes Präfix).

support

Das Kommando opsi-cli support hilft beim Analysieren und Lösen von Problemen Ihrer opsi-Umgebung (siehe opsi-cli support --help). opsi-cli support health-check überprüft verschiedene Aspekte, die das reibungslose Laufen einer opsi-Umgebung beeinträchtigen können, und stellt einen Bericht zusammen.

Der folgende Aufruf zeigt eine kompakte Darstellung des Berichts.

opsi-cli support health-check

Einen ausführlichen Bericht erhalt man mit dem Schalter --detailed. Alternativ kann explizit eine Kategorie angegeben werden, für die ein ausführlicher Bericht erzeugt wird, z.B.

opsi-cli support health-check system_packages

Zusätzlich gibt es mit opsi-cli support client-logs die Möglichkeit, von einem einzelnen Client alle Log-Dateien von opsi-Komponenten einzusammeln. Die Dateien werden auf client-Seite komprimiert. Das Archiv wird via opsi-messagebus übertragen und im aktuellen Arbeitsverzeichnis abgelegt. Dort kann es dann ausgepackt, analysiert und weitergegeben werden.

terminal

Das Kommando opsi-cli terminal startet einen einfachen Terminal-Client, über den Sie eine Verbindung zu opsi-Servern und -Clients herstellen können. Er funktioniert ähnlich wie SSH bzw. PuTTY. Für den zu kontaktierenden host geben Sie die opsi-Host-ID an.

opsi-cli terminal test-1.domain.tld

Um den opsi-Configserver anzusprechen, können Sie auch dieses Kommando verwenden:

opsi-cli terminal configserver

Sobald Sie das Terminal schließen (Kommando exit oder Tastenkombination [Strg]+[D]), wird die Verbindung beendet.

Das Kommando öffnet auf der Ziel-Maschine die konfigurierte Standard-shell im Hintergrund und überträgt Ein- und Ausgaben. Das ist für Windows in der Regel cmd, für MacOS zsh und für Linux je nach Distribution verschieden (häufig bash).

opsi-makepackage

Den Befehl opsi-makepackage nutzen Sie, um aus einer Paketquelle (Workbench) ein opsi-Paket mit der Endung .opsi zu erstellen. Dazu wechseln Sie ins Quellverzeichnis und rufen dann den Befehl opsi-makepackage auf.

opsi-makepackage kennt einige Optionen, die das Verhalten beeinflussen. Die Liste der verfügbaren Parameter kann mittels opsi-makepackage --help angezeigt werden.

Ein opsi-Paket können Sie auf beliebigen opsi-Depotservern installieren; dazu verwenden Sie das Kommando opsi-package-manager.

opsi-outdated-to-setup

Das Kommandozeilen-Werkzeug opsi-outdated-to-setup können Sie verwenden, um Action Requests für Clients zu setzen, auf denen es Localboot-Produkte gibt, für die im Depot eine neuere Version verfügbar ist.

opsi-outdated-to-setup --help
usage: opsi-outdated-to-setup [-h] [--version] [--log-level {0,1,2,3,4,5,6,7,8,9}] [--clients CLIENTS] [--dry-run]
                              [--client-groups CLIENT_GROUPS] [--exclude-products EXCLUDE_PRODUCTS]
                              [--include-products INCLUDE_PRODUCTS] [--add-failed] [--uninstall-where-only-uninstall]
                              [--exclude-client-groups EXCLUDE_CLIENT_GROUPS] [--include-product-groups INCLUDE_PRODUCT_GROUPS]
                              [--exclude-product-groups EXCLUDE_PRODUCT_GROUPS] [--setup-on-action SETUP_ON_ACTION]

Set outdated localboot Products to setup.
[…]

Außerdem können Sie mit opsi-outdated-to-setup Action Requests setzen, um fehlgeschlagene Installationen zu wiederholen. Dazu verwenden Sie die Option --add-failed.

Die Parameter --exclude-products, --include-products, --exclude-product-groups und --include-product-groups definieren die Produkte genauer. Die Clients können Sie genauer über --clients, --client-groups und --exclude-client-groups definieren.

Die Option --uninstall-where-only-uninstall setzt alle installierten Produkte auf uninstall, falls sie außer dem uninstall-Skript kein registriertes Skript (setup, always usw.) enthalten.

Verwenden Sie den Parameter --dry-run, um einen Testlauf zu starten, ohne tatsächlich etwas zu verändern.

--setup-on-action ist eine besondere Option, mit der Sie auf allen Clients, auf denen etwas geändrt wurde (also die ein nicht aktuelles Paket installiert haben), ein Produkt auf setup setzen. Das ist beispielsweise in Kombination mit shutdownwanted nützlich, um nach der Installation einen Shutdown auszuführen, oder auch bei swaudit, um die Audit-Daten zu aktualisieren.

opsi-package-manager

Das Tool opsi-package-manager nutzen Sie, um Produkt-Pakete auf einem opsi-Depotserver zu installieren und zu deinstallieren.

Wenn Sie ein Paket installieren möchten, muss es für den Benutzer opsiconfd lesbar sein (siehe Kapitel Berechtigungen). Wir empfehlen daher, Produkt-Pakete unterhalb von /var/lib/opsi abzulegen.

So installieren Sie ein opsi-Paket:

opsi-package-manager -i <opsi-package>

So installieren Sie ein opsi-Paket und setzen interaktiv die Standardwerte für Produkteigenschaften:

opsi-package-manager -p ask -i <opsi-package>

So installieren Sie ein opsi-Paket und stellen es für alle Clients auf setup, auf denen es installiert ist:

opsi-package-manager -S -i <opsi-package>

So installieren Sie ein opsi-Paket und stellen es für alle Clients auf setup, auf denen es installiert ist; zusätzlich beeinflusst das die davon abhängenden Pakete:

opsi-package-manager -s -i <opsi-package>

So deinstallieren Sie ein opsi-Paket:

opsi-package-manager -r <opsi-package>

opsi-package-manager -x <opsi-package> --new-product-id <product-id>

Eine Übersicht über alle Optionen liefert opsi-package-manager --help.

opsi-package-updater

Das Kommandozeilen-Werkzeug opsi-package-updater dient dazu, opsi-Produkte aus einem oder mehreren Repositorys zu laden und auf dem opsi-Depotserver zu installieren. Es ist dafür gedacht, opsi-Pakete zeitgesteuert automatisch zu aktualisieren (z. B. über einen Cronjob).

Repositorys sind Quellen, die opsi-Pakete zum Download anbieten. Sie können jedes Repository gesondert in Hinblick auf Zugang und Verhalten konfigurieren.

Geben Sie opsi-package-updater --help ein, um die Onlinehilfe anzuzeigen:

opsi-package-updater --help
usage: opsi-package-updater [-h] [--version] [--config CONFIGFILE]
                            [--verbose | --log-level {0,1,2,3,4,5,6,7,8,9}]
                            [--force-checksum-calculation] [--repo repository_name]
                            [--use-inactive-repository] [--ignore-errors] [--no-zsync]
                            {install,update,download,list} ...

Updater for local opsi products. Operates in different MODEs: install, update, download and list. Each
mode has their own options that can be viewed with MODE -h
[…]

Verwenden Sie den Parameter --repo, um die Operationen auf ein einzelnes Repository einzuschränken.

Der opsi-package-updater unterstützt die folgenden Kommandos:

list: verfügbare Repositorys oder opsi-Pakete auflisten
download: opsi-Pakete aus einem Repository herunterladen
install: opsi-Pakete aus einem Repository herunterladen und installieren
update: lokal installierte opsi-Pakete aus den Repositorys aktualisieren

Für alle Kommandos gibt es eine eigene Hilfe, die Sie über opsi-package-updater <command> --help einblenden.

Mit dem Parameter -v (verbose) gestalten Sie die Ausgabe ausführlicher. Den Schalter können Sie auch mehrfach verwenden (-vv, -vvv usw.).

Beispiele

So zeigen Sie die aktivierten Repositorys an:

opsi-package-updater list --active-repos

So listen Sie die in den Repositorys verfügbaren Pakete auf:

opsi-package-updater list --products

So installieren Sie das Paket ubuntu aus dem Repository uib_linux; gleichzeitig sorgt -vv für eine sehr ausführliche Ausgabe:

opsi-package-updater -vv --repo uib_linux install ubuntu

So laden Sie alle in den aktivierten Repositorys verfügbaren Pakete herunter und installieren sie:

opsi-package-updater install

So zeigen Sie die verfügbaren Aktualisierungen an:

opsi-package-updater list --updatable-products

So aktualisieren Sie die lokal installierten Pakete firefox und javavm aus den Repositorys; -vv produziert informativen Output:

opsi-package-updater -vv update firefox javavm

Repositorys

Die allgemeinen Einstellungen zum opsi-package-updater finden Sie in der Datei /etc/opsi/opsi-package-updater.conf. In mehreren Abschnitten ist dort unter anderem geregelt, wo die opsi-Pakete liegen (packageDir), wie das Logfile (logFile) und wie das Verzeichnis mit den Repositorys heißt (repositoryConfigDir). Außerdem nehmen Sie hier Einstellungen zur Benachrichtigung per E-Mail und zu Wake on LAN (WoL) auf den Clients vor.

Die Konfigurationsdateien für die einzelnen Repositorys finden Sie im Verzeichnis /etc/opsi/package-updater.repos.d/. Dort liegt auch eine kommentierte Vorlage (Datei example.repo.template), die alle verfügbaren Optionen auflistet und erklärt.

Es gibt zwei Arten von Repositorys: Internet-Repositorys und opsi-Server-Repositorys.

Internet-Repositorys

Internet-Repositorys sind gekennzeichnet durch die folgenden Parameter:

baseURL: die Adresse, z. B. http://opsipackages.43.opsi.org/stable
dirs: eine kommaseparierte Liste von Verzeichnissen, z. B. opsi4.3/products/localboot, opsi4.3/products/netboot
username und password für Repositorys, die eine Authentifizierung erfordern
authcertfile und authkeyfile für zertifikatsbasierte Authentifizierung
verifyCert: Aktivierung und Deaktivierung der Server-Zertifikats-Prüfung für HTTPS-Verbindungen
proxy: Proxyserver

Einen Proxyserver können Sie für jedes Repository über die gleichnamige Option einrichten; alternativ tragen Sie den Proxyserver in der Datei /etc/opsi/opsi-package-updater.conf ein.

opsi-Server-Repositorys

Wenn Sie in der Repository-Konfigurationsdatei hinter opsiDepotId die Host-ID eines anderen opsi-Servers eintragen, handelt es sich um ein opsi-Server-Repository. Bei einem opsi-Depotserver steht an dieser Stelle der zentrale opsi-Configserver. Damit bezieht der Depotserver Pakete aus dem Repository /var/lib/opsi/repository des Configservers.

Repository-Verhalten

Für jedes Repository können Sie darüber hinaus ein paar Einstellungen zum Verhalten vornehmen:

autoupdate: Aktuellere Versionen installierter Pakete werden heruntergeladen und installiert.
autoinstall: Verfügbare Pakete, die lokal noch nicht installiert sind, werden heruntergeladen und installiert.
autosetup: Neu installierte und aktualisierte Pakete werden für alle Clients, auf denen diese Pakete installiert sind, auf setup gesetzt.
onlyDownload: Neue Pakete werden nur heruntergeladen.
ignoreErrors: Wenn bei einzelnen Paketen Fehler auftreten, führt das nicht zum Abbruch.

Die Option onlyDownload kommt oft in Verbindung mit aktivierten Benachrichtigungen zum Einsatz. So kann nach dem Herunterladen der neuen Pakete automatisch eine E-Mail verschickt werden, und die eigentliche Installation bleibt einem Administrator überlassen.

Standard-Produkte einspielen

Um die opsi-Standard-Produkte aus den uib-Repositorys einzuspielen, verwenden Sie den folgenden Befehl:

opsi-package-updater -v install

Das Kommando aktualisiert alle vorhandenen opsi-Pakete inklusive der Templates für Betriebssystem-Installationen aus den opsi-Repositorys.

Abbildung 2. Installieren Sie die Standard-Produkte auf Ihrem opsi-Server.

Bei Verwendung der vorkonfigurierten virtuellen Maschine können Sie alternativ das Desktop-Icon doppelklicken um die Standard-Produkte zu installieren.

opsi-setup

Vor opsi 4.3 war opsi-setup ein zentrales Werkzeug für verschiedene Konfigurations-Aufgaben auf dem opsi-Server.

Mit opsi 4.3 wurden viele dieser Aufgaben automatisiert. Andere Funktionalitäten übernimmt opsiconfd setup.

opsi-set-rights

Das Kommando opsi-set-rights (eigentlich ein Skript, das den Befehl opsi-setup --set-rights ausführt) korrigiert die Zugriffsrechte von Dateien und Verzeichnissen auf einem opsi-Server. Ohne weitere Parameter aufgerufen bearbeitet opsi-set-rights automatisch alle Dateien und Verzeichnisse, die für opsi relevant sind. Alternativ geben Sie einen Pfad beim Aufruf an, um nur ein bestimmtes Verzeichnis zu modifizieren.

opsi-wakeup-clients

Auf dem opsi-Configserver können Sie Cronjobs dazu verwenden, Produkt-Installationen und -Updates zeitlich zu steuern und so z. B. wichtige Administrations-Aufgaben in die Nacht verlegen. Damit das gelingt, müssen Clients Wake on LAN (WOL) unterstützen oder eine Weckfunktion im BIOS haben, die den Computer aus dem Ruhezustand oder dem Energiesparmodus zu einer bestimmten vordefinierten Zeit automatisch aufweckt.

Das Kommandozeilentool opsi-wakeup-clients (früher: wake_clients_for_setup.py) können Sie verwenden, um diesen Prozess zu steuern.

Die Parameter von wake_clients_for_setup.py haben wir fast alle genauso für opsi-wakeup-clients übernommen; lediglich der Parameter --depotId heißt jetzt --depot-id.

Verwenden Sie opsi-wakeup-clients --help, um eine Onlinehilfe einzublenden:

opsi-wakeup-clients --help
usage: opsi-wakeup-clients [-h] [--version] [--verbose] [--log-file LOGFILE]
                           [--log-level {0,1,2,3,4,5,6,7,8,9}] [--wol-timeout WOLTIMEOUT]
                           [--ping-timeout PINGTIMEOUT] [--connect-timeout CONNECTTIMEOUT]
                           [--event-timeout EVENTTIMEOUT] [--reboot-timeout REBOOTTIMEOUT]
                           [--host-group-id HOSTGROUPID] [--depot-id DEPOTID] [--host-file INPUTFILE]
                           [--product-group-id PRODUCTGROUPID] [--event EVENTNAME] [--reboot]
                           [--shutdownwanted] [--no-auto-update] [--max-concurrent MAXCONCURRENT]

Wakeup clients for software installation.
[…]

Im Wesentlichen erledigt opsi-wakeup-clients die folgenden Aufgaben:

Es setzt für eine bestimmte Gruppe von Clients
eine bestimmte Gruppe von Produkten auf setup.
Dann weckt es die ausgewählten Clients per Wake on LAN.

Falls ein Client nur geweckt und nicht gestartet wurde, kann opsi-wakeup-clients ein Signal senden, um ein bestimmtes Ereignis auszuführen.

Die Angabe der ausgewählten Clients erfolgt dabei auf verschiedenen Wegen:

Definieren Sie eine Host-Gruppe, die Sie z. B. mit opsi-configed erstellt haben (siehe Abschnitt Clients gruppieren):

--host-group-id <HOSTGROUPID>

Geben Sie ein opsi-Depot an, was automatisch alle Clients des Depots auswählt:

--depot-Id <DEPOTID>

Übergeben Sie eine Datei, die die gewünschten Clients auflistet:

--host-file <DATEI>

Um mehrere Produkte auf setup zu setzen, geben Sie beim Aufruf eine Produktgruppe an, die Sie z. B. mit opsi-configed erstellt haben (siehe Abschnitt Produktgruppen pflegen).

--product-group-id <PRODUCTGROUPID>

Als Letztes geben Sie das Event an, das Sie auslösen möchten; dazu dient der Parameter --event:

--event <EVENTNAME>

Die Namen von Gruppen in opsi müssen eindeutig sein, egal, ob es um eine Host-Gruppe (Bereich Directory oder Gruppen in opsi-configed) oder eine Produktgruppe geht.

Das nächste Beispiel zeigt, wie Sie für alle Clients der Host-Gruppe nightly-cron-gruppe-0 die Produkte aus der Produktgruppe nightly-cron-produkte auf setup stellen:

opsi-wakeup-clients --event=gui_startup --product-group-id=nightly-cron-produkte --host-group-id=nightly-cron-gruppe-0

Anschließend werden die Clients per Wake on LAN geweckt, und nach einer kurzen Wartezeit wird der Befehl gesendet, um das Event gui_startup auszuführen.

Cronjob einrichten

Um das Ganze nun täglich zu einem bestimmten Zeitpunkt auszuführen, tragen Sie den Befehl in die Crontab des Servers ein. Rufen Sie dazu als Root den Befehl crontab -e auf, und im sich öffnenden Standardeditor können Sie nun Folgendes eintragen:

# For more information see the manual pages of crontab(5) and cron(8)
#
# m h  dom mon dow   command

# Cronjobs zum Wecken und Installieren der PCs
5 0 * * * /usr/bin/opsi-wakeup-clients --log-level=5 --event=gui_startup --product-group-id=nightly-cron-produkte --host-group-id=nightly-cron-gruppe-1 --wol-timeout=120 --event-timeout=120
5 2 * * * /usr/bin/opsi-wakeup-clients --log-level=5 --event=gui_startup --product-group-id=nightly-cron-produkte --host-group-id=nightly-cron-gruppe-2 --wol-timeout=120 --event-timeout=120

Das Kommando opsi-wakeup-clients wird einmal um 0:05 Uhr für die Client-Gruppe nightly-cron-gruppe-1 und einmal um 2:05 Uhr für die Client-Gruppe nightly-cron-gruppe-2 aufgerufen.

Wenn Sie einen solchen Automatismus einrichten, sollten Sie verhindern, dass Installationen versehentlich außerhalb des geplanten zeitlichen "Wartungsfensters" passieren. Sie verhindern das über das Working Window (Zeitfenster) in der opsi-client-agent-Konfiguration.