Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

Bonnes pratiques pour les réglages à distance

Le fonctionnement détaillé des réglages à distance des appareils, et comment les modifier en toute sécurité sur un appareil ou sur un grand nombre : valeurs souhaitées et rapportées, règles de fusion, révisions, dérive, secrets, tâches et anciens firmwares.

Cette page s’adresse aux administrateurs et intégrateurs qui modifient les réglages des appareils depuis Hermetry, manuellement ou via l’API, sur un appareil ou sur plusieurs. Elle explique les règles qui régissent l’onglet Settings et comment les utiliser en toute sécurité. Comment ouvrir l’onglet, créer des baselines et lancer des jobs est expliqué dans Remote device settings ; les routes figurent dans Firmware and device settings API.

Valeurs souhaitées et valeurs remontées

Pour chaque section de réglages d’un appareil, Hermetry conserve deux documents :

  • Desired : ce que Hermetry a demandé en dernier à l’appareil d’exécuter, avec un numéro de révision qui augmente à chaque modification.
  • Reported : ce que l’appareil indique exécuter, avec la révision qu’il a appliquée.

Chaque modification envoie la section entière à l’appareil, et non seulement les clés modifiées. L’appareil n’applique une section que si sa révision est supérieure à la dernière qu’il a appliquée. Une section restée trop longtemps en attente de l’appareil est retirée ; l’appareil conserve alors les réglages qu’il possède.

États dans l’onglet SettingsSignification
En attenteEnvoyée, ou en attente que l’appareil se connecte
L’appareil l’essaieL’appareil exécute la modification à titre d’essai et l’annule automatiquement s’il ne peut plus joindre le cloud
AppliquéeL’appareil exécute la modification
Annulée par l’appareilL’appareil l’a essayée puis est revenu en arrière
Refusée par l’appareilL’appareil ne l’a pas acceptée
Appareil hors ligneLa modification a attendu trop longtemps (7 jours pour une modification unique) et a été retirée
À vérifier après mise à jourUne mise à jour du firmware a modifié la description de la section ; une personne doit la relire et enregistrer
Modifiée sur l’appareilDérive : l’appareil exécute d’autres valeurs que celles demandées par Hermetry (voir ci-dessous)
Non modifiable depuis iciHermetry n’a jamais défini cette section ; elle affiche seulement ce que l’appareil indique

Construction d’une modification

Il existe deux façons d’écrire une section, qui traitent différemment ce que l’on omet.

MéthodeUtilisée parCe que vous envoyez
Section complèteL’onglet Settings, PUTToutes les valeurs de la section. Ce qui est omis ne fait pas partie de la nouvelle section.
Merge patchPATCH, baselines, jobs de réglagesUniquement ce qui change, sous forme de JSON merge patch (RFC 7386)

Un merge patch suit exactement ces règles :

  • Les objets fusionnent clé par clé. Une clé non nommée conserve sa valeur.
  • null supprime la clé.
  • Toute autre valeur remplace entièrement l’ancienne. Une liste est toujours remplacée entièrement : pour modifier une entrée d’une liste, envoyez la liste complète.

Le patch est appliqué au dernier document desired de la section, et non à ce que l’appareil remonte. Ce n’est que lorsque Hermetry n’a jamais défini la section qu’un patch part des valeurs remontées ; si l’appareil n’a pas encore remonté la section non plus, l’écriture est refusée (section_not_reported).

Bonnes pratiques :

  • Ne placez dans une baseline que ce que vous voulez modifier. Tout le reste reste tel quel sur chaque appareil.
  • Ne mettez jamais de null dans une baseline, sauf si la clé doit disparaître de chaque appareil du job.
  • Gardez hors des baselines les listes propres à chaque appareil (par exemple des listes d’adresses différentes selon le site) : la liste de la baseline remplace celle de chaque appareil.
  • Les réglages que la description marque comme modifiables uniquement sur l’appareil sont conservés à partir du rapport de l’appareil. Une modification de ceux-ci est refusée (remote_forbidden).
  • Utilisez ?dryRun=true (ou Check dans un job) pour voir quels réglages une modification touche et si elle nécessite une confirmation, avant tout envoi.

Révisions et If-Match

La lecture d’une section renvoie sa révision desired dans l’en-tête ETag, sous la forme W/"7". Chaque écriture doit renvoyer cette révision dans If-Match ; "7" et 7 sont également acceptés.

RéponseSignification
428 if_match_requiredL’écriture n’avait pas de If-Match
412 rev_mismatchQuelqu’un a modifié la section après votre lecture

En cas de 412, relisez la section, reconstruisez votre modification sur le nouveau document et écrivez à nouveau. Ne recopiez pas la nouvelle révision dans l’en-tête pour renvoyer l’ancien document : cela écraserait la modification de l’autre personne. L’onglet Settings effectue la même vérification (« Quelqu’un d’autre a modifié ces réglages depuis leur ouverture. Rechargez-les pour voir la dernière version. »).

Dérive

