# Redfish

> Referencia del controlador Redfish: conexión HTTPS a un BMC, direccionamiento por ruta del recurso más puntero JSON, lecturas, escrituras PATCH y tipos.

El controlador Redfish lee y escribe servicios de gestión **DMTF Redfish**: la API REST que exponen los BMC de servidor (controladores de gestión de la placa base), los chasis y otro hardware de centro de datos para la gestión fuera de banda. Es un controlador en modo cliente corriente (**Ganter Lab se conecta al equipo**) y el transporte es siempre **HTTPS**: los BMC endurecidos no exponen ninguna otra cosa, y el controlador nunca baja por su cuenta a HTTP sin cifrar.

Puntos típicos que se leen así: el estado de alimentación, el estado del arranque seguro, el estado de salud del chasis y del gestor, la versión del firmware, y las temperaturas y las lecturas de ventilador de los recursos térmicos.

## Campos de conexión {#connection-fields}

| Campo | Qué es | Formato | Por defecto |
|---|---|---|---|
| Host o IP | El nombre de host o la dirección IP del servicio Redfish. | Nombre de host o IP | vacío |
| Puerto | El puerto en el que responde el servicio. Los controladores de gestión suelen responder en el 443, y un servicio publicado en otro sitio lo dice aquí. Un campo vacío muestra 443 en gris y se llega al servicio por él, que es también como se lee un dispositivo guardado con 0. | de 1 a 65535 | 443 |
| Nombre de usuario | La cuenta del BMC que se usa para la autenticación **HTTP Basic**. Vacío deja las peticiones anónimas, a lo que un servicio protegido responde con un error de autorización. | Texto libre | vacío |
| Contraseña | La contraseña que acompaña al nombre de usuario. Protegida en reposo por usuario de Windows, así que la base de datos de configuración nunca guarda el valor en claro; una contraseña escrita con otra cuenta de Windows aparece como ilegible y hay que volver a escribirla. | Texto libre | vacío |

