Skip to content

UniFi — red + monitorización

Equipo UniFi añadido al homelab el 2026-07-31: un CloudKey Gen2 Plus como controlador, un switch Pro HD 24 PoE y un AP U7 Long-Range (WiFi 7). Integrado en Home Assistant y monitorizado en Grafana vía unpoller → Prometheus.

Sin gateway UniFi

No hay UDM/USG/UXG: UniFi no toca routing, DHCP ni DNS. Manda el router actual y Pi-hole sigue de DNS. El riesgo de lockout de red por cable es nulo.

Inventario

Pieza Modelo IP Firmware Notas
Controlador Cloud Key Gen2 Plus (UCKP) 192.168.0.169 UniFi OS 5.1.4 / Network 10.5.67 MongoDB 3.6; soporta API keys
Switch UniFi Switch Pro HD 24 PoE (USW-Pro-HD-24-PoE) 192.168.0.209 7.4.1 24×PoE + 4×SFP+ (p25-28). Infra crítica: el AP tira PoE de aquí
AP UniFi U7 Long-Range (U7-LR, WiFi 7) 192.168.0.228 8.0.74 SSID real monxas-6

Accesos

Tres vías, todas con el secreto en SOPS (secrets/unifi.sops.yaml, recipients ramon + media-208). Ver Rotating secrets.

  1. SSH root (root @ .169) — break-glass, no vía de trabajo. Útil para firmware, estado de servicios y lectura directa de Mongo: 
    ssh [email protected]   # mongo --quiet --port 27117 ace  (db.device / db.user / db.wlanconf)
# catálogo modelo→nombre: /usr/lib/unifi/dl/uidb/uidb.json
  2. Integration API key (Network Integration API, X-API-KEY) — para consultas: 
    curl -sk -H "X-API-KEY: $KEY" https://192.168.0.169/proxy/network/integration/v1/sites
  3. Admin local claude (user+pass, admin completo) — lo usan Home Assistant y unpoller. Login local: POST https://192.168.0.169/api/auth/login → cookie TOKEN.

Cuenta local obligatoria para HA/unpoller

La cuenta cloud (monxas/email) da "Failed to connect" en Home Assistant. Hay que crear un admin local (toggle "Restrict to Local Access Only"). En esta build de UniFi OS la web no deja (/admins da 404, el menú del avatar es solo cloud) → se crea desde la app móvil de UniFi.

Home Assistant

Integración UniFi Network nativa: Host 192.168.0.169, Port 443, Verify SSL OFF, cuenta local claude. Resultado: Silver, ~129 entidades (switch 113 — control por puerto/PoE, AP 9, CloudKey 2, WLAN 4).

HA autodescubre "CloudKey+" = UniFi Protect. Se ignora: Protect no está instalado y no hay cámaras.

Router — ASUS TUF-AX6000

El gateway/DHCP de la casa es un ASUS TUF-AX6000 (192.168.0.1, ASUSWRT stock build 388) con AiMesh de 3 nodos (TUF + RT-AX58U + ZenWiFi AC Mini). No es UniFi; el equipo UniFi cuelga detrás sin gateway propio.

  • Home Assistant: integración AsusRouter ya montada — presencia (63 device- trackers), controles (reboot, wifi 2.4/5G on/off, LED, block-internet, restart firewall/wifi, rebuild AiMesh), binarios internet/nodos. Sensores cpu, ram, boot_time activados 2026-07-31 (venían off por defecto; se habilitan vía WS API config/entity_registry/update, sin reiniciar HA). No hay sensor de temperatura para este modelo.
  • SSH: admin/alfagann (+ clave dedicada asus_exporter para el exporter).
  • Reservas DHCP en nvram dhcp_staticlist (formato <MAC>IP>>). Switch .209 / AP .228 / CloudKey .169 fijados.

Monitorización (unpoller + asus-exporter → Prometheus → Grafana)

unpoller v3 corre en media-208 como contenedor Docker, saca las métricas de UniFi y las expone en Prometheus, que ya vive ahí en host-network.

  • Stack: /home/monxas/stacks/unpoller/ (docker-compose.yml + .env chmod 600). Imagen ghcr.io/unpoller/unpoller:latest. Credenciales del admin local claude.
  • Métricas: http://localhost:9130/metrics (namespace unpoller_, ~353 series).
  • Prometheus: job unifi → localhost:9130 en appdata/prometheus/prometheus.yml (backup .bak.20260731-unifi). up{job="unifi"}=1.
  • Grafana: carpeta UniFi con 5 dashboards oficiales de unpoller (Prometheus):
ID Dashboard Para
11312 USW Insights Switch (puertos, PoE, tráfico)
11314 UAP Insights AP (clientes, señal, canales)
11311 Network Sites Vista de sitio
11315 Client Insights Clientes
11310 Client DPI Tráfico por app (DPI)

Namespace de métricas

unpoller v3 emite unpoller_* (no el viejo unifipoller_*). Los dashboards 11310-11315 en su revisión actual ya usan unpoller_* → coinciden. Si algún día salen vacíos, revisar este prefijo primero.

Router en Prometheus — asus-exporter

El ASUS stock no tiene SNMP y HA no exporta bien sus valores numéricos, así que hay un mini-exporter propio (asus_* en :9134) que lee /proc del router por SSH. Corre en media-208 (systemd asus-exporter.service). Métricas: throughput WAN (eth1), load, RAM, uptime. Código en ansible/roles/observability_collector/files/asus-exporter/.

Dashboard unificado "Red"

Carpeta Red en Grafana → dashboard red-homelab ("Red — Router + UniFi"), que junta las 3 fuentes: router ASUS (WAN/CPU/RAM/uptime), switch (throughput + PoE), AP (tráfico + clientes) y estado internet/AiMesh (hass_*). JSON versionado en grafana/dashboards/red-network.json.

Alertas → Telegram

Grupo red_network en alerts.yml (9 reglas, enrutan por severity a Telegram vía Alertmanager): internet_down, router_asus_down, aimesh_node_down, unifi_switch_down, unifi_ap_down, unifi_poller_down, asus_exporter_down, router_high_load, router_low_memory. Copia de referencia en prometheus/red-network-alerts.yml.

prometheus.yml / alerts.yml se editan a mano

El repo no plantillea el prometheus.yml/alerts.yml completos (solo fragmentos de referencia). Los cambios se hacen directos en media-208:/home/monxas/appdata/prometheus/ (backups .bak.20260731-*) y se aplican con docker kill -s HUP prometheus.

Gotchas

  • Red "Default" UniFi definida como 192.168.1.0/24 con DHCP activado, pero inerte (no hay gateway). Solo habría que corregirla si algún día se mete un gateway UniFi.
  • SSID element-… auto-generado (onboarding/BLE), aparte del real monxas-6.
  • Switch = punto único: reconfigurar perfiles de puerto puede tumbar el AP (PoE) y lo que cuelgue. Cuidado con los cambios de VLAN/puerto.

Pendiente

  • ✅ Reservas DHCP de .209/.228/.169 hechas en el ASUS (2026-07-31).
  • ✅ SSID element-… revisado → onboarding oculto, se deja.
  • (Opcional) Plegar unpoller a un rol de Ansible leyendo de secrets/unifi.sops.yaml en vez del .env local, para alinearlo con el pipeline SOPS.