Betrieb im Alltag

Den Zustand prüfen#

sudo aictl status

Der Befehl prüft alle Bausteine der Plattform, die Erweiterungen, die Modell-Engine, die Anmeldung, die angehängten Modell-Rechner und die Lizenz. Jede Prüfung erscheint als eigene Zeile:

Ist mindestens eine Zeile [FAIL], endet der Befehl mit dem Exit-Code 1 und der Meldung, wie viele Prüfungen fehlgeschlagen sind. Warnungen allein ergeben den Exit-Code 0. So kannst du status auch in eine Überwachung einbinden.

Die Abschnitte der Ausgabe#

Die Ausgabe ist immer gleich gegliedert:

Einige Zeilen sind bewusst nur Warnungen und lassen status nie fehlschlagen:

• Ein Modell-Rechner, der nicht erreichbar ist (er könnte gerade beitreten oder gewartet werden).
• Die Websuche, wenn keine Suchmaschine Ergebnisse liefert.
• Speicherplatz unter 5 GiB. Unter 1 GiB wird daraus ein Fehler.
• Eine Systemuhr, die zwei Minuten oder mehr vom Lizenzserver abweicht.
• Ein eigenes Zertifikat, das in weniger als 30 Tagen abläuft. Ist es abgelaufen, wird daraus ein Fehler.
• Ein Backup, das es auf diesem Server noch nie gab oder das älter als eine Woche ist. Siehe Backup und Wiederherstellung.
• Eine Erweiterung, die nicht mehr auf der Lizenz steht. Siehe Lizenz.

Hinweis: Hast du die Plattform mit aictl stop angehalten, zeigt status nur eine einzige Zeile: stopped by operator — run sudo aictl start to resume. Der Exit-Code ist dann 0.

Maschinenlesbare Ausgabe#

sudo aictl status --json

Gibt alle Prüfungen als JSON-Liste aus, in derselben Reihenfolge wie die Textausgabe. Jeder Eintrag hat die Felder group (Abschnitt), name, ok, warn (nur bei Warnungen) und detail. Der Exit-Code ist derselbe wie ohne --json.

Ohne sudo#

Die Installation gibt der Person, die sudo aictl install ausgeführt hat, Lesezugriff auf die Plattform. Nach einer neuen Anmeldung am Server funktionieren dann aictl status, aictl license info, aictl license check, aictl auth info, aictl brand show und aictl update status ohne sudo. Alle anderen Befehle brauchen sudo.

Hinweis: Der Lesezugriff bleibt erhalten, auch wenn die Plattform ihre Dateien neu schreibt, etwa bei einer Lizenzbestätigung oder einer Wiederherstellung. Meldet ein Befehl trotzdem «permission denied», verwende sudo oder führe sudo aictl install erneut aus.

Meldungen ansehen#

sudo aictl logs

Ohne weitere Angabe zeigt der Befehl die letzten Meldungen aller Bausteine und aller Erweiterungen. Du kannst ihn eingrenzen:

Mehrere Angaben lassen sich kombinieren. Ein unbekannter Name führt zu einer Fehlermeldung, die alle gültigen Namen auflistet.

Beispiele:

sudo aictl logs -f                    # alles live verfolgen
sudo aictl logs archive -f            # alles einer Erweiterung live
sudo aictl logs protocol/worker -n 50 --since 10m

Kommen die Meldungen aus mehreren Teilen der Plattform, beginnt jede Zeile mit ihrer Herkunft, zum Beispiel core/ oder protocol/.

status zeigt dir, was nicht funktioniert, logs zeigt dir, warum.

Die Plattform anhalten und starten#

Die ganze Plattform#

sudo aictl stop
sudo aictl start
sudo aictl restart

Gut zu wissen:

• Der Hintergrunddienst läuft auch bei angehaltener Plattform weiter, damit die Lizenz bestätigt wird. Die Modell-Engine wird nie angehalten.
• Auch install, update, apply und restore heben einen gespeicherten Stopp auf.
• start und restart warten bis zu 5 Minuten, bis alles gesund ist. Dauert es länger, gibt es nur eine Warnung. Prüfe dann mit sudo aictl status, was noch startet.
• Fehlen Teile der Plattform ganz, zum Beispiel nach einer Aufräumaktion auf dem Server, baut start beziehungsweise restart die Plattform vollständig neu auf. Das dauert länger und braucht eine gültige Lizenz.
• restart liest geänderte Einstellungen nicht neu ein. Dafür gibt es apply.

Einzelne Dienste#

sudo aictl restart protocol/worker    # ein Dienst einer Erweiterung
sudo aictl restart archive            # alle Dienste einer Erweiterung
sudo aictl stop <dienst>              # ein Baustein der Plattform

Die Namen sind dieselben wie bei logs. Das Anhalten einzelner Dienste ist vorübergehend und wird nicht gespeichert:

• Ein Baustein der Plattform, den du einzeln anhältst, wird vom Hintergrunddienst innerhalb von etwa 30 Sekunden wieder gestartet.
• Ein Dienst einer Erweiterung bleibt dagegen angehalten, bis du ihn startest oder apply, update, start oder restart für die ganze Plattform ausführst.

Wenn zwei Befehle gleichzeitig laufen#

Befehle, die etwas verändern, warten aufeinander. Läuft bereits ein anderer, siehst du zum Beispiel Waiting for aictl update (pid 1234, running for 3m) to finish…. Brichst du das Warten mit Ctrl-C ab, wurde nichts verändert.

