# Redfish > Referenz zum Treiber Redfish: HTTPS-Verbindung zu einem BMC, Adressierung über Ressourcenpfad und JSON-Zeiger, Lesevorgänge, Schreibvorgänge per PATCH und Typen. Der Treiber Redfish liest und schreibt Verwaltungsdienste nach **DMTF Redfish**: die REST-API, die BMCs von Servern (Baseboard Management Controller), Gehäuse und andere Hardware im Rechenzentrum für die Verwaltung außerhalb des Betriebssystems anbieten. Das ist ein gewöhnlicher Treiber im Client-Betrieb, **Ganter Lab verbindet sich mit der Anlage**, und der Übertragungsweg ist immer **HTTPS**: Gehärtete BMCs bieten nichts anderes an, und der Treiber fällt von sich aus nie auf einfaches HTTP zurück. Typische Punkte, die so gelesen werden: Betriebszustand der Stromversorgung, Zustand von Secure Boot, Zustand von Gehäuse und Verwaltungscontroller, Firmwareversion, Temperaturen und Lüfterwerte aus den Ressourcen zur Wärme. ## Verbindungsfelder {#connection-fields} | Feld | Was es ist | Format | Standard | |---|---|---|---| | Host | Hostname oder IP-Adresse des Redfish-Dienstes. | Hostname oder IP | leer | | Port | Der Port, auf dem der Dienst antwortet. Verwaltungscontroller antworten üblicherweise auf 443, und ein anderswo veröffentlichter Dienst sagt es hier. Ein leeres Feld zeigt 443 grau, und der Dienst wird über diesen Port erreicht; ein mit 0 gespeichertes Gerät liest sich genauso. | 1 bis 65535 | 443 | | Benutzername | Das Konto am BMC für die Anmeldung über **HTTP Basic**. Leer lässt die Anfragen anonym, was ein geschützter Dienst mit einem Fehler zur Berechtigung beantwortet. | Freitext | leer | | Passwort | Das Passwort zum Benutzernamen. Im Ruhezustand je Windows-Benutzer geschützt, die Konfigurationsdatenbank hält den Klartext also nie; ein unter einem anderen Windows-Konto eingegebenes Passwort erscheint als unlesbar und muss neu eingegeben werden. | Freitext | leer | Beim Verbinden prüft der Treiber den Dienst, indem er die Dienstwurzel (`/redfish/v1/`) liest. Das TLS-Zertifikat des BMC wird angenommen, wenn Windows ihm vertraut oder wenn Sie genau dieses Zertifikat unter [Anlagenzugriff](#equipment-access) auf der Seite dieses Treibers freigegeben haben: Das selbstsignierte Zertifikat, mit dem ein BMC ausgeliefert wird, braucht in Windows nichts installiert. Eine fehlgeschlagene Verbindung sagt auf der Seite Ereignisse und in der Protokolldatei des Tages, warum, mit dem zugrunde liegenden Fehler dahinter, ein abgelehntes Passwort und ein Zertifikat, das auf Freigabe wartet, sind also auseinanderzuhalten. Das Abfrageintervall ist einstellbar: Der Standard des Geräts (1000 ms) gilt für jedes Tag, das keinen eigenen nennt. ## Adressierung der Tags {#tag-addressing} Ein Redfish-Tag wird über einen **Ressourcenpfad** und einen wahlweisen **JSON-Zeiger** in das Dokument adressiert, das diese Ressource zurückgibt: | Feld | Wirkung | Werte | Standard | |---|---|---|---| | Ressourcenpfad | Der Pfad der Redfish-Ressource relativ zur Dienstwurzel, die per GET geholt wird, z. B. `redfish/v1/Chassis/1/Thermal`. | Freitext (Pflichtfeld) | leer | | JSON-Zeiger (leer = ganzes Dokument) | Ein Zeiger nach RFC 6901, der ein Feld des zurückgegebenen JSON auswählt, z. B. `/Temperatures/0/ReadingCelsius`. Elemente eines Feldes werden über den Index adressiert; `~1` schreibt ein `/` innerhalb eines Feldnamens und `~0` ein `~`. Ein fehlendes führendes `/` wird ergänzt. Leer gibt das ganze Dokument als Text zurück. | JSON-Zeiger oder leer | leer | Beispiele der zusammengesetzten Adresse (als Vorschau der Quelle auf dem Bus gezeigt, die nur gelesen wird): - `redfish/v1/Systems/1#/PowerState`: der Betriebszustand des Systems als Zeichenkette. - `redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius`: der erste Temperaturfühler, als Zahl. - `redfish/v1/Systems/1/SecureBoot#/SecureBootEnable`: Secure Boot, als Wahrheitswert. Bei einem Lesevorgang holt der Treiber die Ressource per GET, liest das JSON, folgt dem Zeiger und wandelt das Ergebnis in den erklärten Datentyp des Tags. Ein Zeiger, der nichts im Dokument benennt, und ein Feld, das das Dokument als JSON-`null` trägt, lesen beide als kein Wert: Das Tag geht auf schlechte Qualität, und seine Regel für Lesefehler entscheidet, was dargestellt wird, statt dass das Wort `null` als guter Messwert ankommt. Eine Antwort, die kein JSON ist, wird unmittelbar als der erklärte Typ gelesen. Ein Status, den der Dienst außerhalb des Erfolgsbereichs zurückgibt, ist der Dienst, der den Lesevorgang ablehnt: Das Tag geht ebenso auf schlechte Qualität, und sein Grund nennt den Status und einen kurzen Auszug aus dem Fehlerdokument, das der Dienst dazu gesendet hat (`HTTP 404 Not Found: …`). Jeder andere Lesevorgang ohne Wert sagt ebenfalls, warum: ein Tag ohne Ressourcenpfad, ein Zeiger, der im Dokument nichts benennt, und ein Feld, das als `null` geführt wird (jeweils mit Ressource und Zeiger), und eine Antwort, die sich nicht als der erklärte Typ lesen lässt. Ein Dienst, der gar nicht antwortet, ist die Verbindung des Geräts, die ausfällt: Das Gerät meldet es und verbindet sich neu, und seine Tags verweisen auf das Gerät. Die rote Zeile des Tags sagt einen solchen Status in der Sprache der Station, bei 401, 403 und 404 mit seiner Bedeutung, und die rote Zeile des Geräts sagt bei jedem Versuch, warum seine Verbindung fehlschlägt, ein Port, der ablehnt, oder ein Status wie 401; die Seite Ereignisse behält die eigenen Worte des Dienstes. ## Schreiben {#writes} Tags mit einer schreibbaren Zugriffsart schreiben das adressierte Feld per PATCH: Der Treiber baut das kleinste JSON-Dokument, das nur den Pfad des Zeigers abdeckt (bei `/Parent/Child` den Rumpf `{"Parent":{"Child":}}`), und sendet es an die Ressource. Daraus folgen zwei Einschränkungen: - Ein Schreibvorgang **verlangt einen JSON-Zeiger**. Ein Tag auf das ganze Dokument (leerer Zeiger) lässt sich nicht schreiben: Der Bereich des Tags lehnt die Kombination schon beim Bearbeiten ab und sagt, dass das Feld fehlt, und ein Versuch, der den Dienst dennoch erreicht, schlägt mit dem Grund im Journal fehl. - Der BMC entscheidet, was schreibbar ist; ein PATCH, den der Dienst ablehnt, wird mit dem Status und einem kurzen Auszug aus dem Fehlerdokument beantwortet, das der Dienst dazu gesendet hat (`HTTP 400 Bad Request: …`), und wer den Wert geschrieben hat, liest den Grund. Wie überall sonst ist der Wert, den Sie in das Schreibfeld des Tags tippen, der technische Wert, und die Umrechnungsstufen des Tags werden rückwärts durchlaufen, bevor der Rohwert auf den Bus geht, wie auf der Seite [Connector](connector) beschrieben. ## Unterstützte Datentypen {#supported-data-types} Boolean, Int32, Int64, Float, Double und String. Wählen Sie den Typ, der zum JSON-Feld passt: Wahrheitswerte für Kennzeichen wie `SecureBootEnable`, Zahlen für Messwerte, Zeichenketten für Zustände wie `PowerState` oder `Health`. ## Befehle {#commands} Ein Redfish-Dienst veröffentlicht je eine Aktion für alles, worum er gebeten werden kann, jede unter ihrem eigenen Pfad unter der Ressource, auf die sie wirkt. Die Station rät sie nicht, weil nur die Dokumentation der Hardware sagt, welche es gibt: Sie erklären sie am Gerät, auf der Karte **Befehle** seiner Seite. Jeder Befehl trägt einen Namen, den Aktionspfad (`redfish/v1/Systems/1/Actions/ComputerSystem.Reset`) und wahlweise den Namen des einen Werts, den er nimmt (`ResetType`); der Befehl Ausführen in der Zeile sendet ihn, und was der Dienst geantwortet hat, wird zurückgemeldet. Ein Befehl wird außerdem zu einer Methode am Gerät im eigenen OPC UA-Adressraum dieser Station, alles, was eine Methode aufrufen kann, kann ihn also erteilen. Der Wert reist als Rumpf der Anfrage. Ein Wert, der bereits JSON ist, wird so gesendet, wie er geschrieben steht; alles andere wird als `{"": ""}` gesendet, was die Form ist, die die Reset-Aktion von Redfish selbst erwartet. Eine Aktion, die der Dienst ablehnt, wird mit dem Status und einem kurzen Auszug aus dem Fehlerdokument beantwortet, das der Dienst dazu gesendet hat (`HTTP 400 Bad Request: …`), in denselben Worten wie bei einem abgelehnten Schreibvorgang, und sonst wird nichts am Gerät gestört. ## Gerätesuche {#discovery} Die Schaltfläche **Geräte suchen** liest einen Dienst: Tragen Sie seine Adresse auf der Karte Suchbereich auf der Seite des Treibers ein (`https://bmc-host` oder die Adresse, die der Hersteller dokumentiert), und der Suchlauf geht das erste System, den ersten Verwaltungscontroller und das erste Gehäuse dieses Dienstes durch und bietet das Gerät mit diesen Punkten fertig zum Hinzufügen an. Der Suchlauf liest den Dienst über HTTPS und ohne Anmeldedaten, weil er läuft, bevor es das Gerät gibt, das sie hielte, ein Dienst, der jede Anfrage anmeldepflichtig macht, antwortet also nichts und wird stattdessen von Hand angelegt. Die eigene Suche von Redfish über SSDP braucht UDP-Multicast, das der Treiber im Prozess nicht macht, über Rundruf wird also nichts gefunden: Der Suchlauf liest die Adresse, die Sie ihm geben. Ein Redfish-Gerät, das Sie schon haben, findet seine Punkte von seiner eigenen Seite aus: **Tags suchen** im Kopf seiner Karte der Tags durchläuft dieselben Ressourcen, angemeldet mit dem Benutzernamen und dem Passwort des Geräts, sodass auch ein Dienst antwortet, der jede Anfrage anmeldepflichtig macht, und bietet nur die Punkte an, für die das Gerät noch kein Tag hat (siehe [Die Tags eines Geräts suchen](connector-discovery#discovering-a-devices-tags)). ## Anlagenzugriff {#equipment-access} Ein BMC antwortet meist mit einem eigenen Zertifikat, selbstsigniert oder vom Hersteller ausgestellt, für das keine in Windows installierte Wurzel bürgt. Diese Wurzel muss auf diesem Rechner nicht installiert werden. Die erste Verbindung wird abgewiesen, das Gerät zeigt im Baum und auf seiner Seite **Wartet auf Freigabe des Zertifikats**, deren Schaltfläche **Zertifikat prüfen** diese Karte auf dem Zertifikat öffnet, und das Zertifikat wartet unter **Anlagenzugriff** am Ende der Seite des Redfish-Treibers, derselben Karte wie auf der Seite des OPC UA-Treibers, bis Sie entscheiden: | Gruppe | Was sie zeigt | Was Sie tun können | |---|---|---| | Wartet auf Freigabe | Jedes abgewiesene Zertifikat unter dem Namen, den es behauptet: sein SHA-256-Fingerabdruck, die Adresse, unter der es angetroffen wurde, wann es zuletzt versucht wurde und wie oft, und seine Details (Antragsteller, Aussteller, Domänennamen, Gültigkeitsdaten). Das Zertifikat, das **Zertifikat prüfen** eines Geräts geöffnet hat, ist als Zur Prüfung ausgewählt markiert. | **Freigeben** nimmt das Zertifikat ab dem nächsten Verbindungsversuch an. **Sperren** weist es weiter ab, ohne es hier erneut aufzuführen. **Alle ausstehenden Zertifikate verwerfen** leert die Liste, ohne etwas freizugeben oder zu sperren. | | Freigegebene Anlagen | Die Zertifikate, die Sie freigegeben oder importiert haben, mit der Angabe, wer wann entschieden hat, und der Adresse, unter der jedes zuletzt angetroffen wurde. | **Freigabe zurücknehmen** schließt die Verbindung und bringt das Zertifikat in die Liste zurück. **Zertifikat importieren** gibt eine öffentliche Zertifikatsdatei, die Sie bereits haben (.der, .cer, .crt oder .pem), vor der ersten Verbindung frei. | | Gesperrte Anlagen | Die Zertifikate, die Sie gesperrt haben. Ein gesperrtes Zertifikat wird abgewiesen, auch wenn Windows ihm vertraut. | **Entsperren** bringt das Zertifikat in die Liste zurück, ohne es freizugeben. | Prüfen Sie den Fingerabdruck mit derjenigen Person, die den Server betreut, bevor Sie das Zertifikat freigeben. Eine Freigabe nimmt genau dieses Zertifikat an und kein anderes, und nur innerhalb seiner Gültigkeitsdaten; sie steht für die Wurzel ein, die Windows fehlt, und für den Namen, den das Zertifikat trägt, sodass sich ein BMC, der über seine IP-Adresse angewählt wird, verbindet, obwohl sein Zertifikat einen anderen Namen trägt, und sonst wird am Zertifikat nichts gelockert. Antwortet die Anlage an einer Adresse, deren Zertifikat Sie freigegeben haben, mit einem anderen (ein erneuertes Zertifikat, ein ausgetauschter Controller), hört das Lesen auf, das neue wartet hier, und die Station meldet "Zertifikat geändert: ``" mit einer Schaltfläche **Prüfen**. Ein Zertifikat, dem Windows bereits vertraut, wird wie bisher angenommen und erscheint hier nie; nichts wird automatisch freigegeben. Der eigene Fehlschlag des Treibers nennt den Grund statt eines namenlosen TLS-Fehlers: "Das Zertifikat dieser Anlage (die ersten 16 Zeichen des Fingerabdrucks) wartet unter Anlagenzugriff auf der Seite des Redfish-Treibers auf Ihre Freigabe. Das Lesen beginnt, sobald Sie es freigeben." Ein gesperrtes liest "…ist an dieser Station gesperrt. Prüfen Sie es unter Anlagenzugriff auf der Seite des Redfish-Treibers." Ein Zertifikat außerhalb seiner Gültigkeitsdaten, widerrufen oder mit gebrochener Signatur wird mit diesem Grund abgewiesen und nie aufgeführt, weil keine Freigabe es einwandfrei macht. Eine Gerätesuche auf dem BMC, über die Karte Suchbereich oder über **Tags suchen** auf der Seite des Geräts, trifft auf dieselben Entscheidungen: Ein unbekanntes Zertifikat beendet die Suche mit diesem Satz und wartet hier. Die Entscheidungen liegen im Datenordner der Station unter `ua\pki\redfish` und überstehen einen Neustart. Die Befehle werden nur einer Rolle gezeichnet, die den Connector konfigurieren darf, und sie wirken nur im eigenen Fenster der Station: Ein Browser auf einem anderen Gerät liest die Karte, ohne sie zu ändern, und kein Werkzeug eines Agenten gibt ein Zertifikat frei (`connector_browse` meldet das wartende Gerät mit `awaitingCertificate`). Die Liste hält bis zu 100 Zertifikate, die auf Freigabe warten; ist sie voll, wird ein neues weiter abgewiesen, aber nicht aufgeführt, und die Karte sagt das.