CrumbCodex-v.0.0/waldmitte/tools/cf_tools.md

title, slug, lang, summary, tags

title	slug	lang	summary	tags
cf_tools	cf_tools	de	Kurzbeschreibung hier.	Crumbforest

cf_tools

Kurzer Einstiegstext.

Notizen

• Punkt 1
• Punkt 2

FAQ

Q: Worum geht es? A: …

CF Tools — Kurz-Doku (Stand heute)

Ziel: Kleine, robuste Shell-Hilfen rund um unseren Snapshot-Collector unter /var/cf. Fokus: Übersicht behalten, Qualität prüfen, aufräumen – ohne den Live-Betrieb zu stören.

---

Verzeichnis-Layout

/var/cf
├── snapshots/               # Bilder, nach Layer/Device
│   └── L1/
│       └── SVGA_ESP01/
│           ├── 1758995431.jpg
│           └── ...
└── index/                   # flache Indizes je Device (optional)
    └── L1-SVGA_ESP01.txt

---

Voraussetzungen

• Debian/Raspberry Pi OS (arm64) oder ähnlich
• Bash, coreutils, findutils
• jq (für JSON-Ausgabe): sudo apt-get install -y jq
• Optional: inotify-tools für Live-Follow: sudo apt-get install -y inotify-tools

---

Installation

# Datei ablegen & ausführbar machen:
sudo tee /usr/local/bin/cf-tools.sh >/dev/null <<'SH'
# (hier steht dein cf-tools.sh Inhalt)
SH
sudo chmod +x /usr/local/bin/cf-tools.sh

# Bequemer Kurzbefehl:
sudo ln -sf /usr/local/bin/cf-tools.sh /usr/local/bin/cf-tools

Standardpfade sind im Script fix: ROOT=/var/cf, SNAPS=$ROOT/snapshots, INDEX=$ROOT/index.

---

Schnellstart

# Letzte 60 Minuten – Bilder pro Device zählen (Layer L1):
cf-tools recent L1 60

# Top-5 Talker im 60-Minuten-Fenster:
cf-tools top L1 60 5

# Kennzahlen eines Geräts (Text):
cf-tools device L1 SVGA_ESP04

# Kennzahlen als JSON (ideal für Monitoring):
cf-tools device-json L1 SVGA_ESP04 | jq

# Letzte Datei (voller Pfad):
cf-tools last-file L1 SVGA_ESP10

# Doppelte Layer/Device-Pfade finden:
cf-tools dupe-ids

---

Kommandoreferenz

Basics

• cf-tools recent [LAYER] [min] Zählt pro Device die Dateien der letzten min Minuten (Default: L1, 60).

• cf-tools top [LAYER] [min] [N] Sortiert nach Anzahl, zeigt Top-N (Default: L1, 60, 5).

• cf-tools device LAYER DEVICE Einzeilige Kennzahlen: TOTAL, SIZE, AGE_S, RECENT_60m, LAST.

• cf-tools device-json LAYER DEVICE Gleiches als JSON (für Prom/Logs/API-Verbrauch).

• cf-tools last-file LAYER DEVICE Gibt den Pfad der jüngsten Datei zurück.

• cf-tools dupe-ids Zeigt doppelte Paare LAYER/DEVICE (z. B. Tippfehler oder doppelt geflashte IDs).

Maintenance

• cf-tools prune-empty Leere Verzeichnisse entfernen.

• cf-tools rebuild-index Baut index/LAYER-DEVICE.txt aus Dateinamen/Mtime neu.

• cf-tools fix-perms Setzt Besitz sysop:sysop und 2775 rekursiv auf /var/cf.

Misc

• cf-tools gallery-url LAYER DEVICE Linksnack zur Mini-Gallery des Collectors.

• cf-tools follow LAYER DEVICE (optional, braucht inotify-tools) Live-Anzeige neuer Dateien (nur Dateinamen; sicher für Produktion).

