# Redfish

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

Le pilote Redfish lit et écrit des services de gestion **DMTF Redfish** : l'API REST
qu'exposent les BMC de serveur (contrôleurs de gestion de carte mère), les châssis et
d'autres matériels de centre de données pour la gestion hors bande. C'est un pilote ordinaire
en mode client (**Ganter Lab se connecte à l'équipement**) et le transport est toujours
**HTTPS** : les BMC durcis n'exposent rien d'autre, et le pilote ne retombe 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 ventilateur des ressources thermiques.

## Champs de connexion {#connection-fields}

| Champ | Ce que c'est | Format | Par 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 du 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 données de configuration ne détient jamais la valeur en clair; un mot de passe saisi sous un autre compte Windows paraît 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](#equipment-access),
sur la page de ce pilote : le certificat autosigné livré avec un BMC n'a besoin de rien
d'installé dans Windows. Une connexion qui échoue 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.

L'intervalle de scrutation est configurable : la valeur de l'équipement (1000 ms) s'applique à
chaque tag qui n'énonce pas la sienne.

## Adressage d'un tag {#tag-addressing}

Un tag Redfish est adressé par un **chemin de ressource** suivi d'un **pointeur
JSON** facultatif dans le document que cette ressource renvoie :

| Champ | Ce qu'il fait | Valeurs | Par défaut |
|---|---|---|---|
| Chemin de ressource | Le chemin, relatif à la racine de service, de la ressource Redfish à lire par 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 renvoyé, par exemple `/Temperatures/0/ReadingCelsius`. Les éléments de tableau sont adressés par leur indice; `~1` échappe un `/` dans un nom de champ et `~0` un `~`. Une barre oblique de tête manquante est ajoutée pour vous. Vide renvoie le document entier sous forme de texte. | Pointeur JSON ou vide | vide |

Des exemples de l'adresse assemblée (montrée en lecture seule dans l'aperçu de la source) :

- `redfish/v1/Systems/1#/PowerState` : l'état d'alimentation du système, sous forme de texte.
- `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 fait un GET sur la ressource, 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 comme `null` JSON, se lisent tous deux
comme aucune valeur : le tag passe en mauvaise qualité et sa politique d'échec de lecture décide
de ce qui est présenté, plutôt que de laisser le mot `null` arriver comme une bonne lecture. Une
réponse qui n'est pas du JSON est analysée directement selon le type déclaré. Un statut 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 le statut 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 {#writes}

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

- Une écriture **exige un pointeur JSON**. Un tag qui porte le 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 le statut 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 décrit sur la page [Connector](connector).

## Types de donnée pris en charge {#supported-data-types}

Boolean, Int32, Int64, Float, Double et String. Choisissez le type qui correspond au champ
JSON : des booléens pour les indicateurs tels que `SecureBootEnable`, des nombres pour les
relevés, du texte pour les états tels que `PowerState` ou `Health`.

## Commandes {#commands}

Un service Redfish publie une action par chose qu'on peut lui demander, 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 au besoin le nom de l'unique
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 sait appeler une méthode peut
la lancer.

La valeur voyage comme corps de la requête. Une valeur qui est déjà du JSON est envoyée telle
quelle; 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 le statut 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 {#discovery}

Le bouton **Découvrir** lit un seul service : posez son adresse dans la carte Portée du
balayage de la page du pilote (`https://bmc-host`, ou l'adresse que le fournisseur documente) et
le balayage parcourt le premier système, le premier gestionnaire et le premier 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 n'existe l'équipement qui les
porterait : un service qui authentifie chaque requête ne répond donc rien et s'ajoute plutôt à
la main. La découverte SSDP propre à Redfish demande de la multidiffusion UDP, que le pilote
en processus ne fait pas : rien n'est donc trouvé par diffusion, et 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](connector-discovery#discovering-a-devices-tags)).

## Accès des équipements {#equipment-access}

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.