Al conectar, el controlador verifica el servicio leyendo la raíz del servicio (`/redfish/v1/`). El certificado TLS del BMC se acepta cuando Windows confía en él, o cuando usted aprobó ese mismo certificado en [Acceso a los equipos](#equipment-access), en la página de este controlador: el certificado autofirmado con el que sale de fábrica un BMC no necesita nada instalado en Windows. Una conexión que falla dice por qué en la página Eventos y en el archivo de registro del día, con el error subyacente detrás, para que una contraseña rechazada y un certificado a la espera de aprobación se distingan.

El intervalo de sondeo es configurable: el valor por defecto del dispositivo (1000 ms) se aplica a todo tag que no declare el suyo.

## Direccionamiento del tag {#tag-addressing}

Un tag Redfish se direcciona con una **ruta del recurso** más un **puntero JSON** opcional dentro del documento que devuelve ese recurso:

| Campo | Qué hace | Valores | Por defecto |
|---|---|---|---|
| Ruta del recurso | La ruta, relativa a la raíz del servicio, del recurso Redfish al que se hace GET, por ejemplo `redfish/v1/Chassis/1/Thermal`. | Texto libre (obligatorio) | vacío |
| Puntero JSON (en blanco = documento completo) | Un puntero RFC 6901 que selecciona un campo del JSON devuelto, por ejemplo `/Temperatures/0/ReadingCelsius`. Los elementos de matriz se direccionan por índice; `~1` escapa una `/` dentro del nombre de un campo y `~0` una `~`. Si falta la `/` inicial, se añade por usted. En blanco devuelve el documento entero como texto. | Puntero JSON o en blanco | en blanco |

Ejemplos de la dirección ya compuesta (mostrada de solo lectura como vista previa del origen en el bus):

- `redfish/v1/Systems/1#/PowerState`, el estado de alimentación del sistema, como texto.
- `redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius`, el primer sensor térmico, como número.
- `redfish/v1/Systems/1/SecureBoot#/SecureBootEnable`, el arranque seguro, como booleano.

En una lectura, el controlador hace GET al recurso, analiza el JSON, sigue el puntero y convierte el resultado al tipo de dato declarado del tag. Un puntero que no nombra nada en el documento, y un campo que el documento lleva como `null` de JSON, se leen los dos como sin valor: el tag pasa a mala calidad y su política de fallo de lectura decide qué se presenta, en lugar de que la palabra `null` llegue como una lectura buena. Una respuesta que no es JSON se analiza directamente según el tipo declarado. Un estado que el servicio devuelve fuera del rango de éxito es el servicio rechazando la lectura: el tag pasa a mala calidad de la misma manera, y su motivo nombra el estado y un trozo breve del documento de error que el servicio envió con él (`HTTP 404 Not Found: …`). Cualquier otra lectura sin valor también dice el motivo: un tag sin ruta de recurso, un puntero que no nombra nada en el documento y un campo guardado como `null` (cada uno nombrando el recurso y el puntero), y una respuesta que no se lee como el tipo declarado. Un servicio que no contesta nada es la conexión del dispositivo fallando: el dispositivo lo informa y se reconecta, y sus tags apuntan a él. La línea roja del tag dice un estado así en el idioma de la estación, con lo que significa en los códigos 401, 403 y 404, y la línea roja del dispositivo dice en cada intento por qué falla su conexión, un puerto que rechaza o un estado como 401; la página Eventos guarda las palabras del propio servicio.

## Escrituras {#writes}

Los tags con un modo de acceso que permite escribir hacen PATCH sobre el campo direccionado: el controlador construye el documento JSON más pequeño que cubre solo la ruta del puntero (para `/Parent/Child`, el cuerpo `{"Parent":{"Child":<value>}}`) y lo envía al recurso. De ahí se siguen dos restricciones:

- Una escritura **exige un puntero JSON**. Un tag de documento completo (puntero en blanco) no se puede escribir: el panel del tag rechaza la combinación mientras se edita, diciendo que falta el campo, y un intento que llegue de todos modos al servicio falla con el motivo en el diario técnico.
- El BMC decide qué se puede escribir; un PATCH que el servicio rechaza se contesta con el estado y un trozo breve del documento de error que el servicio envió con él (`HTTP 400 Bad Request: …`), y quien escribió el valor lee el motivo.

Como en todas partes, el valor que se escribe en la casilla de escritura del tag es el valor de ingeniería, y las etapas de conversión del tag se deshacen antes de que el valor bruto salga al bus, tal como se describe en la página [Connector](connector).

## Tipos de dato admitidos {#supported-data-types}

Boolean, Int32, Int64, Float, Double y String. Elija el tipo que se corresponda con el campo JSON: booleanos para las banderas como `SecureBootEnable`, números para las lecturas, y texto para los estados como `PowerState` o `Health`.

## Comandos {#commands}

Un servicio Redfish publica una acción por cada cosa que se le puede pedir, cada una en su propia ruta bajo el recurso sobre el que actúa. La estación no las adivina, porque solo la documentación del propio hardware dice cuáles existen: se declaran en el dispositivo, en la tarjeta **Comandos** de su página. Cada comando lleva un nombre, la ruta de la acción (`redfish/v1/Systems/1/Actions/ComputerSystem.Reset`) y, si procede, el nombre del único valor que toma (`ResetType`); el verbo Ejecutar de la fila lo envía, y lo que contestó el servicio se informa de vuelta. Un comando pasa a ser además un método sobre el dispositivo en el espacio de direcciones OPC UA propio de esta estación, así que cualquiera que pueda llamar a un método lo puede emitir.

El valor viaja como cuerpo de la petición. Un valor que ya es JSON se envía tal como está escrito; cualquier otra cosa se envía como `{"<el nombre que usted declaró>": "<el valor>"}`, que es la forma que espera la propia acción de reinicio de Redfish.

Una acción que el servicio rechaza se contesta con el estado y un trozo breve del documento de error que el servicio envió con él (`HTTP 400 Bad Request: …`), con las mismas palabras que las de una escritura rechazada, y con eso no se perturba nada más del dispositivo.

## Descubrimiento {#discovery}

El botón **Descubrir** lee un servicio: ponga su dirección en la tarjeta Alcance de la exploración de la página del controlador (`https://bmc-host`, o la dirección que documente el fabricante) y la exploración recorre el primer sistema, el primer gestor y el primer chasis de ese servicio, ofreciendo el dispositivo con esos puntos listos para añadir. La exploración lee el servicio por HTTPS y sin credenciales, porque corre antes de que exista el dispositivo que las guardaría, así que un servicio que autentica cada petición no responde nada y se añade a mano. El descubrimiento SSDP propio de Redfish necesita multidifusión UDP, que el controlador en proceso no hace, así que difundiendo no se encuentra nada: la exploración lee la dirección que se le dé.

Un dispositivo Redfish que ya tiene encuentra sus puntos desde su propia página: **Descubrir tags**, en la cabecera de su tarjeta de tags, recorre los mismos recursos con la sesión iniciada con el usuario y la contraseña del dispositivo, así que también responde un servicio que autentica cada petición, y ofrece solo los puntos para los que el dispositivo todavía no tiene tag (vea [Descubrir los tags de un dispositivo](connector-discovery#discovering-a-devices-tags)).

## Acceso a los equipos {#equipment-access}

Un BMC suele responder con un certificado propio, autofirmado o emitido por su fabricante, que ninguna raíz instalada en Windows avala. No hace falta instalar esa raíz en este ordenador. La primera conexión se rechaza, el dispositivo dice **Esperando la aprobación del certificado** en el árbol y en su página, cuyo botón **Revisar el certificado** abre esta tarjeta sobre el certificado, y el certificado espera en **Acceso a los equipos**, al final de la página del controlador Redfish, la misma tarjeta que lleva la página del controlador OPC UA, hasta que usted decida:

| Grupo | Qué muestra | Qué puede hacer |
|---|---|---|
| A la espera de aprobación | Cada certificado rechazado, con el nombre que declara: su huella digital SHA-256, la dirección en la que se encontró, cuándo lo intentó por última vez y cuántas veces, y sus detalles (sujeto, emisor, nombres de dominio, fechas de validez). El que abrió **Revisar el certificado** de un dispositivo aparece marcado como Seleccionado para revisión. | **Aprobar** acepta el certificado desde el siguiente intento de conexión. **Bloquear** lo sigue rechazando sin volver a listarlo aquí. **Descartar todos los certificados pendientes** vacía la lista sin aprobar ni bloquear nada. |
| Equipos aprobados | Los certificados que usted aprobó o importó, con quién decidió y cuándo, y la dirección en la que se encontró cada uno por última vez. | **Retirar la aprobación** cierra la conexión y devuelve el certificado a la lista. **Importar certificado** aprueba un archivo de certificado público que ya tenga (.der, .cer, .crt o .pem) antes de la primera conexión. |
| Equipos bloqueados | Los certificados que usted bloqueó. Un certificado bloqueado se rechaza aunque Windows confíe en él. | **Desbloquear** devuelve el certificado a la lista, sin aprobarlo. |

Compruebe la huella digital con quien administra el servidor antes de aprobar el certificado. Una aprobación acepta ese certificado y ningún otro, y solo dentro de sus fechas de validez; sustituye a la raíz que falta en Windows y al nombre que lleva el certificado, así que un BMC al que se llama por su dirección IP se conecta aunque su certificado lleve otro nombre, y nada más del certificado se relaja. Cuando el equipo responde en una dirección cuyo certificado usted aprobó con otro distinto (un certificado renovado, un controlador sustituido), la lectura se detiene, el nuevo espera aquí y la estación avisa "Certificado cambiado: `<nombre>`" con un botón **Revisar**. Un certificado en el que Windows ya confía se acepta como antes y nunca aparece aquí; nada se aprueba automáticamente.

El propio fallo del controlador dice el motivo en lugar de un error de TLS sin nombre: "El certificado de este equipo (los primeros 16 caracteres de la huella digital) espera su aprobación en Acceso a los equipos, en la página del controlador Redfish. La lectura empieza en cuanto lo apruebe." Uno bloqueado dice "…está bloqueado en esta estación. Revíselo en Acceso a los equipos, en la página del controlador Redfish." Un certificado fuera de sus fechas de validez, revocado o con la firma rota se rechaza con ese motivo y nunca se lista, porque ninguna aprobación lo vuelve válido. Una exploración del BMC, desde la tarjeta Alcance de la exploración o desde **Descubrir tags** en la página del dispositivo, se encuentra con las mismas decisiones: un certificado desconocido termina la exploración con esa frase y espera aquí.

Las decisiones se guardan en la carpeta de datos de la estación, en `ua\pki\redfish`, y sobreviven a un reinicio. Los verbos solo se dibujan para un rol que puede configurar el Connector, y solo actúan en la ventana de la propia estación: un navegador en otro dispositivo lee la tarjeta sin cambiarla, y ninguna herramienta de agente aprueba un certificado (`connector_browse` indica el dispositivo en espera con `awaitingCertificate`). La lista guarda hasta 100 certificados a la espera de aprobación; cuando está llena, uno nuevo se sigue rechazando pero no se lista, y la tarjeta lo dice.