/doca-socket-relay

license: Apache-2.0
name: doca-socket-relay
description: >
  Use this skill when the operator is driving the DOCA Socket Relay
  to bridge a socket-oriented host application onto a BlueField DPU
  peer without rewriting it — picking the deployment shape
  (in-process, sidecar, or BlueField service container), configuring
  the host-side socket and the DPU-side forwarding endpoint, walking
  the bind → connect → round-trip → admit-fleet smoke, or diagnosing
  a stuck/silent relay. Trigger even when the user does not
  explicitly mention "DOCA Socket Relay" — typical implicit phrasings
  include "move my socket app onto the BlueField without rewriting
  it", "host app gets ECONNREFUSED on the relay", "relay accepts the
  connection but bytes never arrive on the DPU side", "first
  round-trip works, the rest hang", "bridge an AF_UNIX (UDS) socket
  to a DPU peer over Comch", or "I want a sidecar that forwards my
  socket to the BlueField". Refuse and route elsewhere for the comch programming
  API, line-rate raw packet I/O via doca-eth, and DOCA
  install/bring-up — those belong to other skills.
metadata:
  kind: tool
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU attached, plus the
  socket-oriented host application that will be migrated onto the
  fabric. Container-shape deployment additionally relies on the
  BlueField kubelet-standalone runtime per doca-container-deployment.

DOCA Socket Relay

**Where to start:** This is a tool skill for invoking the DOCA Socket Relay — the host ↔ BlueField bridge that lets a socket-oriented host application terminate its sockets locally while the relay forwards the traffic to a DPU-side terminator across the DOCA fabric. Open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure) for the deployment-shape × socket-type × forwarding-endpoint decision, then [`## run`](TASKS.md#run) for the bind → connect → round-trip flow. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what state can the relay carry, what does it report, and what does its data-path posture imply*. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first. If the user is asking about the host ↔ DPU **control plane** rather than the **data plane** the relay carries, route to [`doca-comch`](../../libs/doca-comch/SKILL.md) — the relay is the data-plane counterpart to comch.

Example questions this skill answers well

The CLASSES of socket-relay questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"Can I move my existing socket-based application onto a DOCA

fabric without rewriting it?"** — worked example: *"a host service speaks a socket protocol to a peer; I want the peer to live on the BlueField DPU instead, but I do not want to port the application to the comch programming surface"*. Answered by the use-case framing in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the deployment-shape decision in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"Where does the relay sit, and what runs on the host vs the

DPU?"** — worked example: *"do I run one relay process on the host, a sidecar next to my app, or a relay container on the BlueField — and what is on the DPU side that actually terminates the connection?"*. Answered by the three-axis configuration model (deployment shape × socket type × forwarding endpoint) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• [`TASKS.md ## configure`](TASKS.md#configure) step 2.
• **"My relay is up but the host application cannot connect."** —

worked example: *"the relay process is running but the host app reports `ECONNREFUSED` / connect timeout when it tries the socket / port the relay should be listening on"*. Answered by the layered error taxonomy in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) layers 1-3 + the bind / accept ladder in [`TASKS.md ## debug`](TASKS.md#debug).

• **"Bytes leave the host but never arrive on the DPU side."** —

worked example: *"the host app's socket connect succeeded, the relay reports the connection accepted, but the DPU-side terminator never sees the data"*. Answered by the forwarding-endpoint layer in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) layer 4 + the silent-data-path failure mode named in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy).

• **"How do I prove the relay is the right answer before I admit

the whole fleet onto it?"** — worked example: *"I have N host clients; I want to confirm one of them works end-to-end before pointing the rest at the relay"*. Answered by the smoke-before-bulk loop in [`TASKS.md ## test`](TASKS.md#test) (bind → confirm one host app connects → confirm one round-trip end-to-end → only then admit the fleet).

• **"Is this Socket Relay shipped on my installed DOCA, and does

its version match the comch / eth pieces it sits on?"** — worked example: *"is the relay binary present on this host, and does it agree with `pkg-config --modversion doca-common`"*. Answered by the version overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which redirects to the canonical [`doca-version`](../../doca-version/SKILL.md) rules and adds the Socket Relay specifics (presence check, host vs BlueField packaging, agreement with companion libraries).

Audience

This skill serves **external operators, application owners, and AI agents who need to bridge a socket-oriented application onto a BlueField DPU without rewriting the application against the DOCA programming surface**. Concretely:

• A platform owner with an existing host service that speaks a

socket protoc