Datenendpunkt (TCP 6556)

Der Datenendpunkt ist ein TCP-Dienst, der den Anlagen-Snapshot in drei Formaten ausliefert: CheckMk-Local-Agent-Format, strukturiertes XML und JSON — auf einem einzigen Port. Das Format wählt der Client über den HTTP-Pfad (/checkmk, /xml, /json); Clients ohne HTTP-Request (klassischer CheckMk-Pull) erhalten das konfigurierte Standardformat. Für die Auswertung der STARFACE-Sektionen in CheckMk liefert das Modul das Erweiterungspaket starface_fluxpunkt.mkp mit.

Grundlagen

Typ: TCP-Server mit optionalem HTTP-Modus (GET, auch POST/HEAD/OPTIONS werden als Request-Zeile akzeptiert)
Endpunkt: TCP 6556 (Standard — entspricht der CheckMk-Agenten-Konvention; im Modul konfigurierbar). Ist der Port beim Start belegt, weicht das Modul automatisch auf den Folge-Port aus und zeigt eine Warnung an.
Authentifizierung/Absicherung: keine Anmeldung — der Zugriff wird ausschließlich über die Monitoring-Hosts-Liste (IPv4/CIDR) begrenzt: Die STARFACE-Firewall wird automatisch nur für die eingetragenen Hosts geöffnet, zusätzlich prüft der Dienst jede Verbindung auf Anwendungsebene.
Format: Antwort im HTTP-Modus mit Content-Type-/Content-Length-Headern und Connection: close; ohne HTTP-Request als roher Text. Zeichensatz durchgehend UTF-8.
Voraussetzungen: aktive Modulinstanz mit gültiger Lizenz; Kachel TCP-Endpunkt eingeschaltet (Standard: ein)
Datenquelle: gemeinsamer Anlagen-Snapshot aller Monitoring-Schnittstellen (Cache-Lebensdauer standardmäßig 30 Sekunden, konfigurierbar)

Firewall-Automatik

Ohne (aktiven) Eintrag in der Monitoring-Hosts-Liste bleibt Port 6556 von außen geschlossen — auch bei eingeschalteter Kachel. Verbindungen von nicht gelisteten Adressen werden angenommen und ohne Antwort geschlossen. Der Dienst bedient ausschließlich IPv4.

Formatauswahl im Überblick:

Anfrage	Format
Verbindung ohne HTTP-Request (z. B. `nc`)	konfiguriertes Standardformat (Voreinstellung: CheckMk)
`GET /checkmk`	CheckMk-Local-Agent-Format
`GET /xml`	XML-Snapshot
`GET /json`	JSON-Snapshot
`GET /?format=checkmk\|xml\|json`	Query-Parameter überschreibt den Pfad
unbekannter Pfad oder Formatname	Standardformat (kein Fehler — Robustheit vor URL-Validierung)

Endpunkte

`GET /checkmk`

Liefert das CheckMk-Local-Agent-Format (Content-Type: text/plain; charset=utf-8), bestehend aus vier Blöcken in verbindlicher Reihenfolge:

Agent-Header: <<<check_mk>>> (gemeldete Agent-Version 2.5.0p6, AgentOS: linux, Hostname) und <<<labels:sep(0)>>> mit den Host-Labels {"cmk/os_family": "linux", "starface/role": "pbx"}.
Linux-Standardsektionen aus dem STARFACE-eigenen check_mk_agent.sh (CPU, RAM, Dateisysteme, Netzwerk, Prozesse, Uptime, …).

STARFACE-Sektionen (<<<starface*>>>):

