handbuch.md — CrumbForest / crumbcollector Betriebshandbuch

Für Menschen und für andere KI-Instanzen, die ohne Session-Kontext
verstehen müssen: was ist das hier, wie ist es aufgebaut, was ist zu
beachten. Stand: 2026-07-12.

Vorwort

Dieses Handbuch beschreibt keinen Scanner.

Es beschreibt einen Sammler.

Ein Sammler verändert den Wald nicht.

Er hört zu.

Er sammelt.

Er dokumentiert.

Er legt einen Checkpoint an.

Er wartet auf die Entscheidung eines Menschen.

Erst danach beginnt ein Import.

Darum besitzt crumbcollector keine Abkürzung
an der Passkante.

Der Wald kennt seine eigenen Namen.

Der Sammler schreibt sie zuerst auf,
bevor jemand beginnt, sie zu verändern.

1. Was ist crumbcollector

Ein Rust-Binary (src/main.rs), das alte RZ-Nodes read-only über SSH
ausliest und geordnet in eine CrumbForest-NetBox importiert. Kein Ansible,
kein Agent auf den Ziel-Nodes, kein automatischer Write ohne menschliches
--approved.

Pipeline — fünf Kanten, eine Richtung:

sweep/SSH → probe (read-only) → <host_raw.json → transform → classify
  → checkpoint (DryRun) → 3-Pass-Import (--approved schreibt) → Log

CLI-Befehle:

Passkante (CrumbStyle): kein Schreiben auf Legacy-Nodes · kein Massenimport
ohne Checkpoint · kein Abbruch wegen einzelner Stille (ein stummer Node ist
eine Beobachtung, kein Fehler) · keine erfundene Identität · kein Write ohne
Approval · keine Beobachtung ohne Log.

2. Node-Registry (Stand 2026-07-12)

Wichtig: Die crumbzero-Wanderer sind mobile Nodes ohne feste Basis —
"kein WLAN angemeldet" ist ein Normalzustand, kein Fehler.

3. Netzwerk-Topologie

WireGuard-Netz: 10.42.0.0/24
  10.42.0.1   = nullfeld (Cloud-Backbone, Strato-VM, öffentlich erreichbar)
  10.42.0.11  = deepsea
  10.42.0.12  = wolke
  10.42.0.13  = snakeview
  10.42.0.15  = rattlecam
  10.42.0.16  = thinkpad/crumbmaster
  10.42.0.18  = jetpack (GPU-Node, im Heimnetz UND im VPN)
  10.42.0.19  = cruncher
  10.42.0.20  = crumbzero00
  10.42.0.21  = crumbzero01

NetBox-Sites (nicht mit dem Projektnamen "CrumbForest" verwechseln —
CrumbForest ist der Wald, keine einzelne Site!):

Physischer Umzug am 2026-07-12: deepsea, rattlecam und cruncher sind an
diesem Tag in den Container (crumbcase00) umgezogen. wolke war schon vorher
extern (LTE4-Container) und ist jetzt auf roaming gemappt. snakeview blieb
im Baumhaus. Die alten eth0-IPs in den raw.json-Dumps (z.B. 192.168.1.x
bei deepsea) sind teils stale/gecacht von vor dem Umzug — nicht blind
danach die Site ableiten, lieber beim Menschen nachfragen.

Bekannte Störquelle: MikroTik / "Pelikan-VLAN"

Ein MikroTik-Board sitzt zwischen mehreren Nodes und dem Rest des Netzes.
Symptom: ICMP-Ping geht durch, SSH auf Port 22 hängt komplett (kein
Reject, kein Timeout — echtes Blackhole). Betroffen bisher: thinkpad. Das
88er-Subnet (192.168.88.x = MikroTik-Default) bei wolke/rattlecam deutet
auf denselben MikroTik im Pfad hin, auch wenn die Site dafür nicht
zwingend crumbcase00 sein muss. Bei SSH-Fehlern auf diese Nodes zuerst das
MikroTik-Routing prüfen, nicht den Sammler-Code.

4. NetBox-Betrieb

