The Service opsiconfd

The central service on every opsi server is the opsiconfd. It provides various services over HTTPS (port 4447):

  • /rpc: JSON-RPC-API

  • /dav: WebDAV access to Workbench, Repository, Depot, Boot directory

  • /admin: Admin page for status information and administrative tasks

  • /grafana: Reverse proxy access to a local Grafana server (see chapter Grafana)

  • /status: simple status output for monitoring tools

  • /public: public file sharing without authentication

You can extend the opsiconfd with addons. For example, the opsi WebGUI is such an addon. Read more about this in section Addons.

Command Line Interface

The opsiconfd has a command line interface that provides the following commands:

  • start: Starts the opsiconfd (default command).

  • stop: Stops a running opsiconfd.

  • force-stop: Like stop, but also terminates active client connections.

  • status: Shows the service status (same output as systemctl status).

  • restart: Restarts the opsiconfd service (systemctl restart).

  • reload: Sends a SIGHUP signal to running opsiconfd (worker) processes. The processes then reload the configuration files.

  • setup: Starts a The opsiconfd setup Command.

  • log-viewer: Displays the opsiconfd logs (see section Logfiles) in the terminal.

  • health-check: Starts a Health Check.

  • diagnostic-data: Writes health check data and information about the environment that is helpful for problem analysis to a file.

  • backup: Creates a backup (see section opsiconfd backup/restore).

  • restore: Restores a backup (see section opsiconfd backup/restore).

Server Role

An opsi server can take on the role of an opsi config server or an opsi depot server. The configuration file /etc/opsi/opsi.conf defines the role. Starting with opsi 4.3, this configuration file also defines the server ID.

The configuration file */etc/opsi/opsi.conf* defines the server role, among other things.
Abbildung 1. The configuration file /etc/opsi/opsi.conf defines the server role, among other things.
If you run the opsi server as a Docker container, environment variables control the behavior (see section Docker Compose).

Here is an example for an opsi config server:

[host]
id = "opsi.domain.tld"
key = "5b4324721a114195098bdaf3fab54a9f"
server-role = "configserver"

[service]
url = "https://localhost:4447"

Example for an opsi depot server:

[host]
id = "opsi-depot.domain.tld"
key = "a1b5098fabcaf315b13249cba1a24d17"
server-role = "depotserver"

[service]
url = "https://opsi.domain.tld:4447"
Starting with opsi 4.3, the file /etc/opsi/opsi.conf replaces the previously used file /etc/opsi/backends/jsonrpc.conf.

Configuration

You can configure the opsiconfd via the file /etc/opsi/opsiconfd.conf, environment variables, or command line parameters when calling it. The following order applies:

  1. Entries in the configuration file override the default settings.

  2. Environment variables override entries in the configuration file.

  3. Command line parameters override environment variables.

You can get a list of all configuration options by entering the following command in a terminal window: 
opsiconfd --help
...
--admin-networks ADMIN_NETWORKS [ADMIN_NETWORKS ...]
                                A list of network addresses from which administrative connections are allowed.
                                [env var: OPSICONFD_ADMIN_NETWORKS]
                                (default: ['0.0.0.0/0', '::/0'])
...

After the name of the command line parameter (e.g., --admin-networks), the corresponding environment variable is shown in uppercase (here: ADMIN_NETWORKS). If you omit the two leading dashes --, you get the name of the option for the configuration file (admin-networks).

  • In the configuration file /etc/opsi/opsiconfd.conf, it looks like this:

admin-networks = [10.1.1.0/24,192.168.1.0/24]

  • The setup via the environment variable looks like this:

OPSICONFD_ADMIN_NETWORKS="[10.1.1.0/24,192.168.1.0/24]"

  • The command line call looks like this:

opsiconfd --admin-networks 10.1.1.0/24 192.168.1.0/24
You can usually apply changes to the configuration during runtime using the opsiconfd reload command. However, some parameters require a restart via opsiconfd restart.

The hostcontrol.conf File

You can control opsi clients via the HostControl functionality. Since opsi 4.3, this is preferably done via the opsi Message Bus. However, the previous method still exists; in this case, the opsi config server establishes a connection to the client agent and executes commands over this connection. Wake on LAN (WOL) packets can be sent over the network to start clients as needed.

