Gateway-Überblick¶

Für alle, die die WLPC-Gateway-Software in ein Gateway einbauen: Hersteller, die ihr eigenes Image bauen. Kunden, die nur die Konsole benutzen, können diesen Abschnitt überspringen.

Unterstützte Architektur ist derzeit nur armv7.

Ein Programm auf dem Gateway spricht mit der Plattform: der Bootstrap-Agent. Er weist die Identität des Gateways mit dem TPM nach, holt die Konfiguration, die Ihr Template beschreibt, speichert sie und gibt sie über einen lokalen Socket an Ihre eigene Software weiter. Er startet oder stoppt Ihre Software nicht, schaltet keine LEDs und löscht keine Daten. Das bleibt bei Ihrem Image.

Zwei Wege zur Installation¶

Manuell installieren: für ein einzelnes Gateway, etwa ein Testgerät eines Integrators oder ein Gateway, das schon im Feld ist. Jeder Schritt läuft auf dem Gateway, mit Befehlen, ohne Installer.
Mit Yocto und RAUC installieren: für Hersteller, die Gateways in Serie bauen. Der Agent kommt in Ihr Image und wird mit ihm aktualisiert. Für Serien ist das der empfohlene Weg.

Den passenden Weg wählen¶

Sie möchten	Lesen	Hinweise
Den Agenten in ein Yocto-Image einbauen und mit RAUC aktualisieren	Mit Yocto und RAUC installieren	Signiertes Release-Archiv, im Rezept festgelegt, kein Installer, kein root.
Den Agenten auf einem einzelnen Gateway ohne Image-Bau installieren, aktualisieren oder entfernen	Manuell installieren	Befehle auf dem Gateway; das Archiv wird dort geprüft, bevor es läuft.
Prüfen, dass ein Download echt ist	Signatur prüfen	Tun Sie das, bevor Sie eine Version festlegen.
Der Plattform sagen, wohin sich das Gateway verbindet	Ziel am Gerät setzen	Pallax-Workspace und Gateway-Typ gehören zum Gerät, nicht zum Template.
Ihre Software starten, sobald die Konfiguration da ist, und das Ziel bestätigen	Software starten und bestätigen	Eine `.path`-Unit und eine Markierungsdatei.
Die Konfiguration aus Ihrer eigenen Software lesen	Referenz der lokalen API	Ein Unix-Socket, kein Netzwerk-Port.
Jeden lokalen Aufruf mit einer echten Antwort sehen	Beispiele der lokalen API	`curl` über den Socket, Werte ersetzt.
Den Agenten von einem Labor-Gateway entfernen oder neu installieren	Deinstallieren	Was im TPM und in `/etc/iot-config` bleibt.
Herausfinden, warum ein Gateway nicht hochkommt	Fehlerbehebung	`NO_CONFIG`, `TEMPLATE_INVALID`, TPM-Slots und der Rest.

Was läuft, und als wer¶

Der Agent ist ein einziger Dienst, bootstrap-agent.service. Er läuft dauerhaft und reagiert auf Ereignisse. Er ist die einzige Unit.

Ein Prozess, eine Unit. Die Unit ist Type=simple mit Restart=on-failure und RestartSec=5s. Der Agent ruft nie systemctl auf und startet keinen anderen Prozess.
Ereignisgesteuert. Eine Schleife wartet auf den lokalen Socket, auf den Check-in-Zeitpunkt (im Agenten selbst geführt) und auf die Bestätigungsmarkierung (siehe Software starten und bestätigen). Gemessen auf dem Laborgerät (Bedingungen unter Größe): In 419 von 434 Fenstern zu je 10 Sekunden machte der Agent keinen einzigen Kontextwechsel; die übrigen 15 Fenster sind die 15 Check-ins.
Keine Rechte. Der Dienst läuft als Benutzer bootstrap-agent (vom Rezept angelegt), mit der Gruppe tss, ohne Capabilities und ohne neue Rechte. Das einzige Gerät, das er öffnen darf, ist der TPM-Resource-Manager /dev/tpmrm0. Gemessen auf dem Laborgerät: alle fünf Capability-Mengen 0, NoNewPrivs 1, Benutzer-ID 988, ein Prozess mit zwei Threads.
Schreibt nur an zwei Stellen: ins Zustandsverzeichnis /etc/iot-config und nach /run/bootstrap-agent. LEDs oder anderen Systemzustand schreibt er nicht.

