English

Fehlerbehebung

Alle bekannten Probleme an einer Stelle. Suchen Sie unten Ihren Fall. Auf dem Gateway zeigt das Protokoll des Agenten, was er gerade tut:

journalctl -u bootstrap-agent.service -n 50

Das Gerät erscheint nicht in der Liste

Wo: Devices in der Konsole.

• Es wurde nie hinzugefügt. Fügen Sie es hinzu, siehe Gerät hinzufügen, oder übernehmen Sie es, siehe Massenimport und Claim.
• Es wurde in einer anderen Organisation hinzugefügt. Fragen Sie in Ihrem Team, oder suchen Sie die EUI (Strg+K, auf dem Mac ⌘K).

CHAIN_INVALID, obwohl der Upload richtig aussieht

Wo: Geräte-CA registrieren.

Der Check-in eines Geräts scheitert mit CHAIN_INVALID. Alle fünf Ursachen unten führen zu genau diesem Fehler. Prüfen Sie sie deshalb in dieser Reihenfolge:

1. Falsche CA an der Bestellung. Die hochgeladene Geräte-CA ist nicht die CA, die das Geburtszertifikat dieses Geräts tatsächlich ausgestellt hat. Vergleichen Sie Subject, Issuer und Fingerprint im Bereich Trust anchor der Bestellung mit dem, was der Hersteller Ihnen gegeben hat.
2. CN und EUI passen nicht. Der CN im Geburtszertifikat ist nicht die EUI des Geräts. Meist ein Gerät aus der falschen Charge, oder ein umetikettiertes oder doppeltes Gerät.
3. Falsche Bestellung. Das Gerät ist unter einer anderen Bestellung eingetragen als der, zu deren Trust anchor seine Kette führt. Bestellungen sind streng getrennt; so ein Gerät wird abgelehnt statt stillschweigend angenommen. Prüfen Sie, welcher Bestellung ak_fingerprint oder EUI des Geräts tatsächlich zugeordnet sind. Übliche Ursache ist ein doppelter oder verirrter Allowlist-Eintrag an der falschen Bestellung.
4. Gesperrt (widerrufen). Das Zertifikat steht auf der Sperrliste (CRL) des Herstellers. Die veröffentlicht der Aussteller der Geräte-CA, nicht der Chip-Hersteller; das ist eine ganz andere Vertrauenskette. Sehen Sie im Bereich Trust anchor unter CRL status nach. Steht dort „No CRL distribution point declared on this certificate“, wird für diese CA gar nicht auf Sperrung geprüft (diese Installation lehnt ohne angegebene CRL nicht ab).
5. Abgelaufen. Das Geburtszertifikat (nicht nur die CA) ist nicht mehr gültig.

Lösung: Klären Sie erst, welche der fünf Ursachen zutrifft, bevor Sie etwas neu hochladen. Dieselbe CA erneut hochzuladen hilft nicht, wenn CN/EUI, die Bestellung oder eine Sperrung die Ursache ist. Was genau geprüft wird, steht unter Wie die Geräteidentität funktioniert.

TPM-Slots

Wo: GET /v1/status (state, last_error_code, tpm_transient_avail, tpm_transient_capacity, siehe Referenz der lokalen API) und journalctl -u bootstrap-agent.service.

Das TPM hat nur wenige Plätze für temporäre Objekte (3 auf unserem Laborgerät). Der Agent belegt sie für einen Check-in und gibt sie gleich danach frei. Beim Start protokolliert er tpm transient capacity at agent start, und alle 5 Minuten tpm occupancy mit der Zahl der freien Plätze. Ein Check-in scheitert, wenn kein Platz frei ist. Es gibt zwei verschiedene Ursachen.

1. „Kein freier Platz“ beim Start. state ist error, last_error_code ist TPM_STUCK_POWER_CYCLE_REQUIRED, und das Protokoll sagt tpm: no free transient object slots at agent start, before this process created anything. Die Plätze waren belegt, bevor der Agent irgendetwas getan hat, meist von einem anderen Programm auf dem Image, das im selben Zeitfenster beim Start das TPM öffnet (Secure-Boot-Messung, Entsperren der Festplatte, ein weiterer Attestierungsdienst). Der Agent leert in diesem Fall nichts.