The HostControl configuration is located in the file /etc/opsi/backends/hostcontrol.conf. The following parameters are available:

  • useMessagebus: This parameter controls how the opsi Message Bus is used for HostControl. The following values are allowed:

    • False: The opsi Message Bus is not used, meaning that a connection to the opsi-client-agent is established for each command.

    • True: Only the opsi Message Bus is used. If a client is not connected to the opsi Message Bus, it is considered unreachable, and the command is not executed. If all clients are configured to use the opsi Message Bus, this is the preferred setting.

    • hybrid (default): The opsi Message Bus is used if the client has an active Message Bus connection. If not, a connection to the opsi-client-agent is established.

  • opsiclientdPort: Network port for connecting to an opsi-client-agent

  • hostRpcTimeout: Timeout in seconds when connecting to an opsi-client-agent

  • resolveHostAddress: This parameter controls name resolution:

    • True: When connecting from the opsi config server to the opsi-client-agent, the IP address of the opsi client is preferably determined via name resolution.

    • False: When connecting, the IP address stored in the opsi backend is preferred.

  • maxConnections: Maximum number of simultaneous connections to client agents

  • broadcastAddresses: WOL packets are sent to broadcast addresses; this parameter assigns network addresses to broadcast addresses. The assignment has the following form:
    { "<network-address>": { "<broadcast-address>": <port-list> } }

This example illustrates the configuration:

"broadcastAddresses": {
                                "0.0.0.0/0": {
                                                "255.255.255.255": [7, 9, 12287]
                                },
                                "10.10.0.0/16": {
                                                "10.10.1.255": [12287],
                                                "10.10.2.255": [12287]
                                },
                                "10.10.3.0/24": {
                                                "10.10.3.255": [12287]
                                },
                                "192.168.1.0/24": {
                                                "192.168.1.255": [12287, 9, 12287]
                                }
                }

Multiple broadcast addresses can be assigned to a network address. Different ports can be configured for each broadcast address. The appropriate broadcast addresses are determined based on the IP address of a client stored in the opsi backend. If the IP address is part of multiple networks, the most specific entry is used.

The opsiconfd setup Command

Bei jedem opsiconfd-Start nimmt der Dienst automatisch Anpassungen an der opsi-Umgebung vor. Daher sind in der Regel nur wenig manuelle Konfigurations- und Wartungsarbeiten erforderlich.

opsiconfd setup umfasst unter anderem die folgenden Setup-Tasks:

  • Konfigurationsdateien automatisch aktualisieren

  • System-Ressourcen-Limits (ulimit) anpassen

  • Benötigte Benutzer und Gruppen erstellen

  • Benötigte Dateien und Verzeichnisse anlegen

  • Datei /etc/sudoers konfigurieren

  • Berechtigungen für Dateien und Verzeichnisse setzen

  • Log-Dateien aufräumen

  • systemd konfigurieren

  • MySQL-Datenbank einrichten, Schema-Upgrades und Cleanup

  • File-Backend automatisch in die MySQL-Datenbank migrieren

  • Redis konfigurieren und Cleanup

  • Grafana-Konfiguration anpassen und Addons installieren

  • opsi-CA und TLS-Server-Zertifikat erstellen und erneuern

  • DHCP-Server konfigurieren

  • Samba konfigurieren und Freigaben anlegen

Sie können den Setup-Lauf aber auch jederzeit von Hand über diesen Befehl starten:

opsiconfd setup

Jetzt beginnt ein vollständiges Setup; beim "normalen" opsiconfd-Start findet ein reduzierter Setup-Lauf statt, um den Start des Dienstes zu beschleunigen.

Über den opsiconfd-Parameter skip-setup können Sie Setup-Tasks permanent abschalten.

In der Regel arbeitet opsiconfd setup nicht-interaktiv. Für die folgenden Aufgaben wird opsiconfd setup jedoch auch interaktiv verwendet:

  • Manuelle Einrichtung einer MySQL-Datenbank-Verbindung (--configure-mysql), siehe Kapitel MySQL

  • Manuelle Registrierung eines opsi-Depots (--register-depot)

  • Umbenennung eines opsi-Configservers (--rename-server)

