So funktioniert aictl

Der gewünschte Zustand#

Alle Einstellungen deiner Installation stehen in einer einzigen Datei, der Einstellungsdatei /etc/aictl/spec.yaml. Darin steht, was du festgelegt hast: Domain, Zertifikatsart, Administrator, Branding, veröffentlichte Adressen und installierte Erweiterungen samt Version.

Wichtig zu wissen:

• Nur Abweichungen werden gespeichert. Alles, was du nicht ausdrücklich festlegst, nimmt aictl aus seinen eigenen Standardwerten. Eine neue Version von aictl kann diese Standardwerte anpassen, zum Beispiel neuere, getestete Versionen der Bausteine. aictl spec show zeigt alle geltenden Werte und markiert, welche aus deiner Einstellungsdatei stammen.
• Tippfehler werden nicht verschluckt. Ein unbekannter oder falsch geschriebener Eintrag ist ein Fehler und wird nicht stillschweigend ignoriert.
• Es gibt eine Kopie. Bei jedem Speichern legt aictl eine Kopie unter /var/lib/aictl/spec.yaml ab. Fehlt die Datei in /etc/aictl, stellt jeder Befehl sie automatisch aus dieser Kopie wieder her und meldet das.
• Die meisten Einstellungen änderst du mit einem eigenen Befehl, zum Beispiel aictl proxy hostname oder aictl brand edit. Diese Befehle prüfen, was sie schreiben, und sind deshalb der sicherste Weg.

Der Abgleich#

Aus der Einstellungsdatei erzeugt aictl sämtliche Konfigurationsdateien der Plattform und bringt die laufenden Dienste auf diesen Stand. Diesen Vorgang nennen wir Abgleich. Ein Abgleich:

• startet, was fehlt,
• erneuert nur die Dienste, deren Konfiguration sich tatsächlich geändert hat,
• lässt deine Daten unangetastet,
• erzeugt Passwörter und Schlüssel nur, wenn sie noch nicht existieren.

Weil alle Konfigurationsdateien bei jedem Abgleich neu erzeugt werden, gehen Handänderungen an diesen Dateien verloren. Die einzige Datei, die du selbst bearbeiten darfst, ist die Einstellungsdatei.

install, apply und update#

Drei Befehle führen einen Abgleich aus. Sie unterscheiden sich darin, was sie zusätzlich tun:

Gemeinsam ist allen dreien:

• Erweiterungen bleiben auf ihrer festgehaltenen Version. Neue Versionen von Erweiterungen holst du gezielt mit sudo aictl extension update.
• Sie sind wiederholbar. Ein zweiter Lauf ändert nichts, was schon stimmt.
• Sie heben einen mit aictl stop angehaltenen Zustand auf. Danach läuft die Plattform wieder.

update hat eine Abkürzung: Gibt es keine neue Version und haben sich weder Einstellungen noch gespeicherte Zugangsdaten geändert, endet er nach der Prüfung mit dem Hinweis, dass nichts zu tun ist. Mit sudo aictl update --force oder sudo aictl apply führst du den vollständigen Abgleich trotzdem aus.

Welche Änderung braucht welchen Befehl?#

Viele Befehle speichern eine Änderung nur. Wirksam wird sie erst mit dem nächsten Abgleich:

Tipp: Nach dem Entfernen von Zugangsdaten oder dem Import eines Zertifikats kann update melden, es gebe nichts zu tun. Verwende in diesen Fällen apply.

Der Hintergrunddienst#

Auf dem Hauptserver läuft ständig ein Dienst von aictl. Er wird bei der Installation als Systemdienst aictl eingerichtet und startet mit dem Server.

Was er tut:

• Etwa alle 30 Sekunden startet er Kerndienste, die nicht laufen, und sorgt so dafür, dass die Plattform nach einem Neustart oder einem Absturz wieder läuft. Ausnahme: Du hast die Plattform mit aictl stop angehalten, oder die Lizenz ist abgelaufen.
• Im selben Takt gleicht er die Sprachmodelle ab. Er erkennt, welche Modelle auf welchen Rechnern vorhanden sind, und meldet sie der KI-Zentrale.
• Er führt die geplanten Aufgaben der Erweiterungen aus, zum Beispiel ein nächtliches Aufräumen.
• Er bestätigt die Lizenz beim Start und danach alle 12 Stunden beim Lizenzserver, nach einem Fehlschlag alle 5 Minuten.
• Er nimmt weitere Rechner für Modelle auf (Port 7700).
• Er prüft einmal täglich, welche Suchmaschinen für die Websuche antworten.
• Ist das automatische Update eingeschaltet, prüft er regelmässig, ob eine neue Version erschienen ist, und spielt sie ein.

Was er nicht tut:

• Er übernimmt keine geänderten Einstellungen. Dafür ist apply da.
• Er richtet keine Erweiterungen neu ein. Die Dienste einer Erweiterung starten nach einem Neustart des Servers von selbst wieder, eine fehlgeschlagene Einrichtung wiederholt aber nur apply.
• Er legt keine DNS-Einträge an.

Läuft gerade ein anderer Befehl von aictl, überspringt der Hintergrunddienst seine Runde und versucht es beim nächsten Mal wieder.

