Monitoring-Systeme einrichten

Von CheckMk bis Gatus — die Anbindung in wenigen Minuten.

Dieses Kapitel beschreibt die Einrichtung gängiger Monitoring-Systeme. Dieselben Anleitungen finden Sie auch direkt in der Moduloberfläche auf dem Tab Anleitungen — dort inklusive Download-Schaltflächen für MIB-Datei und Templates.

Voraussetzung für alle Varianten: Die IP-Adresse (oder das Netz) des Monitoring-Servers ist als aktiver Eintrag unter Monitoring-Hosts hinterlegt, und der jeweilige Endpunkt ist eingeschaltet.

CheckMk

Das Modul antwortet auf TCP-Verbindungen am konfigurierten Port (Default 6556) mit dem klassischen CheckMk-Local-Agent-Format inklusive der STARFACE-spezifischen Sektionen <<<starface>>>, <<<starface_accounts>>>, <<<starface_sip_provider>>>, <<<starface_modules>>> etc.

Setup in CheckMk

1. In CheckMk unter Setup → Hosts → Add host den FQDN bzw. die IP der STARFACE eintragen.
2. Save & go to service configuration ausführen. Die Linux-Standardsektionen (CPU, RAM, Festplatten, Prozesse, RAID, …) erkennt CheckMk automatisch über den Discovery-Mechanismus.
3. Fix all — die Services werden ins Monitoring übernommen.
4. Activate changes, fertig.

STARFACE-Sektionen auswerten

Die STARFACE-spezifischen Sektionen (<<<starface>>>, <<<starface_accounts>>>, …) wertet CheckMk nicht automatisch aus — hierfür ist serverseitig ein Check-Plugin erforderlich:

• Das Ausgabeformat ist 1:1 kompatibel zur historischen STARFACE-MonitoringComponent. Ein bereits vorhandenes mkp-Paket für STARFACE funktioniert daher ohne Anpassung weiter.
• Alternativ lassen sich eigene Check-Plugins schreiben — eine Anleitung finden Sie unter Agentenbasierte Check-Plugins schreiben (checkmk.com).

Test von der Konsole

# Plain-CheckMk-Pull (klassisch, kein HTTP)
nc <pbx> 6556

# Oder explizit über HTTP (auch für JSON/XML verfügbar)
curl http://<pbx>:6556/checkmk

SNMP (LibreNMS, …)

Der eingebettete Micro-SNMP-Agent ist ausschließlich read-only (GetRequest, GetNextRequest, GetBulkRequest) und antwortet per SNMPv1/v2c auf dem konfigurierten UDP-Port (Default 1161). Der klassische SNMP-Port 161 ist nicht wählbar, da das Modul ohne Root-Rechte keine Ports unterhalb von 1024 binden kann — konfigurieren Sie Ihren SNMP-Manager entsprechend.

MIB importieren

Laden Sie die MIB-Datei FP-STARFACE-MIB.txt über die SNMP-Kachel (Tab Einstellungen) herunter und importieren Sie sie in Ihren SNMP-Manager (LibreNMS, Zabbix, PRTG, …).

OID-Wurzel: 1.3.6.1.4.1.99999.1

Test von der Konsole

# Walk vom Modul-Root
snmpwalk -v2c -c <community> <pbx>:1161 1.3.6.1.4.1.99999.1

# Einzelne Skalare
snmpget -v2c -c <community> <pbx>:1161 1.3.6.1.4.1.99999.1.1.2.0   # STARFACE-Version
snmpget -v2c -c <community> <pbx>:1161 1.3.6.1.4.1.99999.1.7.4.0   # MemTotal in Bytes
snmpget -v2c -c <community> <pbx>:1161 1.3.6.1.4.1.99999.1.2.2.0   # accountsTotal

# GetBulk (v2c)
snmpbulkget -v2c -c <community> -Cn0 -Cr10 <pbx>:1161 1.3.6.1.4.1.99999.1.2

Traps

Der Agent sendet SNMPv2c-Traps an die konfigurierten Trap-Empfänger:

• SipProviderDown — SIP-Provider nicht erreichbar
• AllPhonesOffline — alle Telefone offline
• RaidDegraded — RAID degradiert
• DiskAlmostFull — Festplatte fast voll
• BackupStale — letztes Backup veraltet
• LicenseExpiring — Lizenz läuft demnächst ab