Um eine Interaktion von opsiconfd setup mit dem Benutzer vollständig auszuschließen, etwa bei der Verwendung in Skripten, können Sie den Parameter --non-interactive verwenden.

Admin Page

The opsiconfd admin page provides status information and administrative tasks for the opsiconfd in the web browser. Access is via https://<opsi-server>:4447/admin; users must be members of the opsi admin group (see chapter Permissions). The following sections briefly introduce the individual tabs.

Info

Here you can see general information about the opsiconfd, including the number of connected depot servers and clients, information about the opsi CA, and the server certificate.

In the lower half, you can see the opsiconfd configuration; you can reload the configuration using the Service reload button.

On the *Info* tab, you can also view the *opsiconfd* configuration.
Abbildung 2. On the Info tab, you can also view the opsiconfd configuration.

Maintenance

On this tab, you can put the opsiconfd into maintenance mode and end it again. During this time, there is no client activity. Click the Set application to 'maintenance' state button to activate maintenance mode. At the top, you will see the message "accomplished": true and next to it the IP addresses for which maintenance mode does not apply — these are usually the localhost IP 127.0.0.1 and the IP address of the opsi config server. All accesses from other computers are then no longer possible; users will see the message Maintenance mode, please try again later.

In the Address exceptions (optional) field, you can enter additional IP addresses from which you want to access the opsiconfd even in maintenance mode. Separate multiple IPs with commas.

Use the Set application to 'normal' state button to end maintenance mode again.

Der Reiter *Maintenance* (de)aktiviert den Wartungsmodus und zeigt den aktuellen Status an.
Abbildung 3. The Maintenance tab (de)activates maintenance mode and shows the current status.
In der Voreinstellung wechselt der opsi-Configserver in den Maintenance-Modus, wenn Sie ein Backup erstellen oder eine Sicherungskopie wiederherstellen (siehe Kapitel Backup des opsi-Servers).

Users

Hier richten Sie die Zwei-Faktor-Authentifizierung für Benutzer auf dem opsi-Configserver ein. Nachdem Sie die opsiconfd-Konfiguration entsprechend angepasst und den Dienst neu gestartet haben, generieren Sie über den Button Generate new secret and activate TOTP ein Einmalpasswort. Es besteht aus sechs Ziffern und wird zusätzlich zur Anmeldung am opsi-Server benötigt (siehe Abschnitt Zwei-Faktor-Authentifizierung).

Auf dem Reiter *Users* können Sie die Zwei-Faktor-Authentifizierung einrichten.
Abbildung 4. Auf dem Reiter Users können Sie die Zwei-Faktor-Authentifizierung einrichten.

Clients

Die Seite zeigt Informationen über verbundene Clients und Sessions an. Gesperrte Clients erscheinen in der Liste Blocked Clients. Einzelne Clients können Sie im Bereich Unblock Clients über deren IP-Adresse und Execute freigeben; alternativ entsperren Sie über Unblock all clients alle gesperrten Client auf einmal.

Beachten Sie, dass Clients in diesem Fall (Web-)Clients meint, die auf die Admin-Seite zugreifen. Hier finden Sie keine Informationen über mit opsi verwaltete Rechner. Die Admin-Seite sperrt einen Client z. B. dann, wenn es zu viele fehlgeschlagene Anmeldeversuche gab.

Um alle Sessions eines Clients zu löschen, geben Sie dessen IP-Adresse im Feld Delete client sessions ein und bestätigen das mit Execute.

Auf diesem Reiter sehen Sie eine Liste gesperrter Clients und geben diese ggf. wieder frei.
Abbildung 5. Auf diesem Reiter sehen Sie eine Liste gesperrter Clients und geben diese ggf. wieder frei.

Depots

Im oberen Bereich des Reiters können Sie weitere Depotserver zu Ihrer opsi-Umgebung hinzufügen. Dazu tragen Sie in die beiden Felder die Depot-ID (also den FQDN des opsi-Depotservers) und eine Beschreibung ein. Nach einem Klick auf Create depot sollten Sie das neue Depot in der Tabelle sehen; hier steht im Feld Messagebus noch not connected. Damit Configserver und Depotserver miteinander kommunizieren können, führen Sie auf dem Depotserver noch das folgende Kommando aus:

