85.1.46. pepsi-settings

manage per-address stage option overrides

Handbuchabschnitt:

1

85.1.46.1.1. Name

pepsi-settings - Konfigurations-Überschreibungen pro Adresse setzen, auflisten und entfernen.

85.1.46.1.2. Übersicht

pepsi-settings [GLOBAL-OPTIONS] set ADDRESS STAGE OPTION VALUE

pepsi-settings [GLOBAL-OPTIONS] unset ADDRESS STAGE [OPTION]

pepsi-settings [GLOBAL-OPTIONS] import ADDRESS SOURCE

pepsi-settings [GLOBAL-OPTIONS] get ADDRESS

pepsi-settings [GLOBAL-OPTIONS] list [–json]

pepsi-settings [GLOBAL-OPTIONS] remove ADDRESS

85.1.46.1.3. Beschreibung

pepsi-settings ist das Operator-Werkzeug für die Tabelle pepsi.settings, die es erlaubt, die Optionen einer Stage pro E-Mail-Adresse zu überschreiben. Eine Stage liest ihre Optionen normalerweise aus ihrem [stage-<name>]-Abschnitt in der Konfigurationsdatei; die Einstellungstabelle liefert Überschreibungen für Nachrichten an oder von einem bestimmten Korrespondenten, wobei der INI-Wert als Standardwert für jede Option dient, die die Überschreibung nicht nennt.

Jeder Datensatz bildet eine kleingeschriebene Umschlag-Adresse auf ein JSON-Objekt ab, dessen oberste Schlüssel Stage-Abschnittsnamen (stage-<name>) sind und dessen Werte Objekte von OPTION zu Wert sind. Für eine gegebene Nachricht ist die relevante Adresse der Umschlag-Absender, wenn die Nachricht lokal entsteht (state.local_origin), sonst ein Umschlag-Empfänger. Die Adresse wird exakt abgeglichen (kein Domain- oder Subadress-Rückfall).

Wenn die Empfänger einer eingehenden Nachricht auf unterschiedliche wirksame Konfigurationen für die gleich laufende Stage auflösen — ob der Unterschied nun aus dieser Tabelle oder aus einem domain:/address:-Geltungsbereich der Datenbank-Überlagerung stammt —, teilt die Pipeline die Nachricht transparent in einen Datensatz je eigener Konfiguration auf, sodass jeder Empfänger unter seinen eigenen Einstellungen verarbeitet wird; siehe pepsi-dispatch(1).

Dieses Werkzeug ist keine Stage. Es verbindet sich über den gemeinsamen [pepsi-postgres]-Abschnitt mit derselben Datenbank wie die anderen Komponenten und führt keine eigene Konfiguration ein. Als root gestartet, läuft es als Dienstkonto pepsi weiter; siehe Ausführung als root.

85.1.46.1.3.1. Verhältnis zur Konfigurations-Überlagerung in der Datenbank

Die Tabelle pepsi.settings ist die oberste Schicht der Geltungsbereichskette, die in pepsi.conf(5) beschrieben ist:

configuration file  <  global  <  domain:<d>  <  address:<a>  <  pepsi.settings

Die drei mittleren Schichten leben in einer anderen Tabelle, pepsi.config_override, und werden mit pepsi-config(1) verwaltet. Die beiden sind bewusst nicht zusammengelegt:

  • Diese Tabelle wird von den Kontoinhabern selbst geschrieben, aus ihrem eigenen Postfach, über pepsi-stage-edit-settings(1), beschränkt auf die Stage-Abschnitte, die der Operator erlaubt hat;

  • config_override definiert die Pipeline und ist nur über die PostgreSQL-Rolle pepsi-config beschreibbar, die keine Komponente hält, die Mail verarbeitet.

Sie getrennt zu halten ist eine Sicherheitsgrenze und keine Verdopplung: In einer einzigen Tabelle hörte ein Fehler in der Namensraumprüfung pro Adresse auf, ein Leck bei Überschreibungen zu sein, und würde zu einem Benutzer, der den Mailserver umkonfiguriert. pepsi-setup(1) verifiziert die Berechtigungen nach jeder Installation gegen die laufende Datenbank.

Wo beide Mechanismen dieselbe Option für dieselbe Nachricht benennen, gewinnt diese Tabelle — sie ist die höhere Schicht, und was sie anfassen darf, ist bereits durch die EDITABLE_STAGES-Positivliste des Operators begrenzt.

Die Prüfungen, die pepsi-stage-edit-settings(1) auf die eigenen Entscheidungen eines Kontoinhabers anwendet, finden dort statt, wenn der Inhaber schreibt, nicht wenn eine Stage den Datensatz liest – eine Stage kann nicht erkennen, wer ihn geschrieben hat. Dieses Werkzeug gehört dem Operator und unterliegt ihnen nicht: Es darf zum Beispiel WHITELIST_NAME von pepsi-stage-auto-whitelist(1) oder pepsi-stage-secretary(1) für eine Adresse auf eine gemeinsame Whitelist zeigen lassen, die ein Inhaber nicht selbst wählen darf. Ein Inhaber, der diese Stage später per Mail bearbeitet, behält den gespeicherten Wert, sofern er ihn nicht ändert.

85.1.46.1.4. Befehle

set ADDRESS STAGE OPTION VALUE

