Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Bewährte Methoden für Remote-Geräteeinstellungen

Wie sich Remote-Geräteeinstellungen im Detail verhalten und wie Sie sie auf einem einzelnen Gerät oder auf vielen sicher ändern: Soll- und Istwerte, Zusammenführungsregeln, Revisionen, Drift, Geheimnisse, Jobs und alte Firmware.

Diese Seite richtet sich an Administratoren und Integratoren, die Gerät« einstellungen über Hermetry ändern, manuell oder über die API, auf einem Gerät oder auf vielen. Sie erklärt die Regeln hinter dem Reiter Settings und wie man sie sicher nutzt. Wie man den Reiter öffnet, Baselines anlegt und Jobs startet, steht unter Remote device settings; die Routen stehen unter Firmware and device settings API.

Soll- und Istwerte

Für jeden Einstellungsabschnitt eines Geräts führt Hermetry zwei Dokumente:

  • Soll: was Hermetry dem Gerät zuletzt zu betreiben aufgetragen hat, mit einer Revisionsnummer, die mit jeder Änderung steigt.
  • Ist: was das Gerät meldet, dass es betreibt, mit der Revision, die es angewendet hat.

Jede Änderung sendet den gesamten Abschnitt an das Gerät, nicht nur die geänderten Schlüssel. Das Gerät wendet einen Abschnitt nur an, wenn seine Revision höher ist als die zuletzt angewendete. Ein Abschnitt, der zu lange auf das Gerät gewartet hat, wird zurückgezogen; das Gerät behält dann die Einstellungen, die es hat.

Status im Reiter SettingsBedeutung
UnterwegsGesendet oder wartet darauf, dass das Gerät online kommt
Gerät probiert es ausDas Gerät führt die Änderung probeweise aus und macht sie selbstständig rückgängig, wenn es die Cloud nicht wieder erreicht
AngewendetDas Gerät führt die Änderung aus
Vom Gerät rückgängig gemachtDas Gerät hat sie probiert und ist zurückgegangen
Vom Gerät abgelehntDas Gerät hat sie nicht akzeptiert
Gerät war offlineDie Änderung hat zu lange gewartet (7 Tage für eine einzelne Änderung) und wurde zurückgezogen
Prüfung nach UpdateEin Firmware-Update hat die Beschreibung des Abschnitts geändert; eine Person muss prüfen und speichern
Am Gerät geändertDrift: Das Gerät betreibt andere Werte, als Hermetry angefordert hat (siehe unten)
Von hier aus nicht geändertHermetry hat diesen Abschnitt nie gesetzt; es zeigt nur an, was das Gerät meldet

Wie eine Änderung aufgebaut wird

Es gibt zwei Arten, einen Abschnitt zu schreiben, und sie behandeln Weggelassenes unterschiedlich.

ArtVerwendet vonWas man sendet
Ganzer AbschnittDer Reiter Settings, PUTJeder Wert des Abschnitts. Was man weglässt, gehört nicht zum neuen Abschnitt.
Merge-PatchPATCH, Baselines, EinstellungsjobsNur das, was sich ändert, als JSON Merge Patch (RFC 7386)

Ein Merge-Patch folgt genau diesen Regeln:

  • Objekte werden Schlüssel für Schlüssel zusammengeführt. Ein Schlüssel, den man nicht nennt, behält seinen Wert.
  • null entfernt den Schlüssel.
  • Jeder andere Wert ersetzt den alten vollständig. Eine Liste wird immer vollständig ersetzt: Um einen Eintrag einer Liste zu ändern, sendet man die komplette Liste.

Der Patch wird auf das letzte Soll-Dokument des Abschnitts angewendet, nicht auf das, was das Gerät meldet. Nur wenn Hermetry den Abschnitt nie gesetzt hat, startet ein Patch bei den gemeldeten Werten; hat das Gerät den Abschnitt auch noch nicht gemeldet, wird der Schreibvorgang abgelehnt (section_not_reported).

