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.

Ver como Markdown

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

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, 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

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

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.

Tipos de dado suportados

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

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

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).

Acesso a equipamentos

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.