Sektion	Inhalt
`<<<starface>>>`	Appliance-Typ und -Seriennummer, STARFACE-Version, Lizenz, RAID-Status (falls konfiguriert), Sicherheitseinstellungen, SIP-Health, Telefone (bekannt/online/IP-Wechsel), Server-Traffic (Web-Sessions, App-Verbindungen, verbundene/geparkte/Konferenz-Anrufe), RTP-Qualität (Jitter, Paketverlust, RTT, MOS — Mittelwert, Median, Maximum)
`<<<starface_backups>>>`	je Backup-Ziel: Ort, Zeitpunkt, Statusmeldung
`<<<starface_channels>>>`	maximale Channels, aktive Channels, Anrufe der letzten 5 Minuten
`<<<starface_accounts>>>`	Benutzerkonten gesamt/admin/aktiv/verfügbar/klingelnd/nicht erreichbar
`<<<starface_peers>>>`	je SIP-Peer: Name, IP-Adresse, Latenz (`lastms`)
`<<<starface_sip_provider>>>`	Registrierungsstatus je Amtsleitung
`<<<starface_modules>>>`	installierte Module mit Version, Hersteller und Instanznamen
`<<<starface_database>>>`	Datenbank- und CDR-Größe (Bytes)
`<<<starface_db_connections>>>`	PostgreSQL-Verbindungen gesamt/aktiv/idle/idle-in-transaction/max sowie Aufschlüsselung nach Anwendung (`by_app`) und Datenbank (`by_db`)
`<<<starface_java>>>`	JVM-Name/-Version, Heap-, Non-Heap- und Maximalspeicher

Local-Checks (<<<local>>>) — von CheckMk ohne Zusatzpaket automatisch als Services erkannt; Servicenamen und Metriken sind kompatibel zum XML-Monitoring-Referenzmodul: STARFACE update, STARFACE version, Licensed/Used full users, Licensed/Used light users, Licensed/Used iQueues (Standard, priority based, skill based), Licensed/Used terminal server permissions, Licensed/Used app premium permissions, Update contract valid until, STARFACE Module <Name> (je Modulinstanz), STARFACE Log Status Support/PBX, STARFACE All Phones Offline, STARFACE Hardware ID, STARFACE Fax Queue, STARFACE Backup <Ziel> und STARFACE SIP Provider <URI>.

# Klassischer CheckMk-Pull (ohne HTTP)
nc pbx.example.de 6556

# Identischer Inhalt per HTTP
curl http://pbx.example.de:6556/checkmk

Antwort (gekürzt):

<<<check_mk>>>
Version: 2.5.0p6
AgentOS: linux
Hostname: pbx
…
<<<labels:sep(0)>>>
{"cmk/os_family": "linux", "starface/role": "pbx"}
…
<<<starface>>>
appliance_type "STARFACE Pro"
appliance_serial_number SF-123456
starface_version 10.0.1.2
owner "Beispiel GmbH"
sip_status_localhost OK
known_phones 42
online_phones 41
rtp_estimated_mos 4.38
…
<<<starface_backups>>>
local 2026-08-04 01:30:00 OK
<<<starface_channels>>>
20 max calls
3 last5min calls
<<<starface_accounts>>>
total_accounts 35/50
…
<<<starface_sip_provider>>>
sip.provider.example 4922171234567 Registered
<<<starface_database>>>
database_size 1073741824
cdr_size 268435456
<<<local>>>
0 "STARFACE update" update=0 STARFACE is up to date.
0 "STARFACE version" major=10|minor=0|build=1|revision=2 The installed STARFACE version is 10.0.1.2.
…

`GET /xml`

Liefert den vollständigen Anlagen-Snapshot als strukturiertes XML (Content-Type: application/xml; charset=utf-8) mit dem Wurzelelement starface und den Abschnitten appliance, license, security, sip, channels, accounts, peers, sipProviders, modules, backups, database, java sowie raid (nur bei konfiguriertem RAID).

Nicht identisch mit GetMonitoringDataXML

Dieses Snapshot-XML ist nicht das local-Sensor-Dokument der XML-RPC-Abfrage GetMonitoringDataXML. Für bestehende PRTG-/XPath-Sensoren verwenden Sie die XML-RPC-Abfrage; dieses Format eignet sich für eigene Auswertungen des vollständigen Snapshots.