opsiconfd setup --register-depot
Beachten Sie, dass das Kommando opsi-setup --register-depot nach dem Wechsel von opsi 4.2 auf 4.3 nicht mehr verfügbar ist (siehe Abschnitt opsi-setup).
Neue opsi-Depots tragen Sie auf diesem Reiter ein.
Abbildung 6. Neue opsi-Depots tragen Sie auf diesem Reiter ein.

Falls es gesperrte Produkte auf einem Depotserver gibt, erscheinen diese ebenfalls auf diesem Reiter im Bereich Locked Products. Über den Button Unlock neben einem Produkt heben Sie die Sperre für dieses eine Produkt auf; Unlock all hebt die Sperre für alle gesperrten Produkte auf.

Gibt es gesperrte Produkte? Der Reiter *Depots* zeigt diese an und bietet einen Button zum Entsperren.
Abbildung 7. Gibt es gesperrte Produkte? Der Reiter Depots zeigt diese an und bietet einen Button zum Entsperren.

RPC-Infos

Die Tabelle auf diesem Reiter zeigt die letzten RPC-Aufrufe (Remote Procedure Call) an. Sie können die Anzeige per Klick auf den Namen der Tabellenspalte sortieren.

In dieser Tabelle sehen Sie die letzten RPC-Aufrufe.
Abbildung 8. In dieser Tabelle sehen Sie die letzten RPC-Aufrufe.

RPC-Interface

Dieser Reiter führt alle zur Verfügung stehenden Methoden der JSON-RPC-API auf. Wenn Sie die Checkbox Show deprecated methods anklicken, tauchen auch veraltete Methoden im Drop-down-Menü auf. Wählen Sie aus dem Drop-down-Menü Method eine Methode aus. Je nach Methode sehen Sie weitere Eingabefelder, etwa Attribute, Filter oder verfügbare Parameter. Die Felder erwarten eine gültige JSON-Kodierung; auf eventuelle Syntaxfehler weist das Interface hin.

Ein Klick auf den Button Execute führt die Methode aus. Anfrage, Verarbeitungsdauer und Ergebnis erscheinen darunter im JSON-Format.

Über diesen Reiter können Sie Methoden der JSON-RPC-API ausführen.
Abbildung 9. Über diesen Reiter können Sie Methoden der JSON-RPC-API ausführen.

Redis-Interface

Hier können Sie Redis-Status-Informationen anzeigen, Redis-Befehle ausführen und den Cache leeren. Klicken Sie auf Info+, um detaillierte Informationen zur Redis-Version, dem Betriebssystem, der Architektur des Servers usw. einzublenden.

Die Antwort im unteren Bereich des Reiters erscheint im JSON-Format.

Zeigen Sie auf diesem Reiter Informationen zu Redis an.
Abbildung 10. Zeigen Sie auf diesem Reiter Informationen zu Redis an.
Über die Schaltfläche Debug keys können Sie Keys (Schlüssel, also die Bezeichnungen für die verschiedenen Datenstrukturen, die in der Datenbank gespeichert sind) debuggen. Das kann hilfreich sein zur Fehlersuche, Leistungsüberwachung oder Datenanalyse. Beachten Sie, dass ein versehentliches Löschen oder Überschreiben eines Schlüssels zu Datenverlust führen kann; erstellen Sie im Zweifelsfall vorher ein Backup (siehe Kapitel Backup des opsi-Servers).

Addons

Auf diesem Reiter installieren Sie opsiconfd-Erweiterungen. Diese laden Sie zunächst von unserer Website opsi-Tools herunter und speichern sie auf dem opsi-Server. Dann klicken Sie auf dem Reiter Addons auf Durchsuchen, navigieren im Dateiauswahldialog zur Zip-Datei, wählen diese aus und klicken dann auf Install addon.

Zu den bereits installierten Erweiterungen sehen Sie in der Tabelle neben dem Namen und der ID auch die Versionsnummer und den Installationspfad auf dem Server.

Installieren Sie Addons und zeigen Sie Informationen zu diesen an.
Abbildung 11. Installieren Sie Addons und zeigen Sie Informationen zu diesen an.

Log Viewer

