Integración domótica OPNsense, gratuita y de código abierto
Cortafuegos OPNsense: estado, puertas de enlace, tráfico, presencia en red, reglas, WireGuard.
Publicado por William-De71
- Dispositivos
- Versión 0.1.0
- Requiere Gladys >=5.1.0
- ★ 0
Presentación
Esta integración trae su cortafuegos OPNsense a Gladys, mediante la API de OPNsense en su red local:
- un dispositivo cortafuegos: uso de CPU, memoria y disco, temperatura, tiempo en marcha, actualizaciones pendientes, versión y pares WireGuard conectados;
- un dispositivo por puerta de enlace (estado, latencia, pérdida de paquetes) y por interfaz (velocidades recibida y enviada, enlace, dirección IPv4);
- las reglas del cortafuegos de la categoría que elija, como interruptores: active o desactive una regla desde un panel o una escena;
- los dispositivos de su red (teléfonos, ordenadores…) como sensores de presencia, a partir de la tabla ARP y de las concesiones DHCP;
- escenas: puerta de enlace caída, alguien ha llegado a casa, nuevo dispositivo en la red, conexión VPN, servicio detenido, actualización disponible; y acciones para despertar un ordenador, bloquear un dispositivo, reiniciar un servicio, buscar actualizaciones o reiniciar;
- cuatro widgets de panel.
Todo se queda en su red: la integración solo habla con OPNsense, nunca con una nube.
Requisitos previos
- Gladys Assistant 5.1.0 o posterior.
- OPNsense 25.1 o posterior (escrita a partir de la API de OPNsense 26.7), accesible desde el equipo de Gladys.
- Un usuario de OPNsense dedicado a Gladys, con una clave de API. Créelo en Sistema > Acceso > Usuarios y dele los privilegios de las funciones que quiera (campo Privilegios):
| Función | Privilegio de OPNsense |
|---|---|
| Cortafuegos (CPU, memoria, disco) | Lobby: Dashboard |
| Puertas de enlace | System: Gateways |
| Interfaces | Status: Interfaces, Reporting: Traffic |
| Dispositivos de red | Diagnostics: ARP Table, y Services: Dnsmasq DNS/DHCP o DHCP: Kea(v4) |
| WireGuard | VPN: WireGuard: Status |
| Servicios (disparador, reinicio) | Status: Services |
| Actualizaciones (búsqueda) | System: Firmware |
| Interruptores de reglas | Firewall: Rules [new], Firewall: Categories |
| Acción sobre los alias | Diagnostics: PF Table IP addresses |
| Reinicio | Diagnostics: Reboot System |
| Wake-on-LAN (plugin os-wol) | Services: Wake on LAN |
Un privilegio no concedido simplemente desactiva su función. «System: Firmware» también permite instalar actualizaciones por la API: concédalo solo si quiere la búsqueda de actualizaciones. Los nombres de los privilegios son los de la interfaz en inglés de OPNsense.
En la página del usuario, sección Claves de API, pulse +: se descarga un archivo key.txt, con una línea key= y una línea secret=.
Configuración
En Gladys, abra Integraciones > OPNsense, instálela y rellene:
| Campo | Qué introducir |
|---|---|
| Dirección de OPNsense | La dirección de la interfaz web, por ejemplo https://192.168.1.1 (añada el puerto si no es el 443). |
| Clave de API | La línea key= de key.txt. |
| Secreto de la API | La línea secret= de key.txt. No se vuelve a mostrar ni se escribe en los registros. |
| Verificar el certificado | Déjelo sin marcar con el certificado autofirmado de OPNsense; márquelo con un certificado válido. |
| Intervalo de lectura | De 10 a 300 segundos, 30 por defecto. |
| Dispositivos de red ofrecidos | Los dispositivos ofrecidos en el descubrimiento: los que tienen nombre (por defecto), todos o ninguno. |
| Retardo de ausencia | Minutos sin respuesta antes de que un dispositivo esté ausente, 5 por defecto. |
| Categoría de las reglas | Las reglas del cortafuegos de esta categoría se convierten en interruptores (gladys por defecto; vacío: ninguna). |
| Idioma de los textos | Idioma de los nombres, estados y resúmenes de escenas; automático sigue su panel. |
Pulse Probar la conexión: Gladys muestra el nombre y la versión de su OPNsense.
Uso
Dispositivos
Abra Integraciones > OPNsense > Descubrimiento y añada los dispositivos que quiera. Nada se crea sin usted.
| Dispositivo | Funciones |
|---|---|
| OPNsense (cortafuegos) | Uso de CPU, memoria y disco (%), temperatura, tiempo en marcha (días), actualizaciones pendientes, versión, pares VPN |
| Puerta de enlace | Estado (en línea, sin conexión, degradada, pendiente), latencia (ms), pérdida de paquetes (%) |
| Interfaz | Velocidades recibida y enviada (Mbit/s, vistas desde la interfaz: en la WAN, recibido es la descarga), enlace, dirección IPv4 |
| Regla | Activada: un interruptor |
| Dispositivo de red | Presencia |
Presencia de los dispositivos
Un dispositivo de su red está presente en cuanto responde en la tabla ARP de OPNsense, y ausente cuando lleva fuera el retardo de ausencia. El sensor de presencia envía 1 cada minuto mientras el dispositivo está, como la presencia Bluetooth de Gladys: úselo en la acción de escena Comprobar presencia del usuario para saber si alguien está en casa. Un teléfono con dirección Wi-Fi privada (aleatoria) solo conserva la misma dirección en su red si la opción se fija por red: compruébelo en el teléfono.
Reglas del cortafuegos
En OPNsense, abra Cortafuegos > Reglas, edite una regla (por ejemplo «Bloquear la tableta de los niños») y asígnele la categoría gladys (créela en Cortafuegos > Categorías). Tras un descubrimiento, la regla aparece como un interruptor: encendido activa la regla, apagado la desactiva, y OPNsense aplica el cambio al instante. Solo se pueden conmutar las reglas del nuevo editor de reglas, no las reglas automáticas.
Widgets del panel
- Cortafuegos OPNsense: indicadores de CPU, memoria y disco, temperatura, puertas de enlace, tiempo en marcha, actualizaciones, y dos botones: buscar actualizaciones y reiniciar (con confirmación).
- Conexión a internet: latencia, pérdida de paquetes, descarga y subida de una puerta de enlace y una interfaz (la WAN por defecto), con el gráfico del tráfico en cuanto se añade el dispositivo de la interfaz.
- Dispositivos de red: los dispositivos conectados ahora, los que se fueron, o todos.
- VPN WireGuard: los pares, conectados o no, y su último contacto.
Escenas
Disparadores:
- Estado de puerta de enlace cambiado: en línea, degradada (latencia, pérdida) o sin conexión, filtrado por puerta de enlace y estado.
- Dispositivo llegó o se fue: para un dispositivo de red añadido en Gladys.
- Nuevo dispositivo en la red: una dirección MAC nunca vista, una vez por dirección.
- Par VPN conectado o no: un par WireGuard.
- Servicio iniciado o detenido: Unbound, Dnsmasq, WireGuard…
- Actualización disponible: una búsqueda de actualizaciones encontró novedades.
Acciones: leer el estado (CPU, puertas de enlace, dispositivos presentes… para un mensaje), despertar un dispositivo (Wake-on-LAN, plugin os-wol, a través de las VLAN), añadir o quitar una dirección de un alias, reiniciar un servicio, buscar actualizaciones, reiniciar.
Ejemplos:
- Cuando la puerta de enlace
WAN_DHCPpasa a sin conexión → enviar un mensaje «Internet ha caído, el 4G toma el relevo». - Cuando aparece un nuevo dispositivo en la red → enviar su nombre, fabricante y dirección IP al administrador.
- Cada noche a las 21:00 → añadir la IP de la tableta de los niños al alias
kids_block, usado por una regla de bloqueo; quitarla a las 7:00.
Transporte
Solo local: la integración habla con la API de OPNsense por HTTPS en su red, con la clave de API. Ningún dato sale de su red (el propio OPNsense contacta con su réplica de actualizaciones durante una búsqueda).
Solución de problemas
- «OPNsense rechaza la clave de API»: vuelva a copiar la clave y el secreto desde
key.txt, sin espacios. - «El certificado HTTPS es rechazado»: desmarque «Verificar el certificado», o instale un certificado válido para la dirección introducida.
- «le falta un privilegio»: añada los privilegios indicados arriba al usuario de OPNsense de la clave.
- Ningún dispositivo de red: compruebe el privilegio «Diagnostics: ARP Table» y la opción «Dispositivos de red ofrecidos».
- Falta una regla: debe llevar la categoría y proceder del nuevo editor de reglas.
- El Wake-on-LAN falla: instale el plugin
os-wolen Sistema > Firmware > Plugins, e introduzca la interfaz (lan,opt1…) para un dispositivo nunca visto. - Registros: añada la variable de entorno
DEBUG=gladys-integration-sdky abra una issue en GitHub con las versiones de Gladys, de la integración y de OPNsense, y los registros (la clave de API y su secreto nunca aparecen en ellos).
Parámetros de configuración
Estos son los parámetros que OPNsense te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Clave de API de OPNsense | section | No | En OPNsense, cree un usuario dedicado (Sistema > Acceso > Usuarios), dele los privilegios indicados en la documentación y añada una clave de API: se descarga un archivo key.txt con la clave y su secreto. Todo se queda en su red. |
| Dirección de OPNsense | string | Sí | La dirección de su interfaz web, con el puerto si no es el 443. |
| Clave de API | string | Sí | La línea «key=» de key.txt. |
| Secreto de la API | secret | Sí | La línea «secret=» de key.txt. |
| Verificar el certificado | boolean | No | Déjelo sin marcar con el certificado autofirmado de OPNsense. Márquelo con un certificado válido (Let’s Encrypt, autoridad interna). |
| Opciones | section | No | Las reglas del cortafuegos se convierten en interruptores cuando llevan la categoría de abajo. Los dispositivos de la red se convierten en sensores de presencia al añadirlos desde la pantalla de descubrimiento. |
| Intervalo de lectura (s) | number | No | De 10 a 300 segundos, 30 por defecto. |
| Dispositivos de red ofrecidos | select | No | Qué dispositivos de la tabla ARP y de las concesiones DHCP aparecen en la pantalla de descubrimiento. |
| Retardo de ausencia (min) | number | No | Un dispositivo está ausente tras este tiempo sin respuesta. De 1 a 60, 5 por defecto: un teléfono en reposo sale de la red un rato. |
| Categoría de las reglas | string | No | Las reglas de esta categoría (Cortafuegos > Reglas) se convierten en interruptores. Vacío: ninguna. |
| Idioma de los textos | select | No | Nombres, estados y resúmenes de escenas. Automático: el idioma de su panel, en cuanto se haya mostrado un widget de OPNsense. |
Cómo instalar OPNsense en Gladys
- En Gladys, abre Integraciones: OPNsense 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/william-de71/gladys-opnsense:0.1.0), 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/William-De71/gladys-opnsense.
OPNsense 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
OPNsense 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 William-De71, 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