Un cliente Go en Linux y OpenWrt: decisiones de despliegue de Fleetd

Instalar un cliente en un servidor y en un router doméstico parece, al principio, el mismo trabajo: copiar un ejecutable, escribir una configuración y arrancarlo. El uso continuado plantea otras preguntas. ¿Quién lo inicia tras reiniciar el equipo? ¿Qué ocurre si la red aún no está lista? ¿Dónde están los registros? ¿Se conservarán la identidad y los datos de protección contra repeticiones?

Fleetd administra servidores Linux y routers OpenWrt o iStoreOS. Después de explicar el alta de dispositivos y la firma de comandos, esta entrega aborda cómo convertir el cliente en un servicio persistente y fácil de diagnosticar. Describe v0.3.0: el instalador admite amd64 y arm64 con systemd o procd de OpenWrt, no cualquier dispositivo con núcleo Linux.

Un código común, binarios por arquitectura

OpenWrt también es Linux. Conexiones, autenticación, autorización y métricas básicas del núcleo pueden compartir implementación. Fleetd no mantiene clientes separados para servidores y routers: compila el mismo código para Linux y genera ejecutables amd64 y arm64.

El mismo cliente significa código y protocolo comunes, no un archivo intercambiable entre arquitecturas.

Arquitectura declarada	Selección del instalador
`x86_64`, `amd64`	`amd64`
`aarch64`, `arm64`	`arm64`
Otras	El instalador se detiene

OpenWrt cubre hardware MIPS y ARM de 32 bits que esta vía no contempla. Que Go permita compilación cruzada no garantiza soporte del proyecto. Añadir una arquitectura exige revisar dependencias, artefactos, detección, actualizaciones y comportamiento en equipos reales.

uname -m sirve como primera comprobación. El núcleo, el espacio de usuario y las funciones disponibles también condicionan la ejecución.

Un ejecutable reduce la preparación del entorno

El cliente se compila con CGO_ENABLED=0, reduciendo la dependencia del entorno C enlazado dinámicamente del equipo. No necesita un compilador Go ni un runtime Node.js o Python para arrancar. Esto ayuda en routers con almacenamiento y paquetes limitados.

No elimina todos los requisitos: debe existir conectividad, HTTPS necesita certificados de confianza válidos, la configuración requiere almacenamiento escribible y el núcleo debe ofrecer las funciones necesarias. Algunos recolectores también llaman a herramientas externas: docker para contenedores y wg para WireGuard.

La decisión simplifica la instalación básica, manteniendo explícitas las dependencias adicionales de ciertas funciones.

Detectar el entorno antes de registrar el servicio

El instalador sigue esta secuencia:

Exige root e identifica la arquitectura.
Detecta systemd o el entorno procd de OpenWrt.
Descarga el cliente correspondiente de tu servidor Fleetd.
Ejecuta version para comprobar que el archivo puede arrancar.
Crea o conserva la configuración, instala el programa y registra e inicia el servicio.
Muestra la huella del dispositivo para verificarla y aprobarla en la consola.

Una descarga correcta solo prueba que llegó un archivo. Ejecutar version comprueba además su arranque básico. No valida conexiones duraderas, recolección, permisos, inicio automático ni recuperación tras actualizar el firmware.

Para descargar, se prefiere curl y se recurre a wget si falta. En sistemas mínimos hay que confirmar que la herramienta disponible admite las peticiones HTTPS necesarias. No hay una orden universal de instalación de paquetes: las versiones de OpenWrt y el software incluido en cada firmware difieren.

La instalación inicial tiene un límite de confianza concreto. El servidor extrae el ejecutable de un paquete de versión subido cuya firma verifica. El instalador confía en ese servidor y en HTTPS; no verifica de forma independiente la firma del binario en el dispositivo. Las actualizaciones posteriores verificadas por el cliente siguen otro flujo, que merece una entrega aparte.

systemd y procd supervisan el mismo proceso

Una vez instalado el programa, el gestor de servicios del sistema controla su ciclo de vida.

Elemento	Equipo systemd	Equipo OpenWrt / procd
Ejecutable	`/usr/local/bin/fleetd-agent`	`/usr/bin/fleetd-agent`
Configuración	`/etc/fleetd/agent.yaml`	`/etc/fleetd/agent.yaml`
Servicio	`/etc/systemd/system/fleetd-agent.service`	`/etc/init.d/fleetd-agent`
Estado en instalación nueva	`/var/lib/fleetd`	`/etc/fleetd`
Registros	Journal de systemd	Registro del sistema OpenWrt

La unidad systemd apunta ExecStart al cliente, establece Restart=always con cinco segundos de espera y ordena el arranque respecto a network-online.target.

OpenWrt recibe un archivo de inicio con USE_PROCD=1, orden de arranque, comando y parámetros respawn. La salida estándar y los errores llegan al registro del sistema. Ambas variantes ejecutan la misma entrada del cliente y leen el mismo tipo de YAML. Las diferencias de distribución quedan en la instalación y la integración del servicio.

Hay dos recuperaciones distintas: el gestor trata la salida del proceso; el cliente trata la pérdida de conexión. Si el servidor no responde, el proceso puede seguir vivo y reintentar con espera progresiva. Si el proceso termina, su código de reconexión ya no puede ayudar.

El orden de arranque tampoco garantiza disponibilidad remota. Ni un objetivo de red ni un inicio tardío aseguran que DNS, el enlace ascendente y el servidor estén preparados. El cliente debe tolerar fallos de conexión.

En OpenWrt importa dónde se guarda el estado

Esta diferencia afecta directamente a la protección contra repeticiones. /var/lib/fleetd suele ser apropiado en un servidor. En configuraciones habituales de OpenWrt, /var utiliza almacenamiento temporal en RAM. Reiniciar el proceso y reiniciar el dispositivo no tienen el mismo efecto.

