Beispiele der lokalen API¶

Jeder Aufruf der lokalen Schnittstelle des Agenten, mit dem curl-Befehl und der Antwort, die der Agent gab. Die Aufrufe liefen auf dem Labor-Gateway gegen cproto-v0.2.0-rc.2. Die Zusammenfassung der Schnittstelle steht unter Referenz der lokalen API.

Werte ersetzt. Jeder Befehl dieser Seite wurde unverändert in eine Shell auf dem Labor-Gateway eingefügt. Statuscodes, Fehlercodes, Header und die Form jeder Antwort sind echt. Die Profilversion (42), die ETags, die Hashes und der Zeitstempel sind ersetzt; Listen sind gekürzt. Die Header Date und Content-Length sind weggelassen.

Kurzablauf¶

Für Software, die über die API bestätigt statt über die Markierungsdatei (die Datei ist empfohlen, siehe Zwei Wege zu bestätigen):

Pakete abrufen: GET /v1/profile/packages, dann den Inhalt jedes Pakets mit GET /v1/profile/packages/{id} (Die Paketliste, Ein Paket). Merken Sie sich profile_version.
Auf eine Änderung warten: GET /v1/events?profile_version=PROFILE_VERSION antwortet mit 200 und der neuen Version, wenn sich die Konfiguration ändert, oder nach 60 Sekunden mit 204; fragen Sie dann erneut (Auf eine Änderung warten). Bei 200 gibt es eine neue Konfiguration: Rufen Sie sie ab (Schritt 1) und bestätigen Sie sie (Schritt 3).
Bestätigen: Sobald ein Paket angewendet ist, POST /v1/profile/packages/{id}/ack mit {"profile_version": PROFILE_VERSION, "applied": true} (Ein Paket bestätigen), mit der Version, die Sie abgerufen haben. Ein ack mit einer älteren Version bekommt 409: Rufen Sie neu ab. Sind alle Pakete bestätigt, sendet der Agent confirmed.

Führen Sie die Befehle auf dem Gateway als root oder als Mitglied der Gruppe bootstrap-agent aus (siehe Transport und Zugriff). Der Agent antwortet mit einer Zeile JSON; | jq . gibt sie eingerückt aus, ein Feld pro Zeile, und jq -r reduziert sie auf einen Wert. Auf dem Labor-Gateway war jq installiert. Wo es fehlt, rückt | python3 -m json.tool ebenfalls ein.

Aufrufe, die private Schlüssel ausgeben, stehen am Ende dieser Seite

Das ganze Profil und die Pakete mit Zugangsdaten enthalten private Schlüssel. Sie stehen nur unter Aufrufe, die Geheimnisse liefern, hinter einer Warnung. Alles davor gibt kein Geheimnis aus.

Status¶

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

{
  "interface_version": 1,
  "interface_minor_version": 6,
  "agent_version": "cproto-v0.2.0-rc.2",
  "state": "ready",
  "attestation_mode": "tpm",
  "profile_version": 42,
  "last_checkin": "2026-01-01T12:00:00Z",
  "tpm_transient_avail": 3,
  "tpm_loaded_sessions": 0,
  "tpm_transient_capacity": 3,
  "tpm_transient_used": 0,
  "identity_cert_state": "not_configured",
  "auth_mode": "tpm",
  "auth_mode_source": "server",
  "activation": "listen",
  "profile_ready_marker": "/etc/iot-config/profile-ready"
}

Nur ein Feld:

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

ready

last_error_code fehlt oben, weil es keinen gab. Die Felder sind unter Zustand erklärt.

Die Paketliste¶

Die Liste nennt jedes Paket mit Version, Hash und ob es bestätigt ist. Den Inhalt enthält sie nie:

curl -s --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile/packages | jq .

{
  "profile_version": 42,
  "packages": [
    {
      "id": "check_in_interval_seconds",
      "version": 42,
      "sha256": "EXAMPLE-HASH-BASE64=",
      "acked": true
    },
    {
      "id": "log_level",
      "version": 42,
      "sha256": "EXAMPLE-HASH-BASE64=",
      "acked": true
    }
  ]
}

Die Liste des Labor-Gateways hatte sechs Pakete; zwei sind gezeigt.

Warum der Hash so aussieht. sha256 ist die SHA-256 des Paketinhalts in Base64 (44 Zeichen, endet auf =), so wie die Plattform sie sendet. ?pretty=1 ergänzt denselben Hash in Hex als sha256_hex (64 Zeichen), zum Vergleich mit sha256sum. Es rückt nicht ein; das macht jq:

curl -s --unix-socket /run/bootstrap-agent/api.sock 'http://localhost/v1/profile/packages?pretty=1' | jq -r '.packages[] | "\(.id) \(.sha256_hex)"'

check_in_interval_seconds EXAMPLE-HASH-HEX
log_level EXAMPLE-HASH-HEX

Ein Paket ohne Geheimnisse¶

Die Antwort ist der Inhalt des Pakets ohne Umschlag: ein String, eine Zahl oder ein Objekt. Diese beiden Pakete enthalten kein Geheimnis:

curl -s --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile/packages/log_level | jq .
curl -s --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile/packages/check_in_interval_seconds | jq .

"warning"
300

Welche Pakete Geheimnisse enthalten, hängt von Ihrem Template ab; auf dem Labor-Gateway waren es target-credential (der Broker-Zugang mit seinem privaten Schlüssel) und target-connection. Lesen Sie diese nur wie unter Aufrufe, die Geheimnisse liefern.

Ein Paket, das es nicht gibt (-i gibt Statuszeile und Header aus):