Setzt eine Optionsüberschreibung. STAGE ist das Stage-Etikett (z. B. check-whitelist; ein führendes stage- wird akzeptiert und ist optional) und wird als Abschnittsschlüssel stage-<name> gespeichert; eine Stage ohne einen solchen Abschnitt in der Konfiguration wird verweigert. VALUE wird als Zeichenkette gespeichert; die Stage parst sie genau so, wie sie den entsprechenden INI-Wert parsen würde (ein Boolean verwendet also YES/NO, eine Zahl ihre Ziffern usw.). Der Datensatz und der Stage-Abschnitt werden bei Bedarf angelegt.

unset ADDRESS STAGE [OPTION]

Entfernt eine OPTION aus dem STAGE-Abschnitt der Adresse. Bei weggelassenem OPTION wird der ganze Stage-Abschnitt entfernt. Ein geleerter Abschnitt und dann ein geleerter Datensatz werden automatisch verworfen.

import ADDRESS SOURCE

Ersetzt das gesamte Einstellungsobjekt der Adresse durch das aus der Datei SOURCE gelesene JSON, oder aus der Standardeingabe, wenn SOURCE - ist. Das JSON muss ein Objekt sein, dessen Schlüssel stage-<name>-Abschnittsnamen und dessen Werte Objekte aus JSON-Skalaren (Zeichenkette, Zahl oder Boolean) sind; die Abschnittsschlüssel werden in Kleinbuchstaben umgewandelt.

get ADDRESS

Gibt das Einstellungsobjekt der Adresse als formatiertes JSON aus, oder einen Hinweis, wenn keines existiert.

list [–json]

Listet alle Datensätze auf. Die Standardausgabe ist eine address<TAB>JSON-Zeile pro Datensatz; –json gibt stattdessen ein JSON-Array von {address, settings}-Objekten aus.

remove ADDRESS

Löscht den Einstellungs-Datensatz der Adresse vollständig.

85.1.46.1.5. Validierung

pepsi-setup(1) validiert die Tabelle nach der Installation des Schemas: Jeder Schlüssel der obersten Ebene muss einen existierenden [stage-<name>]-Abschnitt benennen, und jeder Optionswert muss ein JSON-Skalar (Zeichenkette, Zahl oder Boolean) sein. Eine Überschreibung, die auf einen falsch geschriebenen Stage-Abschnitt verweist, wird als Fehler gemeldet statt stillschweigend ignoriert.

85.1.46.1.6. Ausführung als root

Pepsi gibt jeder Komponente ihre eigene PostgreSQL-Rolle, die über den lokalen Socket durch das Betriebssystemkonto authentifiziert wird, unter dem sie läuft, und root gehört bewusst nicht dazu. Statt den Verbindungsaufbau scheitern zu lassen und Sie zu zwingen, an sudo -u pepsi pepsi-settings … zu denken, erkennt das Werkzeug, dass es als root gestartet wurde, und wird zum unprivilegierten Dienstkonto pepsi — dem Konto, unter dem das Stage-Gerüst pepsi.settings konsultiert —, bevor es sich verbindet.

Alles, was vor der Verbindung geschieht, geschieht weiterhin als aufrufender Benutzer: Die Konfigurationsdatei (mitsamt jedem @inline-secret@-Fragment) wird zuerst gelesen, ebenso das an import übergebene JSON-Dokument, sodass ein nur für root lesbarer Quellpfad funktioniert.

Existiert das Konto pepsi nicht — ein nicht installierter Quellbaum, ein Testaufbau —, bleibt die Identität unangetastet, es wird eine Warnung protokolliert und die Verbindung als aufrufender Benutzer versucht, sodass eine Installation, in der root die Datenbank erreichen kann, weiterhin funktioniert.

85.1.46.1.7. 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 das Flag, gilt die globale Option [pepsi] LOG, und ersatzweise 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.46.1.8. Exit-Status

0

Erfolgreicher Abschluss.

1

Ein Fehler ist aufgetreten: eine fehlerhafte Konfigurationsdatei, ungültiges JSON, eine fehlgeschlagene Datenbankverbindung oder -abfrage oder eine Stage ohne [stage-<name>]-Abschnitt. Der Grund wird in das Log geschrieben.

2

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

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

Keine andere Datei wird gelesen oder geschrieben: Jede Überschreibung liegt in der Tabelle pepsi.settings.

85.1.46.1.10. Beispiele

Mail an vip@example.com über eine andere weiße Liste senden:

pepsi-settings -c /etc/pepsi/pepsi.conf set vip@example.com check-whitelist WHITELIST_NAME vips

Eine andere Menge von Sprachen für einen Empfänger blockieren:

pepsi-settings -c /etc/pepsi/pepsi.conf set bob@example.org block-language BLACKLIST 'ru,zh'

Die Überschreibungen eines Empfängers inspizieren und dann löschen:

pepsi-settings -c /etc/pepsi/pepsi.conf get bob@example.org
pepsi-settings -c /etc/pepsi/pepsi.conf unset bob@example.org block-language BLACKLIST

Ein ganzes Objekt aus einer Datei laden:

pepsi-settings -c /etc/pepsi/pepsi.conf import vip@example.com /tmp/vip.json

85.1.46.1.11. Siehe auch

pepsi-config(1), pepsi-dispatch(1), pepsi-stage-check-whitelist(1), pepsi-stage-block-language(1), pepsi-stage-edit-settings(1), pepsi.conf(5), pepsi-setup(1)

85.1.46.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.