Une section présente une dérive lorsque l’appareil a appliqué une modification de Hermetry puis remonte ensuite des valeurs différentes, généralement parce que quelqu’un l’a modifiée directement sur l’appareil. L’onglet affiche « Modifiée sur l’appareil » et les différences. Hermetry ne corrige pas la dérive de lui-même. Vous choisissez :

ActionEffet
Renvoyer les nôtresRenvoie les valeurs desired de Hermetry sous une nouvelle révision
Garder celles de l’appareilEnregistre les valeurs actuelles de l’appareil comme nouvelles valeurs desired

Résolvez la dérive avant de modifier autrement une section en dérive. Un merge patch, donc un job de réglages, part du dernier document desired ; il renvoie donc aussi les valeurs de Hermetry pour les réglages en dérive.

Définissez qui est responsable de chaque réglage. Si des techniciens sur site doivent pouvoir modifier quelque chose, gardez-le hors des baselines et des jobs.

Secrets

  • Les réglages secrets (mots de passe, clés) ne sont jamais affichés ni renvoyés. Ils apparaissent sous la forme { "set": true }.
  • Un nouveau secret parvient à l’appareil sous forme de référence à usage unique. L’appareil récupère la valeur une seule fois par une requête signée ; une référence non récupérée expire au bout de 30 jours. Un appareil dont le firmware ne peut pas récupérer les références ne reçoit aucun secret : la modification est refusée (secret_ref_unsupported).
  • Pour conserver le secret actuel de l’appareil, laissez le champ inchangé (dans l’API, { "$keep": true }).
  • Les baselines ne peuvent pas contenir de secrets (secret_not_allowed). Définissez-les sur chaque appareil.
  • secret_pending : une modification antérieure contient un secret que l’appareil n’a pas encore récupéré. Attendez, ou saisissez à nouveau le secret.
  • secrets_need_rewrite lors de Renvoyer : la modification contient des secrets que l’appareil ne peut plus récupérer. Saisissez-les à nouveau et enregistrez.

Jobs de réglages

Un job applique une baseline, ou une seule modification, à de nombreux appareils par vagues. Bonnes pratiques :

  1. Sélectionnez par modèle et firmware que vous avez testés. L’étape Check affiche les appareils par modèle et firmware, ainsi que les sections qu’un modèle ne possède pas.
  2. Respectez les vagues. Par défaut : 1 %, puis 10 %, puis le reste. La première vague est un échantillon aléatoire fixe des appareils sélectionnés.
  3. Comprenez le seuil. Une vague réussit lorsque, parmi les appareils ayant répondu, au moins 95 % ont appliqué la modification et au plus 1 % l’ont annulée (valeurs par défaut). Les appareils ayant refusé comptent parmi ceux ayant répondu, donc ils font baisser la part des appliquées. Les appareils encore hors ligne ne comptent pas. Une vague est jugée lorsque tous ses appareils ont répondu, ou 30 minutes après son début (par défaut) sur les appareils ayant répondu d’ici là ; les autres continuent en arrière-plan. Une vague réussie lance immédiatement la suivante, sans délai d’attente. Une vague où aucun appareil n’a répondu met le job en pause.
  4. Choisissez la conduite à tenir en cas de conflit. Une seule modification à la fois peut être en cours sur la section d’un appareil. Un job attend la modification d’un autre job (et passe l’appareil après 24 heures) ou le passe immédiatement. Une modification faite par une personne pendant l’attente du job prévaut.
  5. Définissez la durée d’attente des appareils hors ligne : 7 jours par défaut, de 1 à 90.
  6. Rappelez-vous que l’annulation ne revient pas en arrière. Les appareils déjà modifiés conservent leurs nouveaux réglages.

Un job écrit avec les droits de son créateur, et un job qui modifie des réglages sensibles doit être confirmé lors de sa création. Au plus 5 jobs s’exécutent ou attendent en pause à la fois, un job contient jusqu’à 5 000 appareils, et il envoie les modifications à 200 appareils au maximum par minute.

Mises à jour du firmware et anciens firmwares

  • Après une mise à jour du firmware, Hermetry convertit les valeurs souhaitées enregistrées vers la description des réglages du nouveau firmware. Ce qu’il ne peut pas convertir en toute sécurité est marqué « Check after update ». La section reste dans cet état tant qu’une personne ne l’a pas enregistrée ; les rapports de l’appareil ne la ferment pas, et une tâche considère un tel appareil comme refusé.
  • Fenêtre de support : les écritures de réglages s’arrêtent 24 mois après la date de publication du firmware de l’appareil, telle qu’indiquée dans sa description des réglages. Les réglages restent lisibles (« Read only: update the firmware to change settings »). Une écriture répond 409 firmware_too_old avec la date de fin de la fenêtre.
  • Une tâche n’exclut pas ces appareils à l’avance. Ils sont refusés lorsque leur tour arrive et comptent dans le seuil de la vague. Mettez d’abord leur firmware à jour, ou excluez-les de la sélection.

Fréquence des modifications

Les modifications unitaires depuis l’onglet Settings et l’API, Send again inclus, sont limitées à 600 par minute et par organisation ; au-delà, 429 write_rate_limited. Les écritures d’une tâche sur ses propres appareils ne comptent pas dans cette limite.