doca-socket-relay

DOCA Socket Relay

例

• 「ソケットアプリを書き換えずに BlueField に移行できますか？」 — 対象範囲内です。まずデプロイ形態を選択してください。ここでアプリを comch に移植しないでください。
• 「リレーは起動していますが、ホストアプリで ECONNREFUSED が発生します。」 — DPU 側の相手が停止していると決めつける前に、バインド／リッスンの状態を確認してください。

クイックファクト

バイナリ名、フラグ、パスの正確な情報は、リリースに対応する公開 DOCA Socket Relay ガイドが一次情報です。引用する前に、インストール済みツールの --help で確認してください。ガイドの説明は次のとおりです。

• AF_UNIX サーバーアプリケーションごとにリレーインスタンスは 1 つです。対応するのは SOCK_STREAM のみで、クライアント接続数は最大 512 です。
• BlueField インスタンスには、ソケットパス、Comch サービス名、デバイスの PCI アドレス、リプレゼンタの PCI アドレスを指定し、AF_UNIX サーバーに接続します。ホストインスタンスには、リプレゼンタ以外の同じ情報を指定し、クライアントが接続するソケットパスをバインドします。両側で同じ Comch 名を使用します。
• ソケットパスで ECONNREFUSED が発生する場合： そのパスでリッスンしているものがありません。ホストリレーが起動していない、ソケットパスがクライアントの使用するパスと異なる、または古いソケットファイルが残っています。次に、BlueField インスタンスが起動していることと、両側の Comch 名が一致していることを確認し、ログレベルを上げてください（--help を参照）。
• 接続を終了できるのは、ホスト側アプリケーションのみです。

手順

以下の「読み込み順」に従ってください。設定／実行／デバッグについては、タスク用コンパニオンを開いてください。リレーが転送する内容については、機能用コンパニオンを開いてください。すべてのコンパニオンファイルを開く必要はありません。

最初に確認すること： これは DOCA Socket Relay を呼び出すためのツールスキルです。ソケット指向のホストアプリケーションがソケットをローカルで終端し、リレーがトラフィックを DOCA ファブリック経由で DPU 側の終端へ転送できるようにする、ホスト ↔ BlueField ブリッジです。タスク用コンパニオンを開き、デプロイ形態 × ソケットタイプ × 転送先エンドポイントの選択については ## configure から始めてください。次に、バインド → 接続 → ラウンドトリップのフローについて ## run を確認してください。リレーがどの状態を転送できるか、何を報告するか、データパスの特性が何を意味するかについて質問された場合は、機能用コンパニオンを開いてください。DOCA をまだインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。ホスト ↔ DPU のデータプレーンではなくコントロールプレーンについて質問されている場合は、doca-comch/SKILL.md に案内してください。リレーは comch に対するデータプレーン側の対応機能です。

このスキルの使い方： このファイルを読み、次に質問に必要な ## <name> 見出しをコンパニオンファイルで検索し、そのセクション全体を読んでください。その内容に基づいて完全に回答し、記載されているシンボルとコマンドのみを引用してください。ドキュメントは閲覧せず、doca-public-knowledge-map に記載された入口を使用してください。環境の確認方法は、ユーザーの DOCA ホストで実行するコマンドとして提示してください。対象範囲外のリクエストについては、該当するスキル名を示して終了してください。

このスキルが適切に回答できる質問の例

このスキルが回答できる、Socket Relay に関する質問の種類と、 それぞれの実例です。重要なのは質問の種類であり、 実例はその一例です。

• 「既存のソケットベースのアプリケーションを、書き換えずに DOCA ファブリックへ移行できますか？」 — 実例：「ホストサービスが ソケットプロトコルでピアと通信しています。アプリケーションを comch のプログラミングインターフェイスに移植せずに、代わりに BlueField DPU 上でピアを動かしたいと考えています」。回答では、 機能の補助ドキュメントにあるユースケースの説明と、 タスクの補助ドキュメントにあるデプロイ構成の選択に基づいています。
• 「リレーはどこに配置され、ホストと DPU では何が動作しますか？」 — 実例：「リレープロセスはホスト上で 1 つ実行しますか、アプリの 隣にサイドカーとして配置しますか、それとも BlueField 上で リレーコンテナを実行しますか？また、接続を実際に終端する DPU 側のコンポーネントは何ですか？」。回答では、機能の補助 ドキュメントにある 3 軸の構成モデル（デプロイ構成 × ソケットの種類 × 転送エンドポイント）と、タスクの補助ドキュメントのステップ 2 に基づいています。
• 「リレーは起動していますが、ホストアプリケーションが接続できません。」 — 実例：「リレープロセスは実行中ですが、ホストアプリがリレーの リスニング先であるはずのソケット／ポートに接続しようとすると、 ECONNREFUSED または接続タイムアウトが報告されます」。回答では、 機能の補助ドキュメントのレイヤー 1〜3 にある階層化されたエラー分類と、 タスクの補助ドキュメントにある bind／accept の手順に基づいています。
• 「データはホストから出ていきますが、DPU 側に届きません。」 — 実例：「ホストアプリのソケット接続には成功し、リレーは接続を 受け付けたと報告していますが、DPU 側の終端処理コンポーネントに データが届きません」。回答では、機能の補助ドキュメントの レイヤー 4 にある転送エンドポイントの説明と、同ドキュメントに 記載されたデータパスが無応答になる障害モードに基づいています。
• 「フリート全体で利用を開始する前に、リレーが適切な解決策であると どう確認できますか？」 — 実例：「ホストクライアントが N 台あります。 残りをリレーに向ける前に、そのうち 1 台でエンドツーエンドに動作する ことを確認したいです」。回答では、タスクの補助ドキュメントにある 一括導入前のスモークテスト手順（bind → 1 台のホストアプリが 接続することを確認 → 1 往復のエンドツーエンド通信を確認 → その後にのみフリートを利用開始）に基づいています。
• 「この Socket Relay はインストール済みの DOCA に含まれていますか？ また、そのバージョンは依存する comch／eth コンポーネントと一致していますか？」 — 実例：「このホストにリレーバイナリは存在しますか？また、 pkg-config --modversion doca-common の結果と一致していますか？」。 回答では、機能の補助ドキュメントにあるバージョン情報の補足を参照します。 そこから正規の doca-version/SKILL.md のルールに案内し、 Socket Relay 固有の内容（存在確認、ホストと BlueField のパッケージ、 依存ライブラリとの整合性）を追加で説明します。

