# Redfish

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

El driver Redfish lee y escribe servicios de administración **Redfish de la DMTF**: la API
REST que exponen los BMC de servidor (baseboard management controllers), los chasis y otro
hardware de centro de datos para la administración fuera de banda. Este es un driver
ordinario en modo cliente (**Ganter Lab se conecta al equipo**) y el transporte siempre es
**HTTPS**: los BMC endurecidos no exponen nada más, y el driver nunca baja por su cuenta a
HTTP sin cifrar.

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

## Los campos de conexión {#connection-fields}

| Campo | Qué es | Formato | Valor inicial |
|---|---|---|---|
| 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 contesta el servicio. Los controladores de administración suelen contestar en el 443, y un servicio publicado en otro lado 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, y un servicio protegido las contestará con un error de autorización. | Texto libre | vacío |
| Contraseña | La contraseña que va con el 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 capturada en otra cuenta de Windows se muestra como ilegible y hay que volver a ingresarla. | Texto libre | vacía |

Al conectarse, el driver 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 driver: 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 de fondo detrás, así que una contraseña rechazada y un
certificado a la espera de aprobación se distinguen.

El intervalo de sondeo es configurable: el valor predeterminado del dispositivo (1000 ms)
vale para todo tag que no declare el suyo.

## El direccionamiento del tag {#tag-addressing}

Un tag de 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 | Valor inicial |
|---|---|---|---|
| Ruta del recurso | La ruta del recurso Redfish que se hace GET, relativa a la raíz del servicio, por ejemplo `redfish/v1/Chassis/1/Thermal`. | Texto libre (obligatorio) | vacía |
| Puntero JSON (en blanco = documento completo) | Un puntero RFC 6901 que elige un campo del JSON devuelto, por ejemplo `/Temperatures/0/ReadingCelsius`. Los elementos de un arreglo se direccionan por índice; `~1` escapa una `/` dentro de un nombre de campo y `~0` una `~`. Si falta la `/` inicial, se agrega por usted. En blanco devuelve el documento completo como texto. | Puntero JSON o en blanco | en blanco |

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

- `redfish/v1/Systems/1#/PowerState`, el estado de energía 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 driver hace GET del recurso, interpreta el JSON, sigue el puntero y
convierte el resultado al tipo de dato declarado del tag. Un puntero que no nombra nada
dentro del 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 lectura fallida decide qué se
presenta, en lugar de que la palabra `null` llegue como una lectura buena. Una respuesta que
no es JSON se interpreta directamente como 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 reporta 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.

## Las escrituras {#writes}

Los tags con un modo de acceso escribible hacen PATCH del campo direccionado: el driver arma
el documento JSON más pequeño que cubra solo la ruta del puntero (para `/Parent/Child`, el
cuerpo `{"Parent":{"Child":<valor>}}`) y lo envía al recurso. De ahí salen dos
restricciones:

- Una escritura **necesita un puntero JSON**. Un tag de documento completo (con el puntero en
  blanco) no se puede escribir: el panel del tag rechaza la combinación mientras usted edita,
  diciendo que falta el campo, y un intento que llegue al servicio de todos modos falla con el
  motivo en el diario técnico.
- El BMC decide qué es escribible; 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 todos lados, el valor que usted escribe en la caja 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, como se describe en la página del [Connector](connector).

## Los tipos de dato admitidos {#supported-data-types}

Boolean, Int32, Int64, Float, Double y String. Elija el tipo que corresponda al campo JSON:
booleanos para banderas como `SecureBootEnable`, números para las lecturas, textos para
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 hardware dice cuáles existen: usted las declara 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, opcionalmente, el nombre del único
valor que toma (`ResetType`); el verbo Ejecutar de la fila lo envía, y lo que contestó el
servicio se reporta de vuelta. Un comando se convierte además en un método del dispositivo
dentro del espacio de direcciones OPC UA propio de esta estación, así que cualquier cosa que
pueda llamar a un método puede lanzarlo.

El valor viaja como el cuerpo de la petición. Un valor que ya es JSON se envía tal como se escribió;
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 nada más del dispositivo se perturba por eso.

## El descubrimiento {#discovery}

El botón **Descubrir** lee un solo servicio: ponga su dirección en la tarjeta Alcance del
escaneo de la página del driver (`https://bmc-host`, o la dirección que documente el
fabricante) y el escaneo recorre el primer sistema, el primer manager y el primer chasis de
ese servicio, ofreciendo el dispositivo con esos puntos listos para agregarse. El escaneo lee
el servicio por HTTPS y sin credenciales, porque corre antes de que exista el dispositivo que
las tendría, así que un servicio que autentica cada petición no contesta nada y se agrega a
mano en su lugar. El descubrimiento propio de Redfish por SSDP necesita multidifusión UDP, que
el driver dentro del proceso no hace, así que nada se encuentra por difusión: el escaneo lee
la dirección que usted le dé.

Un dispositivo Redfish que ya tiene encuentra sus puntos desde su propia página: **Descubrir tags**, en el encabezado 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 contesta 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 driver Redfish, la misma tarjeta que lleva la página del driver 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. |

Verifique 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 driver 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 driver 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 driver 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. Un escaneo del BMC, desde la tarjeta Alcance del escaneo o desde **Descubrir tags** en la página del dispositivo, se encuentra con las mismas decisiones: un certificado desconocido termina el escaneo 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.