# Redfish

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

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

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

## 接続の項目 {#connection-fields}

| 項目 | 意味 | 形式 | 既定 |
|---|---|---|---|
| ホスト | Redfish のサービスのホスト名か IP アドレス。 | ホスト名か IP | 空 |
| ポート | サービスが答えるポート。管理コントローラーはたいてい 443 で答えますし、別の場所で公開しているサービスはここでそう伝えます。欄が空のときは 443 が灰色で表示され、サービスにはそのポートで届きます。0 で保存された機器も同じように表示されます。 | 1 から 65535 | 443 |
| ユーザー名 | **HTTP Basic** の認証に使う BMC のアカウント。空のままなら要求は匿名になり、保護されたサービスは認可のエラーで答えます。 | 自由記述 | 空 |
| パスワード | ユーザー名と組になるパスワード。Windows のユーザーごとに保存時に保護されるので、構成のデータベースが平文を持つことはありません。別の Windows アカウントで入力したパスワードは読めないものとして表示されるので、入力し直してください。 | 自由記述 | 空 |

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

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

## タグのアドレス指定 {#tag-addressing}

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

| 項目 | 意味 | 受け付ける値 | 既定 |
|---|---|---|---|
| リソースのパス | GET する Redfish のリソースの、サービスのルートから見たパス。たとえば `redfish/v1/Chassis/1/Thermal`。 | 自由記述（必須） | 空 |
| JSON ポインター（空なら文書の全体） | 返ってきた JSON の 1 つの項目を選ぶ RFC 6901 のポインター。たとえば `/Temperatures/0/ReadingCelsius`。配列の要素は添字で指します。項目名の中の `/` は `~1`、`~` は `~0` で書きます。先頭の `/` が抜けていれば補います。空なら文書の全体を文字列として返します。 | 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 などの状態）を伝えます。サービス自身の言葉はイベントのページに残ります。

## 書き込み {#writes}

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

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

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

## 対応するデータ型 {#supported-data-types}

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

## コマンド {#commands}

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

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

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

## 機器検出 {#discovery}

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

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

## 現場設備へのアクセス {#equipment-access}

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

| グループ | 並ぶもの | できること |
|---|---|---|
| 承認待ち | 拒否された証明書の 1 つ 1 つが、証明書が名乗る名前の下に並びます。SHA-256 のフィンガープリント、それに出会ったアドレス、最後に試した日時と回数、詳細（主体、発行者、ドメイン名、有効期間）が出ます。機器の**証明書を確認する**で開いた証明書には「確認のために選択中」の印が付きます。 | **承認する**と、次の接続の試みからその証明書を受け入れます。**遮断する**と、ここにふたたび並べることなく拒否し続けます。**承認待ちの証明書をすべて破棄**は、何も承認も遮断もせずに一覧を空にします。 |
| 承認した現場設備 | 承認した証明書と取り込んだ証明書が、誰がいつ判断したかと、それぞれに最後に出会ったアドレスとともに並びます。 | **承認を取り下げる**と、接続を閉じ、その証明書を一覧に戻します。**証明書を取り込む**と、手元にある公開証明書のファイル（.der、.cer、.crt、.pem）を最初の接続より前に承認します。 |
| 遮断した現場設備 | 遮断した証明書が並びます。遮断した証明書は、Windows が信頼していても拒否されます。 | **遮断を解除**すると、承認はせずに、その証明書を一覧に戻します。 |

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

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

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