85.1.60. pepsi-config

inspect and edit the effective pepsi configuration

Handbuchabschnitt:

1

85.1.60.1.1. Name

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

85.1.60.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

85.1.60.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 – die Konfiguration der Datei wird gemeldet und der Lauf gelingt dennoch –, denn ein Operator greift zu diesem Werkzeug meist dann, wenn etwas nicht stimmt. (Ein fehlgeschlagener Verbindungsaufbau wird als Warnung protokolliert; eine Verbindung, die zustande kommt, deren Überlagerung aber nicht gelesen werden kann, wird als Fehler protokolliert, und die Konfiguration der Datei wird trotzdem gemeldet. 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 ohne die Datenbank daher 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 Operators 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 ist die Durchsetzung: Keine Pepsi-Komponente, die Mail verarbeitet, darf die Konfiguration schreiben, 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.

85.1.60.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 PASSWORD, PASSPHRASE, SECRET, TOKEN, CREDENTIAL, CLIENT_ID oder PEPPER enthält — bewusst nicht KEY, 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 Operator seine Konfiguration weitergibt. Das Prädikat ist dasselbe, das die administrative API und das Echo der Einstellungen verwenden (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. Die Änderung wird zuerst geprüft, indem die Konfiguration gebaut wird, die sie ergäbe, und der eigene Parser der besitzenden Stage darüber läuft; ein Wert, den diese Stage ablehnen würde, wird mit dem Fehler dieser Stage abgelehnt, und nichts wird gespeichert. Ebenso abgelehnt und nie gespeichert werden: ein Abschnitt, der nur in der Konfigurationsdatei stehen darf, eine Zugangsdaten tragende Option in jedem beliebigen Abschnitt (Zugangsdaten werden nie in der Datenbank gespeichert) und ein 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. Gibt aus, ob die Änderung live wirkt oder einen Neustart braucht, und hält die Änderung – wer, wann, welcher Geltungsbereich, aber nicht den Wert – im Audit-Protokoll fest.

unset [–scope SCOPE] SECTION [OPTION]

Entfernt eine Überschreibung oder — ohne OPTION — jede Überschreibung, die der Geltungsbereich für SECTION trägt. 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 diese 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 —, und eine einzelne Datei größer als 32 MiB, ein leeres Passwort oder ein Verzeichnis ganz ohne reguläre Datei werden abgelehnt. 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, sobald der Eintrag erreicht wird, und bricht die Wiederherstellung ab, statt die Datei zu überspringen — die Einträge davor sind also bereits geschrieben und die danach nicht. Geben Sie –force an, um stattdessen zu überschreiben. Eine Wiederherstellung in ein Verzeichnis, das bereits eine pepsi.conf enthält, will 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 wird es auf dem Terminal ohne Echo abgefragt, wobei export zweimal fragt und eine Abweichung zurückweist. Wurde überhaupt keine Konfigurationsdatei gefunden, gibt es kein Verzeichnis als Standardwert, und –from/–into wird zwingend erforderlich.

85.1.60.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 — dieselbe Regel, die die Einstellungsschicht je Adresse verwendet (pepsi-settings(1)).

85.1.60.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.

85.1.60.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).

85.1.60.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

85.1.60.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

85.1.60.1.10. Siehe auch

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

85.1.60.1.11. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.