Der Reiter bietet schnellen Zugriff auf die opsiconfd-Logfiles (siehe Abschnitt Logfiles). Sie können die Anzeige vergrößern (Button Maximize), die Protokolle nach Loglevel (Filter by level), Kontext (Filter by context) und eigenen Suchbegriffen (Filter by message) filtern. Über Checkboxen aktivieren Sie weitere Funktionen, wie das automatische Zusammenfassen von mehrzeiligen Informationen zu einer einzigen zusammenhängenden Zeile (Collapse multi-line) und das automatische Scrollen (Auto scroll). Die Schriftgröße beeinflussen Sie über die beiden Buttons neben Font size.

Die Admin-Seite bietet schnellen Zugriff auf die *opsiconfd*-Logfiles.
Abbildung 12. Die Admin-Seite bietet schnellen Zugriff auf die opsiconfd-Logfiles.

Terminal

Wechseln Sie zu diesem Reiter, um ein Terminalfenster auf dem opsi-Server zu öffnen. Dazu wählen Sie aus dem Drop-down-Menü Host einen opsi-Server in Ihrer Umgebung aus (Voreinstellung: Configserver) und klicken auf Connect. Anschließend startet das Terminal im Browser; Sie sind als Benutzer opsiconfd angemeldet und starten damit in dessen Home-Verzeichnis /var/lib/opsi.

Öffnen Sie über diesen Reiter ein Terminal auf dem opsi-Server.
Abbildung 13. Öffnen Sie über diesen Reiter ein Terminal auf dem opsi-Server.

Klicken Sie auf den Button Maximize, um das Menü am oberen Rand der Admin-Seite auszublenden und dem Terminal mehr Raum zu geben. Normalize bringt Sie zurück zur alten Ansicht. Alternativ schalten Sie über Fullscreen in die Vollbildansicht, die Sie über die Taste [Esc] verlassen können. Über das Plus und das Minus neben Font size können Sie die Schriftgröße verändern, und ein Klick auf Disconnect schließt das Terminal im Browser.

Sie können Dateien per Klick oder per Drag & Drop hochladen. Das ist beispielsweise praktisch, wenn Sie ein selbst gebautes opsi-Paket (Dateiendung .opsi) installieren wollen. So gehen Sie dazu vor:

  1. Öffnen Sie das Terminal im Browser.

  2. Wechseln Sie ins Verzeichnis mit den Paketen: cd /var/lib/opsi/repository

  3. Ziehen Sie das Paket aus dem Dateimanager ins Browser-Terminal. (ls -l listet zur Kontrolle alle Dateien im aktuellen Verzeichnis auf.)

  4. Installieren Sie das Paket: opsi-package-manager -i <paket.opsi> (siehe auch Abschnitt opsi-package-manager)

Messagebus

Auf dem Reiter können Sie (zu Test- und Debugging-Zwecken) Nachrichten über den Message Bus versenden und empfangen. Der opsi-Server nutzt den Message Bus, um Nachrichten an andere Komponenten zu senden (z. B. Installationsaufträge, Änderungen der Konfiguration oder Statusabfrage von Clients).

Wählen Sie dazu aus dem Drop-down-Menü neben dem Button Send eines der Templates aus und füllen Sie es im oberen Feld mit den richtigen Werten. Klicken Sie abschließend auf Send. Im unteren Bereich des Reiters sehen Sie die gesendete Nachricht (links) und die Antwort vom opsi-Message-Bus (rechts).

Kommunizieren Sie mit dem opsi-Message-Bus über diesen Reiter.
Abbildung 14. Kommunizieren Sie mit dem opsi-Message-Bus über diesen Reiter.

Licensing

Auf dem Reiter Licensing können Sie einsehen, welche opsi-Erweiterungen lizenziert sind. Die erste Tabelle zeigt Informationen zum Lizenznehmer (Name, aktive und nicht-aktive Clients usw.), darunter sehen Sie eine detaillierte Auflistung über die opsi-Module, wann eine Lizenz ausgestellt wurde, wie lange sie noch gültig ist usw.

Blättern Sie ans Ende des Reiters, um neue Lizenzen im neuen Format (Endung .opsilic) einzuspielen. Diese werden auf dem opsi-Server im Verzeichnis /etc/opsi/licenses gespeichert.