curl http://pbx.example.de:6556/xml

Antwort (gekürzt):

<?xml version="1.0" encoding="UTF-8"?>
<starface>
  <appliance>
    <type>STARFACE Pro</type>
    <serial>SF-123456</serial>
    <maxUsers>50</maxUsers>
    <maxConnections>20</maxConnections>
    <starfaceVersion>10.0.1.2</starfaceVersion>
    <debugMode>false</debugMode>
    …
  </appliance>
  <license>
    <owner>Beispiel GmbH</owner>
    <maxUsers>50</maxUsers>
  </license>
  <security>
    <passwordCheck>true</passwordCheck>
    <attackDetection>true</attackDetection>
    …
  </security>
  <sip>
    <localhostStatus>OK</localhostStatus>
    <knownPhones>42</knownPhones>
    <onlinePhones>41</onlinePhones>
    <ipChangedPhones>0</ipChangedPhones>
  </sip>
  <channels max="20" last5min="3" asteriskUptime="12 days, 4:23:11">
    <channel>PJSIP/0001-00000a3f</channel>
  </channels>
  <accounts total="35" admin="2" active="31" available="28" ringing="1" unavailable="4"/>
  <peers>
    <peer name="0001" ipaddr="10.20.30.41" lastms="12"/>
  </peers>
  <sipProviders>
    <registration>sip.provider.example 4922171234567 Registered</registration>
  </sipProviders>
  <modules>
    <module name="Monitoring" version="26" vendor="Fluxpunkt GmbH">
      <instance>Monitoring</instance>
    </module>
  </modules>
  <backups>
    <backup location="local" time="2026-08-04 01:30:00" message="OK"/>
  </backups>
  <database databaseSize="1073741824" cdrSize="268435456"/>
  <java>
    <vmName>OpenJDK 64-Bit Server VM</vmName>
    <heapUsed>734003200</heapUsed>
    <heapMax>2147483648</heapMax>
    …
  </java>
</starface>

`GET /json`

Liefert denselben Snapshot als hierarchisches JSON (Content-Type: application/json; charset=utf-8) — geeignet für Health-Check-Werkzeuge mit JSONPath-Bedingungen (z. B. Gatus) oder eigene Skripte. Die Feldnamen entsprechen dem internen Snapshot-Modell; nicht ermittelbare Zahlenwerte tragen den Sentinel -1.

Wichtige Feldgruppen:

Feldgruppe	Felder (Auswahl)
Appliance/System	`applianceType`, `applianceSerialNumber`, `starfaceVersion`, `starfaceBuildDate`, `systemManufacturer`, `hostname`, `uptimeLinuxMs`, `debugMode`
Lizenz/Update	`licenseOwner`, `licenseMaxUsers`, `updateAvailable`, `starfaceLatestVersion`, `serverLicenseValidUntil`
SIP/Telefone	`sipStatusLocalhost`, `knownPhones`, `onlinePhones`, `ipChangedPhones`, `peers[]`, `sipProviderEntries[]` (`index`, `uri`, `registered`)
Telefonie	`channelsMax`, `channelsActive[]`, `channelsLast5MinCalls`, `currentLinkedCalls`, `currentParkedCalls`, `currentConferenceCalls`
Benutzer	`accountsTotal`, `accountsAdmin`, `accountsActive`, `accountsAvailable`, `accountsRinging`, `accountsUnavailable`, `appWebSessions`, `appConnectedClients`
RTP-Qualität	`rtpActiveChannels`, `rtpAvgJitterMs`, `rtpMedianJitterMs`, `rtpAvgPacketLossPercent`, `rtpAvgRttMs`, `rtpEstimatedMos`, `rtpMedianMos`
OS/Ressourcen	`osLoad1min`, `osLoad5min`, `osLoad15min`, `osMemTotalBytes`, `osMemAvailableBytes`, `osDiskRootTotalBytes`, `osDiskRootFreeBytes`
Datenbank	`databaseSize`, `cdrSize`, `dbConnTotal`, `dbConnActive`, `dbConnIdle`, `dbConnIdleInTx`, `dbConnMax`, `dbConnByApplication[]`, `dbConnByDatabase[]`
Java	`javaVmName`, `javaVersion`, `javaHeapUsed`, `javaHeapMax`, `javaNonHeapUsed`, `javaMaxMemory`
Backups/Module	`backups[]` (`location`, `time`, `message`, `runInfo`), `lastBackupAgeMinutes`, `modules[]` (`name`, `version`, `vendor`, `instances[]`)