• cf-tools purge LAYER DEVICE [older_min] Vorsichtig: Löscht Dateien älter als older_min Minuten (Default: 60).

---

Beispiele (typische Checks)

1) Wer sendet gerade regelmäßig?

cf-tools top L1 10 10

2) Ist ein bestimmtes Device frisch?

cf-tools device L1 SVGA_ESP07
# ... AGE_S=3  RECENT_60m=355  -> OK

3) Monitoring-Hook (JSON)

cf-tools device-json L1 SVGA_ESP05 | jq -r '.age_s'
# → Zahl in Sekunden (z.B. für Alarm, falls > 60)

4) Nach Cleanup leere Ordner entfernen

cf-tools prune-empty

5) Rechte nach Restore reparieren

cf-tools fix-perms

---

Zusammenspiel mit unseren Diensten

• Collector (FastAPI) schreibt Bilder nach /var/cf/snapshots/<Layer>/<Device>/...
• Retention (systemd timer) hält das Volumen sauber (z. B. >7 Tage löschen)
• Doctor (manuell/cron): Health-Report über alle Devices (Durchsatz, Stale, Disk)

cf-tools ergänzt das Trio: schnelle Sichtbarkeit, Ad-hoc-Wartung, Skript-Hooks.

---

Optional: kleine Automatisierungen

Top-Talker minütlich in ein Log (Beispiel)

sudo tee /usr/local/bin/cf-top-minute.sh >/dev/null <<'BASH'
#!/usr/bin/env bash
set -euo pipefail
stamp=$(date '+%F %T')
echo "[$stamp]" >> /var/log/cf-top.log
cf-tools top L1 10 10 >> /var/log/cf-top.log
echo >> /var/log/cf-top.log
BASH
sudo chmod +x /usr/local/bin/cf-top-minute.sh

/etc/systemd/system/cf-top-minute.timer

[Unit]
Description=CF Top Minute Timer
[Timer]
OnCalendar=*:*:00
Unit=cf-top-minute.service
Persistent=true
[Install]
WantedBy=timers.target

/etc/systemd/system/cf-top-minute.service

[Unit]
Description=CF Top Minute
[Service]
Type=oneshot
ExecStart=/usr/local/bin/cf-top-minute.sh

Aktivieren:

sudo systemctl daemon-reload
sudo systemctl enable --now cf-top-minute.timer

---

Best Practices

• NTP aktiv: saubere Timestamps → schöne Dateinamen & zuverlässige „Age“-Checks.
• IDs eindeutig: pro ESP eindeutige DEVICE_ID; Duplikate mit dupe-ids aufspüren.
• Retention früh festlegen: z. B. 48 h für Rohbilder; Alarme & Pose-Snippets länger.
• Rechte konsistent: nach manuellen Kopieraktionen cf-tools fix-perms.
• Stille Geräte im Blick: AGE_S/RECENT_60m per JSON ins Monitoring aufnehmen.

---

Troubleshooting (kurz)

• Ordner existiert nicht: not found: /var/cf/snapshots/L1/XYZ → Device/Layer-Name prüfen (Groß/Klein), ESP-Konfig, Collector-Logs.

• AGE_S sehr groß / RECENT_60m = 0: → ESP online? WLAN/MQTT/Collector erreichbar? cf-doctor.sh laufen lassen.

• Viele leere Ordner: → cf-tools prune-empty

• Index veraltet: → cf-tools rebuild-index

---

Roadmap (wenn wir Lust haben)

• cf-tools summary (kompakter Gesamtstatus aller Devices)
• cf-tools stale [min] (nur Ausreißer listen)
• cf-tools to-archive (Stundenclips vorbereiten, Übergabe an ffmpeg-Job)
• Export als Prometheus-Textformat

---

That’s it. Schlank, CLI-freundlich, gut skriptbar – und nah dran am, was wir wirklich täglich brauchen.