Fehlerbehebung

Die häufigsten Fälle – und wie du sie einkreist.

Das Gerät erscheint nicht im Dashboard #

Prüf zuerst, ob der Agent überhaupt angebunden ist:

node64-agent status

Steht dort „nicht angebunden", fehlt das Enrollment:

node64-agent enroll --token=dein-token

Ein Token ist einmal verwendbar und läuft ab. Hol dir im Zweifel einen neuen im Dashboard.

Der Agent meldet, aber nichts kommt an #

systemctl status node64-agent
journalctl -u node64-agent -n 50

Häufige Meldungen:

401 unauthorized: Invalid or revoked device key Der Schlüssel gilt nicht mehr – das Gerät wurde im Dashboard gelöscht, oder es wurde anderswo neu angebunden. Ein erneutes enroll erzeugt einen neuen Schlüssel.

Server nicht erreichbar DNS oder ausgehende Verbindung. Test:

curl -sS https://app.node64.de/api/v1/openapi.json | head -c 100

Upload abgelehnt: too large Sehr grosse Paketbestände. Melde dich – das ist ein Fall für uns, nicht für dich.

Der Container sieht nur sich selbst #

Läuft der Agent im Container ohne NODE64_HOST_ROOT, meldet er den Container – wenige Pakete, keine Dienste, keine Firewall. Das ist technisch richtig und meistens nicht gemeint. Richtig:

-e NODE64_HOST_ROOT=/host -v /:/host:ro

Nach einem Neustart ist es ein neues Gerät #

Dann fehlt ein dauerhaftes Volume für /var/lib/node64. Dort liegt die Identität. Ohne Volume bindet sich der Agent bei jedem Start neu an.

Befunde verschwinden nicht, obwohl behoben #

Drei häufige Gründe:

1. Der Dienst wurde nicht neu geladen. sshd_config geändert, aber systemctl reload ssh vergessen – dann gilt die alte Konfiguration weiter, und NODE64 misst die alte.
2. Ein Neustart steht aus. Aktualisierte Bibliotheken wirken erst, wenn die Prozesse sie neu laden.
3. Der nächste Lauf war noch nicht. Mit node64-agent once sofort auslösen.

Ein Befund kommt immer wieder #

Wenn eine Änderung bei jedem Lauf zurückgesetzt wird, schreibt sie meist ein Konfigurationsmanagement (Ansible, Puppet, cloud-init) neu. Passe die Vorlage dort an – sonst gewinnt sie jede Nacht.

Der Agent findet keine Firewall #

eingeschraenkt: firewall (kein Firewall-Werkzeug gefunden) heisst: Es ist weder nft, iptables, ufw noch firewalld installiert. In einem Container ist das normal – die Firewall liegt beim Host.

Der Agent meldet ehrlich, was er nicht erheben konnte, statt Lücken als „alles in Ordnung" auszugeben.

Die öffentliche Adresse stimmt nicht #

Hinter einem Reverse Proxy oder in einem internen Netz sieht der Agent nicht die Adresse, unter der dein Dienst erreichbar ist. Beantworte in dem Fall die Rückfrage am Gerät („Ist dieses System aus dem Internet erreichbar?") – die Selbstauskunft ist hier die genauere Information.

Nichts hilft #

Schick uns die Ausgabe von node64-agent status und die letzten Zeilen aus journalctl -u node64-agent. Beides enthält keine Geheimnisse – aber sag trotzdem kurz Bescheid, wenn du etwas herausgestrichen hast. Kontakt