Redfish

Référence du pilote Redfish : connexion HTTPS à un BMC, adressage par chemin de ressource et pointeur JSON, lectures, écritures PATCH et types.

Afficher en Markdown

Le pilote Redfish lit et écrit des services de gestion DMTF Redfish : l'API REST exposée par les BMC de serveurs (baseboard management controllers), les châssis et les autres matériels de centre de données pour la gestion hors bande. C'est un pilote client ordinaire (Ganter Lab se connecte au matériel) et le transport est toujours HTTPS : les BMC durcis n'exposent rien d'autre, et le pilote ne se rabat jamais de lui-même sur du HTTP simple.

Les points typiquement lus ainsi : l'état d'alimentation, l'état du démarrage sécurisé, l'état de santé du châssis et du gestionnaire, la version du micrologiciel, les températures et les relevés de ventilateurs des ressources thermiques.

Champs de connexion

Champ	Ce que c'est	Format	Défaut
Hôte	Le nom d'hôte ou l'adresse IP du service Redfish.	Nom d'hôte ou IP	vide
Port	Le port sur lequel le service répond. Les contrôleurs de gestion répondent couramment sur 443, et un service publié ailleurs le dit ici. Un champ vide affiche 443 en gris et le service est joint sur ce port ; un équipement enregistré avec 0 se lit de la même façon.	De 1 à 65535	443
Nom d'utilisateur	Le compte BMC employé pour l'authentification HTTP Basic. Vide laisse les requêtes anonymes, ce à quoi un service protégé répondra par une erreur d'autorisation.	Texte libre	vide
Mot de passe	Le mot de passe associé au nom d'utilisateur. Protégé au repos par utilisateur Windows, si bien que la base de configuration ne porte jamais la valeur en clair ; un mot de passe saisi sous un autre compte Windows s'affiche comme illisible et doit être saisi de nouveau.	Texte libre	vide

À la connexion, le pilote vérifie le service en lisant la racine de service (/redfish/v1/). Le certificat TLS du BMC est accepté quand Windows lui fait confiance, ou quand vous avez approuvé ce certificat précis sous Accès des équipements, sur la page de ce pilote : le certificat autosigné livré avec un BMC n'a besoin de rien d'installé dans Windows. Une connexion en échec dit pourquoi sur la page Événements et dans le fichier journal du jour, avec l'erreur sous-jacente derrière, si bien qu'un mot de passe refusé et un certificat en attente d'approbation se distinguent.

La période de scrutation est configurable : la valeur par défaut de l'équipement (1000 ms) s'applique à chaque tag qui ne donne pas la sienne.

Adressage des tags

Un tag Redfish est adressé par un chemin de ressource plus un pointeur JSON facultatif dans le document que cette ressource retourne :

Champ	Ce qu'il fait	Valeurs	Défaut
Chemin de ressource	Le chemin, relatif à la racine de service, de la ressource Redfish à récupérer en GET, par exemple `redfish/v1/Chassis/1/Thermal`.	Texte libre (obligatoire)	vide
Pointeur JSON (vide = document entier)	Un pointeur RFC 6901 qui sélectionne un champ du JSON retourné, par exemple `/Temperatures/0/ReadingCelsius`. Les éléments de tableau s'adressent par index ; `~1` échappe un `/` dans un nom de champ et `~0` un `~`. Un `/` de tête manquant est ajouté pour vous. Vide retourne le document entier sous forme de texte.	Pointeur JSON ou vide	vide

Exemples de l'adresse assemblée (montrée en lecture seule dans l'aperçu de source de bus) :

redfish/v1/Systems/1#/PowerState : l'état d'alimentation du système, sous forme de chaîne.
redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius : le premier capteur thermique, sous forme de nombre.
redfish/v1/Systems/1/SecureBoot#/SecureBootEnable : le démarrage sécurisé, sous forme de booléen.