Den Zustand des Dienstes siehst du in sudo aictl status unter «Cluster». Seine Meldungen zeigt journalctl -u aictl. Hast du ihn angehalten, startet ihn sudo systemctl start aictl wieder. apply und update lassen einen absichtlich angehaltenen Dienst angehalten und weisen darauf hin. Ist er dagegen abgestürzt oder fehlt er, richten sie ihn neu ein und starten ihn. install und restore starten ihn in jedem Fall.

Hinweis: Einige Einstellungen liest der Hintergrunddienst nur beim Start, zum Beispiel den Port für weitere Rechner. Ändern sie sich oder wird aictl ersetzt, startet er sich innerhalb von etwa 30 Sekunden selbst neu.

Gleichzeitige Befehle#

Es kann immer nur ein Befehl gleichzeitig die Plattform verändern. Startest du einen zweiten, wartet er und sagt, worauf:

==> Waiting for `aictl update` (pid 1234, running for 3m) to finish…

Brichst du das Warten mit Ctrl-C ab, wurde nichts verändert. Reine Anzeigebefehle wie status oder extension ls warten nicht.

Rechte und sudo#

Fast alle Befehle brauchen Administratorrechte und laufen mit sudo. Fehlen sie, bricht der Befehl sofort ab und zeigt dir den richtigen Aufruf:

error: this command must run as root — …
  try: sudo aictl status

aictl version ohne sudo zeigt nur die Version des Werkzeugs. Die Liste der installierten Erweiterungen erscheint erst mit sudo.

Wo was liegt#

Die eigentlichen Daten deines Teams, also Chats, Benutzer, Dokumente und die Daten der Erweiterungen, verwaltet die Plattform selbst. Sie sind vollständig im Backup enthalten, siehe Backup und Wiederherstellung.

Achtung: Der Ordner /var/lib/aictl enthält alle Passwörter der Plattform und deine Lizenz. Bearbeite die Dateien darin nicht von Hand und schütze den Zugang zum Server. Eine falsche Zeile kann Dienste aussperren.

Ausgaben lesen#

aictl meldet seinen Fortschritt in einer einheitlichen Form:

Fortschrittsmeldungen gehen auf die Fehlerausgabe, Ergebnisse wie Tabellen und Statusberichte auf die Standardausgabe. So kannst du Ergebnisse umleiten, ohne die Fortschrittsmeldungen mitzunehmen. Farben erscheinen nur in einem Terminal und lassen sich mit der Umgebungsvariable NO_COLOR=1 abschalten. Für Skripte bieten status, model ls, node ls und extension ls die Option --json.

Rückgabewerte: Jeder Befehl endet mit 0, wenn alles geklappt hat, und mit 1 bei jedem Fehler. status endet mit 1, sobald eine Prüfung fehlschlägt. Reine Warnungen ändern den Rückgabewert nicht.

Tippfehler: Vertippst du dich bei einem Befehl, schlägt aictl den passenden vor («Did you mean this?»). Viele Befehle kennen Kurzformen, zum Beispiel ls für list, rm für remove, model pull für model install und diagnose für doctor.

Abbrechen#

Lange Wartezeiten, Downloads und Prüfungen kannst du mit Ctrl-C abbrechen. Die Befehle von aictl sind wiederholbar: Führe den abgebrochenen Befehl einfach erneut aus, und er setzt dort an, wo es noch etwas zu tun gibt.

In einer Frage bricht Esc oder Ctrl-C die Frage und damit den ganzen Befehl ab. Was vorher bereits erledigt wurde, bleibt bestehen.

Fragen und Terminal#

Fragen stellt aictl direkt im Terminal, auch wenn die Ein- oder Ausgabe umgeleitet ist. Ja/Nein-Fragen zeigen die Vorgabe in Grossbuchstaben, etwa [Y/n]. Enter übernimmt die Vorgabe.

Ohne Terminal, zum Beispiel in einem Skript ohne Sitzung, verwenden die meisten Fragen ihre Vorgabe. Bei Befehlen, die Daten löschen, ist das anders: restore, uninstall, extension remove und extension prune brechen ohne Terminal ab, solange du nicht ausdrücklich --yes bzw. -y angibst.

Sonderfälle#

Fehlerhafte Einstellungsdatei. Hast du die Einstellungsdatei von Hand bearbeitet und dabei einen Fehler gemacht, laufen die Dienste unverändert weiter. Befehle wie apply brechen mit einem Hinweis ab, und status zeigt den zuletzt angewendeten Stand mit einer Warnung. Den Unterschied zur letzten gültigen Fassung zeigt:

sudo diff /var/lib/aictl/spec.yaml /etc/aictl/spec.yaml

Korrigiere den Fehler und führe sudo aictl apply aus. Solange die Datei fehlerhaft ist, pausieren das Modell-Routing und die geplanten Aufgaben. Startet der Hintergrunddienst in dieser Zeit neu, wartet er, bis die Datei korrigiert ist. Die Plattform selbst läuft weiter.

Einzelne Dienste angehalten. Hältst du einen einzelnen Kerndienst mit aictl stop <dienst> an, startet der Hintergrunddienst ihn innerhalb von etwa 30 Sekunden wieder. Soll die ganze Plattform aus bleiben, verwende aictl stop ohne Dienstnamen. Details stehen unter Betrieb im Alltag.