Redfish

Redfish のドライバーの手引き。BMC への HTTPS の接続、リソースのパスと JSON ポインターによるアドレス指定、読み取り、PATCH の書き込み、そして型。

Redfish のドライバーは、DMTF Redfish の管理サービスを読み書きします。サーバーの BMC（ベースボード管理コントローラー）、シャーシ、そして帯域外管理のためのデータセンターの機材が公開している REST の API です。こちらから接続するふつうの方式のドライバーで、Ganter Lab のほうから現場設備につなぎます。通信は必ず HTTPS です。堅牢にした BMC はそれ以外を公開しませんし、ドライバーが自分の判断でふつうの HTTP に落とすことは決してありません。

この方法でよく読む値は、電源の状態、セキュアブートの状態、シャーシとマネージャーの健全性、ファームウェアの版、そして熱のリソースが持つ温度とファンの読み取りです。

接続の項目

接続のとき、ドライバーはサービスのルート（/redfish/v1/）を読んで、そのサービスを確かめます。BMC の TLS の証明書は、Windows が信頼しているとき、またはこのドライバーのページの現場設備へのアクセスでその証明書そのものを承認したときに受け入れられます。BMC が出荷時から持っている自己署名の証明書のために、Windows に何かをインストールする必要はありません。接続が失敗したときは、イベントのページとその日のログファイルが理由を述べ、その奥にある元のエラーも添えるので、拒否されたパスワードと承認を待っている証明書は区別できます。

読み出し周期は設定できます。機器の既定（1000 ms）は、自分の周期を書いていないすべてのタグに効きます。

タグのアドレス指定

Redfish のタグは、リソースのパスと、そのリソースが返す文書への任意の JSON ポインターでアドレスを取ります。

組み立てられたアドレスの例です（「取得元」の予告として読み取り専用で見えます）。

• redfish/v1/Systems/1#/PowerState：システムの電源の状態を文字列として。
• redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius：最初の温度センサーを数値として。
• redfish/v1/Systems/1/SecureBoot#/SecureBootEnable：セキュアブートをブール値として。

読み取りのとき、ドライバーはそのリソースを GET し、JSON を解釈し、ポインターをたどり、その結果をタグに宣言したデータ型に変換します。文書の中の何も指さないポインターと、文書が JSON の null として持っている項目は、どちらも値なしとして読まれます。null という語が良好な読み取りとして届くのではなく、タグが品質の悪い状態になり、読み取りに失敗したときの方針が何を見せるかを決めます。JSON ではない応答は、宣言した型としてそのまま解釈します。サービスが成功の範囲の外の状態を返したのは、サービスがその読み取りを拒否したということです。タグは同じように品質の悪い状態になり、その理由は状態と、サービスが一緒に送ったエラー文書の短い抜粋（HTTP 404 Not Found: …）を名指しします。値のないほかの読み取りも理由を伝えます。リソースのパスのないタグ、文書の中の何も指さないポインター、null として持たれている項目（どれもリソースとポインターを名指しします）、そして宣言した型として読めない応答です。まったく答えないサービスは、機器の接続の失敗です。機器がそれを伝えて接続し直し、そのタグは機器を指します。タグの赤い行はこうした状態をステーションの言語で伝え、401、403、404 にはその意味が付きます。機器の赤い行は、どの試行でも接続が失敗する理由（拒否するポートや 401 などの状態）を伝えます。サービス自身の言葉はイベントのページに残ります。

書き込み

書き込めるアクセスのタグは、指したその項目を PATCH します。ドライバーはポインターの道すじだけを覆う最小の JSON の文書を組み立て（/Parent/Child なら本文は {"Parent":{"Child":<value>}}）、それをリソースへ送ります。ここから制約が 2 つ出てきます。

• 書き込みには JSON ポインターが要ります。文書の全体を指すタグ（ポインターが空）は書けません。編集している最中にタグのパネルがその組み合わせを拒否し、項目が足りないと伝えます。それでもサービスまで届いた試みは、理由を診断ログに残して失敗します。
• 何を書けるかは BMC が決めます。サービスが拒んだ PATCH には、状態と、サービスが一緒に送ったエラー文書の短い抜粋（HTTP 400 Bad Request: …）が答えとして返り、値を書いた側はその理由を読めます。

ほかのすべてと同じで、タグの書き込みの入力欄に入力する値は工業値です。生値がバスに出る前に、そのタグの変換の段階が逆向きに適用されます。Connector のページに書いてあるとおりです。

対応するデータ型

Boolean、Int32、Int64、Float、Double、String です。JSON の項目に合う型を選んでください。SecureBootEnable のようなフラグにはブール値、読み取り値には数値、PowerState や Health のような状態には文字列です。

コマンド

