API di debug

Acquisito il 28-07-2026 da un CE di questo deployment. sitecli/capture-manifest.json registra quale nodo, e scripts/capture-sitecli.sh --check riverifica la superficie dei comandi su un CE attivo.

L’API vpm/debug esegue comandi Site CLI su un nodo registrato e ne restituisce l’output. Tutto quanto segue è stato accertato su un nodo attivo; nulla di ciò è pubblicato upstream.

Il catalogo dei comandi è autodescrittivo

Chiedete al nodo quali comandi supporta effettuando una POST a exec-user con la chiave command omessa:

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 .

La risposta è un oggetto JSON con chiave il nome del comando:

{
  "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)"]
}

Ogni voce è [category, tier, exampleArgument?, scope?], e questi campi non sono documentazione: determinano come il comando deve essere invocato.

Omettete la chiave; non inviate un valore errato

La discovery funziona lasciando fuori command. Inviare invece un valore sconosciuto restituisce un errore, non il catalogo:

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

Quel messaggio è anche ciò che si ottiene per un comando reale inviato all’endpoint sbagliato, per cui è facile interpretarlo erroneamente come «questo comando non esiste».

Tre trasporti, scelti in base alla voce del catalogo

Condizione	Metodo e percorso	Corpo	Restituisce
scope è GLOBAL	GET .../vpm/debug/global/<cmd>	nessuno	JSON
tier è ExecUser	POST .../vpm/debug/<node>/exec-user	array command	testo
tier è Exec	POST .../vpm/debug/<node>/exec	array command	testo

ExecUser — il tier in sola lettura 31 comandi

Il caso più comune. Passate il comando e i suoi argomenti come array, con il nome del comando per primo:

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 ..." }

Gli argomenti sono elementi separati dell’array, non un’unica stringa:

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

GLOBAL — a livello di sito, e con un trasporto completamente diverso 2 comandi

health e diagnosis sono gli unici due. Sono richieste GET verso un percorso global, non accettano argomenti e restituiscono JSON strutturato invece di testo da terminale.

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

Un comando GLOBAL non è raggiungibile tramite exec-user

Questa è la trappola che costa più tempo. Inviare health o diagnosis a exec-user restituisce command not supported, che si legge come se il comando non esistesse sul nodo — mentre in realtà esiste e avete usato il trasporto sbagliato.

# 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 — il tier privilegiato 1 comando su questa build

Un endpoint separato, e il tier è imposto anziché indicativo: exec rifiuta un comando ExecUser con lo stesso messaggio command not supported. Ogni membro modifica il nodo oppure legge un marcatore di stato.

Nella build in uso da questo tenant, il tier contiene solo ip-link-set. Le build più recenti aggiungono systemctl-restart-NetworkManager, systemctl-restart-crio, systemctl-restart-kubelet, systemctl-start-crio-prune e tre comandi marker-exists-*.

Nulla qui esegue un comando Exec

L’harness di acquisizione rifiuta questo tier e legge il tier dal catalogo live anziché da un elenco hardcoded — così una build futura che promuova un comando a Exec viene rispettata senza che nessuno debba modificare il codice. Eseguitene uno solo deliberatamente, su un nodo che siete disposti a interrompere.

Individuare i nomi del sito e del nodo

Il nome del nodo è il nome della VM Azure, e list-service è un modo economico per confermarlo insieme ai servizi in esecuzione su di esso:

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"]

Alcuni servizi riportano un nome di nodo vuoto, quindi una stringa vuota in quell’elenco è un artefatto della risposta e non un secondo nodo. list-service non fa nemmeno parte del catalogo di 34 comandi: è un endpoint global che il catalogo non pubblicizza, motivo per cui è documentato qui e non nel riferimento dei comandi.

Riprodurre le acquisizioni di questo repository

Ogni pagina di comando incorpora output acquisito da scripts/capture-sitecli.sh, che implementa tutte e tre le regole sopra descritte.

1. Puntatelo a un tenant. Legge XCSH_API_URL e XCSH_API_TOKEN, oppure ricade sul contesto xcsh attivo.

2. Aggiornate il catalogo e verificate che il nodo non sia cambiato sotto la documentazione:

   bash scripts/capture-sitecli.sh --check

   Questo confronta soltanto il catalogo committato e la build del software. Segnala una modifica della build separatamente dai comandi aggiunti o rimossi.

3. Ripetete l’acquisizione quando desiderate evidenze aggiornate:

   bash scripts/capture-sitecli.sh

Le acquisizioni sono evidenze, non artefatti riproducibili

Contatori, uptime ed età dei container cambiano tra un’esecuzione e l’altra, quindi una nuova acquisizione produce sempre un diff. Il catalogo è il contratto stabile ed è identico byte per byte tra le esecuzioni quando il nodo non è cambiato; è ciò che --check confronta. L’output lungo viene troncato e termina con un marcatore esplicito, così una tabella troncata non viene mai mostrata come se fosse completa.

Acquisizione da un nodo cliente: verificate il profilo di redazione

L’output dei comandi contiene l’identità dell’infrastruttura — indirizzamento interno, indirizzi MAC, numeri AS, hostname — e per un cliente si tratta di informazioni che identificano l’organizzazione.

Il filtro di scrub imposta quindi per default un profilo strict che rimuove tutto questo. Questo repository dichiara lab in sitecli/capture-manifest.json, il che conserva tali dettagli, ed è corretto solo qui perché queste acquisizioni provengono da infrastruttura demo di proprietà F5.

Non trasferite quell’impostazione a un’acquisizione presso un cliente. Token, chiavi private, l’identificatore del tenant, gli UUID degli oggetti, gli indirizzi email e i percorsi delle directory home vengono rimossi con entrambi i profili.

Vale la pena conoscere un limite: una tabella dei neighbour BGP stampa l’AS come una semplice colonna senza etichetta su cui ancorare un pattern, quindi gli ASN vengono confrontati per valore con gli intervalli privati. Un ASN pubblico in quel punto sopravvive al profilo strict e richiede una revisione manuale dell’output di show-ip-bgp* prima della pubblicazione.