Zum Inhalt

English

Manuell auf einem Gateway installieren

Für ein einzelnes Gateway: Integratoren, Tests, Gateways, die schon im Feld sind. Der Agent wird mit den Befehlen auf dieser Seite installiert, aktualisiert und entfernt, alle auf dem Gateway als root. Sie brauchen keinen zweiten Rechner, kein Installationsskript und keinen Paketmanager. Jede Datei wird geprüft, bevor etwas daraus läuft. Für Gateways in Serie bauen Sie den Agenten stattdessen in Ihr Image ein, siehe Mit Yocto und RAUC installieren.

Die Schritte liefen Wort für Wort auf einem Labor-Gateway (armv7, schreibgeschütztes Root-Dateisystem, /etc als Overlay auf der Datenpartition /mnt/data) am 11.11.2026: eine Installation von cproto-v0.2.0-rc.1, das Update auf cproto-v0.2.0-rc.2 und ein Neustart. Was nicht getestet wurde, steht dabei.

Voraussetzungen

  • Architektur: nur armv7 (32-Bit-ARM, Hard-Float). Für andere Architekturen gibt es noch keinen Build.
  • glibc 2.34 oder neuer auf dem Gateway: Die höchste Symbolversion, die das Programm braucht, ist GLIBC_2.34.
  • Diese Bibliotheken auf dem Gateway, wie unter Mit Yocto und RAUC installieren: libtss2-esys.so.0, libtss2-mu.so.0, libcurl.so.4, libssl.so.3, libcrypto.so.3, libjson-c.so.5 und glibc.
  • Die Werkzeuge curl, sha256sum, tar und der Befehl openssl in Version 3 auf dem Gateway. Prüfen Sie mit openssl version. OpenSSL 1.1.1 und LibreSSL 3.3 brechen bei der Signaturprüfung mit unknown option -rawin ab; das Labor-Gateway hat OpenSSL 3.2.2. Ohne openssl 3 auf dem Gateway bleibt nur, die Dateien auf einem anderen Rechner zu prüfen wie unter Die Signatur prüfen und sie dann zu kopieren; diese Seite beschreibt das nicht.
  • Eine Datenpartition, die Neustarts und Firmware-Updates übersteht, hier /mnt/data, und ein beschreibbares /etc (auf dem Labor-Gateway ein Overlay auf dieser Partition).
  • Das Gerät in der Konsole angelegt, mit zugewiesenem Template.

1. Version und Ort wählen

Auf dem Gateway, als root:

V=cproto-v0.2.0-rc.2
D=/mnt/data/bootstrap-agent
A=bootstrap-agent-$V-linux-armv7.tar.gz
U=https://packages.pxdc.io/bootstrap-agent/$V

D ist der Ort des Agenten auf der Datenpartition; nehmen Sie Ihre eigene Datenpartition. Jede Version bekommt einen eigenen Ordner unter D; D/current zeigt auf die laufende. Lassen Sie die Shell offen: Die nächsten Schritte nutzen diese Variablen.

2. Den Schlüssel speichern, einmal

Der öffentliche Schlüssel der Agent-Releases. Speichern Sie ihn einmal; er ist für jede Version derselbe.

mkdir -p /etc/bootstrap-agent
cat > /etc/bootstrap-agent/wlpc-agent-ed25519.pub <<'EOF'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAN8+mCK4/qSV4xO6uFNHrc5+8Dje5wK609NI7WEGqYa4=
-----END PUBLIC KEY-----
EOF
openssl pkey -pubin -in /etc/bootstrap-agent/wlpc-agent-ed25519.pub -outform DER | sha256sum

Der letzte Befehl muss 79c12a4d7b4cc3868129a0afac587fd2441246e5c61382bd8221bc2ec52d402a ausgeben. Vergleichen Sie ihn auch mit dem Fingerabdruck, den Ihnen der Support getrennt schickt: Ein Schlüssel, der von derselben Stelle kopiert wurde wie das Archiv, beweist allein nichts.

