Zugangsdaten

Was sind Zugangsdaten?#

Eine Erweiterung legt fest, welche Zugangsdaten sie braucht, und gibt ihnen einen Namen, zum Beispiel PROTOKOLL_HF_TOKEN. Den Wert lieferst du. So landen geheime Werte nie im Paket der Erweiterung.

aictl speichert die Werte geschützt auf dem Server in /var/lib/aictl/ext-secrets.env. Nur Administratoren des Servers können die Datei lesen. Getrennt davon liegen die Zugangsdaten, die die Plattform für sich selbst erzeugt. Die Werte zeigt aictl nie an, auch nicht in Listen.

Jeder Dienst erhält nur die Zugangsdaten, die er ausdrücklich braucht.

Drei Arten von Zugangsdaten#

Erzeugte Werte nutzt eine Erweiterung zum Beispiel, damit sich ihre eigenen Dienste untereinander ausweisen können. Auch die Datenbank-Passwörter und die Schlüssel für die KI-Zentrale erzeugt aictl selbst. Du musst dir dafür nichts ausdenken.

Zugangsdaten setzen#

sudo aictl secret set <NAME>

Ohne weitere Option fragt der Befehl verdeckt nach dem Wert. Ein leerer Wert ist nicht erlaubt, Esc bricht ab.

Für Skripte gibst du den Wert über genau eine dieser Quellen:

sudo aictl secret set PROTOKOLL_HF_TOKEN
sudo aictl secret set PROTOKOLL_HF_TOKEN --from-file ./token.txt
printf %s "$TOKEN" | sudo aictl secret set PROTOKOLL_HF_TOKEN --stdin

Damit die Dienste den neuen Wert erhalten, übernimmst du die Änderung:

sudo aictl apply

Regeln für Namen und Werte#

• Namen bestehen aus Grossbuchstaben, Ziffern und Unterstrichen und beginnen nicht mit einer Ziffer, zum Beispiel MEIN_API_KEY.
• Werte müssen einzeilig sein. Mehrzeilige Inhalte wie einen Schlüssel im PEM-Format kodierst du vorher in Base64. Die Erweiterung muss das dann vorsehen.
• Leerzeichen am Anfang und am Ende eines Werts werden entfernt.
• --value "" gilt als «kein Wert angegeben», und der Befehl fragt nach.
• Werte lassen sich schon vor der Installation der Plattform oder einer Erweiterung setzen, zum Beispiel der Schlüssel für deinen DNS-Anbieter.

Gespeicherte Zugangsdaten anzeigen#

sudo aictl secret ls

Statt ls geht auch list. Die Liste zeigt nur Namen, nie Werte:

Gibt es gespeicherte, aber noch nicht übernommene Werte, endet die Liste mit dem Hinweis, sudo aictl apply auszuführen.

Nach extension install stehen die Werte der Erweiterung auf applied. Ein Wert, den auch eine andere installierte Erweiterung nutzt, bleibt auf stored, bis ein apply ihn überall übernommen hat.

Zugangsdaten entfernen#

sudo aictl secret rm <NAME> [<NAME> …]

Statt rm geht auch remove. Mehrere Namen auf einmal sind möglich. Namen, die nicht gespeichert sind, meldet der Befehl, entfernt die übrigen aber trotzdem. Übernimm die Änderung danach mit sudo aictl apply.

Entfernst du einen Pflichtwert, den eine Erweiterung braucht, scheitert ihr nächster Abgleich. Ihre Dienste laufen mit dem alten Wert weiter, bis sie neu gestartet werden müssen.

Von aictl erzeugte Werte#

Werte, deren Namen mit AICTL_ oder AUTH_EXT_ beginnen, erzeugt und verwaltet aictl selbst. secret set und secret rm lehnen sie ab: «… is generated and managed by aictl, not set by you». Eine Änderung von Hand würde die Erweiterung lahmlegen, die sie nutzt.

Erzeugte Werte bleiben auch nach extension remove erhalten, damit eine Neuinstallation ihre Daten wieder lesen kann. Gelöscht werden sie erst mit extension remove <name> --purge.

Bei der Installation einer Erweiterung#

