XML-RPC-Abfragen

Monitoring registriert drei Abfragen an der XML-RPC-Schnittstelle der STARFACE. Die Schnittstelle ist kompatibel zum verbreiteten „XML-Monitoring"-Referenzmodul (Version 2.1.1): bestehende Sensoren und Vorlagen für PRTG, Zabbix, Riverbird oder servereye funktionieren ohne Anpassung weiter. Alle Abfragen sind lesend und liefern den jeweils aktuellen Anlagen-Snapshot.

Grundlagen

Typ: XML-RPC über HTTPS (POST, Content-Type: text/xml, UTF-8)
Endpunkt: https://pbx.example.de/xml-rpc — der STARFACE-Webserver, unabhängig von der Monitoring-Hosts-Liste des Moduls
Methodenname: <Instanzname>.<Befehl> — der Name der Modulinstanz ist Teil des Methodennamens. Der Standard-Instanzname lautet „Monitoring"; wird die Instanz umbenannt, ändern sich die Methodennamen entsprechend (das Modul meldet sie automatisch neu an).
Authentifizierung: STARFACE-Benutzeranmeldung über den URL-Parameter de.vertico.starface.auth (siehe unten). isActiveDirectoryEnabled ist bewusst ohne Anmeldung aufrufbar.
Ein-/Ausgabe: Eingabe ist ein einzelnes XML-RPC-struct als erster Parameter; die Rückgabe ist ein struct, dessen Schlüssel die Namen der Ausgabevariablen sind.
Voraussetzungen: aktive Modulinstanz mit gültiger Lizenz; die Kachel XML-Monitoring in den Moduleinstellungen ist eingeschaltet (Standard: ein).

Anmeldung

Die beiden Datenabfragen verlangen einen angemeldeten STARFACE-Benutzer. Die Anmeldedaten werden — wie bei der STARFACE-XML-RPC-Schnittstelle üblich — als URL-Parameter de.vertico.starface.auth übergeben:

https://pbx.example.de/xml-rpc?de.vertico.starface.auth=<LoginID>:<Secret>

Das Secret wird aus Login-ID und Passwort des Benutzers berechnet (Hexadezimal, Kleinschreibung):

Secret = SHA-512( LoginID + "*" + SHA-512(Passwort) )

Die Prüfung übernimmt die STARFACE selbst, bevor der Modul-Handler ausgeführt wird.

Abfragen

`GetMonitoringData`

Liefert die Anlagendaten als Text im CheckMk-Local-Agent-Format — identisch zur Ausgabe des Datenendpunkts unter GET /checkmk: Agent-Header, die Linux-Standardsektionen des STARFACE-eigenen check_mk_agent.sh, die <<<starface*>>>-Sektionen und die <<<local>>>-Local-Checks. Die enthaltenen Sektionen beschreibt die Format-Referenz des Datenendpunkts.

Parameter	Typ	Pflicht	Standard	Beschreibung
`useLocalChecks`	Boolean	nein	`false`	Kompatibilitätsparameter des XML-Monitoring-Referenzmoduls. Akzeptiert auch die Zeichenketten `"true"` bzw. `"1"`. Die Rückgabe enthält in der aktuellen Modulversion in beiden Fällen den vollständigen CheckMk-Text einschließlich der `<<<local>>>`-Sektion.

Rückgabe: struct mit dem Mitglied data (String, CheckMk-Local-Format). Ist die Kachel XML-Monitoring deaktiviert oder das Modul nicht lizenziert, ist data ein leerer String.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Monitoring.GetMonitoringData</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>useLocalChecks</name>
            <value><boolean>0</boolean></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

import hashlib
import xmlrpc.client

HOST = "pbx.example.de"
LOGIN_ID = "0101"
PASSWORD = "geheim"

pw_hash = hashlib.sha512(PASSWORD.encode("utf-8")).hexdigest()
secret = hashlib.sha512(f"{LOGIN_ID}*{pw_hash}".encode("utf-8")).hexdigest()