Größe auf dem Gateway¶

Zwei verschiedene Zahlen, die man leicht verwechselt: was der Agent auf der Platte belegt und was er im Arbeitsspeicher braucht, während er läuft. Planen Sie Ihr Image mit beiden.

RAM im Betrieb. Ein Lauf von 72 Minuten auf einem Laborgerät (armv7, ein Kern, echtes TPM, Root-Dateisystem nur lesbar), mit einem unsignierten Lab-Build des Agenten, nicht mit einem Release-Build. Der Agent machte im Lauf 15 Check-ins. Der Speicher wurde 10-mal pro Sekunde abgetastet.

Wert	Gemessen	Bedeutung
PSS (geteilter Speicher anteilig gezählt)	3,6 bis 4,84 MB, Median 4,83 MB, höchster Wert 4,84 MB	Davon sind rund 1,9 MB der eigene Speicher des Agenten und rund 2,9 MB Seiten des Programms und seiner Bibliotheken.
RSS (alle Seiten, die der Prozess berührt)	7,29 bis 7,32 MB	Zählt die geteilten Bibliotheksseiten voll.
Wachstum des eigenen Speichers	Siehe Bekannte Lücken und Grenzen	In einem längeren Lauf mit einem signierten Build gemessen. Bekannt, nicht behoben.
CPU-Zeit	3,5 s in 72 Minuten

Der PSS schwankt, weil andere Prozesse auf dem Gerät die Bibliotheksseiten mitnutzen; der höchste Wert gilt, wenn kein anderer Prozess sie abbildet. Das ist ein einzelner Lauf auf einem Gerät: Nutzen Sie ihn, um Ihr RAM-Budget zu bemessen, nicht als Zusage.

Platte. Das Programm hat 144.900 Bytes (armv7, gestrippt, Release-Variante, gebaut auf Debian Bookworm). Es ist dynamisch gelinkt, Ihr Image muss also die Bibliotheken liefern, die unter Mit Yocto und RAUC installieren stehen.

Bekannte Lücken und Grenzen¶

Was der Agent nicht tut oder was nicht getestet wurde. Jeder Punkt ist eine Tatsache zu dieser Release-Linie, kein Versprechen.