curl http://pbx.example.de:6556/json

Antwort (gekürzt):

{
  "applianceType" : "STARFACE Pro",
  "applianceSerialNumber" : "SF-123456",
  "starfaceVersion" : "10.0.1.2",
  "licenseOwner" : "Beispiel GmbH",
  "sipStatusLocalhost" : "OK",
  "knownPhones" : 42,
  "onlinePhones" : 41,
  "accountsTotal" : 35,
  "channelsMax" : 20,
  "channelsActive" : [ "PJSIP/0001-00000a3f" ],
  "peers" : [ { "name" : "0001", "ipaddr" : "10.20.30.41", "lastms" : "12" } ],
  "sipProviderEntries" : [ { "index" : 1, "uri" : "sip.provider.example", "registered" : true } ],
  "backups" : [ { "location" : "local", "time" : "2026-08-04 01:30:00", "message" : "OK", "runInfo" : 1 } ],
  "rtpActiveChannels" : 1,
  "rtpEstimatedMos" : 4.38,
  "dbConnTotal" : 24,
  "javaHeapUsed" : 734003200,
  …
}

Anwendungsbeispiel

Ein Gatus-Health-Check fragt http://pbx.example.de:6556/json ab und alarmiert über die Bedingung [BODY].sipStatusLocalhost == OK — ein einzeiliger Verfügbarkeitscheck der Telefonie, ohne CheckMk-Server und ohne Anmeldedaten im Monitoring.

CheckMk-Paket `starface_fluxpunkt.mkp`

Die Linux-Standardsektionen und die <<<local>>>-Checks erkennt CheckMk automatisch. Für die <<<starface*>>>-Sektionen liefert das Modul ein CheckMk Extension Package (MKP) mit Check-Plugins und Metrik-Definitionen mit. Nach Installation und Service-Discovery entstehen folgende Services:

Service	Datenquelle	Inhalt
STARFACE Info	`<<<starface>>>`	Appliance, Seriennummer, Version, Lizenzinhaber
STARFACE Phones	`<<<starface>>>`	Telefone bekannt/online/IP-Wechsel
STARFACE SIP Health	`<<<starface>>>`	lokaler SIP-Health-Check
STARFACE Security	`<<<starface>>>`	Passwortprüfung, Angriffserkennung, Black-/Whitelist
STARFACE Server Traffic	`<<<starface>>>`	Web-Sessions, App-Verbindungen, aktuelle Anrufe
STARFACE RTP Quality	`<<<starface>>>`	Jitter, Paketverlust, RTT, MOS
STARFACE Debug Mode	`<<<starface>>>`	Debug-Modus der Anlage
STARFACE RAID	`<<<starface>>>`	RAID-Status (falls konfiguriert)
STARFACE Accounts	`<<<starface_accounts>>>`	Kontenzähler mit Auslastungsmetrik
STARFACE Channels	`<<<starface_channels>>>`	Kanalauslastung, Anrufe der letzten 5 Minuten
STARFACE Backup `<Ziel>`	`<<<starface_backups>>>`	Status je Backup-Ziel
STARFACE Peer `<Name>`	`<<<starface_peers>>>`	Latenz je SIP-Peer
STARFACE Trunk `<URI>`	`<<<starface_sip_provider>>>`	Registrierungsstatus je Amtsleitung
STARFACE Modules	`<<<starface_modules>>>`	installierte Module und Instanzen
STARFACE Database	`<<<starface_database>>>`	Datenbank- und CDR-Größe
STARFACE Java	`<<<starface_java>>>`	JVM-Heap-Auslastung

