Konfiguration

Drei Monitoring-Standards, eine Oberfläche.

Die Moduloberfläche von Monitoring gliedert sich in vier Tabs:

Tab	Inhalt
Info	Modulinformationen, Lizenzierung und Logging-Einstellungen.
Dashboard	Live-Visualisierung der Sensordaten, eigene Dashboards und Wallboard-Links (Edition Monitoring Pro).
Einstellungen	Die gesamte Konfiguration: Monitoring-Hosts, die drei Protokoll-Kacheln, Live-Vorschau sowie Schwellenwerte und Cache.
Anleitungen	Schritt-für-Schritt-Hinweise zur Einrichtung gängiger Monitoring-Systeme (siehe auch Monitoring-Systeme).

---

Der Einstellungen-Tab

Der Tab Einstellungen bündelt die komplette Konfiguration. Oben steht die Kachel Monitoring-Hosts, darunter die vier Protokoll-/Werkzeug-Kacheln (TCP-Endpunkt, SNMP, XML-Monitoring, Live-Vorschau) und am Ende die Kachel Schwellenwerte und Cache.

Das Kachel-Prinzip

Jede Protokoll-Kachel folgt demselben Aufbau:

• Schalter (links): aktiviert oder deaktiviert den jeweiligen Endpunkt.
• Titel (mittig).
• Status-Badge (rechts): zeigt den Live-Zustand des Endpunkts.

Badge	Bedeutung
Aktiv	Der Endpunkt läuft und antwortet auf Anfragen.
Warnung	Der Endpunkt läuft, aber mit Warnung — z.B. wenn der konfigurierte Port belegt war und automatisch auf den Folge-Port ausgewichen wurde.
Gestoppt	Der Endpunkt ist eingeschaltet, aber nicht aktiv. Häufige Gründe: keine Modul-Lizenz, Port-Konflikt, Firewall-Fehler.
Inaktiv	Über den Schalter der Kachel deaktiviert.
Fehler	Der Dienst konnte nicht gestartet werden — der konfigurierte Port ist belegt. Der Schalter wird automatisch wieder ausgeschaltet.

Schreibschutz bei laufendem Dienst

Solange ein Endpunkt aktiv ist, sind seine Felder (z.B. der Port) schreibgeschützt. Deaktivieren Sie den Dienst zunächst über den Schalter der Kachel, um Änderungen vorzunehmen.

Für Ports gilt durchgängig: Erlaubt sind Werte von 1024 bis 65535. Ports unterhalb von 1024 kann das Modul nicht binden, da es ohne Root-Rechte läuft. Ist der konfigurierte Port beim Start belegt, versucht das Modul automatisch den Folge-Port (z.B. 6556 → 6557) und zeigt eine entsprechende Warnung an.

Monitoring-Hosts

Die Kachel Monitoring-Hosts ist die zentrale Zugriffssteuerung: Hier hinterlegen Sie die IPv4-Adressen oder CIDR-Blöcke, denen der Zugriff auf die Monitoring-Endpunkte gewährt wird. Das Modul öffnet die STARFACE-Firewall ausschließlich für diese Hosts.

Pro Eintrag stehen folgende Felder zur Verfügung:

