95.1.44. pepsi-queue

inspect and repair the pepsi-ingress message queue

Handbuchabschnitt:

1

95.1.44.1.1. Name

pepsi-queue - Nachrichten in der Warteschlange auflisten, löschen, zwischen Stages verschieben und losmachen sowie Nachrichten in Quarantäne freigeben.

95.1.44.1.2. Übersicht

pepsi-queue [GLOBAL-OPTIONS] [list] [–json] [–state-only] [–headers] [–body] [–limit N] [–stage STAGE] [–status STATUS] [WORKQUEUE-ID]

pepsi-queue [GLOBAL-OPTIONS] delete WORKQUEUE-ID

pepsi-queue [GLOBAL-OPTIONS] set-stage WORKQUEUE-ID STAGE

pepsi-queue [GLOBAL-OPTIONS] clear-all

pepsi-queue [GLOBAL-OPTIONS] quarantine list [–json] [–limit N]

pepsi-queue [GLOBAL-OPTIONS] quarantine show [–json] TOKEN

pepsi-queue [GLOBAL-OPTIONS] quarantine release TOKEN

pepsi-queue [GLOBAL-OPTIONS] quarantine delete [–yes] TOKEN

pepsi-queue [GLOBAL-OPTIONS] gc

Die Optionen von list werden ohne das Wort list akzeptiert, weil Auflisten die Standardaktion ist, aber nur dann: Vor einem anderen Unterbefehl angegeben (pepsi-queue --stage relay delete 5) werden sie abgelehnt und nicht stillschweigend ignoriert, denn sie würden sich wie ein Filter lesen, den der Befehl nicht anwendet.

95.1.44.1.3. Beschreibung

pepsi-queue ist ein Diagnose- und Reparaturwerkzeug für die pepsi.workqueue-Tabelle, die von der Pepsi-Pipeline geteilt wird. Jede angenommene Nachricht durchläuft eine Pipeline von Filtern, und drei Spalten auf jedem Datensatz verfolgen ihren Fortschritt: eine stage (der Konfigurationsabschnitt des Programms, das gerade für die Nachricht zuständig ist; init für eine frisch angenommene Nachricht), ein status (pending, running, paused, failed oder timeout) und ein optionales JSON-state (Zwischendaten pro Stage). Siehe pepsi.state(7) für die Schlüssel, die state tragen kann.

Das Werkzeug verbindet sich über den gemeinsamen [pepsi-postgres]-Abschnitt mit derselben Datenbank wie die anderen Komponenten; seine einzige eigene Option ist [pepsi-queue] QUARANTINE_MAX_AGE_DAYS, die gc liest. Als root gestartet, läuft es als Dienstkonto pepsi weiter, dem die Warteschlange gehört; siehe Ausführung als root.

Warnung

Die verändernden Unterbefehle wirken sofort und sind nicht umkehrbar. delete entfernt eine Nachricht dauerhaft, und set-stage / clear-all ändern den Verarbeitungszustand an Ort und Stelle.

set-stage und clear-all geben sehr wohl eine Datenbankbenachrichtigung aus: Haben sie mindestens einen Datensatz bewegt, setzen sie ihn auf pending zurück und wecken dann pepsi-dispatch(1), damit die Änderung sofort wirksam wird statt erst bei der nächsten Abfrage. pepsi.workqueue trägt keinen benachrichtigenden Trigger, und pepsi-queue läuft außerhalb der eigenen Schleife des Dispatchers, sodass es sonst niemand täte; quarantine release tut dasselbe. delete und quarantine delete geben keine aus: Ein Datensatz, der weg ist, gibt dem Dispatcher nichts zu beanspruchen.

Das macht clear-all auf einer laufenden Pipeline unsicher: Es setzt Datensätze zurück, die gerade running sind, obwohl ein Worker noch an einem davon arbeiten kann, und gibt sie dann direkt an den Dispatcher zurück, der sie erneut beansprucht. Die Nachricht wird dann zweimal verarbeitet, was bei einer Zustell-Stage eine doppelte Zustellung und bei einer Bounce-Stage einen doppelten Bounce bedeutet. Halten Sie zuerst pepsi-dispatch an, oder verwenden Sie es nur nach einem Absturz, wenn kein Worker mehr da ist, mit dem es kollidieren könnte.

95.1.44.1.4. Befehle