Bezug: Schaltfläche „Checkmk-Plugin (MKP) herunterladen" in der Endpoint-Kachel der Moduleinstellungen — oder direkt per HTTP (vollständige URL im Tab Anleitungen des Moduls):

https://pbx.example.de/downloads/moduledata/<Modul-ID>/starface_fluxpunkt.mkp

Installation (CheckMk Raw Edition, als Site-Benutzer; Enterprise-Editionen alternativ per GUI unter Setup → Maintenance → Extension packages):

mkp add starface_fluxpunkt.mkp
mkp enable starface_fluxpunkt <version>
omd restart

Installieren Sie das MKP vor dem Anlegen des Hosts, dann findet die Service-Discovery Standard- und STARFACE-Services in einem Durchlauf. Die vollständige Einrichtungsanleitung (Host anlegen, Discovery, Host-Check per ICMP oder TCP) enthält das Kapitel Monitoring-Systeme.

Fehlerbehandlung

Situation	Verhalten
Absender-IP nicht in der Monitoring-Hosts-Liste	Verbindung wird angenommen und ohne Antwort geschlossen; zusätzlich blockt die Firewall nicht gelistete Hosts bereits netzseitig.
Kachel TCP-Endpunkt deaktiviert oder Modul unlizenziert	Dienst läuft nicht — Verbindungsaufbau schlägt fehl (connection refused bzw. Firewall-Drop).
Konfigurierter Port beim Start belegt	Automatischer Ausweichversuch auf den Folge-Port (z. B. 6556 → 6557) mit Warnung in der Moduloberfläche; sind beide belegt, bleibt der Dienst inaktiv.
Unbekannter Pfad oder unbekannter `format`-Wert	Antwort im Standardformat — bewusst kein `400`-Fehler.
Interner Renderer-Fehler	Im HTTP-Modus `500 Internal Server Error`; ohne HTTP eine `ERROR:`-Textzeile.
`check_mk_agent.sh` auf der Anlage nicht ausführbar	Die Linux-Standardsektionen fehlen; Header, STARFACE-Sektionen und Local-Checks werden weiterhin geliefert.
JSON-Serialisierungsfehler	Antwortkörper `{"error":"…"}`.

Versionierung & Kompatibilität

Sektionsnamen des CheckMk-Formats, die Servicenamen der Local-Checks und die Struktur von XML-/JSON-Snapshot sind stabile Verträge; das Ausgabeformat der <<<starface*>>>-Sektionen ist 1:1 kompatibel zur historischen STARFACE-MonitoringComponent, sodass vorhandene Check-Plugins weiter funktionieren. Erweiterungen erfolgen additiv (neue Zeilen, Sektionen bzw. Felder) — Auswertungen sollten unbekannte Einträge ignorieren. Gegenüber dem CheckMk-Server meldet sich der Endpunkt derzeit als Agent-Version 2.5.0p6. Änderungen dokumentieren die Release Notes der jeweiligen Modulversion.

Grundlagen​

Endpunkte​

GET /checkmk​

GET /xml​

GET /json​

CheckMk-Paket starface_fluxpunkt.mkp​

Fehlerbehandlung​

Versionierung & Kompatibilität​

Grundlagen

Endpunkte

`GET /checkmk`

`GET /xml`

`GET /json`

CheckMk-Paket `starface_fluxpunkt.mkp`

Fehlerbehandlung

Versionierung & Kompatibilität