Integración domótica Network UPS Tools (NUT), gratuita y de código abierto
Supervise el estado, la carga y la autonomía de los SAI de sus servidores NUT.
Publicado por prohand
- Dispositivos
- Versión 2.3.1
- Requiere Gladys >=5.1.0
- ★ 0
La integración Network UPS Tools (NUT) permite a Gladys obtener valores y estados de los SAI expuestos por un servidor NUT upsd accesible en la red local.
Esta integración está pensada para la supervisión. No envía comandos de apagado, reinicio ni configuración a los SAI.
Requisitos previos
Su SAI ya debe funcionar en NUT. Desde la máquina que aloja Gladys, el servidor NUT debería responder al siguiente comando, tras sustituir los marcadores por sus propios valores:
upsc <ups-name>@<server-address>
Por defecto, upsd escucha en el puerto TCP 3493. Asegúrese de que tanto las reglas de red como las ACL de NUT permiten el acceso desde Gladys.
Las credenciales viajan en texto plano
La integración no utiliza TLS (STARTTLS): el usuario y la contraseña de NUT, así como todas las mediciones, atraviesan la red en texto plano. Manténgala en una red de confianza:
- haga que
upsdescuche solo en la interfaz por la que lo alcanza Gladys (LISTENenupsd.conf) y filtre el puerto 3493 para que solo el host de Gladys pueda conectarse; - cree en
upsd.usersun usuario dedicado para Gladys, sinactionsniinstcmds: la integración solo lee, así que nunca los necesita; - no reutilice nunca esa contraseña en otro sitio.
Configuración
- Abra Integraciones y luego Network UPS Tools (NUT).
- En la pestaña Configuración, introduzca el primer servidor
upsd; su host es obligatorio. - Añada hasta cuatro servidores adicionales en los campos opcionales si lo necesita.
- Para cada servidor, mantenga el puerto
3493salvo que su instalación use otro. Introduzca las credenciales de NUT si se requiere autenticación. - Elija un intervalo de actualización. El valor predeterminado de 300 segundos es adecuado para la mayoría de las instalaciones. Gladys consulta los dispositivos como mucho una vez por minuto: un intervalo más largo se aplica en la consulta más cercana.
- Pulse Guardar configuración y luego use Probar las conexiones NUT.
Elegir el intervalo de actualización
Cada valor publicado se conserva en el historial de Gladys, y un SAI expone hasta doce valores. Un intervalo corto hace crecer rápidamente la base de datos: a 60 segundos, un solo SAI escribe unas 17 000 filas al día, frente a unas 3500 con el intervalo predeterminado de 300 segundos.
Para reducir aún más ese volumen, la integración solo publica los valores que han cambiado desde la medición anterior; un valor que se mantiene estable se vuelve a publicar al menos una vez por hora para que nunca aparezca como obsoleto. Baje a 60 segundos solo si necesita una supervisión fina —la autonomía restante durante un corte, por ejemplo— y suba el intervalo hasta 86 400 segundos si prefiere cuidar la base de datos.
Una vez establecida la conexión, Gladys detecta todos los SAI que devuelve el servidor NUT. Cada SAI aparece en Dispositivos descubiertos como un dispositivo Gladys distinto. En la pestaña Descubrir, haga clic en Añadir a Gladys en cada SAI que quiera integrar: puede añadir varios dispositivos de forma independiente. La lista se reconstruye en cada búsqueda (Buscar) a partir del comando NUT LIST UPS.
Información disponible
No todos los controladores NUT informan de las mismas variables, así que la integración solo crea sensores para la información que cada SAI proporciona realmente.
| Ámbito | Valores posibles |
|---|---|
| Batería | Carga, autonomía, tensión y temperatura |
| Corriente | Tensión y corriente de entrada/salida |
| Carga | Porcentaje de carga, potencia activa y potencia aparente |
| SAI | Temperatura, estado y alarmas |
Los valores solo se publican cuando son numéricos y el controlador los informa realmente. Los estados de texto de NUT se leen durante la comunicación, pero no se publican como funciones de Gladys, para que los datos de detección sigan siendo compatibles con las versiones del Core que aún no reconocen la categoría text.
Widget, escenas y acciones (Gladys 5.1)
La integración requiere Gladys 5.1 o posterior.
Widget «SAI»
En Panel → Editar → Nuevo widget, en la sección Widgets de integraciones, elija SAI y luego el SAI que quiere mostrar. El widget muestra:
- la carga de la batería (indicador) y la autonomía restante;
- la carga del SAI y la tensión de entrada;
- un gráfico de 24 h (carga de la batería y carga del SAI);
- el estado (con red eléctrica, con batería, batería baja…), las alarmas de NUT, la potencia y el servidor;
- un botón Actualizar, que lee el SAI al instante. Nunca envía un comando al SAI.
El widget muestra la última medición realizada por la integración (de 3 minutos como máximo). Cuando el SAI tarda en responder, muestra «Leyendo el SAI…» y se actualiza unos segundos después.
Activadores de escena
En una escena, Añadir activador → Integraciones:
| Activador | Cuándo |
|---|---|
| SAI: corte de corriente, con batería | el SAI pasa a funcionar con batería (OB) |
| SAI: corriente restablecida | el SAI vuelve a la red eléctrica (OL) |
| SAI: batería baja | NUT informa de una batería baja (LB) |
| SAI: sustituir la batería | NUT pide una sustitución (RB) |
- Deje vacío el campo SAI para reaccionar a todos los SAI.
- El estado se comprueba cada minuto, sea cual sea el intervalo de actualización: un corte de corriente se detecta en menos de un minuto.
- Variables disponibles en la escena:
ups_name,status,battery_charge(%),battery_runtime(min),load(%). - Al iniciarse la integración, la primera medición sirve de referencia: no se envía ningún evento para un SAI que ya funciona con batería.
Acción de escena «Leer el estado de un SAI»
En una escena, Nueva acción → Integraciones. Lee el SAI elegido y devuelve a las acciones siguientes: ups_name, status (online, on_battery, low_battery, forced_shutdown, off, bypass, unknown), on_battery, low_battery, replace_battery, battery_charge, battery_runtime (min), load, input_voltage. Una medición de la que el SAI no informa se omite.
Ejemplo: cada mañana, leer el estado del SAI y luego enviar un mensaje con la autonomía restante.
Solución de problemas
| Síntoma | Comprobaciones recomendadas |
|---|---|
| No se encuentra ningún SAI | Compruebe cada host, cada puerto, el cortafuegos y que haya al menos un SAI configurado en cada ups.conf. |
| Error de acceso o de autenticación | Compruebe las ACL de upsd.conf y las credenciales definidas en upsd.users. |
| Faltan algunos valores | Ejecute upsc <ups>@<server>; Gladys solo puede crear las variables que expone su controlador NUT. |
| Datos obsoletos | Un valor estable solo se reescribe una vez por hora, lo cual es normal. Más allá de eso, verifique que el controlador NUT sigue comunicándose con el hardware y revise los registros de upsd. |
| La base de datos de Gladys crece demasiado rápido | Aumente el intervalo de actualización: el volumen del historial es directamente proporcional a él. Cada SAI añadido escribe su propio historial. |
| Añadir un SAI falla con «dispositivo incompleto o no válido» | Actualice la integración. Ese rechazo (HTTP 422) se debía a funciones publicadas sin sus límites min y max, que ahora siempre se declaran. |
| Los valores no cambian nunca tras añadir el dispositivo | Actualice la integración: los dispositivos se publican ahora con la consulta periódica activada. |
| Algunas funciones se muestran sin nombre ni icono | Actualice la integración y luego vuelva a añadir el SAI desde la pestaña Descubrir para que se actualicen sus funciones existentes: la carga y la potencia aparente se publicaban con un par categoría/tipo que el front-end de Gladys no sabe dibujar. |
| El estado de conexión dice «Conectado, pero 1 de 2 servidores NUT no responden» | Los SAI de los demás servidores se siguen leyendo. Compruebe el servidor indicado (host, puerto, cortafuegos, upsd en marcha); el estado vuelve a ser simplemente «conectado» en su siguiente respuesta. |
| Un SAI dejó de actualizarse tras quitar un servidor de la configuración | Su servidor ya no se consulta, y los registros lo indican una vez. Vuelva a añadir el servidor o elimine el dispositivo en Gladys. |
| La carga del SAI se muestra como «Desconocido» | Actualice la integración y luego vuelva a añadir el SAI desde la pestaña Descubrir: la carga (ups.load) se publica ahora en una categoría que permite a Gladys mostrar su nombre, «Load». |
Para ver los errores detallados, abra la pestaña Registros de la integración en Gladys. También puede definir LOG_LEVEL=debug para obtener registros más detallados.
Recursos
La especificación oficial del protocolo de red de NUT detalla los comandos de detección y de lectura que utiliza esta integración.
Parámetros de configuración
Estos son los parámetros que Network UPS Tools (NUT) te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Servidores NUT | section | No | Configure uno o varios servidores upsd accesibles. Cada SAI expuesto por cada servidor configurado se detecta como un dispositivo Gladys independiente. |
| Host del servidor 1 | string | Sí | Dirección IP o nombre DNS del primer servidor NUT upsd. |
| Puerto del servidor 1 | number | No | El puerto TCP predeterminado de NUT es 3493. |
| Usuario del servidor 1 (opcional) | string | No | |
| Contraseña del servidor 1 (opcional) | secret | No | Obligatoria si se ha configurado un usuario. |
| Host del servidor 2 (opcional) | string | No | |
| Puerto del servidor 2 | number | No | |
| Usuario del servidor 2 | string | No | |
| Contraseña del servidor 2 | secret | No | |
| Host del servidor 3 (opcional) | string | No | |
| Puerto del servidor 3 | number | No | |
| Usuario del servidor 3 | string | No | |
| Contraseña del servidor 3 | secret | No | |
| Host del servidor 4 (opcional) | string | No | |
| Puerto del servidor 4 | number | No | |
| Usuario del servidor 4 | string | No | |
| Contraseña del servidor 4 | secret | No | |
| Host del servidor 5 (opcional) | string | No | |
| Puerto del servidor 5 | number | No | |
| Usuario del servidor 5 | string | No | |
| Contraseña del servidor 5 | secret | No | |
| Intervalo de actualización (s) | number | No | Frecuencia con la que las mediciones se escriben en el historial de Gladys. Cada medición es una fila en la base de datos: mantenga 300 s salvo que necesite mediciones más finas. El estado del SAI se sigue comprobando cada minuto para las escenas. |
Cómo instalar Network UPS Tools (NUT) en Gladys
- En Gladys, abre Integraciones: Network UPS Tools (NUT) aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/prohand/gladys-nut:2.3.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/prohand/gladys-nut.
Network UPS Tools (NUT) requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Network UPS Tools (NUT) es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene prohand, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación