Was dieses Modul tut #
Fast jeder Dienst deiner Instanz braucht ein Geheimnis: das Passwort der Datenbank, die Passphrase eines Integritätswerkzeugs, einen API-Schlüssel … Sie von Hand zu verwalten — oder schlimmer, auf den Standardwerten zu belassen — ist eine der häufigsten Ursachen dafür, dass eine Maschine kompromittiert wird.
Das Modul secrets kümmert sich lokal um diesen Lebenszyklus: Es erzeugt jedes Geheimnis mit einem kryptografisch sicheren Generator (CSPRNG), speichert es mit Berechtigungen 0600 (nur root kann es lesen), gibt es mit einer sauberen Ausgabe zurück, die bereit ist, in einer Pipe verkettet zu werden, und rotiert es, wenn du es brauchst. Alles ist nach Domänen organisiert (zum Beispiel mariadb oder tripwire), und jede Domäne kann mehrere Felder haben.
generate ist idempotent: Wenn das Geheimnis einer Domäne bereits existiert, wird es nicht angetastet. So kann ein und dasselbe Image seine Geheimnisse beim ersten Start jeder Instanz erstellen, ohne dass zwei Maschinen dasselbe Passwort teilen. Die Werte werden niemals protokolliert oder in list angezeigt.
Häufige Aufgaben #
Wähle aus, was du tun möchtest. Jedes Rezept bringt den fertigen Befehl mit — tausche einfach die Domäne gegen deine aus und drücke Kopieren.
1
Das Geheimnis eines Dienstes erzeugen
Erstellt ein starkes Passwort für eine Domäne, nur wenn es noch nicht existiert.
Verbinde dich per SSH mit deinem Server über den Benutzer ubuntu.
Erzeuge das Geheimnis der Domäne mariadb. Da es idempotent ist, kannst du es beliebig oft ausführen, ohne befürchten zu müssen, etwas zu überschreiben:
$ sudo imaxe secrets generate mariadbBrauchst du eine lange Passphrase für ein anderes Werkzeug und in einem bestimmten Feld? Passe --format, --len und --field an:
$ sudo imaxe secrets generate tripwire --field local.passphrase --format passphrase --len 400600 gespeichert. Falls es bereits existierte, wurde es nicht geändert — der Befehl endet trotzdem erfolgreich.2
Ein Geheimnis zur Verwendung lesen
Hol dir den Rohwert, bereit zum Verketten in einem anderen Befehl.
get gibt ausschließlich den Wert aus, ohne Schnörkel oder zusätzliche Zeilenumbrüche, damit du ihn per Pipe an einen anderen Prozess übergeben kannst:
$ sudo imaxe secrets get mariadbLiegt das Geheimnis in einem bestimmten Feld der Domäne? Gib es mit --field an:
$ sudo imaxe secrets get tripwire --field local.passphrasePASS="$(sudo imaxe secrets get mariadb)" verwenden und es direkt in deinem Skript nutzen.3
Ein Geheimnis rotieren
Ersetzt den Wert durch einen neuen und markiert die Domäne als rotiert.
Erzeuge einen neuen Wert für die Domäne. Anders als generate ersetzt rotate das vorhandene Geheimnis sehr wohl:
$ sudo imaxe secrets rotate mariadblist). Denk daran, den Dienst, der dieses Geheimnis nutzt, mit dem neuen Wert aus get zu aktualisieren.4
Sehen, welche Domänen existieren
Frage die Metadaten ab, ohne irgendeinen Wert offenzulegen.
Listet die Domänen mit ihren Metadaten auf (wann sie erstellt und wann sie rotiert wurden). Zeigt niemals das Geheimnis selbst:
$ sudo imaxe secrets listBrauchst du es für ein Skript oder eine automatische Prüfung? Fordere die Ausgabe als JSON an:
$ sudo imaxe secrets list --jsonDas Geheimnis ist nur von root lesbar, solange es auf der Festplatte lebt. Sobald du es mit get liest, gelangt es in dein Terminal und in deine Shell: Vermeide es, es im Verlauf (history), in überflüssig exportierten Umgebungsvariablen oder in Logs zu hinterlassen. Bevorzuge punktuelle Befehlssubstitutionen wie "$(sudo imaxe secrets get mariadb)".
Synopsis #
imaxe secrets <subcomando> [<dominio>] [--field CLAVE] [flags]Alle Unterbefehle benötigen root-Rechte (verwende sudo), weil sie Dateien mit 0600 unter /etc/imaxe/ lesen und schreiben. Füge list ein --json hinzu, um eine maschinenlesbare Ausgabe zu erhalten, die für Scripting geeignet ist. Denk daran: get gibt den Rohwert aus, ohne Verzierung, bereit für die Pipe.
Unterbefehle #
| Unterbefehl | Was er tut | Relevante Flags |
|---|---|---|
| generate | Erstellt das Geheimnis einer Domäne, falls es nicht existiert (idempotent, CSPRNG). Ohne Domäne erzeugt es die von generate_on_first_boot. | --len, --format, --field |
| get | Gibt den Wert eines Geheimnisses mit sauberer Ausgabe zurück, geeignet für die Pipe. | --field |
| rotate | Erzeugt ein neues Geheimnis und markiert die Domäne als rotiert. | --field |
| list | Listet die Domänen und Metadaten auf (erstellt, rotiert). Zeigt niemals Werte. | --json |
Argumente und Flags #
| Flag | Typ | Standard | Beschreibung |
|---|---|---|---|
| <dominio> | string | — | Domäne des Geheimnisses (z. B. mariadb, tripwire). Erforderlich bei get und rotate. Bei generate bedeutet leer = die Domänen von generate_on_first_boot. |
| --field | string | value | Feld innerhalb der Domäne. Erlaubt es, mehrere Geheimnisse pro Domäne zu speichern (z. B. local.passphrase). |
| --len | int | 32 | Bei generate: Länge des Geheimnisses in Zeichen. |
| --format | enum | password | Bei generate: Format des Werts — password, passphrase oder hex. |
| --json | bool | false | Bei list gibt es die Metadaten als strukturiertes JSON auf stdout aus. |
Dateien und Pfade #
| Pfad | Inhalt |
|---|---|
| /etc/imaxe/secrets.yml | Konfiguration des Moduls: Standardwerte (length, format), Domänen und Liste von generate_on_first_boot. Wird mit Berechtigungen 0600 gespeichert. |
Beispiel für secrets.yml:
defaults:
length: 32
format: password
domains: {}
generate_on_first_boot:
- mariadb
- tripwireMit dieser Konfiguration erstellt ein sudo imaxe secrets generate ohne Domäne beim ersten Start die Geheimnisse von mariadb und tripwire mit der Standardlänge und dem Standardformat.
Exit-Codes und Logs #
Jede Ausführung gibt einen Code zurück, den du mit echo $? prüfen kannst — nützlich für die Verkettung in Skripten:
get ohne Domäne).Typische Verwendung in einem Skript, unter Ausnutzung der sauberen Ausgabe von get:
$ sudo imaxe secrets generate mariadb \
&& sudo imaxe secrets get mariadb | some-tool --stdin-password \
|| echo "falló con código $?"Fehlerbehebung #
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Es erscheint NOTFOUND (Code 3) | Die Domäne oder das --field wurde noch nicht erzeugt. | Erstelle es zuerst mit secrets generate <dominio> (und demselben --field). |
| Es erscheint USAGE (Code 2) | get oder rotate ohne Angabe der Domäne ausgeführt. | Übergib die Domäne als Argument; sie ist in diesen Unterbefehlen erforderlich. |
generate ändert den Wert nicht | Das Geheimnis existierte bereits: generate ist von Natur aus idempotent. | Wenn du einen neuen Wert möchtest, verwende secrets rotate <dominio>. |
Permission denied beim Lesen | Die Datei ist 0600 und du hast es ohne Rechte ausgeführt. | Führe den Befehl mit sudo aus; nur root greift auf das Geheimnis zu. |
Steckst du beim Modul Geheimnisse fest?
Schreib uns mit der Ausgabe von «imaxe <module> status --json» und wir antworten dir schnell.