proxy = xmlrpc.client.ServerProxy(
    f"https://{HOST}/xml-rpc?de.vertico.starface.auth={LOGIN_ID}:{secret}"
)

result = getattr(proxy, "Monitoring.GetMonitoringData")({"useLocalChecks": False})
print(result["data"])

Antwort (gekürzt):

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
  <params><param><value><struct>
    <member>
      <name>data</name>
      <value><string>&lt;&lt;&lt;check_mk&gt;&gt;&gt;
Version: 2.5.0p6
AgentOS: linux
Hostname: pbx
…
&lt;&lt;&lt;starface&gt;&gt;&gt;
appliance_type "STARFACE Pro"
starface_version 10.0.1.2
sip_status_localhost OK
…
&lt;&lt;&lt;local&gt;&gt;&gt;
0 "STARFACE update" update=0 STARFACE is up to date.
…</string></value>
    </member>
  </struct></value></param></params>
</methodResponse>

`GetMonitoringDataXML`

Liefert die wichtigsten Sensoren als kompaktes XML-Dokument mit dem Wurzelelement local — strukturgleich zum XML-Monitoring-Referenzmodul. XML-Clients (z. B. PRTG-Sensoren) selektieren die Werte per XPath auf //entry[@key='…']; Schlüssel und Struktur bleiben daher stabil.

Die Abfrage erwartet keine Parameter.

Rückgabe: struct mit dem Mitglied data (String, XML-Dokument). Je Sensor ein entry-Element mit den Kindern status (0 = OK, 1 = Warnung, 2 = kritisch), name, value und string (Beschreibung):

`entry`-Schlüssel	Vorkommen	Inhalt
`diskUtilization`	einmal	Auslastung in Prozent. Hinweis: Aus Kompatibilität zum Referenzmodul trägt der Sensor den Namen „Hard disk usage", gemessen wird die RAM-Auslastung ((MemTotal − MemAvailable) / MemTotal). Warnung ab 70 %, kritisch ab 90 %.
`update`	einmal	Verfügbares STARFACE-Update (`value`: `true`/`false`; Major-Update → Status `2`, Minor → `1`).
`major`, `minor`, `build`, `revision`	je einmal	Bestandteile der installierten STARFACE-Version.
`phoneStatus`	einmal	`2`, wenn alle bekannten Telefone offline sind, sonst `0`.
`backup`, `backupTime`	je Backup-Ziel	Status und Zeitpunkt des jüngsten Backups je Ziel; Status `2` bei fehlgeschlagenem Lauf oder Fehlertext in der Meldung.
`provider`	je SIP-Provider	Registrierungsstatus der Amtsleitung (`0` = registriert, `2` = nicht registriert).

Ist die Kachel XML-Monitoring deaktiviert oder das Modul nicht lizenziert, liefert data das leere Dokument <local></local>.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Monitoring.GetMonitoringDataXML</methodName>
  <params>
    <param>
      <value><struct></struct></value>
    </param>
  </params>
</methodCall>
XML

result = getattr(proxy, "Monitoring.GetMonitoringDataXML")({})
print(result["data"])

Inhalt von data (gekürzt):

<local>
  <entry key="diskUtilization">
    <status>0</status>
    <name>Hard disk usage</name>
    <value>42.17</value>
    <string>The hard disk usage in percent. Critical if value &gt;= 90%, warning if value &gt;= 70%.</string>
  </entry>
  <entry key="update">
    <status>0</status>
    <name>STARFACE update</name>
    <value>false</value>
    <string>STARFACE is up to date.</string>
  </entry>
  <entry key="major">
    <status>0</status>
    <name>STARFACE version</name>
    <value>10</value>
    <string>The installed STARFACE version is 10.0.1.2.</string>
  </entry>
  …
  <entry key="provider">
    <status>0</status>
    <name>STARFACE SIP Provider sip.provider.example</name>
    <value>true</value>
    <string>Account registered.</string>
  </entry>
</local>

`isActiveDirectoryEnabled`

