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_idgeordnet. Dies ist auch die Standardaktion, wenn kein Unterbefehl angegeben ist, sodass das Schlüsselwortlistentfallen darf:pepsi-queuelistet alles auf undpepsi-queue 5zeigt nur die Nachricht mitworkqueue_id5.- WORKQUEUE-ID
Eine optionale nachgestellte Nachrichten-ID. Wenn angegeben, wird höchstens diese eine Nachricht angezeigt.
--limitist dann hinfällig, aber--stageund--statuswerden weiterhin zusätzlich angewandt, sodass eine Nachricht, die nicht auch auf sie passt, nicht angezeigt wird.pepsi-queue 5undpepsi-queue list 5sind 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.subjectundstatesindnull, wenn die Nachricht keines von beiden trägt.- –state-only
Gibt das vollständige, ungekürzte JSON-
statejeder 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, sodasspepsi-queue --state-only 5den vollständigenstateder Nachricht 5 ausgibt. Das lässt sich bequem in ein JSON-Werkzeug leiten. Eine Nachricht ohnestategibtnullaus. 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_iddauerhaft.- set-stage WORKQUEUE-ID STAGE
Weist die Nachricht STAGE neu zu und setzt implizit ihren Status auf
pendingzurück, damit die neue Stage sie aufnimmt. Dasstateder Nachricht bleibt unverändert.- clear-all
Setzt jede Nachricht, deren Status
runningoderpausedist, zurück aufpending. Das ist das massenhafte „Losmachen“ nach einem Absturz oder nach einer ins Stocken geratenen Stage. Nachrichten infailedodertimeoutbleiben unberührt, ebenso diepaused-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, derenPROGRAMpepsi-stage-quarantine(1) ist, älteste zuerst, höchstens N (Standardwert100). Die Tabelle zeigt für jede Nachricht das Token, wann sie eintraf, seit wann sie zurückgehalten wird, ihren Umschlagabsender und ihre Empfänger sowiebyundreasonihresstate.quarantine-Eintrags (wer sie in die Quarantäne geschickt hat und warum). –json gibt stattdessen ein Array von Objekten aus, mitworkqueue_id,token,stage,status,received_at,mail_from,rcpt_to,from_header,subject,since,until,released_at,reasonundby(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:undSubject:. Ihr Inhalt ist mitlist --headers --bodyund der hier gezeigtenworkqueue_idzugänglich.- quarantine release TOKEN
Gibt eine zurückgehaltene Nachricht frei: Sie wird in ihrer Quarantäne-Stage auf
pendinggesetzt und der Dispatcher geweckt, und die Stage schickt sie dann an ihreRELEASE_STAGEweiter. Freigegeben wird nur einepaused-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 erstenpepsi-stage-relay-to-internet-Stage, bei derMTA_STSeingeschaltet 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 seinmax_ageverstrichen 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), derenLIST_CONFIRMATION_DAYS-Fenster vorbei ist; dielist-id-Whitelist-Datensätze, die pepsi-stage-auto-whitelist(1) gelernt hat und derenlast_seen + max_idleverstrichen ist, die pepsi-stage-check-whitelist(1) also bereits ignoriert (Datensätze ohnelast_seenlaufen nie ab); die zweiten Faktoren, die per E-Mail eingerichtet und nicht innerhalb vonOTP_CONFIRM_WINDOWbestä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.timermit, 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 einepending- oderpaused-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, mitstate.failure_class = quarantine-expired, und macht aus einemRET=FULL, das ihr Absender angefordert hat, einRET=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 instate.crypto.infestgehalten 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 (Telemetriedecrypt-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.
0behä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_STAGEsie nennt oder nicht (auch ein Milter vor der Warteschlange von pepsi-ingress(1) schickt Mail dorthin), außer einer mitMAX_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,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.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 schemaaus (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.