Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Buenas prácticas en los ajustes remotos

Cómo se comportan en detalle los ajustes remotos de dispositivos y cómo cambiarlos de forma segura en uno o en muchos: valores deseados e informados, reglas de fusión, revisiones, desviación, secretos, trabajos y firmware antiguo.

Esta página es para administradores e integradores que cambian la configuración de dispositivos desde Hermetry, a mano o a través de la API, en un dispositivo o en muchos. Explica las reglas que hay detrás de la pestaña Settings y cómo usarlas con seguridad. Cómo abrir la pestaña, crear líneas base e iniciar trabajos se explica en Remote device settings; las rutas están en Firmware and device settings API.

Valores deseados y valores reportados

Para cada sección de configuración de un dispositivo, Hermetry mantiene dos documentos:

  • Deseado: lo que Hermetry pidió por última vez que ejecute el dispositivo, con un número de revisión que aumenta con cada cambio.
  • Reportado: lo que el dispositivo dice que ejecuta, con la revisión que aplicó.

Cada cambio envía la sección completa al dispositivo, no solo las claves que cambiaron. El dispositivo aplica una sección solo cuando su revisión es superior a la última que aplicó. Una sección que esperó demasiado al dispositivo se retira; entonces el dispositivo conserva la configuración que tiene.

Estado en la pestaña SettingsSignificado
En caminoEnviado, o esperando a que el dispositivo se conecte
El dispositivo lo está probandoEl dispositivo ejecuta el cambio en modo de prueba y lo deshace por sí mismo si no puede volver a alcanzar la nube
AplicadoEl dispositivo ejecuta el cambio
Deshecho por el dispositivoEl dispositivo lo probó y volvió atrás
Rechazado por el dispositivoEl dispositivo no lo aceptó
El dispositivo estaba sin conexiónEl cambio esperó demasiado (7 días para un único cambio) y se retiró
Revisar tras la actualizaciónUna actualización de firmware cambió la descripción de la sección; una persona debe revisarla y guardar
Cambiado en el dispositivoDesviación: el dispositivo ejecuta otros valores de los que pidió Hermetry (véase abajo)
No cambiado desde aquíHermetry nunca estableció esta sección; solo muestra lo que informa el dispositivo

Cómo se construye un cambio

Hay dos formas de escribir una sección, y tratan de forma distinta lo que se omite.

FormaUsada porLo que se envía
Sección completaLa pestaña Settings, PUTCada valor de la sección. Lo que se omite no forma parte de la nueva sección.
Parche de fusiónPATCH, líneas base, trabajos de configuraciónSolo lo que cambia, como parche de fusión JSON (RFC 7386)

Un parche de fusión sigue exactamente estas reglas:

  • Los objetos se fusionan clave a clave. Una clave que no nombras conserva su valor.
  • null elimina la clave.
  • Cualquier otro valor reemplaza por completo al anterior. Una lista siempre se reemplaza completa: para cambiar una entrada de una lista, envía la lista completa.

El parche se aplica sobre el último documento deseado de la sección, no sobre lo que reporta el dispositivo. Solo cuando Hermetry nunca ha establecido la sección un parche parte de los valores reportados; si el dispositivo tampoco ha reportado todavía la sección, la escritura se rechaza (section_not_reported).

Buenas prácticas:

  • Incluye en una línea base solo lo que quieres cambiar. Todo lo demás se mantiene como está en cada dispositivo.
  • No pongas nunca null en una línea base salvo que la clave deba desaparecer de todos los dispositivos del trabajo.
  • Mantén fuera de las líneas base las listas específicas de cada dispositivo (por ejemplo, listas de direcciones que difieren por sede): la lista de la línea base reemplaza la lista de cada dispositivo.
  • Los ajustes que la descripción marca como modificables solo en el dispositivo se mantienen según el informe del dispositivo. Un cambio en ellos se rechaza (remote_forbidden).
  • Usa ?dryRun=true (o Check en un trabajo) para ver qué ajustes toca un cambio y si necesita confirmación, antes de que se envíe nada.

Revisiones y If-Match

Al leer una sección, se devuelve su revisión deseada como cabecera ETag, con la forma W/"7". Cada escritura debe devolver esa revisión en If-Match; "7" y 7 también se aceptan.

RespuestaSignificado
428 if_match_requiredLa escritura no tenía If-Match
412 rev_mismatchAlguien cambió la sección después de que la leyeras

Ante un 412, vuelve a leer la sección, reconstruye tu cambio sobre el nuevo documento y escribe de nuevo. No copies la nueva revisión en la cabecera y reenvíes el documento antiguo: eso sobrescribe el cambio de la otra persona. La pestaña Settings hace la misma comprobación (“Alguien más ha cambiado estos ajustes desde que los abriste. Vuelve a cargarlos para ver la última versión.”).

Desviación

Una sección tiene desviación cuando el dispositivo aplicó un cambio de Hermetry y después informa de valores distintos, normalmente porque alguien lo cambió en el propio dispositivo. La pestaña muestra “Cambiado en el dispositivo” y qué difiere. Hermetry no corrige la desviación por sí mismo. Tú eliges:

AcciónEfecto
Enviar los nuestros de nuevoEnvía de nuevo los valores deseados de Hermetry como una nueva revisión
Conservar los del dispositivoGuarda los valores actuales del dispositivo como nuevos valores deseados

Resuelve la desviación antes de cambiar de otra forma una sección desviada. Un parche de fusión, y por tanto un trabajo de configuración, parte del último documento deseado, así que también devuelve los valores de Hermetry para los ajustes desviados.

Decide quién es responsable de cada ajuste. Si los técnicos en sitio deben poder cambiar algo, mantenlo fuera de las líneas base y de los trabajos.

Secretos

  • Los ajustes secretos (contraseñas, claves) nunca se muestran ni se devuelven. Se leen como { "set": true }.
  • Un secreto nuevo llega al dispositivo como referencia de un solo uso. El dispositivo obtiene el valor una vez mediante una petición firmada; una referencia que no se obtiene caduca a los 30 días. Un dispositivo cuyo firmware no puede obtener referencias no recibe ningún secreto: el cambio se rechaza (secret_ref_unsupported).
  • Para conservar el secreto actual del dispositivo, deja el campo sin cambios (en la API, { "$keep": true }).
  • Las líneas base no pueden contener secretos (secret_not_allowed). Establécelos en cada dispositivo.
  • secret_pending: un cambio anterior lleva un secreto que el dispositivo todavía no ha obtenido. Espera, o introduce el secreto de nuevo.
  • secrets_need_rewrite al pulsar Enviar de nuevo: el cambio lleva secretos que el dispositivo ya no puede obtener. Introdúcelos de nuevo y guarda.

Trabajos de configuración

Un trabajo aplica una línea base, o un solo cambio, a muchos dispositivos por oleadas. Buenas prácticas:

  1. Selecciona por modelo y firmware que hayas probado. El paso Check muestra los dispositivos por modelo y firmware, y las secciones que un modelo no tiene.
  2. Mantén las oleadas. Por defecto son 1 %, luego 10 % y después el resto. La primera oleada es una muestra aleatoria fija y representativa de los dispositivos seleccionados.
  3. Entiende el filtro. Una oleada se supera cuando, entre los dispositivos que respondieron, al menos el 95 % aplicó el cambio y como máximo el 1 % lo deshizo (los valores por defecto). Los dispositivos que rechazaron cuentan entre los que respondieron, así que bajan el porcentaje de aplicados. Los dispositivos aún sin conexión no cuentan. Una oleada se evalúa cuando todos sus dispositivos han respondido, o 30 minutos después de empezar (por defecto), con los dispositivos que hayan respondido hasta entonces; los demás continúan en segundo plano. Una oleada superada inicia la siguiente de inmediato, sin tiempo de espera. Una oleada en la que ningún dispositivo respondió pausa el trabajo.
  4. Elige qué ocurre ante un conflicto. Solo puede haber un cambio en curso a la vez en la sección de un dispositivo. Un trabajo espera el cambio de otro trabajo (y omite el dispositivo tras 24 horas) u omite el dispositivo de inmediato. Un cambio que una persona haga mientras el trabajo espera prevalece.
  5. Define cuánto esperar a los dispositivos sin conexión: 7 días por defecto, de 1 a 90.
  6. Recuerda que cancelar no deshace los cambios. Los dispositivos ya cambiados conservan su nueva configuración.

Un trabajo escribe con los permisos que tenía su creador, y un trabajo que cambia ajustes peligrosos debe confirmarse al crearse. Como máximo 5 trabajos se ejecutan o esperan en pausa a la vez, un trabajo abarca hasta 5.000 dispositivos y envía cambios a un máximo de 200 dispositivos por minuto.

Actualizaciones de firmware y firmware antiguo

  • Después de una actualización de firmware, Hermetry convierte los valores deseados almacenados a la descripción de ajustes del nuevo firmware. Lo que no puede convertir de forma segura se marca como «Check after update». La sección permanece en ese estado hasta que una persona la guarda; los informes del dispositivo no la cierran, y un trabajo considera rechazado a ese dispositivo.
  • Ventana de soporte: las escrituras de ajustes se detienen 24 meses después de la fecha de publicación del firmware del dispositivo, según consta en su descripción de ajustes. Los ajustes siguen siendo legibles («Read only: update the firmware to change settings»). Una escritura responde 409 firmware_too_old con la fecha en que terminó la ventana.
  • Un trabajo no excluye de antemano a estos dispositivos. Se rechazan cuando llega su turno y cuentan contra la puerta de la oleada. Actualice primero su firmware o exclúyalos de la selección.

Frecuencia de cambios

Los cambios individuales desde la pestaña Settings y la API, incluido Send again, están limitados a 600 por minuto por organización; por encima de eso, 429 write_rate_limited. Las escrituras propias de un trabajo a sus dispositivos no cuentan para este límite.