• Name — frei wählbare Bezeichnung (z.B. „CheckMk-Server RZ1").
• IP / CIDR — eine einzelne IPv4-Adresse (10.20.30.40) oder ein Netz in CIDR-Notation (192.168.0.0/24). Die Eingabe wird live validiert; bei CIDR-Blöcken zeigt die Oberfläche an, wie viele IPv4-Adressen der Block umfasst.
• Kommentar — optionale Notiz.
• Aktiv — Einträge lassen sich deaktivieren, ohne sie zu löschen.

Ohne Eintrag bleibt alles geschlossen

Sind keine (aktiven) Monitoring-Hosts konfiguriert, bleiben TCP-Endpunkt und SNMP-Agent von außen unerreichbar — unabhängig davon, ob die Endpunkte eingeschaltet sind.

TCP-Endpunkt

Der Multi-Format-TCP-Server liefert CheckMk-, XML- oder JSON-Ausgaben auf einem einzigen Port (Default 6556/TCP).

• TCP-Port — der Port, auf dem der Endpunkt lauscht.
• Default-Format ohne HTTP-Request — verbindet sich ein Client ohne HTTP-Request (klassischer CheckMk-Pull), liefert der Endpunkt das hier gewählte Format. Per HTTP lässt sich das Format explizit wählen:

# Klassisch (TCP, ohne HTTP — liefert das Default-Format)
nc <pbx> 6556

# Explizit per HTTP-Pfad
curl http://<pbx>:6556/checkmk
curl http://<pbx>:6556/xml
curl http://<pbx>:6556/json

# Alternativ per Query-Parameter
curl "http://<pbx>:6556/?format=json"

Die CheckMk-Ausgabe enthält neben den Linux-Standardsektionen des check_mk_agent die STARFACE-spezifischen Sektionen (<<<starface>>>, <<<starface_accounts>>>, <<<starface_sip_provider>>>, <<<starface_modules>>>, …). Die Standardsektionen (CPU, RAM, Festplatten, Prozesse, …) erkennt CheckMk im Rahmen der Service-Discovery automatisch; für die Auswertung der STARFACE-Sektionen ist serverseitig ein Check-Plugin erforderlich (siehe Monitoring-Systeme → CheckMk).

SNMP

Der eingebettete, read-only SNMPv1/v2c-Agent beantwortet snmpget-, snmpwalk- und snmpbulkget-Anfragen und versendet SNMPv2c-Traps.

• UDP-Port — Default 1161 (der privilegierte Standard-Port 161 ist nicht wählbar, siehe Einschränkungen).
• SNMP Community-String — wirkt wie ein Passwort. Ersetzen Sie den SNMP-Default public durch einen individuellen, schwer zu erratenden String. Ein leerer Wert blockiert sämtliche SNMP-Anfragen.
• MIB-Download — die Datei FP-STARFACE-MIB.txt beschreibt alle exportierten OIDs und wird direkt aus der Kachel heruntergeladen. Importieren Sie sie in Ihren SNMP-Manager (LibreNMS, Zabbix, PRTG, …), bevor Sie Sensoren konfigurieren.

Der Agent sendet SNMPv2c-Traps für folgende Ereignisse: SIP-Provider nicht erreichbar (SipProviderDown), alle Telefone offline (AllPhonesOffline), RAID degradiert (RaidDegraded), Festplatte fast voll (DiskAlmostFull), Backup veraltet (BackupStale) und auslaufende Lizenz (LicenseExpiring).

Monitoring Pro

SNMP-Endpunkt und SNMP-Live-Vorschau erfordern eine Monitoring Pro-Lizenz.

XML-Monitoring

Der XML-RPC-Handler GetMonitoringData ist kompatibel zur XML-Monitoring-2.1-Schnittstelle: Bestehende PRTG-, Zabbix-, Riverbird- und servereye-Templates funktionieren ohne Anpassung weiter. Die Kachel zeigt fertige Aufruf-Beispiele (XML-RPC-Endpunkt, Methodenaufruf, Aufruf mit Extra-Parameter) für die eigene Anlage an.

Für die Authentifizierung stehen zwei Endpunkte mit identischem Aufruf-Format zur Verfügung:

XML-RPC-Function	Credential (Passwort-Argument)
GetMonitoringData	Headless-API-Token (Pflicht) — im STARFACE-Admin-Interface erzeugen und in der Kachel im Feld Headless API Token hinterlegen. Ohne konfigurierten Token wird jeder Aufruf abgelehnt.
GetMonitoringDataAuth	STARFACE-Access-Token (OAuth/JWT) eines Kontos mit Admin-Berechtigung — für Systeme, die die Standard-STARFACE-Anmeldung verwenden.

Verfügbare Sensoren: cpuLoad, memInfo, diskSpace, starfaceAccounts, allPeersOffline, hardwareID, sipProvider (mit Extra-Parameter), moduleInstances, starfaceVersion, starfaceBackup, starfaceUpdate, faxQueue, pbxLogErrorString, supportLogErrorString.

Live-Vorschau

Mit der Live-Vorschau sehen Sie exakt, was ein externes Monitoring-System erhalten würde — direkt aus der Oberfläche, ohne externes Werkzeug:

1. Quelle wählen: TCP-Endpunkt, XML-Monitoring-Sensor oder SNMP-Walk.
2. Je nach Quelle Format bzw. Sensor wählen; für den Sensor sipProvider zusätzlich den Extra-Parameter (z.B. die SIP-Provider-URI) angeben.
3. Ausführen — die Vorschau zeigt URL, Content-Type und die vollständige Antwort.

Deaktivierte Endpunkte werden in der Quellen-Auswahl entsprechend gekennzeichnet; aktivieren Sie den jeweiligen Endpunkt zuerst über den Schalter seiner Kachel.

Schwellenwerte und Cache

• Fax-Warteschlange — Warn- und Kritisch-Schwelle für die Anzahl wartender Faxe (Sensor faxQueue).
• PBX-Log / Support-Log — Such-String und Max-Alter (Minuten) für die Log-Sensoren pbxLogErrorString und supportLogErrorString.
• Cache-Lebensdauer (Sekunden) — TTL für den geteilten Anlagen-Snapshot, aus dem alle drei Schnittstellen bedient werden. Der Cache verhindert Lastspitzen, wenn mehrere Monitoring-Systeme parallel abfragen. Empfohlen: 30–60 Sekunden.

---

Der Dashboard-Tab

Sensordaten live — im Modul und auf dem Wallboard.

Der Tab Dashboard visualisiert die Monitoring-Werte in Echtzeit — die Anzeige pollt in einem konfigurierbaren Aktualisierungsintervall und zeigt jeweils den aktuellen Stand.

Für Verlaufs-Darstellungen führt das Modul zusätzlich eine 24-Stunden-Zeitreihe über ein ausgewähltes Metrik-Subset (CPU-Last 1/5/15, RAM-, Festplatten- und JVM-Heap-Auslastung). Sie wird unabhängig von geöffneten Dashboards kontinuierlich im 30-Sekunden-Raster erfasst und im Arbeitsspeicher gehalten (Ringpuffer) — beim Modul-Update oder Neustart beginnt die Aufzeichnung von vorn. Monitoring ersetzt damit bewusst keinen Langzeit-Datenspeicher; für eine dauerhafte Historie binden Sie ein externes Monitoring-System über eine der drei Schnittstellen an.

• Vorgefertigtes Dashboard — sofort einsatzbereit, read-only.
• Eigene Dashboards — über Neues Dashboard anlegen und per Visual hinzufügen frei zusammenstellen. Verfügbare Visual-Typen: Tacho, Wert, Verlauf, Text, Status-Badge und Modul-Instanz-Check. Jedes Visual wird mit einer Metrik verknüpft.
• Wallboards — über die Schaltfläche Wallboard erzeugen Sie login-freie Links für TV-/Kiosk-Displays. Jeder Link ist durch einen eigenen Token abgesichert und einzeln widerrufbar.

Wallboard-Links sind login-frei

Wer einen Wallboard-Link besitzt, sieht die Monitoring-Werte ohne Anmeldung. Behandeln Sie die Links entsprechend vertraulich und widerrufen Sie nicht mehr benötigte Tokens.

Monitoring Pro

Live-Dashboards und Wallboards sind Teil der Edition Monitoring Pro.

---

Häufige Stolpersteine

• Endpunkt ist „Aktiv", aber von außen nicht erreichbar
  Prüfen Sie, ob die IP-Adresse (oder das Netz) des Monitoring-Servers als aktiver Eintrag unter Monitoring-Hosts steht. Die STARFACE-Firewall lässt nur diese Hosts durch.

• Badge zeigt „Warnung" nach dem Start
  Der konfigurierte Port war belegt; das Modul ist automatisch auf den Folge-Port ausgewichen (z.B. 6556 → 6557, etwa wenn die STARFACE-eigene Monitoring-Komponente auf Cloud-Anlagen Port 6556 belegt). Konfigurieren Sie Ihr Monitoring-System auf den tatsächlich verwendeten Port — oder tragen Sie in der Kachel einen anderen freien Port ein.

• GetMonitoringData liefert authentication failed
  Es ist kein Headless API Token in der XML-Monitoring-Kachel hinterlegt, oder der übergebene Token stimmt nicht überein. Der frühere Modus „beliebiger STARFACE-Login" wird aus Sicherheitsgründen nicht unterstützt — verwenden Sie alternativ GetMonitoringDataAuth mit einem Admin-Access-Token.

• SNMP-Manager erhält keine Antwort
  Prüfen Sie (1) die Monitoring Pro-Lizenz, (2) den Port — Default ist 1161, nicht 161, (3) den Community-String und (4) den Monitoring-Hosts-Eintrag des SNMP-Managers.

• Endpunkte starten nicht, alle Badges zeigen „Gestoppt"
  Ohne gültige Modullizenz bleiben sämtliche externen Endpunkte deaktiviert. Die Live-Vorschau im UI funktioniert dennoch, sodass Sie die Konfiguration bereits testen können.