list [–json] [–state-only] [–headers] [–body] [–limit N] [–stage STAGE] [–status STATUS] [WORKQUEUE-ID]

Listet eingereihte Nachrichten auf, nach workqueue_id geordnet. Dies ist auch die Standardaktion, wenn kein Unterbefehl angegeben ist, sodass das Schlüsselwort list entfallen darf: pepsi-queue listet alles auf und pepsi-queue 5 zeigt nur die Nachricht mit workqueue_id 5.

WORKQUEUE-ID

Eine optionale nachgestellte Nachrichten-ID. Wenn angegeben, wird höchstens diese eine Nachricht angezeigt. --limit ist dann hinfällig, aber --stage und --status werden weiterhin zusätzlich angewandt, sodass eine Nachricht, die nicht auch auf sie passt, nicht angezeigt wird. pepsi-queue 5 und pepsi-queue list 5 sind gleichwertig.

–json

Gibt ein hübsch formatiertes JSON-Array von Objekten (workqueue_id, stage, status, mail_from, subject, received_at, state) statt der menschenlesbaren Tabelle aus. subject und state sind null, wenn die Nachricht keines von beiden trägt.

–state-only

Gibt das vollständige, ungekürzte JSON-state jeder passenden Nachricht aus (die Tabellenansicht kürzt es ab), einen hübsch formatierten Block pro Nachricht, jeder mit einer Kommentarzeile # workqueue_id überschrieben. Mit einer expliziten WORKQUEUE-ID entfällt diese Überschrift und die Ausgabe ist nur der State jener Nachricht, sodass pepsi-queue --state-only 5 den vollständigen state der Nachricht 5 ausgibt. Das lässt sich bequem in ein JSON-Werkzeug leiten. Eine Nachricht ohne state gibt null aus. Dies hat Vorrang vor –json.

–headers, –body

Schreibt den gespeicherten Header-Block (–headers) oder Body (–body) der Nachricht WORKQUEUE-ID auf die Standardausgabe, Byte für Byte und ohne dass sonst etwas ausgegeben wird. Beide zusammen schreiben die ganze Nachricht (Header-Block, trennende Leerzeile, Body), genau so, wie eine Stage sie wieder zusammensetzt, die die vollständige Nachricht lädt. Beide brauchen eine WORKQUEUE-ID und lassen sich nicht mit –json oder –state-only kombinieren. Die Ausgabe ist rohe Mail (CRLF-Zeilenenden, möglicherweise 8-Bit), gedacht für eine Datei oder eine Pipe, z. B. pepsi-queue --headers --body 5 | pepsi-detect-language.

–limit N

Zeigt höchstens N Nachrichten. Standardwert ist 100. Hat keine Wirkung, wenn eine WORKQUEUE-ID angegeben ist, da höchstens ein Datensatz passen kann.

–stage STAGE

Zeigt nur Nachrichten, deren Stage gleich STAGE ist.

–status STATUS

Zeigt nur Nachrichten mit dem angegebenen Status.

delete WORKQUEUE-ID

Löscht die Nachricht mit der angegebenen workqueue_id dauerhaft.

set-stage WORKQUEUE-ID STAGE

Weist die Nachricht STAGE neu zu und setzt implizit ihren Status auf pending zurück, damit die neue Stage sie aufnimmt. Das state der Nachricht bleibt unverändert.

clear-all

Setzt jede Nachricht, deren Status running oder paused ist, zurück auf pending. Das ist das massenhafte „Losmachen“ nach einem Absturz oder nach einer ins Stocken geratenen Stage. Nachrichten in failed oder timeout bleiben unberührt, ebenso die paused-Nachrichten in einer Stage, die pepsi-stage-quarantine(1) ausführt: Sie stecken nicht fest, sondern werden zurückgehalten, und sie zurückzusetzen würde sie freigeben.

quarantine list [–json] [–limit N]

Listet die Nachrichten auf, die eine Quarantäne-Stage zurückhält: die paused-Nachrichten in jeder Stage, deren PROGRAM pepsi-stage-quarantine(1) ist, älteste zuerst, höchstens N (Standardwert 100). Die Tabelle zeigt für jede Nachricht das Token, wann sie eintraf, seit wann sie zurückgehalten wird, ihren Umschlagabsender und ihre Empfänger sowie by und reason ihres state.quarantine-Eintrags (wer sie in die Quarantäne geschickt hat und warum). –json gibt stattdessen ein Array von Objekten aus, mit workqueue_id, token, stage, status, received_at, mail_from, rcpt_to, from_header, subject, since, until, released_at, reason und by (null, wenn nicht vorhanden). Die Zeiten sind RFC 3339, in UTC.

