¿Cómo se actualiza el cliente Fleetd? Verificación de firmas, versiones y recuperación ante fallos

Cómo Fleetd v0.3.0 verifica firmas, arquitectura y versiones antes de sustituir el agente, y qué límites tiene la recuperación manual.

Una de las peores cosas que le puede pasar a una herramienta de administración remota es actualizar un cliente y no poder volver a conectarse a esa máquina.

Si el servidor está cerca, todavía se puede iniciar sesión para repararlo. Pero si el enrutador con OpenWrt está en otro lugar y la actualización corta la conexión, puede que el botón «Reintentar» del panel no sirva de mucho.

Así que, tras las cinco entregas anteriores sobre el desarrollo de Fleetd, esta vez toca hablar de la actualización del cliente. No consiste solo en descargar un archivo nuevo: también hay que responder tres preguntas. ¿Se puede confiar en ese archivo? ¿Es adecuado para esta máquina? ¿Qué se hace si algo falla después de instalarlo?

Primero, el alcance: este artículo se basa en el código fuente y la documentación públicos de Fleetd v0.3.0, commit c4a066d. Esta versión admite actualizaciones remotas iniciadas por un administrador, pero no busca automáticamente versiones nuevas de forma periódica ni revierte una actualización automáticamente según el estado de salud del programa. Las comprobaciones de fallos propuestas aquí son recomendaciones, no el resultado de un ensayo de actualización ya realizado en producción.

En una actualización remota, primero hay que separar quién decide qué

El proceso de actualización de Fleetd se inicia desde el panel. Un administrador sube un paquete de lanzamiento y elige una versión para una máquina conectada; también puede actualizar las máquinas conectadas de la misma arquitectura que tengan una versión anterior.[1]

El servidor se encarga de distribuir el paquete y transmitir la solicitud de actualización. El cliente decide si la acepta.

Esta distinción importa: que un archivo aparezca en el propio panel no debería convertirlo automáticamente en fiable. El cliente tiene configurada localmente la clave pública de lanzamiento release_key y debe verificar por sí mismo la firma del paquete recibido. Si esa clave pública no está configurada, rechaza la actualización remota.[2]

Si el servidor también tiene configurada una clave pública de lanzamiento, verifica el paquete al subirlo. Pero esa comprobación del servidor no sustituye la del cliente. Según el código fuente, cuando el servidor no tiene configurada esa clave pública, puede limitarse a analizar el manifiesto del paquete para almacenarlo y mostrarlo. Por tanto, que la subida se complete no demuestra que el cliente vaya a aceptarlo.[4]

La clave privada de lanzamiento determina quién puede crear paquetes que serán considerados fiables; la clave pública determina en quién confía el cliente. En una instalación propia, hay que dejar claro quién controla las claves de lanzamiento, en lugar de tratar cualquier paquete descargado como un archivo instalable.

Esto también es distinto de la firma de comandos del navegador tratada anteriormente: la firma de comandos autoriza operaciones concretas; la firma de lanzamiento autentica paquetes de software. No deben confundirse sus funciones ni la gestión de sus claves.

Firmar no es solo calcular el hash de un archivo

El paquete de lanzamiento de v0.3.0 contiene un manifiesto, una firma y el binario del cliente. El manifiesto registra la versión, la arquitectura de CPU, el tamaño del archivo y su SHA-256.[3]

La firma cubre los bytes originales del manifiesto; el hash incluido en este, a su vez, vincula el contenido del binario. El cliente primero verifica la firma Ed25519 con la clave pública de confianza y después comprueba que el tamaño y el hash del binario coincidan con el manifiesto.

Esto resuelve dos cuestiones relacionadas:

  • ¿Firmó el manifiesto quien posee la clave privada correspondiente y permanece sin modificaciones?
  • ¿Es el binario descargado realmente el archivo descrito por ese manifiesto?

Un hash sin una firma de origen fiable no cumple la misma función. Si un atacante puede sustituir tanto el archivo como el hash que lo acompaña, ambos pueden seguir «coincidiendo».

Pero una firma válida tampoco demuestra que el software esté libre de errores. Demuestra que el archivo procede del proceso de firma en el que se confía, no que el programa funcione correctamente en todas las máquinas. Una filtración de la clave privada de lanzamiento, un problema en el entorno de compilación o un programa defectuoso firmado por los propios mantenedores requieren otras medidas.

