API de Depuração

Capturado em 2026-07-28 de um CE deste deployment. sitecli/capture-manifest.json registra qual nó, e scripts/capture-sitecli.sh --check reverifica a superfície de comandos contra um CE ativo.

A API vpm/debug executa comandos do Site CLI em um nó registrado e retorna sua saída. Tudo abaixo foi estabelecido contra um nó ativo; nada disso está publicado upstream.

O catálogo de comandos é autodescritivo

Pergunte ao nó o que ele suporta enviando um POST para exec-user com a chave command omitida:

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 .

A resposta é um objeto JSON indexado pelo nome do 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)"]
}

Cada entrada é [categoria, tier, argumentoDeExemplo?, escopo?], e esses campos não são documentação — eles determinam como o comando deve ser chamado.

Omita a chave; não envie um valor errado

A descoberta funciona ao deixar command de fora. Enviar um valor desconhecido no lugar retorna um erro, não o catálogo:

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

Essa mensagem é também o que você obtém para um comando real enviado ao endpoint errado, então é fácil interpretá-la equivocadamente como “este comando não existe”.

Três transportes, escolhidos pela entrada do catálogo

Condição	Método e caminho	Corpo	Retorna
scope é GLOBAL	GET .../vpm/debug/global/<cmd>	nenhum	JSON
tier é ExecUser	POST .../vpm/debug/<node>/exec-user	array command	texto
tier é Exec	POST .../vpm/debug/<node>/exec	array command	texto

ExecUser — o tier somente leitura 31 comandos

O caso comum. Passe o comando e seus argumentos como um array, com o nome do comando primeiro:

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

Argumentos são elementos separados do array, não uma única string:

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

GLOBAL — abrangente ao site, e um transporte totalmente diferente 2 comandos

health e diagnosis são os únicos dois. São requisições GET para um caminho global, não recebem argumentos e retornam JSON estruturado em vez de texto de terminal.

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

Um comando GLOBAL não é acessível por exec-user

Esta é a armadilha que custa mais tempo. Enviar health ou diagnosis para exec-user retorna command not supported, o que soa como se o comando não existisse no nó — quando de fato ele existe e você usou o transporte errado.

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

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

Exec — o tier privilegiado 1 comando neste build

Um endpoint separado, e o tier é imposto em vez de meramente indicativo: exec rejeita um comando ExecUser com a mesma mensagem command not supported. Todo membro ou altera o nó ou lê um marcador de estado.

No build que este tenant executa, o tier contém apenas ip-link-set. Builds mais recentes adicionam systemctl-restart-NetworkManager, systemctl-restart-crio, systemctl-restart-kubelet, systemctl-start-crio-prune e três comandos marker-exists-*.

Nada aqui executa um comando Exec

O harness de captura recusa este tier, e lê o tier a partir do catálogo ativo em vez de uma lista fixa no código — então um build futuro que promova um comando para Exec é respeitado sem que ninguém edite código. Execute um apenas deliberadamente, em um nó que você esteja disposto a interromper.

Encontrando os nomes do site e do nó

O nome do nó é o nome da VM do Azure, e list-service é uma maneira econômica de confirmá-lo juntamente com os serviços em execução nele:

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

Alguns serviços reportam um nome de nó vazio, então uma string vazia nessa lista é um artefato da resposta, e não um segundo nó. list-service também não está no catálogo de 34 comandos: é um endpoint global que o catálogo não anuncia, e é por isso que está documentado aqui e não na referência de comandos.

Reproduzindo as capturas deste repositório

Cada página de comando incorpora a saída capturada por scripts/capture-sitecli.sh, que implementa todas as três regras acima.

1. Aponte-o para um tenant. Ele lê XCSH_API_URL e XCSH_API_TOKEN, ou recorre ao contexto xcsh ativo.

2. Atualize o catálogo e confirme que o nó não mudou por baixo da documentação:

   bash scripts/capture-sitecli.sh --check

   Isso compara apenas o catálogo comitado e o build de software. Ele reporta uma mudança de build separadamente de comandos adicionados ou removidos.

3. Recapture quando quiser evidências novas:

   bash scripts/capture-sitecli.sh

Capturas são evidências, não artefatos reproduzíveis

Contadores, uptimes e idades de contêineres mudam entre execuções, portanto recapturar sempre produz um diff. O catálogo é o contrato estável e é idêntico byte a byte entre execuções quando o nó não mudou; é isso que --check compara. Saídas longas são truncadas e terminam com um marcador explícito, então uma tabela truncada nunca é exibida como se estivesse completa.

Capturando de um nó de cliente: verifique o perfil de redação

A saída de comandos carrega identidade de infraestrutura — endereçamento interno, endereços MAC, números AS, hostnames — e, para um cliente, isso é informação que identifica a organização.

O filtro de limpeza, portanto, adota por padrão um perfil strict que remove tudo isso. Este repositório declara lab em sitecli/capture-manifest.json, o que preserva esse detalhe, e isso só é correto aqui porque estas capturas vêm de infraestrutura de demonstração de propriedade da F5.

Não leve essa configuração para uma captura de cliente. Tokens, chaves privadas, o identificador do tenant, UUIDs de objetos, endereços de e-mail e caminhos de diretórios home são removidos em ambos os perfis.

Vale conhecer uma limitação: uma tabela de vizinhos BGP imprime o AS como uma coluna simples, sem rótulo em que ancorar um padrão, então os ASNs são correspondidos por valor contra as faixas privadas. Um ASN público ali sobrevive ao perfil strict e exige uma revisão manual da saída de show-ip-bgp* antes de você publicá-la.