85.1.40. pepsi-queue

inspect and repair the pepsi-ingress message queue

Handbuchabschnitt:

1

85.1.40.1.1. Name

pepsi-queue - Nachrichten in der Warteschlange auflisten, löschen, zwischen Stages verschieben und losmachen.

85.1.40.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] 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, da sie sich wie ein Filter lesen würden, den der Befehl nicht anwendet.

85.1.40.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 schaltet durch eine Filter-Pipeline weiter, verfolgt durch drei Spalten auf jedem Datensatz: eine stage (der Konfigurationsabschnitt des aktuell für die Nachricht zuständigen Programms; init für eine frisch angenommene Nachricht), einen 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; es führt keine eigene Konfiguration ein. 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. delete gibt 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 — ein Worker kann noch an einem davon arbeiten — 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.

85.1.40.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 — praktisch, um es in ein JSON-Werkzeug zu 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, die trennende Leerzeile, Body — genau so, wie eine Stage, die die vollständige Nachricht lädt, sie wieder zusammensetzt. 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 massenhafte „Losmachen“, das nach einem Absturz oder einer ins Stocken geratenen Stage verwendet wird. Nachrichten in failed oder timeout bleiben unberührt.

gc

Bereinigt die Herkunftsnachweis-Nonce-Tabelle (pepsi.origin_nonce) und löscht jeden Eintrag, dessen zweiwöchiger Ablauf vergangen ist. Eine abgelaufene Nonce kann einen zurückkehrenden Bounce nicht 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 ihn erneut auflöst, aber ein Host, den sie nie wieder auflöst, würde sie sonst für immer behalten. Zum periodischen Lauf vorgesehen; das Debian-Paket liefert einen pepsi-origin-gc.timer, 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).

85.1.40.1.5. Audit-Protokoll

Die drei 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) und clear-all als queue.clear-all (mit der Anzahl der zurückgesetzten Datensätze). Eine Nachricht von Hand zu bewegen ist ein administrativer Akt, gleich über welche Oberfläche 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.

85.1.40.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 sie 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 — dem Konto, unter dem der Dispatcher läuft und dem pepsi.workqueue gehört —, bevor es sich verbindet. Der Wechsel gilt dauerhaft für die Lebensdauer des Prozesses; das Werkzeug benötigt keine eigenen Privilegien.

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

Existiert das Konto pepsi nicht — ein nicht installierter Quellbaum, ein 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.

85.1.40.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 (Standardwert: 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.

85.1.40.1.8. Exit-Status

0

Erfolgreicher Abschluss. Eine WORKQUEUE-ID, auf die kein Datensatz passt, ist kein Fehler: list, delete und set-stage sagen es auf der Standardausgabe und enden dennoch mit 0.

1

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

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

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

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

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

85.1.40.1.11. Siehe auch

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

85.1.40.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.