El cliente debe volver a comprobar la versión y la arquitectura

Después de verificar la firma, el cliente comprueba que la arquitectura del manifiesto coincida con su propio runtime.GOARCH y que la versión del manifiesto sea más reciente que la que está ejecutando.[2]

Por tanto, un paquete arm64 correctamente firmado no puede instalarse en un cliente amd64 solo porque aparezca en la lista del panel.

La comparación de versiones también tiene límites concretos. v0.3.0 compara los tres números enteros de la versión principal, secundaria y de revisión; ignora el sufijo que sigue a un guion.[3]

Por ejemplo, según las reglas de esa función, 0.4.0-dev y 0.4.0 tienen el mismo núcleo de versión, por lo que la segunda no se considerará más reciente que la primera. No se trata de las reglas completas de ordenación de versiones preliminares de SemVer: no se puede sustituir el comportamiento del código por una intuición general sobre SemVer.

Se rechazan las versiones iguales y las anteriores. Esto impide bajar arbitrariamente de versión mediante la vía normal de actualización, pero no es una protección contra las regresiones de versión a todos los niveles: quien tenga permisos para modificar archivos locales todavía puede reemplazar el programa, y restaurar un archivo anterior es una vía de mantenimiento prevista expresamente en la documentación.

En los lanzamientos habituales, el manifiesto debe indicar la misma versión que está integrada en el binario. El script de compilación del proyecto establece la versión del programa y, cuando se proporciona una versión de lanzamiento y un archivo de clave privada de firma, también genera paquetes firmados para las arquitecturas correspondientes.[5]

Antes de sustituirlo, hay que pedirle al programa nuevo que indique su versión

El cliente no sobrescribe su ejecutable en cuanto termina la descarga.

Primero escribe el binario verificado en un archivo .new junto al ejecutable. Después ejecuta el subcomando version de ese archivo nuevo y exige que el programa termine dentro de un tiempo límite y que su salida coincida con la versión del manifiesto firmado.[2]

Este paso detecta algunos errores evidentes, como un programa que no arranca, un artefacto de compilación incorrecto o un programa que declara otra versión.

Sigue siendo una comprobación muy limitada. Que pueda mostrar un número de versión no significa que funcionen correctamente la lectura de la configuración, la conexión con el servidor, la recopilación de métricas o la ejecución de operaciones autorizadas. Un programa que supera la prueba de version todavía puede fallar durante el arranque normal.

Una vez superada la comprobación, el programa intenta conservar el ejecutable anterior como .old y luego sustituye la ruta definitiva por .new mediante un cambio de nombre. Situar el archivo temporal en el mismo directorio forma parte de este proceso de sustitución; no debe suponerse que una copia entre sistemas de archivos cualesquiera tenga el mismo comportamiento.

Tras la sustitución, el proceso actual comunica el resultado y sale. El arranque posterior queda a cargo de systemd o procd. Las plantillas de instalación del proyecto configuran mecanismos de reinicio para ambos; si ejecutas el cliente manualmente o has modificado la configuración del servicio, tendrás que comprobar por separado qué se encarga de iniciar el programa nuevo.

Por eso, que el panel reciba un resultado de instalación correcta y que el proceso nuevo ya esté funcionando y conectado son dos momentos distintos.

Para recuperarse de un fallo, hay que ver en qué fase ocurrió

Decir que «si falla, se revierte» es demasiado impreciso. Según la implementación de v0.3.0, hay que distinguir al menos estas fases:

Fase en la que falla Qué hace la implementación actual Qué queda por comprobar
Falla la descarga o la comprobación de la firma, el contenido, la arquitectura o la versión Devuelve un error y no sustituye el programa definitivo Si se ha registrado la causa del error y si el cliente anterior sigue funcionando normalmente
Falla la autocomprobación de versión del programa nuevo Elimina el archivo temporal y conserva el programa definitivo Si el problema está en la compilación, el entorno de ejecución o el identificador de versión
Falla el cambio de nombre durante la sustitución Devuelve un error y limpia el archivo temporal Los permisos del directorio y el estado del sistema de archivos y del disco
Tras la sustitución, falla el arranque o el funcionamiento del proceso nuevo No hay un proceso de reversión automática basado en el estado de salud El acceso fuera de banda, el archivo anterior, las copias de seguridad de la configuración y la capacidad de recuperación manual