Redfish のサービスは、頼めることの 1 つずつにアクションを公開していて、それぞれが、そのアクションが働きかけるリソースの下の自分のパスにあります。ステーションはそれを当てにいきません。どれがあるのかは、その機材自身の文書だけが述べるからです。機器のページのコマンドのカードで宣言してください。コマンドはそれぞれ、名前、アクションのパス（redfish/v1/Systems/1/Actions/ComputerSystem.Reset）、そして受け取る 1 つの値の名前（ResetType、任意）を持ちます。行の実行の操作がそれを送り、サービスが何と答えたかを伝えます。コマンドは、このステーション自身の OPC UA のアドレス空間で機器のメソッドにもなるので、メソッドを呼べるものなら何からでも出せます。

値は要求の本文として運ばれます。すでに JSON である値は書いたそのまま送られ、それ以外は {"<宣言した名前>": "<値>"} の形で送られます。これは Redfish 自身のリセットのアクションが期待する形です。

サービスが拒んだアクションには、状態と、サービスが一緒に送ったエラー文書の短い抜粋（HTTP 400 Bad Request: …）が答えとして返ります。拒否された書き込みと同じ言葉で、それによって機器のほかのものが乱されることはありません。

機器検出

機器検出のボタンは、1 つのサービスを読みます。ドライバーのページの「スキャンの範囲」のカードにそのアドレス（https://bmc-host、あるいはメーカーが文書に書いているアドレス）を入れてください。スキャンはそのサービスの最初のシステム、マネージャー、シャーシを巡り、それらのポイントを備えた機器を、そのまま追加できる形で差し出します。スキャンは HTTPS で、資格情報なしにサービスを読みます。資格情報を持つはずの機器がまだ存在しないうちに走るからです。ですから、あらゆる要求に認証を求めるサービスは何も答えないので、そちらは手で追加してください。Redfish 自身の SSDP による探索は UDP のマルチキャストを必要とし、プロセス内のこのドライバーはそれを行わないので、同報で見つかるものはありません。スキャンは、与えたアドレスを読みます。

すでにある Redfish の機器は、自分のページからポイントを見つけます。「タグ」のカードの見出しにあるタグ検出は、機器のユーザー名とパスワードでサインインして同じリソースを巡るので、あらゆる要求に認証を求めるサービスも答え、機器にまだタグがないポイントだけを出します（機器のタグを検出するを参照）。

現場設備へのアクセス

BMC はたいてい、自己署名の証明書やメーカーが発行した証明書など、Windows にインストールされたどのルートも保証しない自前の証明書で答えます。そのルートをこのコンピューターにインストールする必要はありません。最初の接続は拒否され、機器はツリーとそのページで証明書の承認を待っていますと表示し、そのページの証明書を確認するのボタンがこのカードをその証明書の位置で開きます。証明書は、Redfish のドライバーのページの最後にある現場設備へのアクセスで、判断を待ちます。OPC UA のドライバーのページにあるのと同じカードです。

承認する前に、サーバーを管理している担当者とフィンガープリントを照合してください。承認で受け入れるのはその証明書だけで、しかも有効期間の内側だけです。承認は、Windows に足りないルートと、証明書に書かれた名前の代わりになります。そのため、IP アドレスで接続する BMC も、証明書に別の名前が書かれていてもつながります。証明書のそのほかの点は何もゆるめません。承認した証明書のアドレスで現場設備が別の証明書を出すと（証明書の更新、コントローラーの交換など）、読み取りは止まり、新しい証明書がここで待ち、ステーションが確認するのボタン付きで「証明書が変わりました：<名前>」と知らせます。Windows がすでに信頼している証明書はこれまでどおり受け入れられ、ここには出ません。何かが自動で承認されることはありません。

ドライバー自身の失敗は、名前のない TLS のエラーではなく理由を述べます：「この現場設備の証明書（フィンガープリントの先頭 16 文字）は、Redfish ドライバーのページの「現場設備へのアクセス」であなたの承認を待っています。承認すると読み取りが始まります。」遮断した証明書なら「…はこのステーションで遮断されています。Redfish ドライバーのページの「現場設備へのアクセス」で確認してください。」となります。有効期間の外にある証明書、失効した証明書、署名の壊れた証明書は、その理由で拒否され、一覧には並びません。承認しても健全にはならないからです。「スキャンの範囲」のカードからの BMC のスキャンも、機器のページのタグ検出からのスキャンも、同じ判断にしたがいます。知らない証明書はその文でスキャンを終わらせ、ここで待ちます。

判断はステーションのデータフォルダーの ua\pki\redfish に保存され、再起動しても残ります。操作が描かれるのは Connector を構成できるロールだけで、操作が効くのはステーション自身のウィンドウの中だけです。別の機器のブラウザーはカードを読むだけで変えられず、エージェントのツールが証明書を承認することもありません（connector_browse は待っている機器を awaitingCertificate で示します）。一覧に並ぶ承認待ちの証明書は 100 件までです。いっぱいになると、新しい証明書は引き続き拒否されますが一覧には並ばず、カードがそのことを伝えます。