Wartungsseite#

Ist ein Bereich der Plattform kurz nicht erreichbar, zeigt das Gateway statt einer technischen Fehlermeldung eine Wartungsseite mit deinem Firmennamen und Logo (siehe Branding). Das passiert zum Beispiel:

• während eines Backups,
• wenn apply oder update einen Bereich neu startet,
• wenn ein Bereich abgestürzt ist und gerade neu startet.

Die Seite lädt sich alle 30 Sekunden neu und verschwindet von selbst, sobald der Bereich wieder antwortet. Programme, die über eine Schnittstelle zugreifen, bekommen statt der Seite eine kurze Fehlermeldung im JSON-Format.

Keine Wartungsseite gibt es, wenn das Gateway selbst nicht läuft: nach aictl stop, während einer Wiederherstellung und in den letzten Sekunden eines Backups. Dann meldet der Browser, dass die Seite nicht erreichbar ist. Bleibt die Wartungsseite länger stehen, zeigt sudo aictl status, welcher Bereich nicht läuft.

Geänderte Einstellungen übernehmen#

sudo aictl apply

apply erzeugt die Konfiguration aus deinen Einstellungen neu und bringt die laufende Plattform auf diesen Stand. Nur Dienste, deren Konfiguration sich tatsächlich geändert hat, werden neu erstellt. Deine Daten bleiben erhalten.

Du brauchst apply nach:

• aictl proxy hostname (Adressen veröffentlichen oder ändern),
• aictl proxy set-cert (eigenes Zertifikat einspielen),
• aictl secret set oder secret rm (Zugangsdaten),
• aictl brand edit (Branding),
• einer Änderung an der Einstellungsdatei,
• einer fehlgeschlagenen Erweiterung, die erneut eingerichtet werden soll.

Im Unterschied zu update prüft apply nicht auf eine neue Version, lädt keine neuen Bestandteile herunter und übernimmt keine neue Einstellungsdatei. Es wendet nur an, was bereits eingestellt ist. Danach bietet es an, fehlende DNS-Einträge anzulegen, und zeigt eine Zusammenfassung.

Gut zu wissen:

• apply braucht eine gültige Lizenz. Ist die Lizenz eingeschränkt, wird es verweigert, siehe Lizenz.
• apply richtet den Hintergrunddienst neu ein und startet ihn, falls er fehlt oder abgestürzt ist. Hast du ihn absichtlich angehalten, bleibt er angehalten, und apply weist darauf hin.
• Der Befehl endet mit einem Fehler, wenn danach eine Prüfung fehlschlägt oder eine Erweiterung nicht eingerichtet werden konnte. Die Plattform läuft trotzdem weiter. Ein erneutes apply versucht es noch einmal.

Der Hintergrunddienst#

Auf dem Hauptserver läuft ständig der Hintergrunddienst von aictl. Die Installation richtet ihn als Systemdienst namens aictl ein, der beim Hochfahren automatisch startet. Er erledigt:

Erweiterungen richtet der Hintergrunddienst nicht neu ein. Ihre Dienste starten nach einem Neustart des Servers von selbst, ein einzeln angehaltener Dienst einer Erweiterung bleibt aber angehalten.

Hast du die Plattform mit stop angehalten oder ist die Lizenz gestoppt, lässt der Hintergrunddienst die Plattform angehalten.

Den Hintergrunddienst prüfen und neu starten#

sudo systemctl status aictl           # läuft er?
sudo journalctl -u aictl -n 100       # seine letzten Meldungen
sudo journalctl -u aictl -f           # live verfolgen
sudo systemctl restart aictl          # neu starten

Von Hand neu starten musst du ihn kaum: Ersetzt du aictl, etwa mit dem Installationsskript, oder änderst du controlPlane.port, controlPlane.allowPublicNodeEndpoints oder localNodeName in der Einstellungsdatei, startet sich der Dienst innerhalb von etwa 30 Sekunden selbst neu. Die Plattform läuft dabei weiter.

Starte aictl serve nie von Hand, solange der Systemdienst läuft. Der zweite Start scheitert, weil der Port bereits belegt ist.

Wenn der Hintergrunddienst nicht läuft#

status meldet dann im Abschnitt «Cluster» einen Fehler. Ohne den Dienst werden abgestürzte Bausteine nicht neu gestartet, die Lizenz nicht bestätigt und keine Modell-Rechner aufgenommen. Die laufende Plattform arbeitet aber weiter.

• Starte ihn mit sudo systemctl start aictl und schau mit sudo journalctl -u aictl nach der Ursache.
• install, apply und ein vollständiges update richten ihn neu ein. Ein update, das «nichts zu tun» meldet, tut das nicht.
• Ist die Einstellungsdatei fehlerhaft, wartet der Dienst und versucht es alle 30 Sekunden erneut. Die Plattform selbst läuft weiter. Behebe den Fehler, siehe Fehlerbehebung.
• Wird die Einstellungsdatei fehlerhaft, während der Dienst läuft, arbeitet die Plattform mit dem zuletzt angewendeten Stand weiter. Modell-Verteilung und geplante Aufgaben pausieren, bis die Datei wieder lesbar ist.

Version anzeigen#

aictl version

Zeigt die Version von aictl mit Build-Informationen und die neueste verfügbare Version. Mit sudo folgt zusätzlich die Liste der installierten Erweiterungen mit installierter und neuester Version und ihrem Zustand. aictl --version zeigt nur die Version.

Lege die Ausgabe jeder Supportanfrage bei.