quarantine show [–json] TOKEN

Zeigt eine Nachricht in einer Quarantäne-Stage, gleich in welchem Status, zusätzlich mit ihrem From: und Subject:. Ihr Inhalt ist mit list --headers --body und der hier gezeigten workqueue_id zugänglich.

quarantine release TOKEN

Gibt eine zurückgehaltene Nachricht frei: Sie wird in ihrer Quarantäne-Stage auf pending gesetzt und der Dispatcher geweckt, und die Stage schickt sie dann an ihre RELEASE_STAGE weiter. Freigegeben wird nur eine paused-Nachricht in einer Quarantäne-Stage.

quarantine delete [–yes] TOKEN

Löscht eine Nachricht in einer Quarantäne-Stage, sofern nicht gerade ein Worker sie bearbeitet. Der Befehl fragt am Terminal nach einer Bestätigung; ohne Terminal verweigert er, sofern nicht –yes angegeben ist. Das optionale Maillog ([pepsi] MAIL_LOG) hält die Löschung fest, wie es jede Nachricht festhält, die die Warteschlange verlässt, mit der Quarantäne-Stage als letzter Stage.

gc

Räumt die Nonce-Tabelle des Herkunftsnachweises (pepsi.origin_nonce) auf und löscht dabei jeden Eintrag, dessen zweiwöchige Ablaufzeit verstrichen ist. Eine abgelaufene Nonce kann keinen zurückkehrenden Bounce mehr authentifizieren, daher ist ihr Verwerfen sicher. Derselbe Lauf löscht die Datensätze des MX-Adress-Caches (pepsi.dns_address), deren DNS-TTL abgelaufen ist: Die Relay-Stage liest nie einen abgelaufenen Datensatz und ersetzt die Datensätze eines Hosts, wenn sie den Host erneut auflöst, aber ein Host, den sie nie wieder auflöst, würde sie sonst für immer behalten.

Danach frischt der Lauf die zwischengespeicherten MTA-STS-Richtlinien (pepsi.mta_sts_policy) auf, unabhängig vom Mailfluss (RFC 8461 Abschnitt 10.2), bevor er die abgelaufenen löscht. Der Lauf ruft jede Richtlinie erneut ab, die die Hälfte ihrer Lebensdauer verbraucht hat oder von der weniger als drei Stunden übrig sind. Der Abruf verwendet die DNS- und Timeout-Einstellungen der ersten pepsi-stage-relay-to-internet-Stage, bei der MTA_STS eingeschaltet ist (ist keine konfiguriert, wird nichts aufgefrischt), und er folgt den Regeln, die die Relay-Stage bei der Verwendung anwendet. Eine Domain, die weiterhin eine Richtlinie veröffentlicht, fällt deshalb nie auf einen Erstkontakt zurück, wie selten sie auch angeschrieben wird. Schlägt eine Auffrischung fehl, bleibt der Datensatz erhalten, bis sein max_age verstrichen ist, und wird dann gelöscht, da die Relay-Stage nie eine abgelaufene Richtlinie durchsetzt. Eine Auffrischung, die überhaupt nicht laufen kann, wird gemeldet, und der Lauf geht weiter.

Danach löscht der Lauf außerdem die festgehaltenen Bestätigungsanfragen von Mailinglisten (pepsi.list_confirmation), deren LIST_CONFIRMATION_DAYS-Fenster vorbei ist; die list-id-Whitelist-Datensätze, die pepsi-stage-auto-whitelist(1) gelernt hat und deren last_seen + max_idle verstrichen ist, die pepsi-stage-check-whitelist(1) also bereits ignoriert (Datensätze ohne last_seen laufen nie ab); die zweiten Faktoren, die per E-Mail eingerichtet und nicht innerhalb von OTP_CONFIRM_WINDOW bestätigt wurden (pepsi.otp_pending, siehe pepsi-stage-encrypt(1)); und die DMARC-Sammelberichte, die pepsi-stage-dmarc-report(1) gespeichert hat (pepsi.dmarc_report, mit ihren Datensätzen) und deren Zeitraum vor mehr als [pepsi-dmarc-reports] RETAIN_DAYS (90) Tagen endete.