このスキルを読み込むタイミング

ユーザーが、またはエージェントが、DOCA がインストールされた実ホストまたは BlueField Arm 上で（あるいは適切なデバイスパススルーを設定した公開 NGC DOCA コンテナー内で）DOCA Socket Relay を操作する必要がある場合に、このスキルを読み込みます。具体的には、次のような場合です。

• ソケットベースのアプリケーションを書き換えずに、同一ホスト上のピアから BlueField 側のターミネーターへ移行する。
• 特定の環境に合わせて、リレーのデプロイ形態（アプリと同じプロセス内、サイドカープロセス／コンテナー、または BlueField 上のサービスコンテナー）を選ぶ。
• アプリケーションのクライアントが接続を試みる前に、リレーがバインドするホスト側ソケットと、リレーが接続先とする DPU 側の転送エンドポイントを設定する。
• 新規リレーデプロイで、バインド → 接続 → 往復通信 → フリートへの展開という流れを実施する。
• リレーの多層エラー構造に照らして、「ホストアプリが接続できない」「接続は受け付けられるがバイトデータが流れない」「最初の往復通信は動作するが、その後はハングする」といった症状を診断する。
• ホストアプリケーション側と DPU 側のターミネーターの見解が食い違っているように見える場合に、リレーの見解と照合する。

一般的な DOCA の概要、comch プログラミング API、RDMA プログラミング、ラインレートの生パケット I/O、または DOCA のインストールには、このスキルを読み込まないでください。これらについては、doca-public-knowledge-map/SKILL.md、doca-comch/SKILL.md、doca-eth/SKILL.md、または doca-setup/SKILL.md を参照してください。

このスキルでできること

これは軽量なローダーです。実質的な内容は、次の 2 つの補助ファイルにあります。

• capabilities 補助ファイル — Socket Relay が中継し、変更する内容：3 軸の設定モデル（デプロイ形態 × ソケットの種類／プロトコル × 転送エンドポイント）、読み取り専用操作と状態変更操作の区分、doca-version/SKILL.md に誘導するバージョン対応状況の補足、階層化されたエラー分類（ツール未インストール／リレー未バインド／ホストアプリ未接続／DPU 側ターミネーターに到達不能／権限／バージョン／複数層にまたがる問題）、doca-comch/SKILL.md に対するデータプレーン側の対となる存在としてのリレーの役割、そして転送エンドポイントの設定ミスがデータパスを気づかれないまま切断する危険性を踏まえた重要な安全ポリシー。
• tasks 補助ファイル — 対象タスクの動詞ごとのステップごとのワークフロー：configure（3 軸の判断と事前条件の確認）、build（リレーはビルド済みで提供されるため、インストールへ誘導）、modify（拒否 — バイナリではなく、起動方法／デプロイを変更）、run（バインド → 接続 → 往復通信の流れ）、test（一括評価の前にスモークテストを行うループ）、debug（階層に沿った診断手順）。さらに、Deferred task verbs ブロックと、バンドルの doca-structured-tools-contract/SKILL.md にある前文に準拠した Command appendix も含まれます。

このスキルでは、DOCA がすでにインストールされたホストまたは BlueField（あるいは適切なデバイスパススルーを設定して公開 NGC DOCA コンテナーが実行中）であり、オペレーターが選択したデプロイ形態に応じて公開 DOCA Socket Relay ガイドが要求する権限を持っていることを前提とします。

このスキルに意図的に含めていないもの

このスキルはエージェント向けのガイダンスであり、サンプルやスクリプトをまとめたものではありません。 境界を明確に保つため、意図的に以下を含めていません。また、プルリクエストで追加しないでください。