Lösung: Trennen Sie das Gerät vom Strom. Ein systemctl restart reicht nicht, und ein Neustart ohne Stromtrennung hat auf unserer Laborplatine nichts geleert. Erholt sich die Zahl nach einer Stromtrennung nicht, prüfen Sie alles auf dem Image, was beim Start /dev/tpmrm0 berührt.

2. Weniger freie Plätze als die Kapazität, während der Agent läuft: ein Leck am Rohgerät. tpm_transient_avail ist kleiner als tpm_transient_capacity, und tpm occupancy zeigt dieselbe Zahl. Wir haben das einmal gesehen, nachdem der Kernel einen Bus-Timeout gemeldet hatte (tpm_try_transmit: send(): error -62): Im Chip blieb ein Objekt zurück, das nur das Rohgerät /dev/tpm0 zeigt, nicht der Resource Manager /dev/tpmrm0. Das Aufräumen beim Start kann das nicht heilen. Es entfernt nur eigene übrig gebliebene Schlüsselobjekte, und nur solche, die über /dev/tpmrm0 sichtbar sind (das einzige TPM-Gerät, das seine Unit erlaubt).

Lösung, als root auf dem Gateway:

tpm2_getcap -T device:/dev/tpm0 handles-transient

tpm2_flushcontext -T device:/dev/tpm0 HANDLE

Nehmen Sie das Handle, das der erste Befehl zeigt und der Resource Manager nicht. Auf dem Laborgerät brachte das die Zahl der freien Plätze auf die volle Kapazität zurück. Ein Neustart des Geräts beseitigt ein solches Leck nicht: Mit einem über das Rohgerät belegten Platz war die Zahl der freien Plätze auf dem Laborgerät vor und nach einem Neustart um eins niedriger. Ein Aus- und Einschalten der Stromversorgung wurde nicht gemessen.

Nutzen Sie /dev/tpm0 nicht für eigene Diagnosen: Ein Objekt, das über das Rohgerät entsteht, bleibt im Chip, eines über /dev/tpmrm0 wird freigegeben, wenn sein Prozess endet (auf dem Laborgerät in beide Richtungen gemessen).

NO_CONFIG

Wo: an der lokalen Schnittstelle des Gateways und am Gerät in der Konsole.

Was Sie sehen: GET /v1/status antwortet mit "state":"no_config", und die Aufrufe, die die Konfiguration lesen, antworten mit 404 und NO_CONFIG.

no_config ist ein normaler Zustand, kein Fehler. Ein Gateway, das niemand übernommen hat oder das noch nicht eingerichtet ist, bleibt so lange darin, wie es dauert, auch Monate, und Ihre eigene Software muss ohne Alarm warten. Suchen Sie nur dann eine Ursache, wenn das Gerät seine Einstellungen haben sollte. Prüfen Sie der Reihe nach:

1. Ist das Gerät in der Konsole, und hat es ein Template? Siehe Das Gerät steht nicht in der Liste und TEMPLATE_INVALID.
2. Was sagt die Plattform? last_error_code in GET /v1/status enthält den Grund der Plattform, wenn sie das Gerät abgewiesen hat, zum Beispiel DEVICE_UNKNOWN, CHAIN_INVALID oder TEMPLATE_INVALID. Die Konsole zeigt einen abgewiesenen Kontakt nicht (siehe Bekannte Lücken und Grenzen); der Support kann ihn auf der Plattform nachsehen.
3. Erreicht das Gateway die Plattform? BOOTSTRAP_AGENT_URL in /etc/bootstrap-agent/agent.env ist gesetzt, und journalctl -u bootstrap-agent.service -n 50 zeigt keinen Netzwerk- oder Zertifikatsfehler.
4. Wurde der Zustand absichtlich gelöscht, zum Beispiel durch einen Werksreset? Dann ist no_config richtig, bis die nächste Einrichtung abgeschlossen ist.