Meldet, ob die Active-Directory-Anmeldung der STARFACE aktiviert ist. Monitoring-Werkzeuge nutzen die Abfrage, um vor der eigentlichen Anmeldung den passenden Anmeldemodus zu wählen.

Die Abfrage erwartet keine Parameter und ist bewusst ohne Authentifizierung aufrufbar — identisch zum XML-Monitoring-Referenzmodul. Sie unterliegt außerdem weder dem Kachel-Schalter noch der Lizenzprüfung und antwortet somit bei jeder aktiven Modulinstanz.

Rückgabe: struct mit dem Mitglied activeDirectoryEnabled — die Zeichenkette "true" oder "false" (kein XML-RPC-Boolean; die Ausgabevariable des Referenzmoduls ist String-typisiert).

Einordnung

Die Abfrage gibt ausschließlich preis, ob die AD-Anmeldung aktiv ist — keine weiteren Anlagen- oder Benutzerdaten. Da sie ohne Anmeldung erreichbar ist, gilt: Wer den Kreis möglicher Aufrufer einschränken möchte, beschränkt den Zugriff auf https://…/xml-rpc netzseitig (Firewall, Reverse-Proxy).

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Monitoring.isActiveDirectoryEnabled</methodName>
  <params>
    <param>
      <value><struct></struct></value>
    </param>
  </params>
</methodCall>
XML

import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("https://pbx.example.de/xml-rpc")
result = getattr(proxy, "Monitoring.isActiveDirectoryEnabled")({})
print(result["activeDirectoryEnabled"])   # "true" oder "false"

Antwort (gekürzt):

<methodResponse>
  <params><param><value><struct>
    <member>
      <name>activeDirectoryEnabled</name>
      <value><string>false</string></value>
    </member>
  </struct></value></param></params>
</methodResponse>

Anwendungsbeispiel

Ein PRTG-Sensor ruft alle fünf Minuten Monitoring.GetMonitoringDataXML auf und wertet die Einträge provider und backup per XPath aus. Fällt die Registrierung einer Amtsleitung aus, alarmiert PRTG — ohne CheckMk-Server und ohne zusätzliche Firewall-Freigabe, weil die Abfrage über den ohnehin erreichbaren STARFACE-Webserver läuft.

Fehlerbehandlung

Situation	Verhalten
Anmeldung fehlt oder ist ungültig (`GetMonitoringData`, `GetMonitoringDataXML`)	Die STARFACE weist den Aufruf mit einer XML-RPC-Fehlerantwort ab; der Modul-Handler wird nicht ausgeführt.
Unbekannter Methodenname (z. B. falscher Instanzname nach Umbenennung)	XML-RPC-Fault der STARFACE („unknown method").
Kachel XML-Monitoring deaktiviert	`GetMonitoringData` liefert `data` = leerer String; `GetMonitoringDataXML` liefert `data` = `<local></local>`.
Modul nicht lizenziert	Wie deaktiviert (leere Nutzlast). `isActiveDirectoryEnabled` antwortet weiterhin.
Interner Fehler bei der Datenerhebung	Rückgabe ist ein leeres `struct` ohne das erwartete Mitglied; Details stehen im Modul-Log.

Versionierung & Kompatibilität

Die drei Methodennamen, die Struktur der Rückgabe-Structs, die entry-Schlüssel des XML-Dokuments und die Servicenamen der <<<local>>>-Checks sind stabile Verträge — kompatibel zum XML-Monitoring-Referenzmodul 2.1.1, damit bestehende Sensoren (XPath-Selektoren, CheckMk-Service-Discovery) Modul-Updates unverändert überstehen. Erweiterungen erfolgen additiv (neue Sektionen bzw. Einträge); Änderungen dokumentieren die Release Notes der jeweiligen Modulversion.

Grundlagen​

Anmeldung​

Abfragen​

GetMonitoringData​

GetMonitoringDataXML​

isActiveDirectoryEnabled​

Fehlerbehandlung​

Versionierung & Kompatibilität​