gc ist für periodische Ausführung gedacht; das Debian-Paket liefert einen pepsi-origin-gc.timer mit, der es stündlich aufruft. Siehe pepsi-stage-relay-to-internet(1) und pepsi-stage-relay-to-smarthost(1) (die die Nonces beim Weiterleiten festhalten) sowie pepsi-stage-anti-spam(1) und pepsi-stage-auto-pay(1) (die sie verifizieren).

Derselbe Lauf prüft außerdem jedes Login im Login-Zuordnungsverzeichnis nach RFC 7293 (pepsi.login_assignment) erneut gegen passwd: Ein Login ohne Eintrag wird als verschwunden markiert, und eines, das zurückgekehrt ist oder seine uid geändert hat, wird als mit neuem Inhaber festgehalten, was die Einstellungen, Whitelists, Quota- und Auto-Reply-Datensätze des vorherigen Inhabers verwirft (siehe pepsi-setup(1), The login assignment record). Eine fehlschlagende passwd-Abfrage entscheidet nichts, und eine Prüfung, bei der die meisten festgehaltenen Logins verschwunden aussehen, markiert keines davon.

Außerdem beendet der Lauf das Zurückhalten von Mail in einer Quarantäne-Stage, also in jeder Stage, die eine QUARANTINE_STAGE-Option von pepsi-stage-decrypt(1) oder pepsi-stage-milter(1) nennt. Liegt dort noch eine pending- oder paused-Nachricht, die vor [pepsi-queue] QUARANTINE_MAX_AGE_DAYS (Standardwert 14) Tagen oder früher eintraf, dann verschiebt gc sie zum eigenen BOUNCE_STAGE der Quarantäne-Stage, sonst zu [pepsi-failure-bouncer] BOUNCE_STAGE, mit state.failure_class = quarantine-expired, und macht aus einem RET=FULL, das ihr Absender angefordert hat, ein RET=HDRS. So erfährt der Absender (gemäß NOTIFY), dass die Nachricht zurückgehalten und nicht freigegeben wurde, und erhält ihren Header-Block zurück, aber nie ihren Inhalt, der ja gerade zurückgehalten wurde.

Zwei Arten von Nachrichten werden stattdessen gelöscht und protokolliert: die Kopie eines Listenbeitrags für ein Mitglied (ihr Umschlagabsender ist die Bounce-Verarbeitung der Liste) und eine Nachricht, deren Inhalt aus einem S/MIME-EnvelopedData-Chiffrat (AES-CBC) stammt oder sich daraus nicht öffnen ließ, wie pepsi-stage-decrypt(1) es in state.crypto.in festgehalten hat. Ob sich ein verändertes CBC-Chiffrat öffnen lässt, hängt von seinem Padding ab und entscheidet, ob die Nachricht zurückgehalten oder zugestellt wird. Eine DSN bei Ablauf würde ihrem Absender also verraten, welcher der beiden Fälle eingetreten ist. Eine solche Nachricht geht dorthin, wohin die eigenen Bounce-Einstellungen der Decrypt-Stage sie schicken, nie an einen Ort, den der Absender beobachten könnte (Telemetrie decrypt-dropped).

Eine zurückgehaltene Nachricht liegt als Klartext gespeichert, solange sie zurückgehalten wird, denn die Quarantäne einer Decrypt-Stage hält, was diese entschlüsselt hat; deshalb hat das Zurückhalten ein Ende. 0 behält zurückgehaltene Mail unabhängig von ihrem Alter. Eine Quarantäne-Stage, die kein Bounce-Ziel hat oder deren Bounce-Stage sie selbst ist, wird in Ruhe gelassen und in der Ausgabe genannt. Um eine Nachricht vorher freizugeben, verwenden Sie bei einer pepsi-stage-quarantine(1)-Stage quarantine release, sonst set-stage.

Jede Stage, die pepsi-stage-quarantine(1) ausführt, ist ebenfalls eine Quarantäne-Stage, ob ein QUARANTINE_STAGE sie nennt oder nicht (auch ein Milter vor der Warteschlange von pepsi-ingress(1) schickt Mail dorthin), außer einer mit MAX_HOLD, die ihr Zurückhalten selbst beendet.

95.1.44.1.5. Audit-Protokoll