Ist state stattdessen error, liegt der Fehler am Gateway selbst (TPM, Speicher, eine fehlende Adresse), nicht bei der Plattform: siehe den TPM-Abschnitt oben.

TEMPLATE_INVALID

Wo: Template zuweisen.

Die Plattform lehnt die Einrichtung oder den Check-in des Geräts ab, weil die Einstellungen, die es bekäme, nicht gültig sind. Ursachen, die Sie in der Konsole sehen und beheben können:

• Dem Gerät ist gar kein Template zugewiesen.
• Sein Template hat die Zielplattform Generic, aber kein Zertifikat.
• Sein Template hat die Zielplattform Pallax und das Gerät hat kein Pallax-Ziel, oder das Template enthält noch den alten Eintrag _target (siehe Pallax-Ziel fehlt).

Den Code sehen Sie im Protokoll des Agenten und in last_error_code von GET /v1/status. Die Konsole zeigt den abgewiesenen Kontakt nicht: Nachdem das Template von einem Laborgerät entfernt wurde, stand die Ablehnung nur im Dienst-Log der Plattform.

Lösung: Öffnen Sie den Reiter Configuration des Geräts und weisen Sie ein Template zu. Ist schon eines zugewiesen, öffnen Sie dieses Template und ergänzen Sie das fehlende Zertifikat (siehe Zertifikatsaktionen). Ein Gerät, das bei CLAIMED hängen bleibt (siehe unten) und nie PROVISIONED erreicht, hat oft genau diese Ursache, nur schon beim ersten Einrichten statt bei einem späteren Check-in.

Pallax-Ziel fehlt

Was Sie sehen: Die Konsole markiert das Gerät mit Template problem (und ein Pallax-Template, das noch _target enthält, mit Target in template). Die Plattform lehnt den Check-in mit TEMPLATE_INVALID ab; die Detailseite des Geräts zeigt den Grund. Das Gerät behält seine alte Konfiguration oder antwortet lokal mit NO_CONFIG, wenn es keine hat.

Ursache: Pallax-Workspace und Gateway-Typ werden am jeweiligen Gerät gesetzt, nicht im Template. Entweder hat das Gerät beides nicht, oder das Template enthält noch den alten Eintrag _target, der abgelehnt wird.

Lösung: Öffnen Sie das Gerät und setzen Sie Pallax-Workspace und Gateway-Typ (siehe Ziel am Gerät setzen); für viele Geräte nutzen Sie Set Pallax target in der Liste Devices. Öffnen Sie danach das Template und entfernen Sie den Eintrag _target, falls es einen hat. Das Gerät übernimmt die Änderung beim nächsten Check-in; ein bereits eingerichtetes Gerät braucht für ein geändertes Ziel Re-provision.

Gerät bleibt bei CLAIMED

Wo: Template zuweisen, Den Agenten auf das Gateway bringen.

CLAIMED wechselt erst zu PROVISIONED, wenn das Gateway sein erstes Einrichten bei der Plattform abgeschlossen hat. Ein Gerät, das bei CLAIMED bleibt, hat das noch nicht getan. Prüfen Sie der Reihe nach:

1. Hat es ein Template? Siehe TEMPLATE_INVALID oben.
2. Ist das Gateway eingeschaltet und online, und läuft bootstrap-agent.service? Ein Gerät, das sich nie verbunden hat, kann die Plattform nicht weiterbringen.
3. Wurde es als unbekannt abgewiesen? Siehe DEVICE_UNKNOWN unten.
4. Ist seine Vertrauenskette gültig? Siehe CHAIN_INVALID oben.
5. Zeigt das Protokoll reading trust bundle? Die Datei aus BOOTSTRAP_AGENT_TRUST_BUNDLE existiert nicht. Lassen Sie die Einstellung leer, oder legen Sie die Datei ab, die Ihnen der Support gegeben hat, siehe Einstellungen.

Auf der Plattform gibt es keine Aktion zum „Lösen“: Hier hängt kein Datensatz, sondern ein Gateway hat sein Einrichten noch nicht abgeschlossen.

Gerät bleibt bei PROVISIONED

Wo: Software starten und bestätigen.

