Redfish

Riferimento del driver Redfish - connessione HTTPS a un BMC, indirizzamento per percorso della risorsa più puntatore JSON, letture, scritture PATCH e tipi.

Visualizza come Markdown

Il driver Redfish legge e scrive i servizi di gestione DMTF Redfish: l'API REST esposta dai BMC dei server (i controllori di gestione della scheda madre), dai telai e da altro hardware di centro dati per la gestione fuori banda. È un normale driver in modo client, cioè è Ganter Lab a collegarsi all'apparecchiatura, e il trasporto è sempre HTTPS: i BMC induriti non espongono altro, e il driver non scende mai da solo all'HTTP in chiaro.

Punti tipici letti in questo modo: lo stato di alimentazione, lo stato del secure boot, lo stato di salute del telaio e del gestore, la versione del firmware, le temperature e le letture delle ventole dalle risorse termiche.

Campi di connessione

Campo	Che cos'è	Formato	Predefinito
Indirizzo host	Il nome host o l'indirizzo IP del servizio Redfish.	Nome host o IP	vuoto
Porta	La porta su cui il servizio risponde. I controllori di gestione rispondono comunemente sulla 443, e un servizio pubblicato altrove lo dice qui. Un campo vuoto mostra 443 in grigio e il servizio viene raggiunto su di essa; un dispositivo salvato con 0 si legge allo stesso modo.	Da 1 a 65535	443
Nome utente	L'account del BMC usato per l'autenticazione HTTP Basic. Vuoto lascia le richieste anonime, cosa a cui un servizio protetto risponde con un errore di autorizzazione.	Testo libero	vuoto
Password di accesso	La password abbinata al nome utente. Protetta a riposo per utente di Windows, così il database di configurazione non contiene mai il valore in chiaro; una password inserita sotto un altro account Windows si presenta come illeggibile e va reinserita.	Testo libero	vuoto

Alla connessione il driver verifica il servizio leggendo la radice del servizio (/redfish/v1/). Il certificato TLS del BMC viene accettato quando Windows lo considera attendibile, o quando è stato approvato proprio quel certificato in Accesso delle apparecchiature, nella pagina di questo driver: il certificato autofirmato con cui viene fornito un BMC non richiede nulla di installato in Windows. Una connessione che fallisce dice perché nella pagina Eventi e nel file di diario della giornata, con l'errore sottostante dietro, così una password rifiutata e un certificato in attesa di approvazione si distinguono.

L'intervallo di interrogazione è configurabile: il valore predefinito del dispositivo (1000 ms) vale per ogni tag che non dichiari il proprio.

Indirizzamento dei tag

Un tag Redfish viene indirizzato da un percorso della risorsa più un puntatore JSON facoltativo dentro il documento che quella risorsa restituisce:

Campo	Che cosa fa	Valori	Predefinito
Percorso della risorsa	Il percorso, relativo alla radice del servizio, della risorsa Redfish da leggere con una GET, per esempio `redfish/v1/Chassis/1/Thermal`.	Testo libero (obbligatorio)	vuoto
Puntatore JSON (vuoto = intero documento)	Un puntatore RFC 6901 che seleziona un campo del JSON restituito, per esempio `/Temperatures/0/ReadingCelsius`. Gli elementi di array si indirizzano per indice; `~1` fa da carattere di fuga per una `/` dentro il nome di un campo e `~0` per una `~`. La `/` iniziale mancante viene aggiunta automaticamente. Vuoto restituisce l'intero documento come testo.	Puntatore JSON oppure vuoto	vuoto

Esempi dell'indirizzo composto (mostrato in sola lettura come anteprima dell'origine sul bus):

redfish/v1/Systems/1#/PowerState: lo stato di alimentazione del sistema, come stringa.
redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius: il primo sensore termico, come numero.
redfish/v1/Systems/1/SecureBoot#/SecureBootEnable: il secure boot, come booleano.