• URL: https://seeds.crumbforest.io
• Token: https://seeds.crumbforest.io/user/api-tokens/, per Env-Var
  NETBOX_TOKEN übergeben (Token-Arg - liest davon)
• Rollen-Mapping: provisioning/node-roles.txt (--roles Flag beim Import)

Bekannter Bug: DeviceType-Duplikate bei Raspberry-Pi-Import

crumbcollector sucht/erzeugt den NetBox-DeviceType nach dem rohen
Modellstring aus der SSH-Probe (z.B. "Raspberry Pi 5 Model B"). Der
kanonische, händisch bereinigte Typ heißt aber "Raspberry Pi 5" (kürzer).
Bei jedem Import, der keinen exakten String-Match findet, legt der Sammler
einen neuen DeviceType an → Duplikat.

Workaround nach jedem Raspberry-Pi-Import:
1. Betroffene Devices per PATCH /api/dcim/devices/<id/ auf den
kanonischen DeviceType umhängen ({"device_type": <kanonische-id})
2. Das leere Duplikat per DELETE /api/dcim/device-types/<id/ löschen
(nur wenn device_count == 0)

Echter Fix wäre in src/transform.rs — Modellstring vor dem Lookup
normalisieren (z.B. " Model B"-Suffix strippen) oder Lookup über
Manufacturer+Fuzzy-Match statt exact-string. Bisher nicht umgesetzt,
zweimal in Folge manuell nachgeputzt (2026-07-10, 2026-07-12).

thinkpad: Route über nullfeld statt Jetpack

Am 2026-07-12 war thinkpad per SSH erreichbar, als der Login über
10.42.0.1 (nullfeld) lief — direkt von Jetpack (10.42.0.18) aus blieb
Port 22 auf 10.42.0.16 dagegen ein Blackhole (siehe §3, MikroTik/
Pelikan-VLAN). Für künftige Collect-Läufe auf thinkpad: nullfeld als
Control-Node/Jump-Host probieren, nicht nur Jetpack.

5. Zugriff & Keys

• Alle Keys liegen auf dem Mac (~/.ssh/crumbforest_*) + USB-Backup. Kein
  zweiter vollständiger Key-Satz (offener Punkt, siehe Roadmap).
• SSH-Aliase (~/.ssh/config): jetpack (192.168.1.172, LAN), strato
  (194.164.194.191 = nullfeld, User branko) — strato-Key war am
  2026-07-12 nicht mehr autorisiert (Permission denied), nicht ungeprüft
  als funktionierend annehmen.
• Control-Node für VPN-interne Nodes ist Jetpack, nicht der Mac — der
  Mac hat nicht immer einen aktiven WireGuard-Tunnel. Vor jedem
  VPN-Reachability-Check erst prüfen: ifconfig | grep 10.42.0.
• Automatischer Tageslauf: provisioning/crumb-sammler.{sh,service,timer}
  auf Jetpack, täglich 03:00 CEST, schreibt nach ~/CrumbCollector_v0/inventar/.

6. Git-Workflow — Achtung Mehrfach-Autor

Dieses Repo wird von mehreren Clients direkt auf main gepusht
(dieser Mac, Claude Desktop, evtl. weitere Sessions). Vor jeder eigenen
Arbeit:

git fetch origin
git status   # eigene uncommitted/untracked Files prüfen
git pull --ff-only

_raw.json-Dateien (Node-Dumps mit IPs/MACs/Serials) niemals commiten
— .gitignore deckt *_raw.json seit 2026-07-12 ab (vorher griff nur
*.raw.json, die Unterstrich-Namenskonvention lief durch).

7. Offene Punkte

• Key-Spiegelung auf Jetpack/Nullfeld für Multi-Crew-Zugriff
• DeviceType-Dedup-Bug in transform.rs (siehe §4) noch nicht im Code gefixt
• thinkpad-Collect über nullfeld als Control-Node noch nicht getestet (nur manueller Login bestätigt, kein crumbcollector collect bisher erfolgreich)
• strato-SSH-Key-Zugriff auf nullfeld prüfen/erneuern