Por eso el instalador de OpenWrt establece state_dir en /etc/fleetd. Conviene distinguir tres archivos:

Archivo	Función
`agent.yaml`	Conexión, claves fiables, permisos y directorio de estado
`agent.key`	Clave que determina la identidad del cliente
`seen.json`	IDs aceptados para impedir repeticiones

Los dos primeros están por defecto en /etc/fleetd. seen.json sigue state_dir: /var/lib/fleetd en una instalación systemd nueva y /etc/fleetd en OpenWrt.

Regenerar una clave perdida produce otra identidad. Perder el historial de solicitudes impide prometer que los permisos todavía vigentes ya usados se reconocerán como duplicados.

No basta con que una escritura termine correctamente. Hay que comprobar si la ruta realmente corresponde a almacenamiento persistente. Firmwares personalizados, diseños de solo lectura o montajes especiales requieren su propia revisión.

La persistencia en flash tiene un coste de escritura. El cliente actual actualiza el registro al aceptar solicitudes autorizadas nuevas; no guarda en ese archivo cada informe de métricas de diez segundos. Si se convierte en un ejecutor de tareas de alta frecuencia, habrá que reevaluar frecuencia de persistencia y características de la flash. Aquí no se ofrecen garantías medidas de resistencia ni rendimiento.

Conservar configuración no restaura automáticamente el servicio

El instalador añade /etc/fleetd/ a /etc/sysupgrade.conf. Esto ayuda a conservar configuración e identidad en actualizaciones que admiten y activan esa conservación. No garantiza que también sobrevivan /usr/bin/fleetd-agent y /etc/init.d/fleetd-agent.

Tras actualizar el firmware puede quedar la configuración, pero ser necesario reinstalar el ejecutable o el archivo de inicio. Los restablecimientos de fábrica y las actualizaciones que descartan configuración quedan fuera de este mecanismo.

Antes de dar la recuperación por terminada, comprueba:

Que la configuración y la identidad siguen presentes.
Que existen el ejecutable y el servicio y siguen funcionando.
Que la huella coincide con la anterior.
Si faltan informes por servicio detenido, red no disponible o aprobación pendiente.

Son comprobaciones recomendadas, no el relato de una prueba de flasheo realizada para este artículo.

Repetir el instalador conserva un agent.yaml existente, cambia el ejecutable y reescribe el servicio. Es útil para recuperar la instalación, pero nuevos valores de --permission, --server o --signer no sobrescriben automáticamente la configuración conservada. Una ruta de estado incorrecta tampoco se corrige sola: hay que revisar el archivo y reiniciar el cliente tras modificarlo.

Compartir cliente no implica igual cobertura

Las métricas básicas proceden principalmente de /proc: CPU, memoria, carga, tiempo activo y tráfico acumulado de interfaces. CPU y velocidad de red necesitan dos muestras; la primera tras el arranque no representa un intervalo completo. Si una interfaz se recrea y sus contadores disminuyen, se omite ese cálculo de velocidad para evitar diferencias absurdas.

La recolección ampliada depende del entorno:

Información	Dependencia actual
Servicios fallidos	`systemctl list-units --state=failed`
Contenedores	`docker ps -a`
Pares WireGuard	`wg show all dump`

Que procd supervise al cliente no significa que exista recolección de salud de servicios procd. La consulta de servicios fallidos sigue usando systemd. Si una herramienta falta o falla, ese recolector no devuelve datos y la monitorización básica puede continuar. Esto evita exigir Docker en cada router, pero no observar fallos no demuestra que todos los servicios estén sanos.

La implementación no explica exhaustivamente todas las causas de ausencia. Hay que distinguir función no aplicable, herramienta ausente, llamada fallida y resultado realmente vacío. No equivalen siempre a cero incidentes.

Los informes básicos se programan cada diez segundos; discos, servicios, contenedores y WireGuard se consultan cada seis rondas. Es una política de programación, no una garantía de tiempo real: las llamadas externas, la red y la carga afectan al intervalo efectivo.

Validar la cadena de funcionamiento

En un cliente permanente importan el arranque, la supervisión, la reconexión y la conservación de identidad y configuración. En systemd, empieza por el estado y los últimos registros:

systemctl status fleetd-agent
journalctl -u fleetd-agent -n 50 --no-pager

En OpenWrt:

logread -e fleetd

Son órdenes de diagnóstico, no reinicios del equipo. Para aplicar cambios, reinicia el cliente con systemctl restart fleetd-agent o, en OpenWrt, /etc/init.d/fleetd-agent restart.

Después confirma aprobación y marcas de tiempo que avanzan en la consola, dejando llegar las siguientes muestras de CPU y red. Un dispositivo de monitorización puede permanecer en monitor: no es necesario habilitar comandos root para validarlo.

Reserva una ventana de mantenimiento para reinicios completos o cambios de firmware, especialmente si el router sostiene tu acceso a internet o remoto. Volver automáticamente con la misma huella tras un reinicio controlado aporta más evidencia operativa que ejecutar version repetidamente.

La CI incluye pruebas y compilaciones amd64/arm64. Compilar correctamente no valida cada firmware OpenWrt en hardware real. Tampoco se presentan mediciones de RAM, sobrecarga de CPU o flash mínima; revisa espacio disponible y observa tu carga.

Fleetd comparte protocolo y lógica, pero mantiene explícitas las diferencias de servicios y directorios. Así reutiliza código sin tratar el router como un servidor pequeño de estructura idéntica. La próxima entrega tratará cómo conseguir alertas útiles a partir de las métricas.