Troubleshooting

Node erscheint nicht im Dashboard

Der Agent konnte sich nicht registrieren. Prüfe der Reihe nach:

Token abgelaufen/verbraucht? Pairing-Tokens sind einmalig und 15 Minuten gültig. Erzeuge im Wizard einen neuen.
Ausgehend geblockt? Der Host braucht ausgehend UDP zum WireGuard-Port und HTTPS (443) — siehe Firewall & Ports.
BP_CONTROL_URL korrekt? Muss auf die erreichbare Zentrale zeigen (mit https://).
Agent-Logs ansehen:
Terminal window
```
docker logs -f blackprotect-node
```
Die Zeile registered as node <id> bestätigt eine erfolgreiche Registrierung.

Node ist „eingeschränkt” oder „offline”

Der Status richtet sich nach dem letzten Heartbeat: eingeschränkt ab > 90 s, offline ab > 5 min ohne Heartbeat.

Läuft der Container noch? docker ps | grep blackprotect-node
Steht der Tunnel? Im Container: wg show — es sollte ein aktueller latest handshake erscheinen.
Bei kurzem Tunnel-Abbruch verbindet sich der Agent automatisch mit Backoff neu; der Schutz läuft dabei mit der zuletzt bekannten Konfiguration weiter.

Konfiguration wird nicht angewendet

Konfig-Updates werden beim nächsten Heartbeat übernommen (Standard alle 30 s). Wenn Regeln nicht greifen:

Ist ein kompiliertes XDP-Objekt vorhanden? Ohne bp_filter.o läuft der Filter im Scaffold-Modus und meldet im Log:
```
[xdp-apply] no compiled XDP object ... running in scaffold mode (rules NOT enforced in-kernel)
```
In diesem Modus ist die Steuerung aktiv, die Regeln werden aber noch nicht im Kernel durchgesetzt. Das kompilierte Objekt wird separat bereitgestellt/eingehängt.
Prüfe, dass die Konfiguration im Dashboard gültiges JSON ist (der Editor lehnt ungültiges JSON beim Speichern ab).

XDP-Attach schlägt fehl

attach failed (needs NET_ADMIN + XDP-capable NIC/driver)

Fehlen --cap-add=NET_ADMIN / --cap-add=SYS_MODULE? Container mit den Rechten aus den Systemvoraussetzungen starten.
Unterstützt der NIC-Treiber kein natives XDP, greift automatisch Generic-XDP (höherer CPU-Overhead, aber funktionsfähig).

Node nach Neustart erneut registrieren?

Nein — sofern /var/lib/blackprotect als Volume eingehängt ist. Der Agent stellt Identität, Schlüssel und letzte Konfiguration aus dem State wieder her und baut den Tunnel ohne neuen Token auf. Ohne persistenten State ist ein neuer Pairing-Token nötig.

Weiter Hilfe nötig?

Melde dich im Discord oder über die Kontakt-Seite — halte die Ausgabe von docker logs blackprotect-node bereit.