Hay otro detalle fácil de pasar por alto: el código primero intenta guardar el programa anterior mediante un enlace físico y, si eso falla, intenta copiarlo mediante lectura y escritura. Algunos fallos de esta vía alternativa no impiden que continúe la sustitución.[2]

Por tanto, la mera presencia de .old en la implementación no permite prometer que siempre se haya generado una copia de seguridad utilizable. Antes de un lanzamiento definitivo, conviene verificar que el archivo anterior realmente existe, que su contenido es correcto y que puede ejecutarse, además de conservar una vía de recuperación independiente.

Del mismo modo, sustituir un archivo mediante un cambio de nombre no constituye una transacción de actualización de toda la máquina ni garantiza la persistencia de los datos tras un corte eléctrico. Para este artículo no se han hecho pruebas de cortes eléctricos, fallos de disco ni dispositivos OpenWrt reales.

Actualiza primero una máquina antes de plantearte una actualización masiva

La documentación del proyecto indica expresamente que no se ha implementado una actualización completamente automática: si se distribuye una versión defectuosa a todas las máquinas a la vez, todos los clientes podrían perder la conexión y, una vez desconectados, ya no sería posible depender del panel para repararlos.[1]

Prefiero dividir la validación de una actualización en tres partes.

La primera consiste en probar los rechazos antes de la instalación. En un entorno aislado, prepara paquetes con una firma incorrecta, contenido modificado, una arquitectura equivocada y una versión igual o anterior. Comprueba que el cliente rechaza la instalación y que el archivo definitivo no se sustituye.

La segunda consiste en probar la sustitución. Comprueba la autoverificación de versión del programa nuevo, la conservación del archivo anterior y si el gestor de servicios llega realmente a iniciar el proceso nuevo.

La tercera consiste en comprobar el funcionamiento después de que la máquina vuelva a estar en línea. Confirma que la versión nueva se reconecta, que las métricas siguen llegando y que se pueden completar las operaciones necesarias. Obsérvala durante un periodo adecuado para tu actividad antes de ampliar el despliegue. Aquí no se establece un umbral universal del tipo «esperar unos minutos basta para estar seguros».

El repositorio ya incluye pruebas del paquete de lanzamiento y de la lógica de instalación. Cubren rutas como firmas incorrectas, archivos manipulados, rechazo por versión o arquitectura, discrepancias en la salida de versión y conservación del archivo anterior tras una sustitución correcta.[6] Para este artículo se leyeron esas pruebas, pero no se volvieron a ejecutar ni se tomaron como prueba de una actualización satisfactoria en un dispositivo real.

Si el programa nuevo ya ha perdido la conexión, la recuperación debe ajustarse al entorno de despliegue. La guía oficial propone sustituir manualmente el binario por el anterior y reiniciar el servicio; las rutas del programa y la forma de gestionar el servicio difieren entre Linux y OpenWrt, así que no conviene copiar sin más los comandos de un tipo de máquina en el otro.[1]

Una actualización fiable debería considerarse terminada cuando la máquina vuelve a estar conectada y completa el trabajo necesario. Las comprobaciones de firma y versión son controles previos; también hay que mantener disponible la vía de recuperación posterior.

Referencias

Fecha de verificación: 2026-11-09. El análisis de la implementación se limita a v0.3.0 y no representa necesariamente el comportamiento de versiones posteriores. Artículo anterior: Después de monitorizar el servidor, ¿cómo hacer que las alertas sean realmente útiles?

  1. Fleetd v0.3.0: guía de actualización del cliente.
  2. Implementación de la actualización y autocomprobación del cliente.
  3. Firma y verificación de paquetes de lanzamiento y comparación de versiones.
  4. Subida y distribución de paquetes de lanzamiento en el servidor.
  5. Script de compilación y plantilla de instalación del servicio del cliente.
  6. Pruebas de instalación y pruebas de paquetes de lanzamiento.

Ilustración conceptual generada con IA; no es una prueba de producto, una interfaz real ni un diagrama de cableado.

Discussion

Share a question or your experience. Comments appear after moderation. Your email is never displayed publicly. Comment privacy

Loading comments…