UniFi mit Zabbix überwachen: SNMPv3, automatische Discovery, WLAN-Clients und Kanalauslastung

Der UniFi-Controller zeigt viel, aber er zeigt es nur, solange man hinschaut. Er sagt nicht, dass ein Access Point gestern Nacht für zwanzig Minuten weg war, und er alarmiert nicht, wenn das 2,4-GHz-Band im Wohnzimmer dauerhaft zu 60 Prozent belegt ist. Zabbix kann beides, und zwar für alle UniFi-Geräte an allen Standorten, ohne dass man ein einziges Gerät von Hand anlegt.

In diesem Teil geht es um SNMP. Am Ende hat Zabbix 17 UniFi-Geräte an zwei Standorten selbst gefunden, jedem das passende Template zugewiesen und zeigt pro Access Point die WLAN-Clients je Netz und die Kanalauslastung je Radio.

Warum SNMP und nicht die Controller-API?

Es gibt zwei Wege an UniFi-Daten: die API des Controllers oder SNMP direkt auf den Geräten. Die API liefert mehr, etwa die Namen der verbundenen Clients, aber sie hängt am Controller. Ist der Controller weg, sind alle Daten weg. SNMP spricht jedes Gerät einzeln an. Fällt ein Switch aus, melden die anderen trotzdem. Für Monitoring ist das der robustere Weg, und mit der Ubiquiti-MIB bekommt man die WLAN-Daten, die wirklich zählen.

SNMPv3 im Controller aktivieren

In UniFi Network 10.6 liegt die Einstellung unter Einstellungen → CyberSecure → Traffic Logging → SNMP Monitoring (in älteren Versionen unter System → Advanced). Dort „Version 3“ aktivieren und Benutzername und Passwort setzen.

UniFi nutzt das eine Passwort für Authentifizierung (SHA) und Verschlüsselung (AES). Die Einstellung gilt für alle Geräte der Site, es dauert eine Minute, bis sie provisioniert sind.

Die Zugangsdaten braucht man gleich dreimal: in der Discovery-Regel, in den Host-Interfaces und als globale Makros. Ich habe sie als globale Makros {$SNMP_USER}, {$SNMP_AUTH} und {$SNMP_PRIV} angelegt, die beiden Passwörter als Secret.

Test von einem Rechner im selben Netz:

snmpget -v3 -l authPriv -u zabbix -a SHA -A 'passwort' -x AES -X 'passwort' 10.0.0.1 1.3.6.1.2.1.1.5.0

Kommt der Gerätename zurück, ist SNMP aktiv. Bei mir antwortete der Controller-Gateway sofort, die Access Points nach einer Minute.

Die Discovery-Regel

Zabbix soll das Netz selbst absuchen. Data collection → Discovery → Create discovery rule:

• IP range: 10.0.0.1-254
• Update interval: 30m
• Checks: zwei SNMPv3-Checks mit den Zugangsdaten. Der erste fragt 1.3.6.1.2.1.1.5.0 (sysName) und ist das Kriterium für Eindeutigkeit und Hostname. Der zweite fragt 1.3.6.1.2.1.1.1.0 (sysDescr), damit die Action den Gerätetyp erkennen kann.
• Device uniqueness criteria: der sysName-Check
• Host name und Visible name: ebenfalls aus dem sysName-Check

Die Discovery-Regel allein legt noch nichts an. Sie sammelt nur. Was damit passiert, bestimmt die Action.

Die Discovery-Actions

Alerts → Actions → Discovery actions. Ich habe drei:

„UniFi-Geräte anlegen“: Bedingung ist nur die Discovery-Regel. Operationen: Host anlegen, zur Gruppe „UniFi/Standort A“ hinzufügen, Template „Network Generic Device by SNMP“ verlinken, Inventar auf automatisch. Da der SNMPv3-Benutzer nur auf UniFi-Geräten existiert, antwortet im ganzen Netz nichts anderes. Eine Typ-Bedingung ist deshalb unnötig.

Mein erster Versuch hatte die Bedingung „sysDescr enthält Ubiquiti“. Das traf nur das Gateway. Access Points melden als sysDescr nur „U7-Pro 8.7.11″, Switches „Linux USW16PoE 3.18.24″. Nach einer halben Stunde ohne einen einzigen Host habe ich die Bedingung entfernt.

„UniFi AP-Template“: Bedingung Discovery-Regel und sysDescr enthält U7, U6, UK- oder UAP (verknüpft mit „oder“, dafür braucht die Action einen eigenen Ausdruck wie A and (B or C or D or E)). Operation: mein AP-Template verlinken.

„UniFi Switch/Gateway-Template“: dasselbe mit USW, UCG, UDM, UXG.

Eine Stunde nach dem Anlegen standen neun Geräte in der Host-Liste, mit Namen aus dem Controller, SNMP-Interface, beiden Templates und Tag. Beim zweiten Standort das Gleiche in zehn Minuten, weil die Actions schon da waren.

Eine Sache, die ich nicht erklären kann: Die beiden Gateways (UCG-Ultra und UDM-Pro) wurden von der Discovery nie gefunden, obwohl sie per snmpget sofort antworten. Ich habe sie von Hand angelegt und es dabei belassen.