Die verändernden Unterbefehle werden im gemeinsamen Audit-Protokoll festgehalten, über denselben Helfer, den die administrative API für dieselben Aktionen verwendet: delete als queue.cancel, set-stage als queue.set-stage (mit der neuen Stage), clear-all als queue.clear-all (mit der Anzahl der zurückgesetzten Datensätze), quarantine release als queue.quarantine-release und quarantine delete als queue.quarantine-delete (jeweils mit dem Token); die Quarantäne-Seite der Konsole und /api/v1/quarantine von pepsi-httpd(1) geben über dieselben Funktionen frei, löschen über sie und halten dieselben Arten fest. Eine Nachricht von Hand zu bewegen ist ein administrativer Akt, gleich über welche Schnittstelle er erfolgt, und ein Protokoll, das nur eine davon sähe, wäre irreführend statt bloß unvollständig. list und gc werden nicht festgehalten: Lesen ist keine Aktion, und der Garbage Collector ist ein Timer und kein Betreiber.

95.1.44.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-queue … zu denken, erkennt das Werkzeug, dass es als root gestartet wurde, und wird zum unprivilegierten Dienstkonto pepsi, bevor es sich verbindet. Unter diesem Konto läuft der Dispatcher, und ihm gehört pepsi.workqueue. Der Wechsel gilt dauerhaft für die Lebensdauer des Prozesses; das Werkzeug benötigt keine eigenen Privilegien.

Die Konfigurationsdatei (und jedes @inline-secret@-Fragment, auf das sie verweist) wird vor dem Wechsel gelesen, sodass eine nur für root lesbare Konfiguration weiterhin normal geladen wird.

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.44.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.44.1.8. Exit-Status

0

Erfolgreicher Abschluss. Eine WORKQUEUE-ID oder ein TOKEN, auf die kein Datensatz passt, ist kein Fehler: list, delete, set-stage und die quarantine-Unterbefehle sagen es auf der Standardausgabe und enden dennoch mit 0, ebenso ein nicht bestätigtes quarantine delete.

1

Ein Fehler ist aufgetreten: eine fehlerhafte Konfigurationsdatei oder eine fehlgeschlagene Datenbankverbindung oder -abfrage. Der Grund wird in das Journal geschrieben.

2

Die Befehlszeile selbst war falsch, einschließlich einer list-Option vor einem anderen Unterbefehl.

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

95.1.44.1.10. Beispiele

Die ersten 20 eingereihten Nachrichten als Tabelle auflisten:

pepsi-queue -c /etc/pepsi/pepsi.conf list --limit 20

Als JSON jede Nachricht anzeigen, die derzeit von der spamfilter-Stage gehalten wird:

pepsi-queue -c /etc/pepsi/pepsi.conf list --json --stage spamfilter

Nur die Nachricht 5 inspizieren und dann ihr vollständiges state-JSON ausgeben:

pepsi-queue -c /etc/pepsi/pepsi.conf 5
pepsi-queue -c /etc/pepsi/pepsi.conf --state-only 5

Nachricht 5 so speichern, wie sie abgelegt ist, und dann nur ihren Header-Block ansehen:

pepsi-queue -c /etc/pepsi/pepsi.conf --headers --body 5 > msg5.eml
pepsi-queue -c /etc/pepsi/pepsi.conf --headers 5

Nachricht 42 erneut an die spamfilter-Stage übergeben:

pepsi-queue -c /etc/pepsi/pepsi.conf set-stage 42 spamfilter

Ansehen, was eine Quarantäne zurückhält, eine Nachricht betrachten und sie dann freigeben:

pepsi-queue -c /etc/pepsi/pepsi.conf quarantine list
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine show TOKEN
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine release TOKEN

Eine zurückgehaltene Nachricht ohne Rückfrage aus einem Skript löschen:

pepsi-queue -c /etc/pepsi/pepsi.conf quarantine delete --yes TOKEN

Nach einem Absturz wiederherstellen, indem alles erneut eingereiht wird, was in Bearbeitung war:

pepsi-queue -c /etc/pepsi/pepsi.conf clear-all

95.1.44.1.11. Siehe auch

pepsi-status(1), pepsi-config(1), pepsi-ingress(1), pepsi-dispatch(1), pepsi-failure-bouncer(1), pepsi-stage-quarantine(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

95.1.44.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.