Braucht eine Erweiterung Zugangsdaten, fragt extension install sie verdeckt ab:

• Vor jeder Frage stehen der Name, ob der Wert Pflicht oder optional ist, eine Beschreibung und, falls vorhanden, ein Link, wo du den Wert bekommst.
• Werte, die schon gespeichert sind, werden nicht erneut gefragt.
• Pflicht: Esc bricht die Installation ab, bevor etwas eingetragen ist.
• Optional: Esc überspringt den Wert. Die Erweiterung läuft ohne die Funktion. Du kannst ihn jederzeit mit secret set nachholen.

Hinweis: Einen übersprungenen optionalen Wert merkt sich aictl und fragt bei späteren Installationen und Updates dieser Erweiterung nicht mehr danach. Es nennt ihn nur noch. Setzen kannst du ihn jederzeit mit sudo aictl secret set.

Werte dürfen alle Zeichen ausser einem Zeilenumbruch enthalten, auch $, #, Leerzeichen und Anführungszeichen. Sie kommen unverändert bei der Erweiterung an.

Mit --yes oder ohne Terminal fragt die Installation gar nicht. Setze Pflichtwerte deshalb vorher mit secret set.

Wenn ein Pflichtwert fehlt#

Fehlt ein Pflichtwert, richtet aictl die Erweiterung nicht ein, bevor es irgendetwas anlegt. Die Meldung nennt alle fehlenden Namen und zu jedem den Link aus der Erweiterung:

missing secret(s): A, B — set each with `sudo aictl secret set <KEY>`

• Bei extension install endet der Befehl mit einem Fehler. Die Erweiterung ist aber bereits eingetragen. Setze den Wert und führe sudo aictl apply aus.
• Bei apply, update und install werden die übrigen Erweiterungen trotzdem eingerichtet. Der Befehl endet am Schluss mit einem Fehler, und apply versucht es beim nächsten Mal erneut.
• Bereits laufende Dienste der Erweiterung laufen mit den Werten weiter, mit denen sie gestartet wurden.

Änderungen übernehmen#

secret set und secret rm speichern nur. Wirksam werden Änderungen mit:

sudo aictl apply

Verwende dafür apply und nicht update: update meldet nach einem secret rm unter Umständen «nothing to do» und übernimmt die Änderung nicht.

Zugangsdaten für den DNS-Anbieter#

Auch der Schlüssel für deinen DNS-Anbieter, den die automatischen Zertifikate brauchen, ist ein Zugangsdatum, zum Beispiel CF_DNS_API_TOKEN für Cloudflare. Du setzt ihn genauso mit secret set. Welcher Name für welchen Anbieter gilt, steht unter Domain und Zertifikate.

Gemeinsame Namen#

Die Namen sind nicht pro Erweiterung getrennt. Verlangen zwei Erweiterungen denselben Namen, zum Beispiel OPENAI_API_KEY, teilen sie sich einen Wert. Entfernst du eine davon mit --purge, bleibt der Wert erhalten, solange die andere ihn noch braucht.

Wenn die Zugangsdaten verloren gehen#

Ist die Datei mit den Zugangsdaten verloren gegangen, meldet aictl status einen Fehler «ext secrets», und apply sowie update warnen am Anfang. Du hast zwei Wege:

1. Aus dem Backup zurückholen (empfohlen): Kopiere secrets/ext-secrets.env aus deinem Backup nach /var/lib/aictl/ext-secrets.env und führe sudo aictl apply aus. Danach ist alles wie vorher.
2. Neu aufbauen: sudo aictl apply erzeugt neue Datenbank-Passwörter und Schlüssel und nennt die Werte, die du selbst wieder setzen musst. Erzeugte Werte, mit denen eine Erweiterung Daten signiert oder verschlüsselt hat, bekommen dabei aber neue Werte. Solche Daten sind danach möglicherweise nicht mehr lesbar.

Sicherung#

Die Zugangsdaten sind Teil jedes Backups (secrets/ext-secrets.env) und werden bei einer Wiederherstellung zurückgespielt. Bewahre Backups deshalb so sicher auf wie die Zugangsdaten selbst. Mehr dazu unter Backup und Wiederherstellung.