Debug-API

Aufgenommen am 28.07.2026 von einer CE dieses Deployments. sitecli/capture-manifest.json hält fest, welcher Knoten verwendet wurde, und scripts/capture-sitecli.sh --check überprüft die Befehlsoberfläche erneut gegen eine aktive CE.

Die vpm/debug-API führt Site-CLI-Befehle auf einem registrierten Knoten aus und gibt deren Ausgabe zurück. Alles Nachfolgende wurde gegen einen aktiven Knoten ermittelt; nichts davon ist offiziell veröffentlicht.

Der Befehlskatalog beschreibt sich selbst

Fragen Sie den Knoten ab, was er unterstützt, indem Sie an exec-user POSTen und den Schlüssel command auslassen:

curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>"}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user" \
  | jq -r .output | jq .

Die Antwort ist ein JSON-Objekt, dessen Schlüssel die Befehlsnamen sind:

{
  "crictl-inspect": ["System Troubleshooting", "ExecUser", " container-id"],
  "diagnosis":      ["System Troubleshooting", "ExecUser", "no argument needed", "GLOBAL"],
  "ip-link-set":    ["Network Troubleshooting", "Exec", " (<device>||<group>) (up||down)"]
}

Jeder Eintrag hat die Form [category, tier, exampleArgument?, scope?], und diese Felder sind keine Dokumentation – sie legen fest, wie der Befehl aufgerufen werden muss.

Lassen Sie den Schlüssel weg; senden Sie keinen falschen Wert

Discovery funktioniert, indem command weggelassen wird. Wird stattdessen ein unbekannter Wert gesendet, erhalten Sie einen Fehler und nicht den Katalog:

{"code":3,"details":[],"message":"exec command failed: command not supported"}

Dieselbe Meldung erhalten Sie auch für einen echten Befehl, der an den falschen Endpunkt gesendet wurde, weshalb sie leicht als „dieser Befehl existiert nicht“ missverstanden wird.

Drei Transportwege, ausgewählt durch den Katalogeintrag

Bedingung	Methode und Pfad	Body	Rückgabe
scope ist GLOBAL	GET .../vpm/debug/global/<cmd>	keiner	JSON
tier ist ExecUser	POST .../vpm/debug/<node>/exec-user	command-Array	Text
tier ist Exec	POST .../vpm/debug/<node>/exec	command-Array	Text

ExecUser – die schreibgeschützte Ebene 31 Befehle

Der Regelfall. Übergeben Sie den Befehl und seine Argumente als Array, den Befehlsnamen zuerst:

curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>","command":["crictl-ps"]}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user"

{ "return_code": 0, "output": "CONTAINER    IMAGE    CREATED    STATE ..." }

Argumente sind separate Array-Elemente, nicht eine einzelne Zeichenkette:

{ "command": ["journalctl", "-u", "vpm", "-n", "200"] }

GLOBAL – standortweit und ein völlig anderer Transportweg 2 Befehle

health und diagnosis sind die einzigen beiden. Es handelt sich um GET-Anfragen an einen global-Pfad, sie nehmen keine Argumente an und geben strukturiertes JSON anstelle von Terminaltext zurück.

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/health" | jq .

Ein GLOBAL-Befehl ist nicht über exec-user erreichbar

Dies ist die Falle, die am meisten Zeit kostet. Wird health oder diagnosis an exec-user gesendet, erhalten Sie command not supported, was so klingt, als existiere der Befehl auf dem Knoten nicht – obwohl er tatsächlich existiert und Sie lediglich den falschen Transportweg verwendet haben.

# Wrong. Returns: exec command failed: command not supported
-d '{"namespace":"system","site":"…","node":"…","command":["health"]}'   # POST exec-user

# Right.
GET .../vpm/debug/global/health

Exec – die privilegierte Ebene 1 Befehl in diesem Build

Ein separater Endpunkt, und die Ebene wird erzwungen und nicht nur empfohlen: exec weist einen ExecUser-Befehl mit derselben Meldung command not supported ab. Jedes Mitglied verändert entweder den Knoten oder liest einen Zustandsmarker.

