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 réseau	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.	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 doit passer la validation de certificat Windows normale : un certificat de BMC auto-signé doit être accordé par cette machine avant que l'équipement ne se connecte. 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 non accordé 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é.

É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 se lit comme une écriture en échec.

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.

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.