85.1.18. pepsi-stage-aliases

expand message recipients through an alias mapping file

Handbuchabschnitt:

1

85.1.18.1.1. Name

pepsi-stage-aliases - die Alias-/Mailinglisten-Expansions-Stage der Pepsi-Pipeline.

85.1.18.1.2. Übersicht

pepsi-stage-aliases [GLOBAL-OPTIONS] worker

85.1.18.1.3. Beschreibung

pepsi-stage-aliases ist ein Stage-Programm, das von pepsi-dispatch(1) ausgeführt wird. Es lädt einen pepsi.workqueue-Datensatz (und weigert sich zu handeln, sofern sein status nicht running ist), liest seinen [stage-<stage>]-Abschnitt und schreibt die Umschlagempfänger der Nachricht über die von ALIASES benannte Alias-Map um. Jeder Empfänger, der auf einen Eintrag in der Map passt, wird durch die Zieladressen dieses Eintrags ersetzt; Empfänger, die auf nichts passen, bleiben unverändert. Die resultierende Empfängerliste wird ohne Rücksicht auf Groß-/Kleinschreibung dedupliziert, sodass jede Adresse höchstens einmal zugestellt wird, und die Nachricht wird zu NEXT_STAGE weitergeschaltet.

Die Stage lädt nur den Umschlag und state — nie die Header oder den Nachrichtentext. Wenn kein Empfänger auf die Map passt (und kein Duplikat entfernt wird), wird die Nachricht unverändert weitergeschaltet.

85.1.18.1.4. Alias-Datei

ALIASES benennt eine menschenlesbare Zuordnungsdatei, die wie eine Postfix-virtual(5)-Tabelle geparst wird. Jede nicht-leere Zeile bildet einen Schlüssel auf eine oder mehrere Ziel-Adressen ab:

# comments begin with '#'; blank lines are ignored
postmaster@example.com   alice@example.com
staff@example.com        bob@example.com, carol@partner.example
@example.net             ops@example.com
sales-*@example.org      sales@example.com

Der Schlüssel (linke Seite) ist das erste durch Leerraum getrennte Feld: eine Volladresse, ein @domain-Catch-All oder ein *-Wildcard-Muster (ein *-Glob wie *@example.org oder sales-*@example.org). Die Ziele (rechte Seite) sind durch Kommas und/oder Leerraum getrennt und werden wörtlich beibehalten — sie können lokal oder entfernt sein, dürfen aber keine Wildcard enthalten. Eine Zeile mit einem Schlüssel, aber ohne Ziele wird ignoriert (ein Empfänger wird nie stillschweigend gelöscht). Erscheint derselbe Schlüssel zweimal, gewinnt die spätere Zeile.

Wie in virtual(5) setzt eine Zeile, deren erstes Zeichen ein Leerraumzeichen ist, die vorherige Zuordnung fort, statt eine neue zu beginnen, sodass eine lange Zielliste über mehrere Zeilen umbrochen werden darf; dazwischenliegende leere und reine Kommentarzeilen unterbrechen eine solche Fortsetzung nicht. Ein # beginnt einen Kommentar nur am Anfang eines Feldes (am Zeilenanfang oder nach Leerraum), sodass bug#42@example.com ein gewöhnlicher Schlüssel ist und kein abgeschnittener.

Warnung

Wildcards sind Globs, keine regulären Ausdrücke. * passt auf jede Folge von Zeichen, und jedes andere Zeichen — ein . eingeschlossen — ist wörtlich zu nehmen. Um eine ganze Domain zu aliasen, schreiben Sie *@example.net (oder den @example.net-Catch-All); .*@example.net ist ein regulärer Ausdruck und verlangt, als Glob gelesen, einen führenden Punkt, passt also auf keine reale Adresse, und jede Nachricht an diese Domain fällt unaliasiert durch. (Die pepsi.whitelist-Muster von pepsi-whitelist(1) sind POSIX-EREs; diese Map ist es nicht.) Sowohl die Syntaxprüfung von pepsi-setup als auch der eigene Map-Parser der Stage lehnen einen regex-artigen Schlüssel ab bzw. markieren ihn und nennen den Glob, den Sie wahrscheinlich gemeint haben.

Die Datei wird in den Speicher gelesen und nur dann neu gelesen, wenn ihre Identität sich ändert — Änderungszeit, Größe und Inode, sodass auch ein Ersetzen unter Beibehaltung der Änderungszeit (cp -p, eine zurückgespielte Sicherung) bemerkt wird —, und ein ausgelasteter Worker parst sie daher nicht für jede Nachricht neu. Eine fehlende Datei ist eine leere Map (keine Aliase konfiguriert). Eine Datei, die existiert, aber nicht gelesen werden kann (Berechtigungen, ein E/A-Fehler), ist ein Fehler: Die Nachricht wird pausiert und mit Back-off erneut versucht, wie bei jedem anderen Fehler des Hosts, statt ohne Alias-Auflösung zugestellt zu werden – ein stillschweigend nicht angewandter postmaster@- oder Catch-all-Eintrag würde sie falsch zustellen oder bouncen. Die nicht lesbare Datei wird nicht zwischengespeichert, sodass der nächste Versuch sie erneut liest. pepsi-setup prüft die ALIASES-Datei zur Installationszeit auf Syntax, wenn sie existiert, und schreibt eine kommentierte Startvorlage, wenn nicht (siehe pepsi-setup(1)); eine fehlerhafte Zeile wird dort vor der Installation als Warnung gemeldet statt erst zur Laufzeit, nie aber als fataler Fehler.

