85.1.41. pepsi-status

summarise the health of the Pepsi mail pipeline

Handbuchabschnitt:

1

85.1.41.1.1. Name

pepsi-status - eine menschenlesbare Gesundheitszusammenfassung der Warteschlange, steckengebliebener Nachrichten, der Zustell- und Fehlerstatistiken sowie der ausgehenden TLS-Ergebnisse ausgeben.

85.1.41.1.2. Übersicht

pepsi-status [GLOBAL-OPTIONS] [–json] [–limit N]

85.1.41.1.3. Beschreibung

pepsi-status gibt einen einmaligen, nur lesenden Gesundheitsbericht der Pepsi-Pipeline aus, vollständig aus der gemeinsamen pepsi-Datenbank gezogen. Es ist dafür gedacht, interaktiv oder über SSH ausgeführt zu werden (zum Beispiel von einem Überwachungs-Host); es verändert nie einen Datensatz und gibt keine Datenbankbenachrichtigung aus, sodass es jederzeit gefahrlos gegen eine Live-Installation ausgeführt werden 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; siehe Ausführung als root.

Der Bericht hat sechs Abschnitte:

Warteschlange

Der aktuelle Inhalt der pepsi.workqueue-Tabelle, aufgeschlüsselt nach stage und status, mit dem Alter der ältesten Nachricht in jedem Bucket und einer Gesamtsumme. Dies ist der Live-Rückstau: pending- und running-Datensätze sind in Bearbeitung, paused-Datensätze warten (zum Beispiel auf eine Zahlungsfrist oder eine Relay-Wiederholung), und failed/timeout-Datensätze benötigen Aufmerksamkeit.

Steckengebliebene Nachrichten

Die einzelnen Nachrichten, deren Status failed oder timeout ist, älteste zuerst. Für jede zeigt der Bericht die workqueue_id, den Status, die Stage, das Alter, den Umschlagabsender und den Betreff sowie — wenn eine Relay-Stage einen festgehalten hat — den strukturierten Grund, warum der nächste Hop die Nachricht abgelehnt hat (entfernter MTA, SMTP-Code, erweiterter Status und Antworttext oder unsere eigene Diagnose, aus state.bounce), den Fehlertext, den die Stage festgehalten hat, als sie die Nachricht fehlschlagen ließ oder zurückstellte (state.last_error, angezeigt als error:), und den Grund, den pepsi-dispatch angab, als es die Nachricht selbst fehlschlagen ließ oder in den Timeout schickte — ein abgestürzter oder hängender Worker oder eine nicht konfigurierte Stage (state.dispatch_error, angezeigt als dispatch:). In der –json-Ausgabe sind die drei die Felder bounce, last_error und dispatch_error jedes problems-Eintrags. Die Liste ist durch –limit gedeckelt; die wahre Rückstaugröße wird immer angezeigt.

Zustellung & Fehler

Kumulative Pipeline-Zähler: die Gesamtzahl der Nachrichten, die abgeschlossen wurden und die Pipeline verlassen haben, die gesamten Stage-Ausführungen sowie je Stage die Anzahl der von ihr gezählten Ausführungen (die Spalte MESSAGES, die der Nenner des Durchschnitts ist), die durchschnittliche Verarbeitungszeit, Worker-Timeouts und Worker-Abstürze. Dies sind Lebenszeit-Gesamtwerte, die seit der Erstellung des Schemas angesammelt wurden. Weil eine erfolgreich zugestellte Nachricht aus der Warteschlange gelöscht wird, gibt es kein Zustellungsjournal je Nachricht und daher kein gleitendes Zeitfenster: Die Werte sind kumulativ, nicht „in der letzten Stunde“.

Ausgehendes TLS

Ergebnisse ausgehender TLS-Sitzungen über die letzten sieben UTC-Berichtstage (der heutige, in UTC, und die sechs davor, unabhängig von der Zeitzone des Servers), gruppiert nach Richtliniendomain und Ergebnistyp, mit markierten nicht-erfolgreichen Ergebnissen. Diese Daten sind nur vorhanden, wenn [pepsi-tlsrpt] SEND_REPORTS aktiviert ist, und nur so lange, wie pepsi-tlsrpt prune sie behält ([pepsi-tlsrpt] RETAIN_DAYS, ebenfalls standardmäßig sieben Tage), eine kürzere Aufbewahrung verkürzt also diesen Abschnitt. Der Abschnitt führt danach alle MX-Host-Adressen auf, die der Resolver-Cache derzeit als nicht verbindbar markiert hat, mit dem Zeitpunkt ihrer letzten erfolgreichen Verbindung (oder never).

Postfach-Quotas

Eine Zeile je lokalem Konto, für das Pepsi Buch geführt hat, älteste Messung zuerst: Belegung, wirksame Grenze, Füllgrad, woher die Zahl stammt (fsquota/maildirsize/scan) und wie lange die Messung des Postfachs zurückliegt. Eine Zeile existiert für jedes Konto, an das Pepsi zugestellt hat — das ist es, was eine anlegt —, ob es eine Quota hat oder nicht; auf einer Installation, die die Funktion nicht nutzt, führt der Abschnitt diese Konten also weiterhin auf, mit - in den Spalten LIMIT und FULL. Leer ist er, und sagt das auch, nur wenn keine lokale Zustellung verbucht wurde.

