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_overridedefiniert die Pipeline und ist nur über die PostgreSQL-Rollepepsi-configbeschreibbar, 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ührendesstage-wird akzeptiert und ist optional) und wird als Abschnittsschlüsselstage-<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 alsoYES/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üsselstage-<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,debugodertrace. Fehlt das Flag, gilt die globale Option[pepsi] LOG, und ersatzweiseinfo.- -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 schemaaus (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.