85.1.18.1.5. Abgleich und Expansion

Ein Empfänger wird kleingeschrieben und wörtlich nachgeschlagen; bei einem Fehlschlag wird der @domain-Catch-All-Schlüssel für seine Domain versucht und schließlich jeder *-Wildcard-Schlüssel — die spezifischste passende Wildcard gewinnt (ein enges sales-*@example.org schlägt ein breites *@example.org, das ein bloßes * schlägt; Gleichstände werden deterministisch aufgelöst). Subadress-(+tag-)Detail wird nicht entfernt, sodass eine spezifische Listenadresse wie list+announce@example.com für sich aliasiert werden kann.

Die Expansion ist transitiv: Wenn ein Alias-Ziel selbst ein Schlüssel ist, wird es seinerseits expandiert, sodass verschachtelte Verteilerlisten zu ihren Blattadressen auflösen. Eine Schleife — ein Alias, der direkt oder über eine Kette auf sich selbst zurückverweist — wird durchbrochen, indem der wiederholte Schlüssel auf seine literale Adresse aufgelöst wird, statt ewig zu rekursieren. Eine Kette, die tiefer als 32 Hops reicht, wird auf dieselbe Weise gestoppt (an die Adresse wird literal zugestellt, mit einer Warnung), sodass eine generierte Map den Stack des Workers nicht zum Überlaufen bringen kann.

85.1.18.1.6. Zustellungsstatusbenachrichtigungen

state.dsn.rcpt ist parallel zur Empfängerliste, daher wird es im Gleichschritt mit den umgeschriebenen Empfängern neu aufgebaut. Ein expandiertes Ziel erbt das NOTIFY des ursprünglichen Empfängers, von dem es stammt, mit entferntem SUCCESS-Schlüsselwort (RFC 3461 §5.2.7.3(c): sonst zöge eine einzige Einlieferung an einen Alias mit fünf Mitgliedern fünf positive DSNs für einen Empfänger nach sich und legte die Mitgliedschaft des Alias offen; ein NOTIFY, das nur SUCCESS war, wird zu NEVER), und trägt gemäß demselben Abschnitt ein ORCPT, das auf den ursprünglichen Empfänger zeigt (sein bestehendes ORCPT, falls es eines hatte, sonst rfc822;<original-recipient>). Ein nicht expandierter Empfänger behält seinen DSN-Eintrag unverändert. RET/ENVID auf Nachrichtenebene und alle anderen state-Schlüssel bleiben erhalten.

85.1.18.1.7. Konfiguration

Die Optionen liegen im eigenen [stage-<name>]-Abschnitt der Stage (PROGRAM = pepsi-stage-aliases): der ALIASES-Map-Dateipfad und das NEXT_STAGE, zu dem die expandierte Nachricht weiterschaltet. Beide sind erforderlich — die Stage schaltet jede Nachricht weiter, die sie sieht, sodass pepsi-setup einen Abschnitt ablehnt, dem eines von beiden fehlt. Sie sind in pepsi.conf(5) dokumentiert.

85.1.18.1.8. State

Eingaben: das Umschlag-rcpt_to und das state.dsn.rcpt pro Empfänger.

Ausgaben: ein umgeschriebenes rcpt_to und ein passendes state.dsn.rcpt, nur geschrieben, wenn die Empfängerliste sich tatsächlich geändert hat (ein Alias traf zu oder ein Duplikat wurde entfernt); kein anderes state wird berührt. Das State-Layout wird in pepsi.state(7) beschrieben.

Übergänge: schaltet zu NEXT_STAGE weiter (der einzige Übergang); die Stage pausiert nie, schlägt nie fehl, leitet nie um und schließt nie ab.

85.1.18.1.9. Befehle

worker

Läuft als persistenter pepsi-dispatch(1)-Worker, der Nachrichten-IDs von der Standardeingabe liest. So führt der Dispatcher die Stage im Produktivbetrieb aus.

85.1.18.1.10. 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.18.1.11. Exit-Status

0

Die Nachricht wurde verarbeitet (zu NEXT_STAGE weitergeschaltet).

1

Ein Fehler ist aufgetreten (Nachricht nicht gefunden oder nicht running, eine fehlkonfigurierte Stage — z. B. ein fehlendes ALIASES oder NEXT_STAGE — oder ein Datenbankfehler). Der Grund wird in das Journal geschrieben. Eine fehlende Alias-Datei ist kein Fehler: Sie wird als leere Map behandelt.

85.1.18.1.12. Beispiele

Nachricht 42 über einen einmaligen Worker erneut verarbeiten (sie muss running sein):

echo 42 | pepsi-stage-aliases -c /etc/pepsi/pepsi.conf worker

Ein Pipeline-Abschnitt, direkt vor der lokalen Zustellung platziert, der Empfänger expandiert und an die Lokale-Zustellung-Stage weiterleitet:

[stage-aliases]
PROGRAM = pepsi-stage-aliases
NEXT_STAGE = local
ALIASES = /etc/pepsi/aliases

85.1.18.1.13. Siehe auch

pepsi-config(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-if(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

85.1.18.1.14. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.