Add exitrace tool and improve documentation

- Add exitrace: Enhanced Exim log analyzer with status classification - Add Maintainer: ljp to all ljp-owned scripts - Update READMEs: Use installer-compatible command examples - Update main and legacy READMEs to include exitrace tool
2025-09-11 12:35:48 +02:00
parent 84ecfaf278
commit bddb3cf1e9
10 changed files with 567 additions and 22 deletions
@@ -0,0 +1,169 @@
+# exitrace
+
+Exim-Log-Trace & Status für einzelne Mails/Adressen/Domain-Ziele:  
+Durchsucht Exim-Logs nach Message-IDs, gruppiert alle Ereignisse und klassifiziert den Delivery-Status
+
+---
+
+## Features
+
+- Sucht in `/var/log/easyname/YYYY/MM/YYYY-MM-DD.log(.gz)` (konfigurierbar via `$LOGROOT`)
+- Zeitfenster: letzte N Stunden/Tage ODER konkretes Datum/Datumsbereich
+- Filter: Absender, Empfänger (Regex), Domain, Message-ID, zusätzliche Regex
+- Gruppiert alle Treffer pro Exim-Message-ID und fasst Status zusammen
+- **Status-Klassifikation**: OK / PARTIAL / DELAY / FAIL / UNKNOWN
+- **MX-Records**: Optional DNS-Abfragen für Ziel-Domain (--mx)
+- Markiert häufige Fehler (z. B. "all hosts for 'domain' have been failing")
+- Sortierte chronologische Ausgabe pro Message-ID
+- **Komprimierte Logs**: Automatischer Support für .gz-Archive
+
+---
+
+## Installation
+
+1. Repository klonen oder Skript kopieren:
+   ```bash
+   git clone <gitea-url>/esn-support-bash-snippets.git
+   cd esn-support-bash-snippets/legacy/exitrace
+   chmod +x exitrace.sh
+   ```
+
+2. Abhängigkeiten:
+   - Standard Unix-Tools (awk, grep, date, zcat)
+   - `dig` (optional, für --mx Feature)
+   - Lesezugriff auf `/var/log/easyname/` (oder custom `$LOGROOT`)
+
+---
+
+## Nutzung
+
+### Standardaufruf
+```bash
+exitrace
+```
+(durchsucht heutiges Log ohne Filter)
+
+### Beispiele
+```bash
+# Mail-Trace einer konkreten Message-ID
+exitrace -m 1uwRvz-000Fz2-CI
+
+# Alle Mails von bestimmtem Absender in den letzten 48 Stunden
+exitrace -f sender@example.com -H 48
+
+# Empfänger-Domain in Zeitspanne
+exitrace -D example.de -r 2025-09-09..2025-09-11
+
+# Regex-Filter auf Empfänger + konkretes Datum
+exitrace -t '.*@example\.de' -d 2025-09-10
+
+# Kombinierte Filter: Absender + Domain + Zeitfenster + MX-Info
+exitrace -f sender@example.com -D example.de -H 48 --mx
+
+# Dry-Run: zeigt nur, welche Logfiles durchsucht würden
+exitrace -n -H 24
+```
+
+---
+
+## Optionen
+
+```
+Usage: exitrace [OPTS]
+
+Zeitfenster (eine Option wählen):
+  -H, --hours N          Letzte N Stunden durchsuchen
+  -DAYS, --days N        Letzte N Tage durchsuchen
+  -d, --date YYYY-MM-DD  Exaktes Datum
+  -r, --range A..B       Datumsbereich (inkl.): YYYY-MM-DD..YYYY-MM-DD
+
+Filter (beliebig kombinierbar):
+  -f, --from ADDR        Envelope-From / "from <...>"
+  -t, --to REGEX         Empfänger (Regex, matcht nach " for <rcpt>" oder in "** ...")
+  -D, --domain NAME      Ziel-Domain (z. B. example.de), prüft auf Zustellungen/Fehler dorthin
+  -m, --msgid ID         Exim-Message-ID (z. B. 1uwRvz-000Fz2-CI)
+  -G, --grep REGEX       Zusätzlicher Regex auf Logzeilen
+
+Sonstiges:
+  --mx                   Zeigt MX-Einträge (und A/AAAA) für --domain
+  -n, --dry-run          Zeigt nur, welche Logfiles untersucht würden
+  -h, --help             Diese Hilfe
+```
+
+---
+
+## Beispielausgabe
+
+```
+[OK] ID=1uwRvz-000Fz2-CI | First=2025-09-10 14:32:15 | From=sender@example.com | Rcpts=recipient@example.de | Delivered=1 Deferred=0 Failed=0
+------------------------------------------------------------------------
+ID:        1uwRvz-000Fz2-CI
+First:     2025-09-10 14:32:15
+Last:      2025-09-10 14:32:47
+From:      sender@example.com
+Rcpts:     recipient@example.de
+Status:    OK (Delivered=1, Deferred=0, Failed=0)
+Log:
+2025-09-10 14:32:15 | <= sender@example.com H=mail.example.com [10.0.0.1] P=esmtp S=1234
+2025-09-10 14:32:47 | => recipient@example.de <recipient@example.de> R=dnslookup T=remote_smtp H=mx.example.de [10.0.0.2]
+------------------------------------------------------------------------
+```
+
+**Status-Klassifikation:**
+- `OK`: Alle Mails erfolgreich zugestellt
+- `PARTIAL`: Teilweise zugestellt, aber auch Fehler/Delays
+- `DELAY`: Noch in Warteschlange (Deferred)
+- `FAIL`: Permanent fehlgeschlagen
+- `UNKNOWN`: Status unklar
+
+Bei MX-Abfrage (--mx) wird zusätzlich angezeigt:
+```
+== MX für example.de ==
+10 mx1.example.de.
+20 mx2.example.de.
+-- A/AAAA der MX:
+mx1.example.de.                     | 192.0.2.1,192.0.2.2
+mx2.example.de.                     | 192.0.2.3
+========================================================================
+```
+
+Bei Delivery-Stalls:
+```
+  Note: DELIVERY STALL erkannt: 'all hosts for domain failing (retry/backoff)'
+```
+
+---
+
+## Setup-Hinweise
+
+Nach Installation über `./install.sh` ist das Script direkt verfügbar:
+```bash
+exitrace -m 1uwRvz-000Fz2-CI
+```
+
+Das Installationsscript erstellt automatisch einen Symlink in `~/bin` (ohne `.sh` Extension).
+
+Umgebungsvariable für abweichenden Logpfad:
+```bash
+export LOGROOT="/var/log/custom"
+```
+
+Logger-spezifisch ggf. in `~/.profile` ergänzen:
+```bash
+cd /var/log/easyname/$(date +%Y)/$(date +%m)/
+```
+
+---
+
+## Notes
+
+- Das Skript analysiert Exim-Logs im Format `/var/log/easyname/YYYY/MM/YYYY-MM-DD.log(.gz)`
+- **Komprimierte Archive**: Automatische Erkennung und Verarbeitung von .gz-Dateien
+- **Status-Logik**: Basiert auf SMTP-Response-Codes und typischen Exim-Nachrichten
+- Bei größeren Zeiträumen kann die Verarbeitung länger dauern
+- Regex-Filter (-t, -G) sollten sorgfältig formuliert werden, um false positives zu vermeiden
+- Die Ausgabe ist nach chronologischem Erstkontakt der Message-ID sortiert
+- **MX-Feature**: Benötigt `dig` für DNS-Abfragen
+- Exit-Codes: 0 = OK (auch bei 0 Treffern), 1 = Fehlerhafte Parameter/Umgebung
+
+Built with the help of Claude Code