A ogni lettura il driver esegue una GET sulla risorsa, analizza il JSON, segue il puntatore e converte il risultato nel tipo di dato dichiarato dal tag. Un puntatore che non nomina nulla nel documento, e un campo che il documento porta come null JSON, si leggono entrambi come nessun valore: il tag passa a cattiva qualità e la sua politica di lettura fallita decide che cosa viene presentato, invece di far arrivare la parola null come lettura buona. Una risposta che non è JSON viene analizzata direttamente secondo il tipo dichiarato. Uno stato che il servizio restituisce fuori dall'intervallo di successo è il servizio che rifiuta la lettura: il tag passa a cattiva qualità allo stesso modo, e il suo motivo nomina lo stato e un breve estratto del documento di errore che il servizio ha inviato insieme a esso (HTTP 404 Not Found: …). Ogni altra lettura senza valore dice anch'essa il motivo: un tag senza percorso della risorsa, un puntatore che non nomina nulla nel documento e un campo tenuto a null (ciascuno nominando la risorsa e il puntatore), e una risposta che non si legge come il tipo dichiarato. Un servizio che non risponde affatto è la connessione del dispositivo che fallisce: il dispositivo lo segnala e si riconnette, e i suoi tag rimandano a esso. La riga rossa del tag dice uno stato simile nella lingua della stazione, con ciò che significa per 401, 403 e 404, e la riga rossa del dispositivo dice a ogni tentativo perché la sua connessione fallisce, una porta che rifiuta o uno stato come 401; la pagina Eventi conserva le parole del servizio stesso.

Scritture

I tag con una modalità di accesso scrivibile eseguono una PATCH sul campo indirizzato: il driver costruisce il documento JSON più piccolo che copre solo il percorso del puntatore (per /Parent/Child, il corpo {"Parent":{"Child":<value>}}) e lo invia alla risorsa. Da questo discendono due vincoli:

Una scrittura richiede un puntatore JSON. Un tag sull'intero documento (puntatore vuoto) non si può scrivere: il pannello del tag rifiuta la combinazione mentre stai modificando, dicendo che il campo manca, e un tentativo che raggiunga comunque il servizio fallisce con il motivo nel diario.
È il BMC a decidere che cosa è scrivibile; una PATCH che il servizio respinge riceve come risposta lo stato e un breve estratto del documento di errore che il servizio ha inviato insieme a esso (HTTP 400 Bad Request: …), e chi ha scritto il valore ne legge il motivo.

Come dappertutto, il valore che scrivi nella casella di scrittura del tag è il valore ingegneristico, e le fasi di conversione del tag vengono percorse all'indietro prima che il valore grezzo vada sul bus, come è descritto nella pagina Connector.

Tipi di dato supportati

Boolean, Int32, Int64, Float, Double e String. Scegli il tipo che corrisponde al campo JSON: i booleani per gli interruttori come SecureBootEnable, i numeri per le letture, le stringhe per gli stati come PowerState oppure Health.

Comandi

Un servizio Redfish pubblica un'azione per ogni cosa che gli si può chiedere di fare, ciascuna al proprio percorso sotto la risorsa su cui agisce. La stazione non le indovina, perché solo la documentazione dell'hardware dice quali esistono: le dichiara l'operatore sul dispositivo, nella scheda Comandi della sua pagina. Ogni comando porta un nome, il percorso dell'azione (redfish/v1/Systems/1/Actions/ComputerSystem.Reset) e, facoltativamente, il nome dell'unico valore che accetta (ResetType); il verbo Invia della riga lo manda, e quello che il servizio ha risposto viene riferito indietro. Un comando diventa anche un metodo sul dispositivo nello spazio degli indirizzi OPC UA proprio di questa stazione, così qualunque cosa sappia chiamare un metodo lo può emettere.

Il valore viaggia come corpo della richiesta. Un valore che è già JSON viene inviato come è scritto; qualunque altra cosa viene inviata come {"<il nome dichiarato>": "<il valore>"}, che è la forma che l'azione di reset propria di Redfish si aspetta.

Un'azione che il servizio rifiuta riceve come risposta lo stato e un breve estratto del documento di errore che il servizio ha inviato insieme a esso (HTTP 400 Bad Request: …), con le stesse parole di una scrittura rifiutata, e nient'altro sul dispositivo ne viene disturbato.

Rilevamento