Was das Standard-Template liefert, und was nicht

„Network Generic Device by SNMP“ liefert Ping, Uptime, Systemname und alle Netzwerk-Interfaces mit Traffic, Fehlern und Status. Das ist für einen Switch das Wesentliche. Für einen Access Point ist es fast nichts, denn CPU, RAM, Clients und Kanalauslastung fehlen.

Dazu kommt Rauschen: WLAN-Interfaces haben naturgemäß Fehler, und das Template meldet „High error rate“ auf jedem wifi0. Zwei Makros auf dem AP-Template lösen das: {$NET.IF.IFNAME.NOT_MATCHES} um ^(wifi|ra|ath|vwire) erweitern, damit die Funk-Interfaces aus der Interface-Discovery fallen, und {$IF.ERRORS.WARN} auf 1000. Die Funkdaten kommen besser aus der UniFi-MIB.

Vorsicht bei Makros: Wenn zwei verlinkte Templates dasselbe Makro definieren, ist nicht klar, welches gewinnt. Bei mir hat das Generic-Template die 2 Fehler pro Sekunde durchgesetzt. Makros, die ein Template-Makro überschreiben sollen, auf Host-Ebene setzen.

Eigene Templates: Die UniFi-MIB

Ubiquiti liefert die MIB UBNT-UniFi-MIB unter 1.3.6.1.4.1.41112.1.6. Dazu kommt die UCD-SNMP-MIB unter 1.3.6.1.4.1.2021, die Load und Speicher liefert, und HOST-RESOURCES für die CPU-Kerne. Alles ließ sich per snmpwalk verifizieren. Die OIDs, die ich nutze:

Access Point, Systemwerte

WLAN-Netze (Low-Level Discovery über die VAP-Tabelle 41112.1.6.1.2.1)

Radios (LLD über 41112.1.6.1.1.1)

Aus den Client-Zahlen aller Netze entsteht ein berechnetes Item „WLAN-Clients gesamt“ mit sum(last_foreach(//unifi.vap.stations[*])). Das ist der Wert, der im Dashboard als Wabe pro AP steht.

Zwei Trigger-Prototypen: Kanalauslastung über 80 Prozent für 15 Minuten (Warnung) und fremde Netze über 50 Prozent (Information). Beim ersten lag eine Falle: Ein inaktives 6-GHz-Radio meldet 99 Prozent Auslastung, aber 0 bei allen Teilwerten. Der Trigger prüft deshalb zusätzlich, ob eigener plus fremder Anteil größer als null ist.

Switches und Gateways bekommen ein zweites Template, nur mit Load, Speicher und CPU aus der UCD-MIB (2021.11.11.0 ist CPU idle, der Rest ist 100 minus idle). Die Interface-Daten kommen vom Generic-Template.

Meine beiden Templates gibt es hier als YAML-Export zum Download: Zabbix-Templates für UniFi (ZIP, Zabbix 7.4). Importieren unter Data collection → Templates → Import.

Was man dann sieht

Pro Standort eine Dashboard-Seite. Oben Ping, Paketverlust und CPU des Gateways als Kacheln. Darunter alle Geräte mit CPU, RAM, Load, Ping, Uptime und Firmware. Dann die Waben mit Clients je AP, der Verlauf über den Tag und die Radios mit der stärksten Kanalauslastung.

Was ich daraus gelernt habe, nach zwei Tagen Daten: Ein Outdoor-AP am Rand des Grundstücks hat auf 2,4 GHz 36 Prozent Kanalauslastung, dreimal mehr als die anderen. Dort funkt ein Nachbar. Das Gateway läuft mit 46 Prozent CPU und 96 Prozent RAM, was für ein UCG-Ultra normal ist, aber zeigt, dass da kein Platz für weitere Dienste ist. Und ein U6-Plus hat eine Firmware von vor einem Jahr, weil er aus der automatischen Aktualisierung gefallen war.

Zwei Standorte getrennt halten

Beide Standorte haben Geräte mit ähnlichen Namen. Deshalb: eigene verschachtelte Hostgruppen „UniFi/Standort A“ und „UniFi/Standort B“, eigene Discovery-Regeln, eigene Actions, eigener Tag standort. Die Dashboard-Seiten filtern auf die Gruppe. Wer das von Anfang an so macht, spart sich das Umgruppieren, das ich nach dem zweiten Standort hatte.

Wie die Daten des zweiten Standorts überhaupt zum Server kommen, ist Thema des nächsten Teils: der Zabbix Proxy.

Fehlersuche

• Discovery findet nichts: Erst snmpget von der Maschine aus, die die Discovery ausführt (Server oder Proxy). Antwortet das Gerät dort nicht, hilft keine Zabbix-Einstellung.
• Hosts werden gefunden, aber nicht angelegt: Action-Bedingungen prüfen. Unter Reports → Audit log sieht man, ob die Action gefeuert hat.
• Items „not supported“ mit Timeout: SNMP-Timeout im Server oder Proxy erhöhen, bei Access Points über WLAN-Backhaul kann die Antwort zwei Sekunden dauern.
• Discovery sofort ausführen: Die Regel vorübergehend auf 5 Minuten stellen oder per API task.create mit dem Typ „execute now“ auf die Discovery-Rule.