95.1.66. pepsi-config

inspect and edit the effective pepsi configuration

Handbuchabschnitt:

1

95.1.66.1.1. Name

pepsi-config - die zusammengeführte Pepsi-Konfiguration nachschlagen, expandieren, ausgeben und bearbeiten.

95.1.66.1.2. Übersicht

pepsi-config [GLOBAL-OPTIONS] get [-f | –filename] SECTION OPTION

pepsi-config [GLOBAL-OPTIONS] pathsub PATH-EXPR

pepsi-config [GLOBAL-OPTIONS] dump [-d | –diagnostics] [–origin [–scope SCOPE]]

pepsi-config [GLOBAL-OPTIONS] set [–scope SCOPE] SECTION OPTION VALUE

pepsi-config [GLOBAL-OPTIONS] unset [–scope SCOPE] SECTION [OPTION]

pepsi-config [GLOBAL-OPTIONS] list [–scope SCOPE] [–drafts]

pepsi-config [GLOBAL-OPTIONS] export [–from DIR] [–password-file FILE] ARCHIVE

pepsi-config [GLOBAL-OPTIONS] import [–into DIR] [–force] [–password-file FILE] ARCHIVE

95.1.66.1.3. Beschreibung

pepsi-config inspiziert und bearbeitet die effektive Konfiguration, die alle Pepsi-Komponenten teilen. Alle Komponenten lesen dieselbe Konfigurationsdatei im INI-Stil (siehe pepsi.conf(5)) und dieselbe Konfigurations-Überlagerung in der Datenbank, sodass dieses eine Werkzeug ihnen allen dient.

Die lesenden Befehle melden die effektive Konfiguration: die Datei, ergänzt durch die Tabelle pepsi.config_override. Für get, pathsub und dump ist eine nicht erreichbare Datenbank kein Fehler, denn ein Betreiber greift zu diesem Werkzeug meist dann, wenn etwas nicht stimmt: Der Befehl meldet die Konfiguration der Datei, und der Lauf gelingt dennoch. Ein fehlgeschlagener Verbindungsaufbau wird als Warnung protokolliert. Kommt die Verbindung zustande, kann der Befehl die Überlagerung aber nicht lesen, protokolliert er einen Fehler und meldet trotzdem die Konfiguration der Datei. dump –origin meldet die Konfiguration der Datei ohne Meldung, wenn keine Verbindung zustande kommt, und mit einer Warnung, wenn die Überlagerung nicht gelesen werden kann. list ist die Ausnahme: Es gibt die gespeicherten Überschreibungen aus und hat daher ohne die Datenbank nichts zu melden; es endet mit einem Wert ungleich null, wenn die Verbindung fehlschlägt oder der Aufrufer die Rolle pepsi-config nicht hält.

Die schreibenden Befehle (set, unset) bearbeiten nur die Datenbank-Überlagerung. Sie ändern nie die Konfigurationsdatei, die die des Betreibers bleibt, und sie werden abgelehnt, sofern der Aufrufer nicht die PostgreSQL-Rolle pepsi-config hält (pepsi-config übernimmt dieses Konto, wenn es als root gestartet wird). Diese Berechtigung setzt die Regel durch, dass keine Pepsi-Komponente, die Mail verarbeitet, die Konfiguration schreiben darf, die die Pipeline definiert, in der sie läuft.

Die Geltungsbereichskette, und welche Abschnitte überhaupt in der Datenbank liegen dürfen, sind in pepsi.conf(5) beschrieben.

95.1.66.1.4. Befehle

get [-f | –filename] SECTION OPTION

Gibt den effektiven Wert von OPTION in SECTION aus. Mit –filename wird der Wert als Pfad interpretiert und eine $-Expansion angewendet.

pathsub PATH-EXPR

Gibt PATH-EXPR aus, wobei ${VAR}- und $VAR-Platzhalter aus dem [PATHS]-Abschnitt und der Umgebung ersetzt werden.

dump [-d | –diagnostics] [–origin [–scope SCOPE]]

Gibt die zusammengeführte Konfiguration aus. Mit –diagnostics wird zusätzlich gezeigt, aus welcher Datei und Zeile jede Option stammt. Mit –origin wird jeder Wert mit der Schicht annotiert, die ihn gesetzt hat (file oder der Datenbank-Geltungsbereich), und jeder Abschnitt damit, ob eine Änderung daran live wirksam wird oder einen Neustart braucht; –scope löst die Kette für eine bestimmte Domain oder Adresse auf (Standardwert global).

–scope wirkt nur zusammen mit –origin. Ohne dieses ist die Ausgabe die Datei, ergänzt allein um die Überlagerungsschicht global, was auch immer –scope sagt (der Wert wird dennoch geparst, ein fehlerhafter Geltungsbereich bleibt also ein Fehler).

Optionen, die Zugangsdaten tragen, werden maskiert als ***: jede Option in den Abschnitten [pepsi-postgres] und [pepsi-admin] sowie jede Option, deren Name PASS (also PASSWORD, PASSPHRASE und [pepsi-list] API_PASS), SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER oder SYSTEM_ID enthält. KEY steht bewusst nicht in dieser Liste, sodass ein TLS_KEY-Pfad weiterhin angezeigt wird. Die Direktive @inline-secret@ führt jedes secrets.d/*.secret-Fragment in die Konfiguration ein, die dieser Befehl darstellt. Ein unmaskierter, als root ausgeführter Dump gäbe daher das SRS-Geheimnis, das Geheimnis zur Schlüsselverschlüsselung, den Pfeffer für Secure-Link und jedes Smarthost-Passwort aus, und einen Dump in einen Fehlerbericht umzuleiten ist der übliche Weg, auf dem ein Betreiber seine Konfiguration weitergibt. Der Befehl verwendet dasselbe Prädikat wie die administrative API und das Echo der Einstellungen (pepsi_common::secrets::is_secret), sodass alle drei konstruktionsbedingt übereinstimmen. Lesen Sie das Fragment selbst, wenn Sie einen Wert brauchen.

set [–scope SCOPE] SECTION OPTION VALUE

Legt eine Überschreibung in der Datenbank ab. SECTION wird zuallererst in Kleinbuchstaben und OPTION in Großbuchstaben umgewandelt, die auf der Kommandozeile verwendete Schreibweise spielt also keine Rolle. Der Befehl prüft die Änderung zuerst: Er baut die Konfiguration, die die Änderung ergäbe, und lässt den Parser der Stage darüber laufen, der der Abschnitt gehört. Einen Wert, den diese Stage ablehnen würde, lehnt der Befehl mit dem Fehler der Stage ab, und nichts wird gespeichert. Ebenso lehnt der Befehl Folgendes ab und speichert es nie: einen Abschnitt, der nur in der Konfigurationsdatei stehen darf; eine Zugangsdaten tragende Option in jedem beliebigen Abschnitt (Zugangsdaten werden nie in der Datenbank gespeichert); eine Option, die ein Programm benennt, das Pepsi ausführt (HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND und das PROGRAM einer Stage, sofern es kein bloßer pepsi-stage-*-Befehl ist); und einen SCOPE domain:/address: für einen Abschnitt, der nicht [stage-*] ist, da nichts andere Abschnitte je Domain oder je Adresse liest (siehe pepsi.conf(5)). Die Administrations-API wendet dieselbe Regel an, und ein Datensatz, der sie verletzt, wird beim Lesen der Überlagerung ignoriert. set gibt aus, ob die Änderung live wirkt oder einen Neustart braucht, und hält die Änderung im Audit-Protokoll fest: wer sie vorgenommen hat, wann und in welchem Geltungsbereich, aber nicht den Wert.

unset [–scope SCOPE] SECTION [OPTION]

Entfernt eine Überschreibung oder, ohne OPTION, jede Überschreibung, die der Geltungsbereich für SECTION enthält. Die betroffenen Optionen fallen auf die nächsttiefere Schicht zurück, letztlich auf die Konfigurationsdatei. Etwas zu entfernen, das nie gesetzt war, wird gemeldet und ist kein Fehler.

list [–scope SCOPE] [–drafts]

Gibt die gespeicherten Überschreibungen mit ihren Zeitstempeln und Urhebern aus. Anders als bei set und unset hat –scope hier keinen Standardwert: Wird keiner angegeben, wird jeder Geltungsbereich aufgeführt. –drafts zeigt zusätzlich vorbereitete Datensätze, die keine laufende Komponente liest.

export [–from DIR] [–password-file FILE] ARCHIVE

Schreibt ein passwortverschlüsseltes Archiv des Konfigurationsverzeichnisses (standardmäßig des Verzeichnisses, in dem die geladene Konfigurationsdatei liegt): die Konfigurationsdatei, etwaige Fragmente daneben und die Geheimnisfragmente in secrets.d. Die Berechtigungsbits jeder Datei werden numerisch festgehalten, Eigentümer und Gruppe namentlich (mit Rückfall auf die numerische ID, wenn das Konto nicht mehr auflösbar ist). ARCHIVE darf - für die Standardausgabe sein; die Fortschritts- und Zusammenfassungszeilen gehen auf die Standardfehlerausgabe, sodass die Standardausgabe nutzbar bleibt. Die Archivdatei selbst wird mit Modus 0600 angelegt. Es werden nur reguläre Dateien archiviert: Symbolischen Verweisen wird nicht gefolgt, und alles andere wird mit einer Warnung übersprungen. Der Befehl lehnt eine einzelne Datei größer als 32 MiB ab, ebenso ein Passwort kürzer als 12 Zeichen und ein Verzeichnis, das überhaupt keine reguläre Datei enthält. Dies deckt bewusst nicht die Datenbank-Überlagerung ab, die pg_dump bereits ordentlich sichert.

import [–into DIR] [–force] [–password-file FILE] ARCHIVE

Stellt ein von export geschriebenes Archiv wieder her. ARCHIVE darf - sein, um von der Standardeingabe zu lesen. Die Eigentumsverhältnisse werden wiederhergestellt, sodass dies normalerweise root erfordert; eine Datei, deren festgehaltener Eigentümer auf dieser Maschine nicht existiert, wird abgelehnt, nicht erraten, und ebenso eine, die einem anderen Konto gehört, wenn der Befehl nicht als root läuft. Diese Eigentumsprüfungen laufen über das ganze Archiv, bevor eine einzige Datei geschrieben wird; eine Wiederherstellung, die daran scheitert, schreibt also nichts. Ein Eintrag, dessen Ziel bereits existiert, wird ebenfalls abgelehnt, doch diese Prüfung geschieht erst, wenn die Wiederherstellung den Eintrag erreicht. Sie bricht die Wiederherstellung deshalb ab, statt die Datei zu überspringen: Die Einträge davor sind bereits geschrieben, die danach nicht. Geben Sie –force an, um stattdessen zu überschreiben. Eine Wiederherstellung in ein Verzeichnis, das bereits eine pepsi.conf enthält, braucht daher entweder –force oder ein leeres –into-Verzeichnis. Archiveinträge, die einen absoluten Pfad oder eine ..-Komponente benennen, werden rundweg zurückgewiesen.

Sowohl export als auch import benötigen das Archivpasswort. Mit –password-file wird es aus FILE gelesen, die für andere nicht lesbar sein darf (chmod 600) und nicht leer sein darf; andernfalls fragt der Befehl es auf dem Terminal ohne Echo ab, wobei export zweimal fragt und eine Abweichung zurückweist. export verlangt ein Passwort von mindestens 12 Zeichen (als Zeichen gezählt, nicht als Bytes) und lehnt eines ab, das auf der Liste gängiger Passwörter steht oder den Namen des Hosts enthält: Das Archiv enthält jedes Geheimnisfragment, den Schlüsselverschlüsselungsschlüssel eingeschlossen, und wer eine Kopie erlangt, kann in Ruhe offline Vermutungen testen, Argon2id hin oder her. import nimmt jedes Passwort an, mit dem das Archiv geschrieben wurde. Wurde überhaupt keine Konfigurationsdatei gefunden, gibt es kein Verzeichnis als Standardwert, und –from/–into wird zwingend erforderlich.

95.1.66.1.5. Geltungsbereiche

SCOPE ist eines von:

global

Die gesamte Installation. Der Standardwert für set und unset.

domain:DOMAIN

Nachrichten, deren maßgebliche Adresse bei DOMAIN liegt.

address:ADDRESS

Nachrichten, deren maßgebliche Adresse genau ADDRESS ist.

Die maßgebliche Adresse ist der Umschlagabsender bei einer lokal erzeugten Nachricht, sonst jeder Umschlagempfänger. Die Einstellungsschicht je Adresse verwendet dieselbe Regel (pepsi-settings(1)).

95.1.66.1.6. Globale Optionen

Diese globalen Optionen stehen vor dem Unterbefehl (ein nachgestelltes Flag wird abgelehnt).

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit. LOGLEVEL ist eines von error, warn, info, debug oder trace. Fehlt der Schalter, gilt die globale Option [pepsi] LOG, und andernfalls info.

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen, einschließlich Drittanbieter-Bibliotheken.

-h, –help

Gibt eine Verwendungsübersicht aus und beendet sich.

-V, –version

Gibt die Version aus und beendet sich.

95.1.66.1.7. Exit-Status

0

Erfolgreicher Abschluss.

1

Ein Fehler ist aufgetreten, zum Beispiel eine fehlerhafte Konfigurationsdatei, ein fehlendes SECTION/OPTION, ein abgelehnter Überschreibungswert, ein Abschnitt, der nur in der Konfigurationsdatei stehen darf, ein falsches Archivpasswort oder unzureichende Datenbankprivilegien für einen Schreibvorgang. Der Grund wird in das Journal geschrieben.

2

Die Kommandozeile selbst war falsch (eine unbekannte Option, eine globale Option nach dem Unterbefehl geschrieben, ein fehlendes Argument).

78

set, unset oder list fand ein Datenbankschema aus einem anderen Pepsi-Release; führen Sie pepsi-setup schema aus (siehe pepsi-setup(1)). Die lesenden Befehle geben stattdessen die Konfiguration der Datei aus, wie bei einer nicht erreichbaren Datenbank.

95.1.66.1.8. Dateien

Wenn –config nicht angegeben ist, wird die erste vorhandene Datei aus der folgenden Liste verwendet. Jede Pepsi-Komponente teilt sich dieselbe Konfigurationsdatei, sodass dies dieselbe Liste ist, die jede durchsucht:

  • $XDG_CONFIG_HOME/pepsi.conf

  • $HOME/.config/pepsi.conf

  • /etc/pepsi/pepsi.conf

  • /etc/pepsi.conf

95.1.66.1.9. Beispiele

Prüfen, für welche Domains Mail angenommen wird:

pepsi-config -c /etc/pepsi/pepsi.conf get pepsi-ingress ACCEPTED_DOMAINS

Die zusammengeführte Konfiguration mit Quellannotationen ausgeben:

pepsi-config -c /etc/pepsi/pepsi.conf dump --diagnostics

Zeigen, woher jeder effektive Wert stammt:

pepsi-config dump --origin

Die Warteschlangenlebensdauer einer Stage erhöhen, ohne eine Datei zu bearbeiten oder etwas neu zu starten:

pepsi-config set stage-relay MAX_LIFETIME '48 h'

Einer Domain eine andere Einstellung geben und sie wieder wegnehmen:

pepsi-config set --scope domain:example.org stage-relay DELAY_DSN_AFTER '4 h'
pepsi-config unset --scope domain:example.org stage-relay DELAY_DSN_AFTER

Alles sichern, was nicht in der Datenbank liegt:

pepsi-config export /root/pepsi-config-backup.pca

95.1.66.1.10. Siehe auch

pepsi.conf(5), pepsi-setup(1), pepsi-settings(1)

95.1.66.1.11. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.