# Redfish

> Referência do driver Redfish: conexão HTTPS a um BMC, endereçamento por caminho de recurso mais ponteiro JSON, leituras, escritas por PATCH e tipos.

O driver Redfish lê e escreve serviços de gerenciamento **DMTF Redfish**: a API
REST exposta por BMCs de servidor (baseboard management controllers), chassis e outro
hardware de datacenter para gerenciamento fora de banda. Este é um driver comum em modo
cliente (**o Ganter Lab conecta ao equipamento**) e o transporte é sempre
**HTTPS**: BMCs endurecidos não expõem outra coisa, e o driver nunca cai para
HTTP simples por conta própria.

Pontos típicos lidos assim: estado de energia, estado do secure boot, saúde do chassi e
do gerenciador, versão de firmware, temperaturas e leituras de ventoinha dos recursos
térmicos.

## Campos de conexão {#connection-fields}

| Campo | O que é | Formato | Padrão |
|---|---|---|---|
| Host | O nome de host ou endereço IP do serviço Redfish. | Nome de host ou IP | vazio |
| Porta | A porta em que o serviço responde. Controladores de gerenciamento costumam responder na 443, e um serviço publicado em outro lugar diz isso aqui. Um campo vazio mostra 443 em cinza e o serviço é alcançado nela, que é também como se lê um dispositivo salvo com 0. | 1 a 65535 | 443 |
| Usuário | A conta do BMC usada para autenticação **HTTP Basic**. Vazio deixa as requisições anônimas, o que um serviço protegido responderá com um erro de autorização. | Texto livre | vazio |
| Senha | A senha que acompanha o usuário. Protegida em repouso por usuário do Windows, então o banco de configuração nunca guarda o valor em claro; uma senha digitada sob outra conta do Windows aparece como ilegível e precisa ser digitada de novo. | Texto livre | vazio |

