From 9241cc3d14faf984c283071aeaa362c343251c49 Mon Sep 17 00:00:00 2001 From: h0tznpl0tz Date: Thu, 11 Sep 2025 15:06:40 +0200 Subject: [PATCH] Improve exitrace parameter naming for better usability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add descriptive parameter names: -FROM, -TO, -DOMAIN, -MSGID, -GREP - Maintain backwards compatibility with old short forms (-f, -t, -D, -m, -G) - Update README with new examples and backwards compatibility section - More intuitive and self-documenting command line interface đŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- legacy/exitrace/README.md | 214 ++++++++++++++++++++++++++---------- legacy/exitrace/exitrace.sh | 36 +++--- 2 files changed, 172 insertions(+), 78 deletions(-) diff --git a/legacy/exitrace/README.md b/legacy/exitrace/README.md index f5536ed..1d4b68d 100644 --- a/legacy/exitrace/README.md +++ b/legacy/exitrace/README.md @@ -1,37 +1,57 @@ # 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 +**Remote Exim-Log-Trace & Status fĂŒr einzelne Mails/Adressen/Domain-Ziele** + +FĂŒhrt Exim-Log-Analyse remote auf `logger.in.nessus.at` aus, wo sich die Exim-Logs befinden. +Durchsucht 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 +- **Remote-AusfĂŒhrung**: Automatische SSH-Verbindung zu `logger.in.nessus.at` +- **Zeitfenster**: Letzte N Stunden/Tage ODER konkretes Datum/Datumsbereich +- **Filter**: Absender, EmpfĂ€nger (Regex), Domain, Message-ID, zusĂ€tzliche Regex +- **Gruppierung**: Alle Treffer pro Exim-Message-ID mit Status-Zusammenfassung - **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 +- **MX-Records**: Optional DNS-Abfragen fĂŒr Ziel-Domain (--mx) +- **Failure-Detection**: Markiert hĂ€ufige Fehler (z.B. "all hosts failing") +- **Chronologische Ausgabe**: Sortiert nach Message-ID Erstkontakt - **Komprimierte Logs**: Automatischer Support fĂŒr .gz-Archive +- **Smart Connection**: Verwendet `go logger` oder `ssh ${LUSER}@logger.in.nessus.at` --- ## Installation -1. Repository klonen oder Skript kopieren: - ```bash - git clone /esn-support-bash-snippets.git - cd esn-support-bash-snippets/legacy/exitrace - chmod +x exitrace.sh - ``` +Via Installer (empfohlen): +```bash +cd ~/.dev/esn-support-bash-snippets +./install.sh +# Dann: 3) Legacy Tools auswĂ€hlen und exitrace installieren +``` -2. AbhĂ€ngigkeiten: - - Standard Unix-Tools (awk, grep, date, zcat) - - `dig` (optional, fĂŒr --mx Feature) - - Lesezugriff auf `/var/log/easyname/` (oder custom `$LOGROOT`) +Manuelle Installation: +```bash +git clone /esn-support-bash-snippets.git ~/.dev/esn-support-bash-snippets +cd ~/.dev/esn-support-bash-snippets/legacy/exitrace +chmod +x exitrace.sh +ln -sf ~/.dev/esn-support-bash-snippets/legacy/exitrace/exitrace.sh ~/bin/exitrace +``` + +## Voraussetzungen + +- **LUSER Environment Variable** ODER installiertes `go` Tool +- **SSH-Zugang** zu `logger.in.nessus.at` +- Standard Unix-Tools (awk, grep, date, ssh/scp) +- `dig` (optional, fĂŒr --mx Feature) + +**Setup:** +```bash +export LUSER="dein-username" +# Oder in ~/.bash_env fĂŒr permanente Konfiguration +echo 'export LUSER="dein-username"' >> ~/.bash_env +``` --- @@ -44,24 +64,43 @@ exitrace (durchsucht heutiges Log ohne Filter) ### Beispiele + +**HĂ€ufige Use-Cases:** ```bash -# Mail-Trace einer konkreten Message-ID -exitrace -m 1uwRvz-000Fz2-CI +# Mail-Trace fĂŒr spezifischen Absender zu t-online.de (letzte 48h) +exitrace -FROM franziskus@adjuva.info -DOMAIN t-online.de -H 48 -# Alle Mails von bestimmtem Absender in den letzten 48 Stunden -exitrace -f sender@example.com -H 48 +# Alle Mails an bestimmte Domain in Zeitspanne +exitrace -DOMAIN gmx.de -r 2025-09-10..2025-09-11 -# EmpfĂ€nger-Domain in Zeitspanne -exitrace -D example.de -r 2025-09-09..2025-09-11 +# Konkrete Message-ID verfolgen +exitrace -MSGID 1uwRvz-000Fz2-CI -# Regex-Filter auf EmpfĂ€nger + konkretes Datum -exitrace -t '.*@example\.de' -d 2025-09-10 +# Regex-Filter auf EmpfĂ€nger + MX-Records anzeigen +exitrace -TO '.*@gmail\.com' -d 2025-09-11 --mx -# Kombinierte Filter: Absender + Domain + Zeitfenster + MX-Info -exitrace -f sender@example.com -D example.de -H 48 --mx +# Kombinierte Filter: Absender + Domain + Zeitfenster +exitrace -FROM noreply@company.com -DOMAIN outlook.com -H 24 +``` -# Dry-Run: zeigt nur, welche Logfiles durchsucht wĂŒrden +**Debugging & Analyse:** +```bash +# Dry-Run: zeigt nur welche Logfiles durchsucht wĂŒrden exitrace -n -H 24 + +# Alle Mails von Domain in letzten 7 Tagen +exitrace -FROM '.*@problematic-domain\.com' -DAYS 7 + +# ZusĂ€tzlicher Regex-Filter +exitrace -DOMAIN example.com -GREP "550.*blocked" -H 12 +``` + +**Backwards Compatibility:** +```bash +# Alte Parameter funktionieren weiterhin +exitrace -f sender@domain.com -D example.de -H 48 +exitrace -m 1uwRvz-000Fz2-CI +exitrace -t '.*@gmail\.com' --mx ``` --- @@ -78,34 +117,55 @@ Zeitfenster (eine Option wĂ€hlen): -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 " 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 + -FROM, --from ADDR Envelope-From / "from <...>" (alias: -f) + -TO, --to REGEX EmpfĂ€nger (Regex, matcht nach " for " oder in "** ...") (alias: -t) + -DOMAIN, --domain NAME Ziel-Domain (z. B. example.de), prĂŒft auf Zustellungen/Fehler dorthin (alias: -D) + -MSGID, --msgid ID Exim-Message-ID (z. B. 1uwRvz-000Fz2-CI) (alias: -m) + -GREP, --grep REGEX ZusĂ€tzlicher Regex auf Logzeilen (alias: -G) Sonstiges: --mx Zeigt MX-EintrĂ€ge (und A/AAAA) fĂŒr --domain - -n, --dry-run Zeigt nur, welche Logfiles untersucht wĂŒrden + -n, --dry-run Zeigt nur, welche Logfiles untersucht wĂŒrden -h, --help Diese Hilfe + +Remote Execution: + Wird automatisch remote auf logger.in.nessus.at ausgefĂŒhrt. + Verwendet 'go logger' oder 'ssh ${LUSER}@logger.in.nessus.at'. ``` --- ## Beispielausgabe +### Erfolgreiche Zustellung ``` -[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 +[OK] ID=1v2K8X-0004Zm-BC | First=2025-09-11 08:32:15 | From=franziskus@adjuva.info | Rcpts=user@t-online.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 +ID: 1v2K8X-0004Zm-BC +First: 2025-09-11 08:32:15 +Last: 2025-09-11 08:32:47 +From: franziskus@adjuva.info +Rcpts: user@t-online.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 R=dnslookup T=remote_smtp H=mx.example.de [10.0.0.2] +2025-09-11 08:32:15 | <= franziskus@adjuva.info H=mail.adjuva.info [10.0.0.1] P=esmtp S=2156 +2025-09-11 08:32:47 | => user@t-online.de R=dnslookup T=remote_smtp H=mx01.t-online.de [217.5.206.120] +------------------------------------------------------------------------ +``` + +### Fehlgeschlagene Zustellung +``` +[FAIL] ID=1v2L9Y-0005Ap-DE | First=2025-09-11 09:15:32 | From=franziskus@adjuva.info | Rcpts=blocked@t-online.de | Delivered=0 Deferred=0 Failed=1 +------------------------------------------------------------------------ +ID: 1v2L9Y-0005Ap-DE +First: 2025-09-11 09:15:32 +Last: 2025-09-11 09:15:55 +From: franziskus@adjuva.info +Rcpts: blocked@t-online.de +Status: FAIL (Delivered=0, Deferred=0, Failed=1) +Log: +2025-09-11 09:15:32 | <= franziskus@adjuva.info H=mail.adjuva.info [10.0.0.1] P=esmtp S=1847 +2025-09-11 09:15:55 | ** blocked@t-online.de R=dnslookup T=remote_smtp H=mx01.t-online.de [217.5.206.120]: SMTP error from remote mail server after RCPT TO:: 550 requested action not taken: mailbox unavailable ------------------------------------------------------------------------ ``` @@ -138,32 +198,66 @@ Bei Delivery-Stalls: Nach Installation ĂŒber `./install.sh` ist das Script direkt verfĂŒgbar: ```bash -exitrace -m 1uwRvz-000Fz2-CI +exitrace -FROM franziskus@adjuva.info -DOMAIN t-online.de -H 48 ``` -Das Installationsscript erstellt automatisch einen Symlink in `~/bin` (ohne `.sh` Extension). - -Umgebungsvariable fĂŒr abweichenden Logpfad: +**LUSER Environment Variable setzen (wichtig!):** ```bash -export LOGROOT="/var/log/custom" +# TemporĂ€r +export LUSER="dein-username" + +# Permanent in ~/.bash_env (empfohlen) +echo 'export LUSER="dein-username"' >> ~/.bash_env +source ~/.bash_env ``` -Logger-spezifisch ggf. in `~/.profile` ergĂ€nzen: +**Verbindungstest:** ```bash -cd /var/log/easyname/$(date +%Y)/$(date +%m)/ +# Test ob go-Tool verfĂŒgbar +go logger + +# Test ob SSH funktioniert +ssh ${LUSER}@logger.in.nessus.at "hostname" ``` --- -## Notes +## Troubleshooting -- 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 +### HĂ€ufige Probleme + +**"LUSER Variable nicht gesetzt"** +```bash +export LUSER="dein-username" +``` + +**"Permission denied" oder SSH-Fehler** +- Kerberos-Login: `kinit ${LUSER}@NESSUS.AT` +- SSH-Keys prĂŒfen oder `go` Tool installieren + +**"Keine Logfiles gefunden"** +- Zeitfenster zu eng: `-H 48` oder `-DAYS 3` probieren +- Dry-run verwenden: `exitrace -n -H 24` + +**AWK-Errors** +- Regex-Syntax prĂŒfen bei `-t` und `-G` Optionen +- Sonderzeichen escapen: `.*@example\.com` + +### Performance-Tipps + +- **Kleine Zeitfenster**: `-H 24` statt `-DAYS 7` +- **Spezifische Filter**: `-f` oder `-m` sind schneller als `-t` +- **Dry-Run nutzen**: `-n` zeigt Suchbereich ohne AusfĂŒhrung + +--- + +## Technical Notes + +- **Remote-AusfĂŒhrung**: Komplettes Script wird via SSH Heredoc ĂŒbertragen +- **Log-Format**: `/var/log/easyname/YYYY/MM/YYYY-MM-DD.log(.gz)` auf logger +- **Status-Logik**: Basiert auf SMTP-Response-Codes und Exim-Nachrichten +- **Komprimierte Archive**: Automatische .gz-Verarbeitung via `zcat` +- **Chronologische Sortierung**: Nach Message-ID Erstkontakt +- **Exit-Codes**: 0 = OK (auch bei 0 Treffern), 1 = Parameter-/Verbindungsfehler Built with the help of Claude Code \ No newline at end of file diff --git a/legacy/exitrace/exitrace.sh b/legacy/exitrace/exitrace.sh index 2f8b42f..fffebc2 100755 --- a/legacy/exitrace/exitrace.sh +++ b/legacy/exitrace/exitrace.sh @@ -33,11 +33,11 @@ Zeitfenster (eine Option wĂ€hlen): -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 ' for ' oder in '** rcpt') - -D, --domain NAME Ziel-Domain (z. B. example.de) - -m, --msgid ID Exim-Message-ID (z. B. 1uwRvz-000Fz2-CI) - -G, --grep REGEX ZusĂ€tzlicher Regex auf Logzeilen + -FROM, --from ADDR Envelope-From / "from <...>" + -TO, --to REGEX EmpfĂ€nger (Regex, matcht ' for ' oder in '** rcpt') + -DOMAIN, --domain NAME Ziel-Domain (z. B. example.de) + -MSGID, --msgid ID Exim-Message-ID (z. B. 1uwRvz-000Fz2-CI) + -GREP, --grep REGEX ZusĂ€tzlicher Regex auf Logzeilen Sonstiges: --mx Zeigt MX-EintrĂ€ge (und A/AAAA) fĂŒr --domain @@ -45,9 +45,9 @@ Sonstiges: -h, --help Diese Hilfe Beispiele: - exitrace -f sender@example.com -D example.de -H 48 - exitrace -m 1uwRvz-000Fz2-CI - exitrace -t '.*@example.de' -r 2025-09-09..2025-09-11 --mx + exitrace -FROM sender@example.com -DOMAIN example.de -H 48 + exitrace -MSGID 1uwRvz-000Fz2-CI + exitrace -TO '.*@example.de' -r 2025-09-09..2025-09-11 --mx Note: Wird automatisch remote auf logger.in.nessus.at ausgefĂŒhrt. USAGE @@ -118,23 +118,23 @@ while [[ $# -gt 0 ]]; do validate_date_range "$DATE_RANGE" REMOTE_ARGS+=("$1" "$2") shift 2 ;; - -f|--from) + -FROM|--from|-f) FROM="${2:-}" REMOTE_ARGS+=("$1" "$2") shift 2 ;; - -t|--to) + -TO|--to|-t) TO_REGEX="${2:-}" REMOTE_ARGS+=("$1" "$2") shift 2 ;; - -D|--domain) + -DOMAIN|--domain|-D) TARGET_DOMAIN="${2:-}" REMOTE_ARGS+=("$1" "$2") shift 2 ;; - -m|--msgid) + -MSGID|--msgid|-m) MSGID="${2:-}" REMOTE_ARGS+=("$1" "$2") shift 2 ;; - -G|--grep) + -GREP|--grep|-G) GREPEXTRA="${2:-}" REMOTE_ARGS+=("$1" "$2") shift 2 ;; @@ -284,11 +284,11 @@ while [[ $# -gt 0 ]]; do -DAYS|--days) DAYS="${2:-}"; shift 2 ;; -d|--date) DATE_ONE="${2:-}"; shift 2 ;; -r|--range) DATE_RANGE="${2:-}"; shift 2 ;; - -f|--from) FROM="${2:-}"; shift 2 ;; - -t|--to) TO_REGEX="${2:-}"; shift 2 ;; - -D|--domain) TARGET_DOMAIN="${2:-}"; shift 2 ;; - -m|--msgid) MSGID="${2:-}"; shift 2 ;; - -G|--grep) GREPEXTRA="${2:-}"; shift 2 ;; + -FROM|--from|-f) FROM="${2:-}"; shift 2 ;; + -TO|--to|-t) TO_REGEX="${2:-}"; shift 2 ;; + -DOMAIN|--domain|-D) TARGET_DOMAIN="${2:-}"; shift 2 ;; + -MSGID|--msgid|-m) MSGID="${2:-}"; shift 2 ;; + -GREP|--grep|-G) GREPEXTRA="${2:-}"; shift 2 ;; --mx) WANT_MX=1; shift ;; -n|--dry-run) DRYRUN=1; shift ;; *) shift ;;