Informationen zu Lizenzen für die Erweiterungen finden Sie auf diesem Reiter.
Abbildung 15. Informationen zu Lizenzen für die Erweiterungen finden Sie auf diesem Reiter.
Frühere opsi-Versionen nutzten zur Freischaltung die Datei /etc/opsi/modules. Sie behält ihre Gültigkeit, neue Lizenzen stellen wir jedoch nur noch im neuen Format aus. Wenden Sie sich an sales@uib.de, um eine Lizenzdatei im neuen Format zu erhalten.

Grafana

Der Reiter Grafana leitet Sie zum Grafanai-Dashboard weiter. Sobald Sie den Tab anklicken, wird das opsiconfd main dashboard auf dem Grafana-Server angelegt bzw. aktualisiert. Außerdem wird der Benutzer opsidashboard angelegt, der für den Zugriff auf das Dashboard verwendet wird.

Logfiles

Der opsiconfd verwendet Redis, um die Logfiles zu schreiben (siehe Kapitel Redis). Darüber hinaus legt der opsiconfd im Verzeichnis /var/log/opsi/opsiconfd eigene Logfiles ab.

Wenn Probleme mit dem Zugriff auf Redis bestehen, findet keine Protokollierung statt. Um dennoch Logfiles zu generieren, können Sie den Parameter log-mode auf local stellen.

opsi unterscheidet 10 verschiedene Loglevel:

  • 0 - none: Logging komplett deaktiviert

  • 1 - essential: sehr wichtige Meldungen

  • 2 - critical: kritische Fehler

  • 3 - error: Fehler

  • 4 - warning: Warnungen

  • 5 - notice: wichtige Hinweise

  • 6 - info: weitere Informationen

  • 7 - debug: Meldungen zur Fehlersuche

  • 8 - trace: sehr viele Details, z. B. Mitschnitt der Kommunikation

  • 9 - secret: vertrauliche Informationen

Die folgenden Parameter steuern den Loglevel:

  • log-level: allgemeiner Loglevel (bis zu welchem Loglevel werden Meldungen in den Redis-Stream übertragen)

  • log-level-stderr: Level der Ausgaben auf dem Terminal (Stderr)

  • log-level-file: Loglevel der Logdateien

Verwenden Sie das Kommando opsiconfd log-viewer, um die Protokolle im Terminal zu betrachten:

opsiconfd log-viewer -l 6 --log-filter="client_address=192.168.1.1"

Da der Aufruf den Log-Stream direkt aus Redis liest, erfolgt die Ausgabe maximal bis zur Stufe log-level.

Alternativ können Sie die Logfiles auf dem Reiter Log Viewer im Admin-Interface anschauen (siehe Abschnitt Log Viewer).

Filter

Der opsiconfd gliedert die Logfiles in Kanäle und Kontexte. Daher können Sie die Meldungen filtern, um nur bestimmte Informationen zu erhalten. Den Loglevel für einen Kanal setzen Sie mit dem Parameter log-levels. Über .*:4,opsiconfd\.headers:8 werden nur Warnungen protokolliert, Meldungen im Kanal opsiconfd.headers jedoch mit dem Loglevel trace.

Nach Kontexten filter der Parameter log-filter. Für den opsiconfd kommt im Wesentlichen der Kontext client_address zum Einsatz. So können Sie beispielsweise mit client_address=192.168.1.1,192.168.1.2 bestimmen, dass Sie nur Meldungen sehen, die mit den beiden Clients mit der IP 192.168.1.1 und 192.168.1.2 zusammenhängen.

Zuordnung von SAML-Rollen zu opsi-Gruppen

Im Standardfall werden die vom IdP übermittelten Rollen eins zu eins den opsi-Gruppen zugeordnet. Sie können jedoch auch eine individuelle Zuordnung von SAML-Rollen zu opsi-Gruppen vornehmen. Die Zuordnung erfolgt über den Parameter saml-role-group-mappings in der Konfiguration. Die Zuordnung erfolgt im Format <role> = <group>, wobei <role> die Rolle des IdP und <group> die opsi-Gruppe ist. Ein Beispiel:

saml-role-group-mappings = ["CN=it-1271,OU=groups,O=acme,C=corp = opsiadmin", "CN=it-1341,OU=groups,O=acme,C=corp = opsiadmin"]