---
title: cf_tools
slug: cf_tools
lang: de
summary: Kurzbeschreibung hier.
tags: [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

```bash
# 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

```bash
# 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?**

```bash
cf-tools top L1 10 10
```

**2) Ist ein bestimmtes Device frisch?**

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

**3) Monitoring-Hook (JSON)**

```bash
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**

```bash
cf-tools prune-empty
```

**5) Rechte nach Restore reparieren**

```bash
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)**

```bash
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`

```ini
[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`

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

Aktivieren:

```bash
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.