Files
memory/patterns/systemd-path-blindness.md
T
2026-10-08 22:00:16 +00:00

50 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
pattern_id: PAT-015
title: "systemd-PATH-Blindness: binaries aus ~/.local/bin verschwinden im Service-Kontext"
category: infrastructure
severity: high
status: active
first_observed: 2026-10
last_updated: 2026-10-08
related_systems: [hermes-agent-01, systemd]
related_solution_docs: [docs/solutions/bug-fixes/2026-10-08-hermes-offsite-backup-aws-path-rca.md]
related_skills: []
---
# PAT-015 — systemd-PATH-Blindness
**Trigger**: Ein Skript, das interaktiv/per SSH fehlerfrei läuft, stirbt als systemd-Service mit
`command not found` (Exit 127) — typischerweise bei pip-user-installierten CLIs (`aws`, `uv`),
Node/npm-Tools oder allem unter `$HOME/.local/bin`, `$HOME/.cargo/bin`, `/opt/*`.
## Symptom
- Journal: `<script>: line NN: aws: command not found` → `status=127`
- Dieselbe Binary funktioniert problemlos in der interaktiven Shell desselben Users.
- Bei `set -e`-Skripten mit Cleanup AM ENDE: sekundär Müll-Akkumulation, weil der Exit
vor dem Aufräumschritt liegt.
## Root Cause
systemd startet Units mit definiertem Minimal-PATH (`/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`),
OHNE die User-Shell-Profile zu sourcen. Pip `--user`-Installationen landen in `~/.local/bin`,
das nur via `~/.profile`/shell-Init in PATH kommt. Interaktiv≠Serviceland.
## Mitigation
1. **Robuste Variante (im Skript):** Absolutpfad mit Fallback-Kette:
`BIN="$(command -v foo || true)"; [ -z "$BIN" ] && BIN="/home/user/.local/bin/foo"; [ -x "$BIN" ] || exit 1`
2. **Unit-seitig:** Drop-in `Environment="PATH=/home/user/.local/bin:$PFAD"` — macht ALLE
Scripts der Unit robust, auch solche Dritter.
3. **Cleanup-Traps:** `trap 'rm -f "$TMPFILE"' EXIT` — garantiert Aufräumen bei JEDEM Exit,
egal wo `set -e` zuschlägt.
## Prevention
- Beim Schreiben neuer systemd-Units mit User-Skripten: PATH-Annahme niemals erben lassen.
- Watchdog-Muster: Backup-Jobs brauchen Alter-des-letzten-Erfolgs-Monitoring (still sterbende
Jobs bleiben sonst Wochen unsichtbar — hier 10+ Tage TOOT).
- Bei Exit-127 im Journal zuerst PATH-Differenz interaktiv vs. Service prüfen (`systemctl show -p Environment`).
## Evidence
- 2026-10-08: hermes-backup.service (backup-to-s3.sh, täglich 04:00 UTC) Exit 127 seit ≥27.09.,
10× ~2G-Tarballs in /tmp bis Root-FS 100 %. Fix: Skript-AWS_BIN + Drop-in-PATH + trap.
Verifikation: Produktionslauf SUCCESS + S3-Readback 2.284.533.218 B.
→ docs/solutions/bug-fixes/2026-10-08-hermes-offsite-backup-aws-path-rca.md