Ao conectar, o driver verifica o serviço lendo a raiz de serviço
(`/redfish/v1/`). O certificado TLS do BMC é aceito quando o Windows confia nele, ou quando
você aprovou exatamente esse certificado em [Acesso a equipamentos](#equipment-access), na
página deste driver: o certificado autoassinado com que um BMC sai de fábrica não precisa de
nada instalado no Windows. Uma conexão que falha diz por quê na página Eventos e no
arquivo de log do dia, com o erro de origem atrás, então uma senha recusada e
um certificado esperando aprovação são distinguidos.

O intervalo de leitura é configurável: o padrão do dispositivo (1000 ms) vale para toda
tag que não declare o próprio.

## Endereçamento da tag {#tag-addressing}

Uma tag Redfish é endereçada por um **caminho de recurso** mais um **ponteiro JSON**
opcional no documento que aquele recurso devolve:

| Campo | O que faz | Valores | Padrão |
|---|---|---|---|
| Caminho do recurso | O caminho, relativo à raiz de serviço, do recurso Redfish a buscar com GET, por exemplo `redfish/v1/Chassis/1/Thermal`. | Texto livre (obrigatório) | vazio |
| Ponteiro JSON (em branco = documento inteiro) | Um ponteiro RFC 6901 que seleciona um campo do JSON devolvido, por exemplo `/Temperatures/0/ReadingCelsius`. Elementos de vetor são endereçados por índice; `~1` escapa uma `/` dentro de um nome de campo e `~0` escapa um `~`. Uma `/` inicial ausente é acrescentada para você. Em branco devolve o documento inteiro como texto. | Ponteiro JSON ou em branco | em branco |

Exemplos do endereço montado (mostrado somente leitura como prévia da origem no barramento):

- `redfish/v1/Systems/1#/PowerState`, o estado de energia do sistema, como texto.
- `redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius`, o primeiro
  sensor térmico, como número.
- `redfish/v1/Systems/1/SecureBoot#/SecureBootEnable`, o secure boot, como booleano.

Numa leitura, o driver busca o recurso com GET, interpreta o JSON, segue o ponteiro e
converte o resultado para o tipo de dado declarado da tag. Um ponteiro que não nomeia nada
no documento, e um campo que o documento carrega como `null` do JSON, leem os dois como sem
valor: a tag vai a qualidade ruim e a política de falha de leitura dela decide o que é
apresentado, em vez de a palavra `null` chegar como leitura boa. Uma resposta que
não é JSON é interpretada diretamente como o tipo declarado. Um status que o serviço devolve
fora da faixa de sucesso é o serviço recusando a leitura: a tag vai a qualidade ruim do mesmo
jeito, e o motivo dela nomeia o status e um trecho curto do documento de erro que o serviço
mandou junto (`HTTP 404 Not Found: …`). Toda outra leitura sem valor também diz o motivo: uma
tag sem caminho de recurso, um ponteiro que não nomeia nada no documento e um campo guardado como
`null` (cada um nomeando o recurso e o ponteiro), e uma resposta que não se lê como o tipo
declarado. Um serviço que não responde nada é a conexão do dispositivo falhando: o dispositivo
relata isso e reconecta, e as tags dele apontam para ele. A faixa vermelha da tag diz um status assim na língua da estação, com o que ele significa nos códigos 401, 403 e 404, e a faixa vermelha do dispositivo diz a cada tentativa por que a conexão dele falha, uma porta que recusa ou um status como 401; a página Eventos guarda as palavras do próprio serviço.

## Escritas {#writes}

Tags com modo de acesso gravável fazem PATCH no campo endereçado: o driver monta o
menor documento JSON que cobre apenas o caminho do ponteiro (em
`/Parent/Child`, o corpo `{"Parent":{"Child":<value>}}`) e o envia ao
recurso. Duas restrições decorrem disso:

- Uma escrita **exige um ponteiro JSON**. Uma tag de documento inteiro (ponteiro em branco) não
  pode ser escrita: o painel da tag recusa a combinação enquanto você edita, dizendo
  que o campo falta, e uma tentativa que chegue ao serviço mesmo assim falha, com o motivo no diário.
- O BMC decide o que é gravável; um PATCH que o serviço rejeita recebe como resposta o status e um trecho curto do documento de erro que o serviço mandou junto (`HTTP 400 Bad Request: …`), e quem escreveu o valor lê o motivo.

Como em todo o resto, o valor que você digita na caixa de escrita da tag é o valor de
engenharia, e os estágios de conversão da tag são revertidos antes de o valor bruto ir para
o barramento, como descrito na página [Connector](connector).

## Tipos de dado suportados {#supported-data-types}

Boolean, Int32, Int64, Float, Double e String. Escolha o tipo que corresponde ao campo
JSON: booleanos para sinalizadores como `SecureBootEnable`, números para leituras, textos
para estados como `PowerState` ou `Health`.

## Comandos {#commands}

Um serviço Redfish publica uma ação por coisa que se pode pedir a ele, cada uma no seu
caminho, sob o recurso em que ela age. A estação não as adivinha, porque só a
documentação do próprio hardware diz quais existem: você as declara no dispositivo, no
cartão **Comandos** da página dele. Cada comando carrega um nome, o caminho da ação
(`redfish/v1/Systems/1/Actions/ComputerSystem.Reset`) e, opcionalmente, o nome do único
valor que ele recebe (`ResetType`); o verbo Executar da linha o envia, e o que o serviço respondeu
é relatado de volta. Um comando também vira um método no dispositivo, dentro do espaço de
endereços OPC UA desta estação, então qualquer coisa que consiga chamar um método consegue dispará-lo.

O valor viaja como corpo da requisição. Um valor que já é JSON é enviado como foi escrito;
qualquer outra coisa é enviada como `{"<o nome que você declarou>": "<o valor>"}`, que é a forma
que a própria ação de reset do Redfish espera.

Uma ação que o serviço recusa recebe como resposta o status e um trecho curto do documento de
erro que o serviço mandou junto (`HTTP 400 Bad Request: …`), com as mesmas palavras de uma escrita
recusada, e nada mais no dispositivo é perturbado por isso.

## Descoberta {#discovery}

O botão **Descobrir** lê um serviço: ponha o endereço dele no cartão Escopo da varredura
da página do driver (`https://bmc-host`, ou o endereço que o fabricante documenta) e a varredura percorre
o primeiro sistema, gerenciador e chassi daquele serviço, oferecendo o dispositivo com esses pontos prontos
para adicionar. A varredura lê o serviço por HTTPS e sem credenciais, porque roda antes de
existir o dispositivo que as guardaria, então um serviço que autentica toda requisição
não responde nada e é adicionado à mão. A descoberta SSDP do próprio Redfish precisa de multicast
UDP, que o driver em processo não faz, então nada é achado por difusão: a
varredura lê o endereço que você lhe dá.

Um dispositivo Redfish que você já tem acha os pontos dele pela própria página: **Descobrir tags**, no cabeçalho do cartão **Tags** dele, percorre os mesmos recursos entrando com o usuário e a senha do dispositivo, então um serviço que autentica toda requisição também responde, e oferece só os pontos para os quais o dispositivo ainda não tem tag (veja [Descobrir as tags de um dispositivo](connector-discovery#discovering-a-devices-tags)).

## Acesso a equipamentos {#equipment-access}

Um BMC costuma responder com um certificado próprio, autoassinado ou emitido pelo fabricante, que nenhuma raiz instalada no Windows garante. Essa raiz não precisa ser instalada neste computador. A primeira conexão é recusada, o dispositivo mostra **Esperando a aprovação do certificado** na árvore e na página dele, cujo botão **Revisar o certificado** abre este cartão no certificado, e o certificado espera em **Acesso a equipamentos**, no fim da página do driver Redfish, o mesmo cartão que a página do driver OPC UA traz, até você decidir:

| Grupo | O que lista | O que você pode fazer |
|---|---|---|
| Esperando aprovação | Cada certificado recusado, sob o nome que ele declara: a impressão digital SHA-256, o endereço em que foi encontrado, quando tentou pela última vez e quantas vezes, e os detalhes (titular, emissor, nomes de domínio, datas de validade). O que o **Revisar o certificado** de um dispositivo abriu fica marcado como Selecionado para revisão. | **Aprovar** aceita o certificado a partir da próxima tentativa de conexão. **Bloquear** continua recusando-o sem listá-lo aqui de novo. **Descartar todos os certificados pendentes** esvazia a lista sem aprovar nem bloquear nada. |
| Equipamentos aprovados | Os certificados que você aprovou ou importou, com quem decidiu e quando, e o endereço em que cada um foi encontrado por último. | **Retirar a aprovação** encerra a conexão e devolve o certificado à lista. **Importar certificado** aprova um arquivo de certificado público que você já tem (.der, .cer, .crt ou .pem) antes da primeira conexão. |
| Equipamentos bloqueados | Os certificados que você bloqueou. Um certificado bloqueado é recusado mesmo que o Windows confie nele. | **Desbloquear** devolve o certificado à lista, sem aprová-lo. |

Confira a impressão digital com quem administra o servidor antes de aprovar o certificado. Uma aprovação aceita aquele certificado e nenhum outro, e só dentro das datas de validade dele; ela substitui a raiz que falta no Windows e o nome que o certificado traz, então um BMC chamado pelo endereço IP conecta mesmo que o certificado dele traga outro nome, e nada mais do certificado é afrouxado. Quando o equipamento responde num endereço cujo certificado você aprovou com outro (um certificado renovado, uma controladora trocada), a leitura para, o novo espera aqui e a estação avisa "Certificado mudou: `<nome>`" com um botão **Revisar**. Um certificado em que o Windows já confia é aceito como antes e nunca aparece aqui; nada é aprovado automaticamente.

A própria falha do driver diz o motivo em vez de um erro de TLS sem nome: "O certificado deste equipamento (os primeiros 16 caracteres da impressão digital) espera a sua aprovação em Acesso a equipamentos, na página do driver Redfish. A leitura começa assim que você aprová-lo." Um bloqueado diz "…está bloqueado nesta estação. Revise-o em Acesso a equipamentos, na página do driver Redfish." Um certificado fora das datas de validade, revogado ou com a assinatura quebrada é recusado com esse motivo e nunca é listado, porque nenhuma aprovação o torna válido. Uma varredura do BMC, pelo cartão Escopo da varredura ou pelo **Descobrir tags** na página do dispositivo, esbarra nas mesmas decisões: um certificado desconhecido encerra a varredura com essa frase e espera aqui.

As decisões ficam na pasta de dados da estação, em `ua\pki\redfish`, e sobrevivem a um reinício. Os verbos só são desenhados para um papel que pode configurar o Connector, e só agem na janela da própria estação: um navegador em outro aparelho lê o cartão sem mudá-lo, e nenhuma ferramenta de agente aprova um certificado (`connector_browse` indica o dispositivo em espera com `awaitingCertificate`). A lista guarda até 100 certificados esperando aprovação; quando está cheia, um novo continua recusado mas não é listado, e o cartão diz isso.