Im Build, den dieser Tenant ausführt, enthält die Ebene ausschließlich ip-link-set. Neuere Builds ergänzen systemctl-restart-NetworkManager, systemctl-restart-crio, systemctl-restart-kubelet, systemctl-start-crio-prune und drei marker-exists-*-Befehle.

Hier wird kein Exec-Befehl ausgeführt

Das Capture-Harness verweigert diese Ebene und liest die Ebene aus dem aktiven Katalog statt aus einer fest codierten Liste – so wird ein zukünftiger Build, der einen Befehl auf Exec hochstuft, respektiert, ohne dass jemand Code ändern muss. Führen Sie einen solchen Befehl nur bewusst aus, auf einem Knoten, dessen Störung Sie in Kauf nehmen.

Die Site- und Knotennamen finden

Der Knotenname ist der Azure-VM-Name, und list-service ist eine günstige Möglichkeit, ihn zusammen mit den darauf laufenden Diensten zu bestätigen:

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/list-service" \
  | jq -r '[.service[].node] | unique'

["", "f5-xc-ce-vm-01"]

Einige Dienste melden einen leeren Knotennamen, daher ist eine leere Zeichenkette in dieser Liste ein Artefakt der Antwort und kein zweiter Knoten. list-service ist außerdem nicht im Katalog mit 34 Befehlen enthalten: es ist ein global-Endpunkt, den der Katalog nicht ausweist, weshalb er hier dokumentiert ist und nicht in der Befehlsreferenz.

Die Captures dieses Repositorys reproduzieren

Jede Befehlsseite bindet Ausgaben ein, die von scripts/capture-sitecli.sh aufgenommen wurden, welches alle drei oben genannten Regeln umsetzt.

1. Richten Sie es auf einen Tenant. Es liest XCSH_API_URL und XCSH_API_TOKEN oder greift auf den aktiven xcsh-Kontext zurück.

2. Aktualisieren Sie den Katalog und bestätigen Sie, dass sich der Knoten nicht unter der Dokumentation verändert hat:

   bash scripts/capture-sitecli.sh --check

   Dies vergleicht ausschließlich den committeten Katalog und den Software-Build. Eine Build-Änderung wird getrennt von hinzugefügten oder entfernten Befehlen gemeldet.

3. Nehmen Sie erneut auf, wenn Sie frische Belege möchten:

   bash scripts/capture-sitecli.sh

Captures sind Belege, keine reproduzierbaren Artefakte

Zähler, Laufzeiten und Container-Alter verändern sich zwischen den Durchläufen, daher erzeugt eine erneute Aufnahme immer ein Diff. Der Katalog ist der stabile Vertrag und ist über Durchläufe hinweg byte-identisch, solange sich der Knoten nicht verändert hat; genau das vergleicht --check. Lange Ausgaben werden gekürzt und enden mit einem ausdrücklichen Marker, sodass eine abgeschnittene Tabelle niemals so dargestellt wird, als wäre sie vollständig.

Aufnahme von einem Kundenknoten: Prüfen Sie das Redaktionsprofil

Befehlsausgaben enthalten Infrastrukturidentitäten – interne Adressierung, MAC-Adressen, AS-Nummern, Hostnamen – und für einen Kunden sind das identifizierende Informationen über die Organisation.

Der Scrub-Filter verwendet daher standardmäßig ein striktes Profil, das all dies entfernt. Dieses Repository deklariert lab in sitecli/capture-manifest.json, wodurch diese Details erhalten bleiben, und das ist hier nur deshalb korrekt, weil diese Captures aus F5-eigener Demo-Infrastruktur stammen.

Übertragen Sie diese Einstellung nicht auf eine Kundenaufnahme. Tokens, private Schlüssel, die Tenant-Kennung, Objekt-UUIDs, E-Mail-Adressen und Home-Verzeichnispfade werden unter beiden Profilen entfernt.

Eine Einschränkung sollte bekannt sein: Eine BGP-Nachbarschaftstabelle gibt die AS als reine Spalte ohne Beschriftung aus, an der sich ein Muster verankern ließe, daher werden ASNs anhand ihres Werts gegen die privaten Bereiche abgeglichen. Eine öffentliche ASN überlebt dort das strikte Profil und erfordert eine manuelle Prüfung der show-ip-bgp*-Ausgabe, bevor Sie sie veröffentlichen.