Bewährte Praxis:

  • Nur das in eine Baseline aufnehmen, was man ändern will. Alles andere bleibt auf jedem Gerät, wie es ist.
  • null nur dann in eine Baseline aufnehmen, wenn der Schlüssel auf jedem Gerät des Jobs verschwinden soll.
  • Gerätespezifische Listen (zum Beispiel Adresslisten, die sich je Standort unterscheiden) nicht in Baselines aufnehmen: Die Liste der Baseline ersetzt die Liste jedes Geräts.
  • Einstellungen, die die Beschreibung als nur am Gerät änderbar kennzeichnet, werden aus dem Bericht des Geräts übernommen. Eine Änderung daran wird abgelehnt (remote_forbidden).
  • Mit ?dryRun=true (oder Check in einem Job) prüfen, welche Einstellungen eine Änderung berührt und ob sie eine Bestätigung braucht, bevor etwas gesendet wird.

Revisionen und If-Match

Beim Lesen eines Abschnitts wird seine Soll-Revision als ETag-Header in der Form W/"7" zurückgegeben. Jeder Schreibvorgang muss diese Revision in If-Match zurücksenden; "7" und 7 werden ebenfalls akzeptiert.

AntwortBedeutung
428 if_match_requiredDer Schreibvorgang hatte kein If-Match
412 rev_mismatchJemand hat den Abschnitt geändert, nachdem Sie ihn gelesen haben

Bei 412 den Abschnitt erneut lesen, die Änderung auf dem neuen Dokument neu aufbauen und erneut schreiben. Die neue Revision nicht in den Header kopieren und das alte Dokument erneut senden: Das würde die Änderung der anderen Person überschreiben. Der Reiter Settings führt dieselbe Prüfung durch („Someone else changed these settings since you opened them. Load them again to see the latest.“).

Drift

Ein Abschnitt ist abgewichen, wenn das Gerät eine Änderung von Hermetry angewendet hat und später abweichende Werte meldet, meist weil jemand sie direkt am Gerät geändert hat. Der Reiter zeigt „Changed on the device“ und die Unterschiede. Hermetry korrigiert Drift nicht von selbst. Sie wählen:

AktionWirkung
Unsere erneut sendenSendet die Soll-Werte von Hermetry erneut als neue Revision
Die des Geräts behaltenSpeichert die aktuellen Werte des Geräts als neue Soll-Werte

Drift auflösen, bevor man einen abgewichenen Abschnitt auf andere Weise ändert. Ein Merge-Patch und damit ein Einstellungsjob startet beim letzten Soll-Dokument und sendet daher auch die Werte von Hermetry für die abgewichenen Einstellungen zurück.

Festlegen, wer jede Einstellung verantwortet. Wenn Techniker vor Ort etwas ändern können müssen, das Element aus Baselines und Jobs heraushalten.

Geheimnisse

  • Geheime Einstellungen (Passwörter, Schlüssel) werden nie angezeigt oder zurückgegeben. Sie erscheinen als { "set": true }.
  • Ein neues Geheimnis gelangt als einmalige Referenz an das Gerät. Das Gerät holt den Wert einmal über eine signierte Anfrage ab; eine Referenz, die nicht abgeholt wird, verfällt nach 30 Tagen. Ein Gerät, dessen Firmware keine Referenzen abrufen kann, erhält gar kein Geheimnis: Die Änderung wird abgelehnt (secret_ref_unsupported).
  • Um das aktuelle Geheimnis des Geräts beizubehalten, das Feld unverändert lassen (in der API { "$keep": true }).
  • Baselines können keine Geheimnisse enthalten (secret_not_allowed). Sie auf jedem Gerät einzeln setzen.
  • secret_pending: Eine frühere Änderung enthält ein Geheimnis, das das Gerät noch nicht abgeholt hat. Darauf warten oder das Geheimnis erneut eingeben.
  • secrets_need_rewrite bei Erneut senden: Die Änderung enthält Geheimnisse, die das Gerät nicht mehr abholen kann. Sie erneut eingeben und speichern.

