95.1.52. pepsi-settings

manage per-address stage option overrides

Handbuchabschnitt:

1

95.1.52.1.1. Name

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

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

95.1.52.1.3. Beschreibung

pepsi-settings ist das Betreiberwerkzeug 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 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), in kanonischer Form: Das Werkzeug speichert ADDRESS und vergleicht die Adresse jeder Nachricht, beides nach Unicode-Normalisierung (NFC), Case-Folding des Local Part und Umwandlung der Domain in ihr A-Label. René@Bücher.example und reneU+0301@xn--bcher-kva.example sind daher ein Datensatz (siehe das Sicherheitskapitel des Handbuchs, „Addresses are compared in one form“).

Die Empfänger einer eingehenden Nachricht können auf unterschiedliche wirksame Konfigurationen für die Stage auflösen, die gleich laufen wird. Der Unterschied kann aus dieser Tabelle stammen oder aus einem domain:/address:-Geltungsbereich der Datenbank-Überlagerung. In diesem Fall 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.

95.1.52.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 Betreiber 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. Lägen beide in einer einzigen Tabelle, würde ein Fehler in der Namensraumprüfung pro Adresse nicht bloß eine Überschreibung durchsickern lassen: Er würde einem Benutzer erlauben, den Mailserver umzukonfigurieren. 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 die EDITABLE_STAGES-Positivliste des Betreibers begrenzt bereits, was sie anfassen darf.

pepsi-stage-edit-settings(1) prüft die eigenen Entscheidungen eines Kontoinhabers, wenn der Inhaber sie schreibt, nicht wenn eine Stage den Datensatz liest, denn eine Stage kann nicht erkennen, wer ihn geschrieben hat. Dieses Werkzeug gehört dem Betreiber und unterliegt diesen Prüfungen 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.

Was eine Überschreibung nicht kann: PROGRAM, das Standard-NEXT_STAGE und BOUNCE_STAGE einer Stage werden aus der Konfiguration des Betreibers genommen, bevor die Überschreibungen angewendet werden, sodass eine Überschreibung davon keine Wirkung hat. Jede andere Option, die die Stage aus ihrem eigenen Abschnitt liest, wird überschrieben, auch ihre Verzweigungsziele (TRUE_STAGE, QUARANTINE_STAGE, RESPONSE_STAGE …).

Überschreibungen gehören einem Inhaber eines Logins: Stellt sich heraus, dass ein Login jemand anderem gegeben wurde (eine neue uid, oder wieder vorhanden, nachdem es fort war), werden die Datensätze des vorherigen Inhabers für die Adressen dieses Logins verworfen, bevor die Mail des neuen Inhabers zugestellt wird. Die Sicherheitsgrenze, die diese Tabelle bildet, wird im Kapitel Threat model (adressbezogene Einstellungen) und im Kapitel Security des Handbuchs beschrieben.

Jede Änderung, die dieses Werkzeug vornimmt (set, unset, import, remove), wird im gemeinsamen Audit-Log (pepsi.event_log) mit der Adresse und der berührten Option festgehalten, aber nicht mit dem Wert, da eine Überschreibung ein Zugangsdatum nennen kann. Änderungen, die ein Kontoinhaber per E-Mail vornimmt, werden nicht protokolliert.

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

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

95.1.52.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 die Komponente 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, bevor es sich verbindet. Unter diesem Konto lesen die Stages pepsi.settings.

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 (in einem nicht installierten Quellbaum oder einem 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.

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

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

78

Das Datenbankschema gehört zu einem anderen Pepsi-Release (nicht installiert, älter, neuer oder verändert); führen Sie pepsi-setup schema aus (siehe pepsi-setup(1)).

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

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

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

95.1.52.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.