Das Gateway hat seine Einstellungen, aber für ACTIVE fehlt noch ein Signal: Der Agent meldet confirmed erst, nachdem Ihre Software {"state":"connected"} nach /run/wlpc/target-confirmed geschrieben hat. Prüfen Sie der Reihe nach:

1. Gibt es das Verzeichnis /run/wlpc (root:wlpc, Modus 2775), und kann der Benutzer des Agenten die Datei lesen (0644)? Ist die Unit Ihrer Software in der Gruppe wlpc, und hat sie ReadWritePaths=/run/wlpc? Siehe Wer /run/wlpc schreiben darf.
2. Gibt es die Datei, und sagt sie connected? Sonst schreibt sie nichts.
3. Läuft Ihre Software, und zeigt ihr eigenes Protokoll, dass der Broker die Verbindung ablehnt? Dann prüfen Sie das Zertifikat des Templates, siehe Template erstellen.

Der Agent meldet nie eine Konfiguration, die Ihre Software nicht anwenden konnte, siehe Bekannte Lücken und Grenzen.

DEVICE_UNKNOWN

Wo: journalctl -u bootstrap-agent.service auf dem Gateway.

Die Plattform kennt kein Gerät mit dem AK-Fingerprint dieses Gateways: Das Gerät wurde nie hinzugefügt, oder AK-Fingerprint oder EUI wurden falsch eingegeben. Der abgewiesene Versuch hält den Fingerprint fest, damit der Support ihn nachsehen kann. Fügen Sie das Gerät hinzu oder korrigieren Sie es (Gerät hinzufügen, Gerät bearbeiten) und führen Sie dann systemctl restart bootstrap-agent.service aus. Sonst wartet der Agent nach dieser Abweisung eine Stunde bis zum nächsten Versuch.

Zustand FAILING oder SILENT

Wo: die Spalte HEALTH unter Devices und die Markierung auf der Geräteseite. Nur Geräte, die PROVISIONED oder ACTIVE sind und sich mindestens einmal gemeldet haben, bekommen diese Markierung.

• FAILING: Das Gateway meldet sich immer wieder, schließt den Nachweis seiner Identität aber nie ab (mindestens drei Versuche und kein erfolgreicher Check-in seit drei Check-in-Intervallen, standardmäßig 3 Stunden). Meist ein TPM-Problem am Gateway, siehe den TPM-Abschnitt oben. Das ist nur eine Warnung: Die Plattform unternimmt nichts am Gerät. Installieren Sie das Gateway nicht neu und setzen Sie es nicht zurück, bevor der Support es sich angesehen hat; das kann die Ursache schwerer auffindbar machen.
• SILENT: Seit drei Check-in-Intervallen (standardmäßig 3 Stunden) ist gar nichts angekommen. Häufigste Ursachen:
  • Das Gateway ist ausgeschaltet, oder sein Netzwerkweg zur Plattform ist blockiert (Firewall, Routing, DNS).
  • bootstrap-agent.service läuft nicht.
  • Sein Template setzt ein ungewöhnlich langes check_in_interval_seconds, siehe Neu einrichten.

Beide Markierungen wechseln beim nächsten erfolgreichen Check-in zurück zu HEALTHY. LAST CHECK-IN zeigt die Zeit des letzten erfolgreichen Check-ins, in UTC. Ist das Gateway eingeschaltet und online, läuft bootstrap-agent.service und bleibt der Zustand trotzdem SILENT, wenden Sie sich an den Support (siehe unten).

Die Zertifikatswarnung („Check this credential“)

Wo: Config templates, nach dem Hochladen eines Zertifikats.

Das Zertifikat ist gespeichert, sieht aber für den Broker des Templates falsch aus: von einer Test-CA signiert oder für einen anderen Host ausgestellt. Siehe Template erstellen, Beim Hochladen des Zertifikats.

Support kontaktieren

Hilft hier nichts, wenden Sie sich an den Support. Nennen Sie die EUI des Geräts, was Sie in der Konsole sehen, und die letzten 50 Zeilen des Agenten-Protokolls (der journalctl-Befehl oben auf dieser Seite). Schicken Sie nie private Schlüssel oder Passwörter.