3. Herunterladen und prüfen

mkdir -p $D/$V && cd $D/$V
curl -fsSLO $U/$A
curl -fsSLO $U/$A.sig
curl -fsSLO $U/$A.sha256
sha256sum -c $A.sha256
openssl pkeyutl -verify -pubin -rawin -inkey /etc/bootstrap-agent/wlpc-agent-ed25519.pub -sigfile $A.sig -in $A

Machen Sie erst nach OK und Signature Verified Successfully weiter. Auf dem Labor-Gateway wurde eine Kopie mit einem angehängten Byte mit Signature Verification Failure abgelehnt. Dann entpacken und jede Datei darin prüfen:

mkdir files && tar -xzf $A -C files
chown -R root:root files && chmod 0755 files
(cd files && sha256sum -c CHECKSUMS.sha256)

Jede Zeile muss mit OK enden. Die Zeile mit chown/chmod ist für cproto-v0.2.0-rc.1: Dieses Archiv speichert seinen obersten Ordner mit Modus 0700, files bekäme diesen Modus, und der Benutzer des Agenten könnte das Programm nicht starten (status=203/EXEC). Bei späteren Versionen ändert die Zeile nichts.

cproto-v0.2.0-rc.1: keine Bestätigung durch den Platzhalter

In diesem Archiv schreibt der Beispieldienst unter examples/ die Bestätigungsdatei gar nicht, und die tmpfiles-Regel macht /run/wlpc nur für root beschreibbar. Mit cproto-v0.2.0-rc.1 bleibt das Gerät deshalb PROVISIONED (gemessen). Ab cproto-v0.2.0-rc.2 schreibt der Platzhalter aus Schritt 7 die Datei als Mitglied der Gruppe wlpc.

4. Benutzer und Gruppen

Der Agent läuft als Benutzer bootstrap-agent; er braucht die Gruppe tss für das TPM, und Ihre Software schreibt die Bestätigung als Mitglied der Gruppe wlpc:

grep -E '^(tss|wlpc):' /etc/group
grep -q '^wlpc:' /etc/group || addgroup -S wlpc
id bootstrap-agent || { addgroup -S bootstrap-agent && adduser -S -D -H -h /nonexistent -s /bin/false -G bootstrap-agent bootstrap-agent; }

Die letzte Zeile legt den Benutzer nur an, wenn er fehlt: ohne Home-Verzeichnis, ohne Login-Shell, in einer eigenen Gruppe, wie das Image-Rezept (groupadd/useradd auf einem System ohne BusyBox). Die Gruppe tss kommt mit der TPM-Software der Firmware; zeigt die erste Zeile sie nicht, legen Sie sie mit addgroup -S tss an.

Auf dem Labor-Gateway teilweise ausgeführt

Auf dem Labor-Gateway gab es den Benutzer und die Gruppen tss und wlpc schon; die Zeilen liefen, legten aber nichts an. Der Zweig, der anlegt, lief nicht.

5. Installieren

ln -sfn $D/$V/files $D/current
install -m 0644 $D/current/systemd/bootstrap-agent.service /etc/systemd/system/
install -m 0644 $D/current/tmpfiles/bootstrap-agent.conf /etc/tmpfiles.d/
mkdir -p /etc/systemd/system/bootstrap-agent.service.d
cat > /etc/systemd/system/bootstrap-agent.service.d/manual.conf <<EOF
[Service]
ExecStart=
ExecStart=$D/current/bootstrap-agent
EnvironmentFile=
EnvironmentFile=$D/current/env/bootstrap-agent.env
EnvironmentFile=-/etc/bootstrap-agent/agent.env
EOF
printf 'BOOTSTRAP_AGENT_URL=https://bootstrap.ztd.dev.pxdc.io\nBOOTSTRAP_AGENT_TRUST_BUNDLE=\n' > /etc/bootstrap-agent/agent.env
  • Die Unit erwartet das Programm in /usr/bin und seine Standardeinstellungen in /usr/lib/wlpc, beides auf dem schreibgeschützten Root. Das Drop-in manual.conf lenkt beides auf D/current. Das ist der einzige Unterschied zu einer Image-Installation.
  • agent.env setzt die Adresse der Plattform, siehe Einstellungen. Das Trust-Bundle wird leer gesetzt: Der Standard zeigt auf eine Datei, die nur ein Image mitbringt.
  • Die tmpfiles-Regel des Archivs legt /run/wlpc mit Modus 2775 für die Gruppe wlpc an, siehe Wer /run/wlpc schreiben darf.