Monitoring Pro

Der SNMP-Agent erfordert eine Monitoring Pro-Lizenz.

PRTG

Das Modul ist kompatibel zur XML-Monitoring-Schnittstelle — bestehende PRTG-Sensoren funktionieren ohne Anpassung weiter.

EXEXML-Sensor

Programm/Skript:  prtg-monitoring.exe
Parameter:        %host Monitoring GetMonitoringData 10 starface cpuLoad

Argument-Reihenfolge:

Pos	Bedeutung
1	%host (PRTG-Variable mit Host-FQDN/-IP)
2	Name der Modulinstanz (hier Monitoring)
3	XML-RPC-Function (GetMonitoringData oder GetMonitoringDataAuth)
4	STARFACE-Login-ID
5	Credential — Headless-API-Token bzw. Access-Token (siehe unten)
6	Sensor-Name
7	(optional) Extra-Parameter, z.B. SIP-Provider-URI

Sensor-Namen

cpuLoad, memInfo, diskSpace, starfaceAccounts, allPeersOffline, hardwareID, sipProvider (mit Extra), moduleInstances, starfaceVersion, starfaceBackup, starfaceUpdate, faxQueue, pbxLogErrorString, supportLogErrorString.

Authentifizierung

Es gibt zwei Endpunkte mit identischem Aufruf-Format, die sich nur im Credential unterscheiden (jeweils Position 5, das Passwort-Argument):

• GetMonitoringData (empfohlen für Drittsysteme): Erfordert einen Headless-API-Token — im STARFACE-Admin-Interface erzeugen, dann in der XML-Monitoring-Kachel hinterlegen. Position 4 (Login-ID) wird ignoriert. Ohne konfigurierten Token wird jeder Aufruf abgelehnt.
• GetMonitoringDataAuth: Erwartet einen STARFACE-Access-Token (OAuth/JWT) eines Kontos mit Admin-Berechtigung.

Zabbix

Zwei Wege: SNMP (empfohlen, native Zabbix-Unterstützung) oder XML-Monitoring (für Bestandsumgebungen, kompatibel zum XML-Monitoring Modul).

Variante 1: SNMP

1. MIB-Datei (SNMP-Kachel im Tab Einstellungen) auf den Zabbix-Server kopieren.
2. Configuration → Hosts → Create host: Host hinzufügen, Interface-Typ SNMP (Port wie im Modul konfiguriert, Default 1161), Community-String passend zur SNMP-Kachel.
3. Template anlegen oder fertige SNMP-Items mit den OIDs aus 1.3.6.1.4.1.99999.1.* konfigurieren.

Variante 2: XML-Monitoring

Erfordert das mitgelieferte STARFACE-Zabbix-Template (Download auf dem Tab Anleitungen).

1. Data collection → Templates → Import mit der YAML-Datei.
2. Hosts → Create host und das Template zuweisen.
3. Macros: {$XML_RPC_AUTH_STRING} setzen — Wert ist Base64 von loginId:headlessToken.

Test von der Konsole

zabbix_get -s <pbx> -k 'starface.cpuLoad'

Gatus

Gatus konsumiert den JSON-Endpoint des Moduls über HTTP — der TCP-Endpunkt verzweigt anhand des URL-Pfads, /json liefert einen hierarchischen JSON-Snapshot des aktuellen Anlagen-Zustands.

Beispiel config.yaml

endpoints:
  - name: STARFACE Modul-Snapshot
    url: http://<pbx>:6556/json
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].sipStatusLocalhost == OK"
      - "[BODY].onlinePhones > 0"
      - "[BODY].osDiskRootFreeBytes > 10000000000"
      - "[BODY].accountsActive >= 0"
    alerts:
      - type: discord
        failure-threshold: 2
        send-on-resolved: true

Authentifizierung & Firewall

Der TCP-Endpunkt ist nicht passwortgeschützt — der Schutz liegt ausschließlich auf der STARFACE-Firewall, die nur konfigurierte Monitoring-Hosts durchlässt. Läuft Gatus auf einem geteilten Server, muss dessen IP / CIDR dort eingetragen sein.