LIMIT ist die tatsächlich geltende Grenze, genau so aufgelöst, wie der Zustellpfad sie auflöst: die eigene Grenze des Kontos, wenn es eine hat, sonst der Site-Standardwert [pepsi] MAILBOX_QUOTA, wobei eine ausdrückliche 0 am Konto unbegrenzt statt erben bedeutet und die Quota des Kernels zusätzlich verschärft, welche der beiden auch gewonnen hat.

USED ist die letzte Messung plus alles seither Zugestellte; sie wächst nur, denn nichts sagt Pepsi, wann ein Benutzer Mail über IMAP löscht, sodass sie eine obere Schranke ist und keine Tatsache. MEASURED ist, wie lange es her ist, dass tatsächlich jemand nachgesehen hat, und das zählt, weil eine Ablehnung bei RCPT darauf beruht, dass eine Messung frisch ist: Ein Konto, das gegen eine sehr alte Messung als „voll“ erscheint, ist eines, um das sich reconcile von pepsi-quota(1) kümmern sollte.

Schlüsseländerungen bei Korrespondenten

Wie viele Verschlüsselungsschlüssel von Korrespondenten die Autocrypt-Regel „das Neueste gewinnt“ in den letzten 30 Tagen ersetzt hat (rotated) und wie viele solcher Ersetzungen ACCEPT_ROTATION = expired abgelehnt hat (held), gefolgt von den jüngsten beider Arten — gedeckelt durch –limit — mit Datum, Adresse, Protokoll, altem und neuem Fingerabdruck und der Angabe, ob der neue Schlüssel der eigene des Korrespondenten war (inbound) oder von einem Dritten eingeführt wurde (gossip). Eine Rotation ist der einzige Weg, auf dem eine Nachricht, die bloß behauptet, von einem Korrespondenten zu stammen, den Schlüssel ändern kann, mit dem wir an ihn verschlüsseln; deshalb wird sie hier angezeigt, statt im Audit-Log zu verbleiben. Die Zahlen werden aus den key.peer.rotate- und key.peer.rotate.held-Zeilen von pepsi.event_log gelesen, die die Datenbank zusammen mit der Änderung selbst schreibt, sodass der Abschnitt so weit zurückreicht, wie [pepsi-admin] EVENT_RETENTION sie aufbewahrt. Siehe pepsi-stage-autocrypt-learn(1).

Freiform-Text im menschenlesbaren Bericht — die Antwort eines entfernten MTA, ein Nachrichtenbetreff, ein Hostname aus dem Resolver-Cache — bekommt vor der Ausgabe seine Steuerzeichen durch Leerzeichen ersetzt. All das wird von jemand anderem gewählt, und dieses Werkzeug ist dafür gedacht, über SSH gegen eine Live-Installation zu laufen, also genau dort, wo eine Terminal-Escape-Sequenz den Bildschirm des Operators neu zeichnen würde. Die --json-Ausgabe ist davon unberührt: Das JSON-Escaping deckt es bereits ab.

85.1.41.1.4. Optionen

–json

Gibt den gesamten Bericht als einzelnes JSON-Objekt aus (Schlüssel queue, problem_total, problems, global, stages, tls_report_days, tls, dns_failures, mailboxes, quota_default_bytes, key_change_days, key_changes_rotated, key_changes_held und key_changes) statt des menschenlesbaren Texts, für Skripting und Überwachung.

–limit N

Listet höchstens N einzelne steckengebliebene (failed/timeout-)Nachrichten und höchstens *N* Postfach-Quota-Konten auf. Standardwert ist 50. Der berichtete Gesamtrückstau ist von dieser Obergrenze unberührt.

Der Abschnitt für steckengebliebene Nachrichten sagt „showing X of Y“, wenn er abgeschnitten ist; der Abschnitt für Postfach-Quotas tut das nicht, sodass diese Liste auf einem Host mit mehr als N verbuchten Konten stillschweigend die N mit den ältesten Messungen sind — was das nützliche Ende davon ist, aber erhöhen Sie –limit, bevor Sie schließen, dass ein Konto fehlt.

85.1.41.1.5. 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-status zu denken, erkennt das Werkzeug, dass es als root gestartet wurde, und wird zum unprivilegierten Dienstkonto pepsi, bevor es sich verbindet; der Bericht selbst bleibt strikt nur lesend.

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.41.1.6. Globale Optionen

Diese Optionen können vor oder nach den anderen Optionen stehen.

-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.41.1.7. Exit-Status

0

Erfolgreicher Abschluss.

1

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

85.1.41.1.8. 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.41.1.9. Beispiele

Den vollständigen Gesundheitsbericht ausgeben:

pepsi-status -c /etc/pepsi/pepsi.conf

Den Bericht als JSON für ein Überwachungssystem über SSH erfassen:

ssh mail.example.com pepsi-status --json

Bis zu 200 steckengebliebene Nachrichten anzeigen:

pepsi-status -c /etc/pepsi/pepsi.conf --limit 200

85.1.41.1.10. Siehe auch

pepsi-queue(1), pepsi-tlsrpt(1), pepsi-quota(1), pepsi-dispatch(1), pepsi.conf(5), pepsi-setup(1)

85.1.41.1.11. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.