95.1.34. pepsi-stage-edit-settings

change per-address settings from a control e-mail

Handbuchabschnitt:

1

95.1.34.1.1. Name

pepsi-stage-edit-settings - die Einstellungen-per-E-Mail-Stage der Pepsi-Pipeline.

95.1.34.1.2. Übersicht

pepsi-stage-edit-settings [GLOBAL-OPTIONS] worker

95.1.34.1.3. Beschreibung

pepsi-stage-edit-settings ist ein Stage-Programm, das von pepsi-dispatch(1) als persistenter Worker ausgeführt wird, der Nachrichten-IDs von der Standardeingabe liest. Es lädt den pepsi.workqueue-Datensatz der Nachricht (und weigert sich zu handeln, sofern sein status nicht running ist), liest seinen [stage-<stage>]-Abschnitt und entscheidet, ob die Nachricht eine Einstellungs-Steuernachricht ist, die ein Kontoinhaber gesendet hat, um seine eigenen Einstellungen pro Adresse zu ändern (die in pepsi-settings(1) beschriebenen pepsi.settings-Überschreibungen).

Eine Nachricht ist nur dann eine Steuernachricht, wenn alles davon zutrifft:

  • sie ist lokal eingeliefert (state.local_origin ist true) und hat einen nicht leeren Umschlagabsender (eine Null-Absender-Nachricht ist nie eine Steuernachricht);

  • ihr Subject: ist genau SUBJECT (Standardwert Pepsi); und

  • einer ihrer Umschlagempfänger ist <CONTROL_LOCAL_PART>@<domain> (Standard-Local-Part pepsi) für eine domain, die die Instanz akzeptiert ([pepsi-ingress] ACCEPTED_DOMAINS).

Jede andere Nachricht wird unverändert zu NEXT_STAGE weitergeschaltet, sodass die Stage gefahrlos überall auf dem lokalen Submission-Pfad platziert werden kann. Eine Steuernachricht, die auch gewöhnliche Empfänger hat, wird zuerst aufgeteilt: Die Steueradresse wandert auf eine eigene Zeile, und die übrigen gehen als gewöhnliche Mail weiter.

Ob eine Nachricht eine Steuernachricht ist (lokal erzeugt, mit dem richtigen Subject, an den Steuer-Local-Part bei einer akzeptierten Domain adressiert), lässt sich allein aus den Metadaten der Nachricht entscheiden, ohne den Nachrichtentext. Diese Stage nimmt daher an der Stage-Fusion teil (siehe pepsi-dispatch(1)), mit einer datenabhängigen Schranke. Ihr Standardwert ist FUSION = yes, und ein Vorgänger fusioniert sie für jede Nicht-Steuernachricht im selben Prozess; diese Nachrichten schaltet sie einfach weiter. Für eine echte Steuernachricht lehnt die Stage die Fusion ab: Die Nachricht wird committet und an einen Worker dieser Stage übergeben, damit der vollständige Nachrichtentext zum Parsen geladen wird. Setzen Sie FUSION = no, um sie abzuwählen.

Die Adresse, deren Einstellungen bearbeitet werden, ist der Umschlagabsender: Der Inhaber bearbeitet seine eigenen Einstellungen, und die Antwort wird an ihn zurückgemailt. (Die Submission-Authentifizierung des Betreibers muss daher den Umschlagabsender binden; andernfalls könnte ein authentifizierter Benutzer die Einstellungen einer anderen Adresse bearbeiten. pepsi-ingress(1) bindet ihn für SASL- und Local-Socket-Logins über USERNAME_MAP; ein MYNETWORKS-Netz oder ein gepinntes Client-Zertifikat wird nur gebunden, wenn SENDER_MAP es nennt.)

95.1.34.1.4. Der Nachrichtentext