À la lecture, le pilote récupère la ressource en GET, analyse le JSON, suit le pointeur et convertit le résultat vers le type de donnée déclaré du tag. Un pointeur qui ne nomme rien dans le document, et un champ que le document porte en null JSON, se lisent tous deux comme aucune valeur : le tag passe en mauvaise qualité et sa politique de lecture en échec décide de ce qui est présenté, plutôt que le mot null n'arrive en lecture correcte. Une réponse qui n'est pas du JSON est analysée directement selon le type déclaré. Un état que le service renvoie hors de la plage de succès est le service qui refuse la lecture : le tag passe en mauvaise qualité de la même façon, et sa raison nomme l'état et un court extrait du document d'erreur que le service a envoyé avec lui (HTTP 404 Not Found: …). Toute autre lecture sans valeur dit aussi pourquoi : un tag sans chemin de ressource, un pointeur qui ne désigne rien dans le document et un champ tenu à null (chacun nommant la ressource et le pointeur), et une réponse qui ne se lit pas selon le type déclaré. Un service qui ne répond pas du tout, c'est la connexion de l'équipement qui échoue : l'équipement le signale et se reconnecte, et ses tags renvoient à lui. La ligne rouge du tag dit un tel statut dans la langue de la station, avec ce qu'il signifie pour 401, 403 et 404, et la ligne rouge de l'équipement dit à chaque tentative pourquoi sa connexion échoue, un port qui refuse ou un statut comme 401 ; la page Événements garde les mots du service lui-même.

Écritures

Les tags dont le mode d'accès est inscriptible modifient le champ adressé en PATCH : le pilote construit le plus petit document JSON couvrant le seul chemin du pointeur (pour /Parent/Child, le corps {"Parent":{"Child":<value>}}) et l'envoie à la ressource. Deux contraintes en découlent :

Une écriture exige un pointeur JSON. Un tag sur document entier (pointeur vide) ne peut pas être écrit : le volet du tag refuse la combinaison pendant que vous modifiez, en disant que le champ manque, et une tentative qui atteindrait tout de même le service échoue avec la raison dans le journal.
C'est le BMC qui décide de ce qui est inscriptible ; un PATCH que le service rejette reçoit pour réponse l'état et un court extrait du document d'erreur que le service a envoyé avec lui (HTTP 400 Bad Request: …), et celui qui a écrit la valeur en lit la raison.

Comme partout ailleurs, la valeur que vous tapez dans la zone d'écriture du tag est la valeur physique, et les étapes de conversion du tag sont remontées avant que la valeur brute ne parte sur le bus, comme le décrit la page Connector.

Types de donnée pris en charge

Boolean, Int32, Int64, Float, Double et String. Choisissez le type qui correspond au champ JSON : des booléens pour les drapeaux comme SecureBootEnable, des nombres pour les relevés, des chaînes pour les états comme PowerState ou Health.

Commandes

Un service Redfish publie une action par chose qu'on peut lui demander de faire, chacune à son propre chemin sous la ressource sur laquelle elle agit. La station ne les devine pas, parce que seule la documentation du matériel dit lesquelles existent : vous les déclarez sur l'équipement, dans la carte Commandes de sa page. Chaque commande porte un nom, le chemin de l'action (redfish/v1/Systems/1/Actions/ComputerSystem.Reset), et éventuellement le nom de la seule valeur qu'elle prend (ResetType) ; le verbe Exécuter de la ligne l'envoie, et ce que le service a répondu est rapporté. Une commande devient aussi une méthode sur l'équipement dans l'espace d'adressage OPC UA propre à cette station, si bien que tout ce qui peut appeler une méthode peut l'envoyer.

La valeur voyage dans le corps de la requête. Une valeur qui est déjà du JSON est envoyée telle qu'écrite ; tout le reste est envoyé sous la forme {"<le nom que vous avez déclaré>": "<la valeur>"}, qui est la forme qu'attend l'action de réinitialisation propre à Redfish.

Une action que le service refuse reçoit pour réponse l'état et un court extrait du document d'erreur que le service a envoyé avec lui (HTTP 400 Bad Request: …), dans les mêmes mots que ceux d'une écriture refusée, et rien d'autre sur l'équipement n'en est dérangé.

Découverte

Le bouton Découvrir lit un service : placez son adresse dans la carte Portée du balayage de la page du pilote (https://bmc-host, ou l'adresse que le fabricant documente) et le balayage parcourt le premier système, le gestionnaire et le châssis de ce service, en proposant l'équipement avec ces points prêts à ajouter. Le balayage lit le service en HTTPS et sans identifiants, parce qu'il tourne avant que l'équipement qui les porterait n'existe, si bien qu'un service qui authentifie chaque requête ne répond rien et s'ajoute à la main. La découverte SSDP propre à Redfish a besoin de multidiffusion UDP, que le pilote interne au processus ne fait pas, si bien que rien n'est trouvé par diffusion : le balayage lit l'adresse que vous lui donnez.

Un équipement Redfish que vous avez déjà trouve ses points depuis sa propre page : Découvrir les tags, dans l'en-tête de sa carte Tags, parcourt les mêmes ressources en s'identifiant avec le nom d'utilisateur et le mot de passe de l'équipement, de sorte qu'un service qui authentifie chaque requête répond lui aussi, et ne propose que les points pour lesquels l'équipement n'a pas encore de tag (voir Découvrir les tags d'un équipement).

