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
| 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. | 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 precisa passar pela validação normal de
certificados do Windows: um certificado autoassinado de BMC precisa ser confiável nesta máquina antes de
o dispositivo conectar. 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 não confiável 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.
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 lê como escrita que falhou.
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.
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á.