6. Starten

systemd-tmpfiles --create /etc/tmpfiles.d/bootstrap-agent.conf
systemctl daemon-reload
$D/current/bootstrap-agent --version
systemctl enable --now bootstrap-agent
journalctl -u bootstrap-agent -n 30 --no-pager

--version gibt die gesetzte Version aus (cproto-v0.2.0-rc.1 im Test). Auf dem Labor-Gateway kam außerdem /usr/lib/libcurl.so.4: no version information available; die Warnung ist harmlos (die curl-Bibliothek des Gateways trägt keine Symbolversionen). Das Log zeigt danach innerhalb von etwa drei Sekunden local interface listening, attestation key loaded, profile persisted and served, profile-ready marker written und bootstrap complete reported to the platform. Die Konsole zeigt das Gerät als PROVISIONED. Den Agenten prüfen Sie mit:

curl -s --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/status

"state":"ready" und eine profile_version heißen: Die Konfiguration ist gespeichert.

7. Ihre Software oder ein Platzhalter

Ihre Software startet, wenn die Konfiguration da ist, und schreibt die Bestätigung, siehe Software starten und bestätigen. Ohne sie nehmen Sie die Beispiele aus dem Archiv als Platzhalter:

cp $D/current/examples/profile-ready-consumer.path /etc/systemd/system/your-software.path
cp $D/current/examples/profile-ready-consumer.service /etc/systemd/system/your-software.service
sed -i 's/^Unit=.*/Unit=your-software.service/' /etc/systemd/system/your-software.path
systemctl daemon-reload
systemctl enable --now your-software.path
systemctl restart your-software.service

Die sed-Zeile lenkt die .path-Unit auf den umbenannten Dienst: Das Beispiel nennt profile-ready-consumer.service, und ohne die Zeile startet systemd die .path-Unit nicht (unit profile-ready-consumer.service to trigger not loaded).

Der Dienst wartet auf den Socket des Agenten, macht einen Aufruf, schreibt {"state":"connected"} nach /run/wlpc/target-confirmed unter seiner eigenen Benutzer-ID (als Mitglied von wlpc, ohne root) und endet; er bleibt active (RemainAfterExit=yes), damit die .path-Unit ihn nicht in einer Schleife neu startet.

Auf dem Labor-Gateway schrieb der Platzhalter mit cproto-v0.2.0-rc.2 die Datei unter seiner eigenen Benutzer-ID (Gruppe wlpc, Modus 0644, Inhalt {"state":"connected"}). Prüfen Sie mit ls -ln /run/wlpc und systemctl is-active your-software.path your-software.service (beide active). Der Platzhalter schreibt die Datei sofort; Ihre Software schreibt sie erst, wenn sie verbunden ist, und nach jeder neuen Konfiguration erneut, siehe Die Datei für jede neue Konfiguration neu schreiben.

8. Auf eine neue Version aktualisieren

Setzen Sie die neue Version und wiederholen Sie damit die Schritte 3, 5, 6 und 7; Schritt 2 ist nicht noch einmal nötig. Schritt 7 ist wichtig: Der Platzhalter wird aus dem Archiv kopiert, und der aus cproto-v0.2.0-rc.1 schreibt die Bestätigung gar nicht. Zum Beispiel:

V=cproto-v0.2.0-rc.2
A=bootstrap-agent-$V-linux-armv7.tar.gz
U=https://packages.pxdc.io/bootstrap-agent/$V

Schritt 5 lenkt D/current auf die neue Version und installiert deren Unit und tmpfiles-Regel; Schritt 6 startet nichts von selbst neu, also starten Sie den Agenten neu:

systemctl restart bootstrap-agent

Die Konfiguration in /etc/iot-config bleibt. Der Ordner der alten Version bleibt auch; um zurückzugehen, setzen Sie V auf die alte Version und führen die Schritte 5 und 6 erneut aus. Einen alten Ordner entfernen Sie mit rm -rf $D/ALTE-VERSION, sobald Sie ihn nicht mehr brauchen.

Auf dem Labor-Gateway prüfte das Update von cproto-v0.2.0-rc.1 auf cproto-v0.2.0-rc.2 wie die Installation (OK, Signature Verified Successfully). Der neue Agent lieferte die gespeicherte Konfiguration sofort aus (serving the profile already on this device; scheduling one boot check-in), holte nichts Neues (check-in complete: unchanged, nothing fetched), und das Gerät wurde ACTIVE, sobald die Bestätigungsdatei da war.

9. Firmware-Updates und Neustarts

Neustart: Nach einem Neustart des Labor-Gateways startete der Agent von selbst, lieferte die gespeicherte Konfiguration aus und meldete sich (restored profile is fully acked; its confirmation rides on the next check-in, dann pending confirmation delivered on check-in und check-in complete: unchanged). Das Gerät blieb ACTIVE; eine wiederholte Bestätigung wird nicht noch einmal abgerechnet.

Der Platzhalter nach dem Neustart

Im Test startete die .path-Unit nach dem Neustart nicht, weil sie ohne die sed-Zeile aus Schritt 7 installiert war (unit profile-ready-consumer.service to trigger not loaded). Mit der Zeile startete sie und schrieb die Datei; ein zweiter Neustart mit der korrigierten Unit lief nicht.

Firmware-Update: Alles, was diese Seite installiert, liegt auf der Datenpartition (D) oder in /etc, das auf dem Labor-Gateway ein Overlay auf dieser Partition ist. Ein Firmware-Update, das das Root-Dateisystem ersetzt und die Datenpartition behält, lässt den Agenten deshalb installiert, solange die neue Firmware die Bibliotheken und Werkzeuge aus den Voraussetzungen hat und /etc gleich einhängt. Ein Zurücksetzen auf Werkseinstellungen, das die Datenpartition löscht, entfernt ihn; führen Sie vorher bootstrap-agent --release-ak aus, siehe Das TPM.

Nicht getestet

Auf dem Labor-Gateway lief mit dieser Installation weder ein Firmware-Update noch ein Zurücksetzen auf Werkseinstellungen.

10. Entfernen

Wie Sie den Agenten entfernen, was zurückbleibt und wie Sie ihn wieder installieren: Deinstallieren.

Was sich vom Betrieb unterscheidet

  • Check-in-Intervall. Der Standard des Agenten ist eine Stunde (Bereich 300 bis 86400 Sekunden, siehe Geräteaktionen). Das Labor-Gateway meldet sich alle 5 Minuten, weil sein Template check_in_interval_seconds auf 300 setzt. Um eine Template-Änderung am Gateway früher zu sehen, nutzen Sie diesen Schlüssel; im Betrieb bleiben Sie beim Standard.
  • Serie. Eine Installation von Hand auf jedem Gateway skaliert nicht und wird von einem Firmware-Update, das Sie ausliefern, nicht abgedeckt. Für Gateways in Serie nehmen Sie Mit Yocto und RAUC installieren.