Lücke oder Grenze	Was es für Sie bedeutet
Der Agent sendet nie `applied: false`.	Eine Konfiguration, die Ihre Software nicht anwenden kann, bleibt der Plattform verborgen: keine Bestätigung und keine Fehlermeldung, die Plattform sieht nur, dass `confirmed` ausbleibt. Die lokale API nimmt `applied: false` an und merkt es sich auf dem Gerät (der `reason` wird nicht gespeichert), meldet es aber nicht weiter, und eine Markierungsdatei mit `connected` überschreibt es mit `applied: true`, siehe `applied: false`.
Eine alte `connected`-Markierung bestätigt auch eine neue Konfiguration.	Der Agent bestätigt eine neue Konfiguration, sobald die Markierung `connected` sagt, auch wenn sie für die vorherige geschrieben wurde. Siehe Software starten und bestätigen.
SIGTERM mitten im Check-in ist getestet; SIGKILL und Stromausfall sind es nicht.	In 15 Tests in einer Testumgebung mit simuliertem TPM und in 3 von 3 Tests auf dem Labor-Gateway mit dem signierten `cproto-v0.2.0-rc.1` (dieselbe Agenten-Quelle wie rc.2) ließ SIGTERM mitten im Check-in die gespeicherte Konfiguration entweder ganz die alte oder ganz die neue. Ein Abbruch mit SIGKILL oder ein Stromausfall waren nicht abgedeckt.
Ein Leck am rohen TPM-Gerät heilt weder der Agent noch ein Neustart.	Beim Start entfernt der Agent nur eigene übrig gebliebene Schlüsselobjekte, und nur solche, die über `/dev/tpmrm0` sichtbar sind. Ein Neustart des Labor-Gateways hat ein solches Leck nicht beseitigt (gemessen). Siehe TPM-Slots.
Der Speicher wächst langsam.	Ein Lauf auf dem Labor-Gateway mit dem signierten `cproto-v0.2.0-rc.1` (dieselbe Agenten-Quelle wie rc.2): 4,15 Stunden, 51 Check-ins, 0 fehlgeschlagen, PSS höchstens 4641 kB (innerhalb der Grenze von 5,0 MB). Der eigene Speicher des Agenten (`Pss_Anon`) wuchs in den 3,14 Stunden nach der ersten Stunde um 24 kB: 7,6 kB pro Stunde, 0,63 kB pro Check-in. In einem beschleunigten Test (aarch64-Container, ein Check-in alle 2 Sekunden, dieselbe Quelle, 2011 Check-ins) fiel das Wachstum pro Check-in über die drei Drittel des Laufs: 0,171, 0,067, 0,022 kB. Der lebende Heap blieb flach (valgrind massif), und LeakSanitizer fand nichts: Das Wachstum ist Speicher, den der glibc-Allocator in der Arena des Worker-Threads behält. `malloc_trim` nach jedem Check-in half nicht (+68 kB statt +72 kB über die Check-ins 100 bis 600). Unsere Grenze von höchstens 2 kB pro Stunde über die letzten 6 Stunden ist nicht erfüllt und wurde auf dem Gerät nicht gemessen.
Die Konsole zeigt einen abgewiesenen Kontakt nicht.	Weist die Plattform einen Aufruf des Gateways ab (zum Beispiel `TEMPLATE_INVALID`, nachdem das Template vom Gerät entfernt wurde), zeigen die Seiten des Geräts in der Konsole das nicht. Das Gateway zeigt es in `last_error_code` von `GET /v1/status` und im Log des Agenten; auf der Plattform steht es nur im Dienst-Log, wo der Support es nachsehen kann.
Der aktuelle Release-Kandidat ist `cproto-v0.2.0-rc.2`, und er ist ein Kandidat.	Archiv, Signatur und Prüfsummen sind veröffentlicht, siehe Download. Das Rezept in diesem Release verweist noch auf den vorigen Kandidaten; das Rezept in unserem Layer verweist auf rc.2.
Mit dem Rezept wurde noch kein vollständiger Yocto-Image-Bau gemacht.	In einem Testbau des Pakets hielt die Paketprüfung an einem Versions-Tag der curl-Bibliothek an. Siehe Mit Yocto und RAUC installieren.
Auf einem Gerät nicht getestet: ein echtes Yocto-Image, SIGTERM bei der Ersteinrichtung.	Testen Sie das auf Ihrem eigenen Image. Das signierte Release-Archiv wurde auf dem Labor-Gateway installiert und betrieben, siehe Manuell installieren.

Archiv: der Go-Agent¶

Frühere Release-Kandidaten benutzten ein Go-Programm und einen zweiten Helfer, den Gateway-Agent, mit mehreren Units. Sie gehören nicht mehr zu dieser Dokumentation. Der Branch archive/go-agent (Stand 936871e) ist der letzte Go-Stand; er enthält einen unveröffentlichten Fix (70aded9), der nicht auf Hardware getestet wurde. Der veröffentlichte Stand ist der Tag v0.11.0-rc.7. Die bereits veröffentlichten Release-Kandidaten bleiben erhalten; der C-Kandidat cproto-v0.1.0-rc.2 trägt noch einen älteren Satz von vier Units und wird hier nicht beschrieben.