Einstellungsjobs

Ein Job wendet eine Baseline oder eine einzelne Änderung auf viele Geräte in Wellen an. Bewährte Praxis:

  1. Nach Modell und Firmware auswählen, die Sie getestet haben. Der Schritt Check zeigt die Geräte je Modell und Firmware sowie die Abschnitte, die ein Modell nicht hat.
  2. Die Wellen beibehalten. Standard sind 1 %, dann 10 %, dann der Rest. Die erste Welle ist ein fester Zufallsquerschnitt der ausgewählten Geräte.
  3. Die Freigabebedingung verstehen. Eine Welle gilt als bestanden, wenn unter den Geräten, die geantwortet haben, mindestens 95 % die Änderung angewendet und höchstens 1 % sie rückgängig gemacht haben (die Standardwerte). Geräte, die abgelehnt haben, zählen zu den antwortenden und senken daher den Anteil angewendeter Änderungen. Noch offline befindliche Geräte zählen nicht. Eine Welle wird bewertet, wenn alle ihre Geräte geantwortet haben, oder 30 Minuten nach ihrem Start (Standard) bei den bis dahin antwortenden Geräten; die übrigen laufen im Hintergrund weiter. Eine bestandene Welle startet die nächste sofort, ohne Wartezeit. Eine Welle, in der kein Gerät geantwortet hat, hält den Job an.
  4. Festlegen, was bei einem Konflikt geschieht. Auf dem Abschnitt eines Geräts darf nur eine Änderung zur Zeit laufen. Ein Job wartet auf die Änderung eines anderen Jobs (und überspringt das Gerät nach 24 Stunden) oder überspringt es sofort. Eine Änderung, die eine Person während des Wartens des Jobs vornimmt, hat Vorrang.
  5. Festlegen, wie lange auf Offline-Geräte gewartet wird: standardmäßig 7 Tage, 1 bis 90.
  6. Beachten, dass Abbrechen nicht zurückrollt. Bereits geänderte Geräte behalten ihre neuen Einstellungen.

Ein Job schreibt mit den Berechtigungen seines Erstellers, und ein Job, der gefährliche Einstellungen ändert, muss bei der Erstellung bestätigt werden. Höchstens 5 Jobs laufen oder warten pausiert gleichzeitig, ein Job umfasst bis zu 5.000 Geräte, und es werden Änderungen an höchstens 200 Geräte pro Minute gesendet.

Firmware-Updates und alte Firmware

  • Nach einem Firmware-Update überführt Hermetry die gespeicherten Sollwerte in die Einstellungsbeschreibung der neuen Firmware. Was sich nicht sicher überführen lässt, wird mit „Check after update“ markiert. Der Abschnitt bleibt in diesem Zustand, bis eine Person ihn speichert; Meldungen vom Gerät schließen ihn nicht, und ein Job zählt ein solches Gerät als abgelehnt.
  • Unterstützungszeitraum: Schreibzugriffe auf Einstellungen enden 24 Monate nach dem Veröffentlichungsdatum der Firmware des Geräts, wie es in dessen Einstellungsbeschreibung vermerkt ist. Die Einstellungen bleiben lesbar („Read only: update the firmware to change settings“). Ein Schreibzugriff beantwortet 409 firmware_too_old mit dem Datum, an dem der Zeitraum endete.
  • Ein Job schließt solche Geräte nicht im Voraus aus. Sie werden abgelehnt, wenn sie an die Reihe kommen, und zählen gegen die Schranke der Welle. Aktualisieren Sie zuerst ihre Firmware oder nehmen Sie sie nicht in die Auswahl auf.

Änderungsrate

Einzelne Änderungen über den Reiter Settings und die API, einschließlich Send again, sind auf 600 pro Minute und Organisation begrenzt; darüber hinaus 429 write_rate_limited. Schreibzugriffe eines Jobs auf seine Geräte zählen nicht dazu.