Der Nachrichtentext wird als nachsichtiges INI-Snippet gelesen: [stage-<name>]-Abschnittsüberschriften und OPTION = value-Zuweisungen. Leerzeilen, Kommentare (#/%/;), eine führende Begrüßung und eine nachgestellte Signatur (eine ---Zeile) werden ignoriert, sodass eine gewöhnliche E-Mail, die die Konfiguration enthält, funktioniert. Jede Zuweisung fügt die gespeicherte Überschreibung für die Option dieser Stage hinzu oder übersteuert sie; eine Zuweisung, deren Wert leer ist (OPTION =), entfernt die Überschreibung und setzt die Option auf ihren INI-Standardwert zurück.

Nur Abschnitte, deren Stage-Name in EDITABLE_STAGES erscheint, dürfen geändert werden; ein Nachrichtentext, der einen anderen Abschnitt anspricht, wird abgelehnt.

Aus Sicherheitsgründen sind drei Arten von Zuweisungen eingeschränkt:

  • eine Zuweisung, die das PROGRAM einer Stage setzt, wird nur akzeptiert, wenn ihr Wert ein pepsi-stage-*-Befehl ist (ohne Pfadkomponente), damit ein Kontoinhaber eine Stage nicht auf eine beliebige ausführbare Datei umlenken kann;

  • eine Zuweisung, die eine Option setzt, die ein von der Stage oder einem setuid-Werkzeug ausgeführtes Programm benennt, wird abgelehnt, sofern ihr Wert nicht leer ist; ein leerer Wert stellt nur die Einstellung des Betreibers wieder her. Diese Optionen sind HELPER (was eine Zustell-Stage mit ihrem setgid-Privileg ausführt), SCAN_HELPER, MAILBOX_HELPER und PIN_COMMAND;

  • eine Zuweisung, die eine Identitätsoption (SIGNING_DOMAIN, WALLET_MODE, WALLET_SCOPE oder WALLET_USER) oder ein Ausgabelimit (MAX_TOTAL oder MAX_TOTAL_PER_DAY) setzt, wird rundweg abgelehnt, wie freizügig EDITABLE_STAGES auch ist.

SIGNING_DOMAIN überschreibt die Domain, als die eine Nachricht DKIM-signiert wird. Ließe die Stage diese Option zu, könnte jeder Kontoinhaber seine Mail als jede Domain signieren lassen, für die dieser Host einen Schlüssel hält. Die Wallet-Optionen wählen, aus wessen Wallet pepsi-stage-auto-pay(1) zahlt; ließe die Stage sie zu, könnte ein Kontoinhaber aus einer mit anderen geteilten Wallet ausgeben. Die Ausgabelimits begrenzen, was ein gestohlenes Submission-Passwort anrichten kann. Dieses Passwort authentifiziert auch die Steuernachricht; dürfte man die Limits ändern, könnte der Dieb die Grenze also aufheben. Das Setzen von UNRESTRICTED_UNSAFE_STAGES = YES in der Konfiguration der Stage hebt alle diese Beschränkungen auf (unsicher; der Standardwert ist NO).

Aus demselben Grund setzt pepsi-setup --wizard nie eine signierende Stage in EDITABLE_STAGES: Er führt nur die eingehenden Schranken, den Abwesenheitsbeantworter und den Schalter für entfernte Inhalte (pepsi-stage-defang(1)) auf, und wo keine davon aktiviert ist, konfiguriert er diese Stage überhaupt nicht.

Die Stage kombiniert die INI-Standardwerte, die bestehenden Überschreibungen der Adresse und die neuen Zuweisungen und validiert das Ergebnis, indem sie den eigenen Konfigurationsparser jeder betroffenen Stage ausführt. Hinzu kommen die Prüfungen, die nur für die eigene Wahl eines Kontoinhabers gelten. Zwei Stages schreiben im Auftrag des Inhabers eine Whitelist: pepsi-stage-auto-whitelist(1), das die Empfänger seiner ausgehenden Mail festhält, und pepsi-stage-secretary(1), das die Absender festhält, die eine Challenge beantworten. Das WHITELIST_NAME einer solchen Stage muss eine Whitelist im eigenen Namensraum <login>/... des Absenders benennen oder die, die die Konfiguration des Betreibers bereits für ihn benennt; eine gemeinsame Whitelist oder die eines anderen Benutzers wird zurückgewiesen. Der Login wird mit den Lokalitätsoptionen (LOCAL_DOMAINS, RECIPIENT_DELIMITER, TARGETS) des Stage-Abschnitts des Betreibers aufgelöst, nicht mit einer Überschreibung des Inhabers selbst. Die Regel gilt nur, wenn die Nachricht die Whitelist ändert, in die die Mail des Absenders einfließt. Ein bereits im Datensatz gespeicherter Wert, den der Betreiber mit pepsi-settings(1) gesetzt haben kann, hindert den Inhaber daher nicht daran, andere Optionen zu bearbeiten. Diese Stage ist der einzige Weg, auf dem ein Kontoinhaber pepsi.settings schreiben kann, daher wird die Regel hier durchgesetzt; die eigenen Schichten des Betreibers (die INI-Datei, pepsi.config_override in jedem Geltungsbereich und mit pepsi-settings(1) geschriebene Datensätze) dürfen jede Whitelist benennen. Die Einstellungen werden auf Grundlage der Konfiguration des Betreibers für den Absender beurteilt, einschließlich der domain:- und address:-Überschreibungen von pepsi.config_override, und die Antwort zitiert genau diese effektive Konfiguration. Ist irgendetwas ungültig, wird keine Änderung vorgenommen, und eine für Menschen lesbare Antwort erläutert jedes Problem. Ist alles gültig, werden die zusammengeführten Überschreibungen gespeichert, und eine Antwort zitiert den vollständigen effektiven Optionssatz (Standardwerte plus Überschreibungen) jeder bearbeitbaren Stage in INI-Syntax.

Von einer in EDITABLE_STAGES aufgeführten Stage wird die gesamte effektive Konfiguration an jeden Kontoinhaber zurückzitiert, der eine Steuernachricht sendet, nicht nur die von ihm geänderten Optionen. Optionswerte, deren Namen nach Zugangsdaten aussehen (die PASS, SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER oder SYSTEM_ID enthalten, also auch PASSWORD und PASSPHRASE), werden durch *** ersetzt, mit derselben Maskierung, die GET /api/v1/config anwendet. Der Rest des Abschnitts jedoch, einschließlich Hostnamen und Dateipfaden, wird wortgetreu offengelegt. Führen Sie keine Stage auf, deren Abschnitt etwas trägt, das Sie einem lokalen Benutzer nicht zeigen würden. Welche Stages überhaupt sicher aufgeführt werden können, ist unter der Einstellungsgrenze im Kapitel Threat model des Handbuchs (tm-settings) und in seinem Kapitel Security dargelegt.

Beide Antworten tragen Subject: SUBJECT und den Null-Umschlagabsender <> (RFC 3834, damit sie nie selbst an einer Schranke aufgehalten werden oder einen Bounce erhalten). Sie werden bei RESPONSE_STAGE injiziert, wo sie DKIM-signiert und wie jede ausgehende Mail weitergeleitet werden. Die Steuernachricht selbst wird dann entfernt.

Die rahmende Prosa beider Antworten ist lokalisiert: Sie wird aus der vom Betreiber anpassbaren edit-settings.<lang>.body-Mustache-Vorlage unter [pepsi] TEMPLATE_DIR gerendert, wobei <lang> aus der/den erkannten Sprache(n) des Absenders gewählt wird (die state.language-Accept-Language-Zeichenkette, die von pepsi-stage-detect-language gesetzt wird), und stets auf Englisch zurückfällt (edit-settings.en.body). In der Vorlage rahmt der Zweig {{#success}} die zitierten effektiven Einstellungen und der Zweig {{^success}} die Problemliste.

Diese Stage lädt den Nachrichtentext, verändert ihn aber nicht.

95.1.34.1.5. Konfiguration

Die Optionen liegen im eigenen [stage-<name>]-Abschnitt der Stage (PROGRAM = pepsi-stage-edit-settings): die erforderliche EDITABLE_STAGES-Positivliste (die mindestens eine existierende Stage benennen muss), das erforderliche RESPONSE_STAGE, bei dem die Antwort injiziert wird, und ein NEXT_STAGE für gewöhnliche Mail. Auch NEXT_STAGE ist erforderlich, da pepsi-setup(1) einen Abschnitt ohne ein solches ablehnt: Jede Nicht-Steuernachricht wird dorthin weitergeschaltet. Die optionalen Steuerparameter SUBJECT/CONTROL_LOCAL_PART/RESPONSE_FROM und der UNRESTRICTED_UNSAFE_STAGES-Sicherheitsschalter vervollständigen den Abschnitt. Sie sind in pepsi.conf(5) dokumentiert.

Die Stage liest ihren eigenen Abschnitt aus der Basis-Konfiguration, nie über die Überschreibungsschicht je Adresse, sodass kein pepsi.settings-Datensatz eines Kontoinhabers ändern kann, was diese Stage für eine Steuernachricht hält oder was sie zulässt.

95.1.34.1.6. State

Eingaben: state.local_origin (steuert, ob die Nachricht eine Steuernachricht ist), state.language (wählt die Sprache der Antwort) sowie der Umschlagabsender/die Umschlagempfänger und der Subject:-Header.

Ausgaben: Die Stage schreibt den pepsi.settings-Datensatz des Umschlagabsenders um und injiziert eine Antwort; sie verändert das state der ursprünglichen Nachricht nicht (die sie entfernt). Das State-Layout wird in pepsi.state(7) beschrieben.

Übergänge:

  • eine gewöhnliche Nachricht (nicht lokal erzeugt oder nicht auf SUBJECT / CONTROL_LOCAL_PART passend) → unverändert zu NEXT_STAGE weiterschalten;

  • eine Steuernachricht mit weiteren Empfängern → die Steueradressen auf eine eigene Zeile aufteilen, und beide Zeilen kehren zu dieser Stage zurück;

  • eine Steuernachricht → die Antwort (das INI-Echo bei Erfolg oder der Fehler bei einer abgelehnten/ungültigen Bearbeitung) bei RESPONSE_STAGE injizieren und abschließen (der ursprüngliche Datensatz wird gelöscht).

Die Stage pausiert nie, schlägt nie fehl und leitet nie um.

Die Bestätigung wird vor dem Speichern der neuen Einstellungen gerendert, sodass eine fehlende Antwortvorlage erneut versucht wird, ohne dass sich etwas geändert hat. Sobald sie gespeichert sind, wird eine Antwort, die nicht eingereiht werden kann, protokolliert und die Anfrage gelöscht: Die Änderung ist vorgenommen und darf nicht noch einmal vorgenommen werden.

95.1.34.1.7. Befehle

worker

Läuft als persistenter pepsi-dispatch(1)-Worker, der Nachrichten-IDs von der Standardeingabe liest.

95.1.34.1.8. Globale Optionen

-c FILE, –config FILE

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

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit (Standardwert [pepsi] LOG, sonst info).

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen.

-h, –help; -V, –version

Gibt eine Verwendungsübersicht / die Version aus und beendet sich.

95.1.34.1.9. Exit-Status

Das Ergebnis jeder Nachricht wird pepsi-dispatch(1) auf der Statuszeile des Workers gemeldet, nicht als Exit-Status.

0

Der Worker lief, bis seine Standardeingabe geschlossen wurde.

1

Ein fataler Fehler ist aufgetreten (unlesbare Konfiguration, die Datenbank konnte nicht geöffnet werden, oder Standardein-/-ausgabe schlug fehl). Der Grund wird in das Journal geschrieben.

78

Der Worker hat den Start verweigert: Ein [stage-*]-Abschnitt, den er bedient, lässt sich nicht parsen (z. B. ein fehlendes EDITABLE_STAGES oder RESPONSE_STAGE). Der Dispatcher reiht erneut ein, was er übergeben hatte, und versucht die Stage später wieder.

Ein Fehler des Hosts (die Datenbank, eine Antwortvorlage, die sich nicht verwenden lässt) wird nicht als Fehlschlag gemeldet: Die Nachricht wird pausiert und erneut versucht, wie unter Stage-Fehler in pepsi-dispatch(1) beschrieben.

95.1.34.1.10. Beispiele

Ein Pipeline-Abschnitt, der Inhabern erlaubt, ihre Whitelist und Sprachrichtlinie zu bearbeiten, mit Antwort über den ausgehenden Pfad:

[stage-edit-settings]
PROGRAM = pepsi-stage-edit-settings
EDITABLE_STAGES = check-whitelist, block-language
RESPONSE_STAGE = dkim-sign
NEXT_STAGE = srs

Ein Steuer-E-Mail-Nachrichtentext (Subject: Pepsi, To: pepsi@example.org), der eine Whitelist setzt und eine Sprach-Blacklist löscht:

[stage-check-whitelist]
WHITELIST_NAME = my-contacts

[stage-block-language]
BLACKLIST =

95.1.34.1.11. Siehe auch

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

95.1.34.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.