curl -s -i --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile/packages/does-not-exist

HTTP/1.1 404 Not Found
Content-Type: application/json

{"code":"NOT_FOUND"}

Nichts geändert: `304`¶

Senden Sie das ETag Ihrer letzten Antwort in If-None-Match. Solange die Konfiguration gleich ist, lautet die Antwort 304 ohne Body. Die erste Zeile liest das aktuelle ETag:

E=$(curl -s -I --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile/packages | sed -n 's/^[Ee][Tt]ag: //p' | tr -d '\r')
curl -s -i --unix-socket /run/bootstrap-agent/api.sock -H "If-None-Match: $E" http://localhost/v1/profile/packages

HTTP/1.1 304 Not Modified
Etag: "EXAMPLE-ETAG"
X-Profile-Version: 42

Ein Paket bestätigen¶

Das überlassen Sie normalerweise der Bestätigungsmarkierung, siehe Zwei Wege zu bestätigen. Jeder Aufruf unten ändert den Zustand des Pakets auf dem Gateway. Die erste Zeile liest die aktuelle Profilversion in PV; die Aufrufe verwenden sie:

PV=$(curl -s --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/status | jq -r .profile_version)

Vermerkt. Mit der aktuellen Version und applied: true lautet die Antwort 204 ohne Body:

curl -s -i --unix-socket /run/bootstrap-agent/api.sock -X POST -d "{\"profile_version\":$PV,\"applied\":true}" http://localhost/v1/profile/packages/log_level/ack

HTTP/1.1 204 No Content

Ohne applied. Die Antwort ist ebenfalls 204, und der Aufruf gilt als applied: false: Das Paket steht danach mit "acked": false in der Paketliste. Senden Sie den Aufruf darüber erneut, um es wieder zu bestätigen.

curl -s -i --unix-socket /run/bootstrap-agent/api.sock -X POST -d "{\"profile_version\":$PV}" http://localhost/v1/profile/packages/log_level/ack

Fehlerhafter Body: 400.

curl -s -i --unix-socket /run/bootstrap-agent/api.sock -X POST -d '{' http://localhost/v1/profile/packages/log_level/ack

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"code":"MALFORMED_REQUEST"}

Alte Version: 409. Die Version wird vor dem Paket geprüft, daher bekommt auch ein unbekanntes Paket mit alter Version 409:

curl -s -i --unix-socket /run/bootstrap-agent/api.sock -X POST -d '{"profile_version":1,"applied":true}' http://localhost/v1/profile/packages/log_level/ack
curl -s -i --unix-socket /run/bootstrap-agent/api.sock -X POST -d '{"profile_version":1,"applied":true}' http://localhost/v1/profile/packages/nope/ack

HTTP/1.1 409 Conflict
Content-Type: application/json

{"code":"STALE_PROFILE_VERSION"}

Unbekanntes Paket mit aktueller Version: 404.

curl -s -i --unix-socket /run/bootstrap-agent/api.sock -X POST -d "{\"profile_version\":$PV,\"applied\":true}" http://localhost/v1/profile/packages/nope/ack

HTTP/1.1 404 Not Found
Content-Type: application/json

{"code":"NOT_FOUND"}

Auf eine Änderung warten¶

Mit der aktuellen Version wartet der Aufruf. Ändert sich nichts, antwortet er nach 60 Sekunden mit 204 ohne Body; fragen Sie dann erneut. PV ist gesetzt wie unter Ein Paket bestätigen.

curl -s -i --unix-socket /run/bootstrap-agent/api.sock "http://localhost/v1/events?profile_version=$PV"

HTTP/1.1 204 No Content

Mit einer alten Version antwortet er sofort mit der aktuellen:

curl -s --unix-socket /run/bootstrap-agent/api.sock 'http://localhost/v1/events?profile_version=1' | jq .

{
  "profile_version": 42
}

Unbekannter Pfad oder unbekannte Methode¶

Ein unbekannter Pfad und eine Methode, die ein Pfad nicht annimmt, bekommen 404, nicht 405:

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

HTTP/1.1 404 Not Found
Content-Type: application/json

{"code":"NOT_FOUND"}

POST /v1/status und GET /v1/profile/packages/{id}/ack antworten genauso mit 404.

Aufrufe, die Geheimnisse liefern¶

Gibt private Schlüssel aus. Nicht kopieren, nicht in Tickets oder Chats einfügen.

GET /v1/profile liefert die ganze Konfiguration, und GET /v1/profile/packages/{id} den Inhalt eines Pakets. Bei einem Paket mit Zugangsdaten, auf dem Labor-Gateway target-credential, ist das der private Schlüssel des Broker-Zugangs im Klartext. ?pretty=1 verbirgt ihn nicht. Senden Sie stattdessen die Paketliste, wenn Sie Ausgaben weitergeben.

Um das Profil zu prüfen, ohne seinen Inhalt zu sehen, lesen Sie nur die Header oder nur die Paketnamen:

curl -s -I --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile
curl -s --unix-socket /run/bootstrap-agent/api.sock http://localhost/v1/profile | jq -r '.packages[].id'

HTTP/1.1 200 OK
Content-Type: application/json
Etag: "EXAMPLE-ETAG"
X-Profile-Version: 42

check_in_interval_seconds
log_level
target-credential

Der vollständige Body und der Inhalt eines Pakets mit Zugangsdaten stehen nicht auf dieser Seite. Ihre Form, mit erfundenen Werten, steht unter Referenz der lokalen API. Lesen Sie sie nur aus Ihrer eigenen Software, die sie braucht.