Il pulsante Rileva legge un solo servizio: metti il suo indirizzo nella scheda Ambito della scansione della pagina del driver (https://bmc-host, oppure l'indirizzo che il fornitore documenta) e la scansione percorre il primo sistema, il primo gestore e il primo telaio di quel servizio, offrendo il dispositivo con quei punti pronti da aggiungere. La scansione legge il servizio in HTTPS e senza credenziali, perché gira prima che esista il dispositivo che le porterebbe, quindi un servizio che autentica ogni richiesta non risponde nulla e va aggiunto a mano. Il rilevamento SSDP proprio di Redfish ha bisogno del multicast UDP, che il driver interno al processo non fa, quindi diffondendo non si trova nulla: la scansione legge l'indirizzo che le dai.

Un dispositivo Redfish che c'è già trova i suoi punti dalla sua stessa pagina: Rileva tag, nell'intestazione della sua scheda Tag, percorre le stesse risorse autenticandosi con il nome utente e la password del dispositivo, così risponde anche un servizio che autentica ogni richiesta, e offre solo i punti per cui il dispositivo non ha ancora un tag (vedere Rilevare i tag di un dispositivo).

Accesso delle apparecchiature

Un BMC risponde di solito con un certificato proprio, autofirmato o emesso dal costruttore, di cui nessuna radice installata in Windows si fa garante. Non serve installare quella radice su questo computer. La prima connessione viene rifiutata, il dispositivo legge In attesa dell'approvazione del certificato nell'albero e nella sua pagina, il cui pulsante Verifica il certificato apre questa scheda sul certificato, e il certificato attende in Accesso delle apparecchiature, alla fine della pagina del driver Redfish, la stessa scheda che porta la pagina del driver OPC UA, finché non si decide:

Gruppo	Che cosa elenca	Che cosa si può fare
In attesa di approvazione	Ogni certificato rifiutato, con il nome che dichiara: la sua impronta SHA-256, l'indirizzo a cui è stato incontrato, quando ha tentato l'ultima volta e quante volte, e i suoi dettagli (soggetto, emittente, nomi di dominio, date di validità). Quello aperto da Verifica il certificato di un dispositivo è segnato come Selezionato per la verifica.	Approva accetta il certificato dal tentativo di connessione successivo. Blocca continua a rifiutarlo senza elencarlo di nuovo qui. Scarta tutti i certificati in attesa svuota l'elenco senza approvare né bloccare nulla.
Apparecchiature approvate	I certificati approvati o importati, con chi ha deciso e quando, e l'indirizzo a cui ciascuno è stato incontrato l'ultima volta.	Ritira l'approvazione chiude la connessione e riporta il certificato nell'elenco. Importa certificato approva un file di certificato pubblico già in proprio possesso (.der, .cer, .crt o .pem) prima della prima connessione.
Apparecchiature bloccate	I certificati bloccati. Un certificato bloccato viene rifiutato anche se Windows lo considera attendibile.	Sblocca riporta il certificato nell'elenco, senza approvarlo.

Verificare l'impronta con chi gestisce il server prima di approvare il certificato. Un'approvazione accetta quel certificato e nessun altro, e solo entro le sue date di validità; sostituisce la radice che manca a Windows e il nome che il certificato porta, così un BMC chiamato con il suo indirizzo IP si collega anche se il suo certificato porta un altro nome, e nient'altro del certificato viene allentato. Quando l'apparecchiatura risponde a un indirizzo di cui era stato approvato il certificato con un altro (un certificato rinnovato, un controller sostituito), la lettura si ferma, il nuovo attende qui e la stazione segnala « Certificato cambiato: <nome> » con un pulsante Verifica. Un certificato che Windows considera già attendibile viene accettato come prima e non compare mai qui; nulla viene approvato automaticamente.

L'errore del driver stesso dice il motivo invece di un errore TLS senza nome: « Il certificato di questa apparecchiatura (i primi 16 caratteri dell'impronta) attende la vostra approvazione in Accesso delle apparecchiature, nella pagina del driver Redfish. La lettura inizia appena lo approvate. » Uno bloccato dice « …è bloccato in questa stazione. Verificarlo in Accesso delle apparecchiature, nella pagina del driver Redfish. » Un certificato fuori dalle sue date di validità, revocato o con la firma non valida viene rifiutato con quel motivo e non viene mai elencato, perché nessuna approvazione lo rende valido. Una scansione del BMC, dalla scheda Ambito della scansione o da Rileva tag nella pagina del dispositivo, incontra le stesse decisioni: un certificato sconosciuto termina la scansione con quella frase e attende qui.

Le decisioni sono conservate nella cartella dati della stazione, in ua\pki\redfish, e sopravvivono a un riavvio. I verbi vengono disegnati solo per un ruolo che può configurare il Connector, e agiscono solo nella finestra della stazione stessa: un browser su un altro dispositivo legge la scheda senza cambiarla, e nessuno strumento di agente approva un certificato (connector_browse segnala il dispositivo in attesa con awaitingCertificate). L'elenco tiene fino a 100 certificati in attesa di approvazione; quando è pieno, uno nuovo viene ancora rifiutato ma non elencato, e la scheda lo dice.