• バイナリ名、フラグの一覧、サブコマンド名、ソケットパスのデフォルト値、ポート番号、出力列名をそのまま記載したもの。 docs.nvidia.com にある公開 DOCA Socket Relay ガイドと、ユーザーのバージョンにインストールされている --help を正とする情報源として扱います。これらをここにコピーすると、このスキルが特定のリリースに固定され、リレーの進化に伴って気付かないうちに古くなります。このスキルでは、代わりにエージェントをそれらの情報源へ案内します。
• あらかじめ用意された出力例。 出力はインストール状況、バージョン、デプロイ環境によって異なります。取得済みの例は、異なるプラットフォームや状態のオペレーターを誤解させます。
• リレーの出力を扱うラッパー、パーサー、スクリプト（言語は問いません）。 出力形式は文書化されています。出力を使ったスクリプトを作成したいユーザーは、最新のガイドを読み、インストール済みのバージョンに合わせてパーサーを作成してください。
• samples/ または reference/ のサブツリー。 これは文書化された DOCA アーティファクトを読み込むための薄いローダーです。実質的な内容は公開ページと --help にあります。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲に含まれることを確認してください（ユーザーが求めているのは、ソケットベースのアプリケーションを書き換えて DOCA プログラミングインターフェイスに移行することなく、DPU 上で動作させる方法であり、comch／eth／RDMA API の学習ではありません）。
2. リレーが運ぶもの、3 軸の構成モデル、読み取り専用と状態変更の区分、バージョンごとの利用可否、階層化されたエラーの概要、可観測性、安全性の方針については、機能に関する補足ドキュメントを参照してください。
3. 文書化された呼び出し方法と、一括処理の前にスモークテストを行うワークフロー（configure、build、modify、run、test、debug、および Command appendix）については、タスクに関する補足ドキュメントを参照してください。

関連スキル

• doca-comch/SKILL.md — ホスト ↔ DPU 間の コントロールプレーンのプリミティブです（ホストと DPU プロセス間の PCIe ベースのメッセージチャネル）。Socket Relay は、ソケット指向のアプリケーション向けのデータプレーン側の対となるものです。comch は、アプリケーションがホスト ↔ DPU の境界を越えてプログラムから 調整 するために使用し、リレーは、書き換えずにソケット形式のバイト列をその境界越しに 転送 するために使用します。段階的に移行するアプリケーションのオーナーは、この 2 つを組み合わせてください。まず comch でコントロールプレーンを移行し、ライブラリごとの書き換えが妥当と判断できるまでは、リレーでデータプレーンを移行します。
• doca-eth/SKILL.md — ソケットレベルの 下位 に位置する、ラインレートのローパケット I/O インターフェースです。リレーはアプリケーションにソケット形式のインターフェースを提供し、基盤となる DOCA ファブリックを利用します。アプリケーションをソケットではなくパケットを直接処理するよう書き換えられる場合や、リレーで実現できるスループット／レイテンシー特性では不十分になった場合は、doca-eth が適切です。
• doca-container-deployment/SKILL.md — BlueField のサービスランタイム契約（kubelet のスタンドアロン実行 + 静的 Pod マニフェスト + サービスごとの設定ファイルのマウント）です。運用担当者が選択したデプロイ形態が、ホスト側プロセスではなく BlueField 上で実行するリレーコンテナーである場合は、このスキルと併せて読み込んでください。そちらのランタイム契約では Pod 仕様／イメージのプル／静的 Pod／生存確認を扱い、このスキルではリレー固有の設定を扱います。
• doca-comm-channel-admin/SKILL.md — comch チャネルを操作する、運用担当者向けの管理 CLI です。ここでの「一覧表示 → 検査 → 判断」というパターンは、Socket Relay 自身の状態にも当てはまります。まず読み取り専用で検査し、スモークテストが成功した場合にのみ状態を変更する操作を許可します。どちらのツールも同じファミリーに属しており、同じパターンが適用されます。
• doca-public-knowledge-map/SKILL.md — 公開されている DOCA Socket Relay ガイドと、その他の公開 DOCA ドキュメント一式への案内です。正規 URL には doca-public-knowledge-map ## DOCA tools（doca-public-knowledge-map/SKILL.md#doca-tools）からアクセスできます。
• doca-version/SKILL.md — DOCA の正規のバージョン処理ルールです。機能の補足ドキュメントにある ## Version compatibility セクションは、本文については簡潔な補足としてここを参照するよう案内します。
• doca-structured-tools-contract/SKILL.md — 構造化ヘルパーツール向けの、バンドル全体に適用される「検出 → 優先 → フォールバック → 報告」の契約です。タスクの補足ドキュメントにあるコマンド付録は、この契約に従います。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、representor の可視性チェック、および公開 NGC DOCA コンテナーを使う まだインストールしていない場合 の手順です。このスキルは、その前提条件が満たされていることを前提とします。
• doca-debug/SKILL.md — 複数領域にまたがるデバッグ手順です。Socket Relay は、レイヤー化されたエラーの表面を持つデータパスブリッジとして ランタイム レイヤーに位置し、原因が DOCA より下位にある場合は、複数領域にまたがるデバッグ手順へとエスカレーションします。