Accès des équipements

Un BMC répond d'ordinaire avec un certificat à lui, autosigné ou émis par son fabricant, dont aucune racine installée dans Windows ne se porte garante. Cette racine n'a pas besoin d'être installée sur cet ordinateur. La première connexion est refusée, l'équipement indique En attente de l'approbation du certificat dans l'arborescence et sur sa page, dont le bouton Examiner le certificat ouvre cette carte sur le certificat, et le certificat attend sous Accès des équipements, à la fin de la page du pilote Redfish, la même carte que porte la page du pilote OPC UA, jusqu'à ce que vous décidiez :

Groupe	Ce qu'il liste	Ce que vous pouvez faire
En attente d'approbation	Chaque certificat refusé, sous le nom qu'il déclare : son empreinte SHA-256, l'adresse où il a été rencontré, quand il a essayé pour la dernière fois et combien de fois, et ses détails (sujet, émetteur, noms de domaine, dates de validité). Celui qu'a ouvert Examiner le certificat d'un équipement est marqué Sélectionné pour examen.	Approuver accepte le certificat dès la tentative de connexion suivante. Bloquer continue de le refuser sans le lister de nouveau ici. Écarter tous les certificats en attente vide la liste sans rien approuver ni bloquer.
Équipements approuvés	Les certificats que vous avez approuvés ou importés, avec qui a décidé et quand, et l'adresse où chacun a été rencontré en dernier.	Retirer l'approbation ferme la connexion et remet le certificat dans la liste. Importer un certificat approuve un fichier de certificat public que vous avez déjà (.der, .cer, .crt ou .pem) avant la première connexion.
Équipements bloqués	Les certificats que vous avez bloqués. Un certificat bloqué est refusé même si Windows lui fait confiance.	Débloquer remet le certificat dans la liste, sans l'approuver.

Vérifiez l'empreinte auprès de la personne qui gère le serveur avant d'approuver le certificat. Une approbation accepte ce certificat et aucun autre, et seulement dans ses dates de validité ; elle tient lieu de la racine qui manque à Windows et du nom que porte le certificat, si bien que un BMC appelé par son adresse IP se connecte même si son certificat porte un autre nom, et rien d'autre du certificat n'est assoupli. Quand l'équipement répond à une adresse dont vous aviez approuvé le certificat avec un autre (un certificat renouvelé, un contrôleur remplacé), la lecture s'arrête, le nouveau attend ici, et la station signale « Certificat modifié : <nom> » avec un bouton Examiner. Un certificat auquel Windows fait déjà confiance est accepté comme avant et n'apparaît jamais ici ; rien n'est approuvé automatiquement.

L'échec du pilote lui-même dit le motif au lieu d'une erreur TLS sans nom : « Le certificat de cet équipement (les 16 premiers caractères de l'empreinte) attend votre approbation sous Accès des équipements, sur la page du pilote Redfish. La lecture commence dès que vous l'approuvez. » Un certificat bloqué donne « …est bloqué à cette station. Examinez-le sous Accès des équipements, sur la page du pilote Redfish. » Un certificat hors de ses dates de validité, révoqué ou à la signature invalide est refusé avec ce motif et n'est jamais listé, car aucune approbation ne le rend valable. Un balayage du BMC, depuis la carte Portée du balayage ou depuis Découvrir les tags sur la page de l'équipement, se heurte aux mêmes décisions : un certificat inconnu termine le balayage avec cette phrase et attend ici.

Les décisions sont conservées dans le dossier de données de la station, sous ua\pki\redfish, et survivent à un redémarrage. Les verbes ne sont dessinés que pour un rôle qui peut configurer le Connector, et ils n'agissent que dans la fenêtre de la station elle-même : un navigateur sur un autre appareil lit la carte sans la changer, et aucun outil d'agent n'approuve un certificat (connector_browse signale l'équipement en attente avec awaitingCertificate). La liste garde jusqu'à 100 certificats en attente d'approbation ; une fois pleine, un nouveau est encore refusé mais pas listé, et la carte le dit.