85.1.33. pepsi-stage-edit-settings

change per-address settings from a control e-mail

Handbuchabschnitt:

1

85.1.33.1.1. Name

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

85.1.33.1.2. Übersicht

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

85.1.33.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 diesen pepsi.workqueue-Datensatz (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.

Die Entscheidung, ob eine Nachricht eine Steuernachricht ist — lokal erzeugt, das richtige Subject, an den Steuer-Local-Part bei einer akzeptierten Domain adressiert — benötigt nur die Nachrichten-Metadaten, nie 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 (die sie einfach weiterschaltet), lehnt die Fusion aber für eine echte Steuernachricht ab, die dann committet und als eigener Worker ausgeführt wird, sodass 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 Operators muss daher den Umschlagabsender binden; andernfalls könnte ein authentifizierter Benutzer die Einstellungen einer anderen Adresse bearbeiten.)

85.1.33.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 wird eine Zuweisung, die das PROGRAM einer Stage setzt, nur akzeptiert, wenn ihr Wert ein pepsi-stage-*-Befehl ist (ohne Pfadkomponente), sodass ein Kontoinhaber eine Stage nicht auf eine beliebige ausführbare Datei umlenken kann; und eine Zuweisung, die SIGNING_DOMAIN setzt, wird rundweg abgelehnt, wie freizügig EDITABLE_STAGES auch ist. Diese Option überschreibt die Domain, als die eine Nachricht DKIM-signiert wird; sie zuzulassen ließe jeden Kontoinhaber seine Mail als jede Domain signieren, für die dieser Host einen Schlüssel hält. Das Setzen von UNRESTRICTED_UNSAFE_STAGES = YES in der Konfiguration der Stage hebt beide 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 und den Abwesenheitsbeantworter auf, und wo keine davon aktiviert ist, konfiguriert er diese Stage überhaupt nicht.

Die resultierenden kombinierten Einstellungen — die INI-Standardwerte plus die bestehenden Überschreibungen der Adresse plus die neuen Zuweisungen — werden validiert, indem der eigene Konfigurationsparser jeder betroffenen Stage ausgeführt wird, dazu die Prüfungen, die nur für die eigene Wahl eines Kontoinhabers gelten: Das WHITELIST_NAME einer Stage, die im Auftrag des Inhabers eine Whitelist schreibt – 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 –, muss eine Whitelist im eigenen Namensraum <login>/... des Absenders benennen oder die, die die Konfiguration des Operators 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 Operators 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, sodass ein bereits im Datensatz gespeicherter Wert – den der Operator mit pepsi-settings(1) gesetzt haben kann – den Inhaber nicht daran hindert, 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 Operators (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 Operators 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 (PASSWORD, PASSPHRASE, SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER), werden durch *** ersetzt — dieselbe 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.

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

Die rahmende Prosa beider Antworten ist lokalisiert: Sie wird aus der vom Operator 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). Die {{#success}} / {{^success}}-Zweige der Vorlage rahmen jeweils das Echo der effektiven Einstellungen und die Problemliste.

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

85.1.33.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 — ebenfalls 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.

85.1.33.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 → 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.

85.1.33.1.7. Befehle

worker

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

85.1.33.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 info).

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen.

-h, –help; -V, –version

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

85.1.33.1.9. Exit-Status

0

Die Nachricht wurde verarbeitet (durchgeleitet oder mit einer Antwort angewendet/abgelehnt).

1

Ein Fehler ist aufgetreten (Nachricht nicht gefunden oder nicht running). Der Grund wird in das Log geschrieben.

Ein Fehler des Hosts (die Datenbank, eine Vorlage oder ein Helfer, die sich nicht verwenden lassen) wird nicht als Fehlschlag gemeldet: Die Nachricht wird pausiert und erneut versucht, wie unter Stage-Fehler in pepsi-dispatch(1) beschrieben. Ein Abschnitt, der sich nicht parsen lässt, lässt den Worker den Start verweigern (Status 78), statt eine Nachricht nach der anderen fehlschlagen zu lassen.

85.1.33.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 =

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

85.1.33.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.