Doca Socket Relay

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 and start at ## configure for the deployment-shape × socket-type × forwarding-endpoint decision, then ## run for the bind → connect → round-trip flow. Open 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 first. If the user is asking about the host ↔ DPU control plane rather than the data plane the relay carries, route to doca-comch — 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
  • the deployment-shape decision in 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
  • 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 layers 1-3 + the bind / accept ladder in 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 layer 4 + the silent-data-path failure mode named in 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 (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, which redirects to the canonical doca-version 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 protocol to a peer and wants the peer to live on the BlueField instead — without porting the host service onto doca-comch.
• A migration engineer evaluating the relay as the first step of a phased move onto DOCA, with the comch / RDMA / Ethernet rewrite reserved for a later phase.
• An SRE / platform operator deploying the relay as a service container on the BlueField via the runtime contract documented in doca-container-deployment.
• An AI agent answering "my host app cannot reach the DPU on the socket I configured — what do I check" with the relay's layered error surface as the diagnosis ladder.

It is not for users debugging the Socket Relay binary itself, not a substitute for the live public DOCA Socket Relay guide, and not the right place for users learning the comch programming API or for users doing line-rate raw-packet I/O. Those audiences belong in doca-comch and doca-eth respectively.

The Socket Relay is shipped as a documented DOCA artifact on installs that include it; depending on the operator's deployment shape, it can be invoked as a CLI on the host or BlueField Arm, or deployed as a service container on the BlueField via the documented kubelet-standalone runtime in doca-container-deployment. The skill uses the same kind: tool three-file shape as the rest of the bundle so the agent's task-verb contract (configure / build / modify / run / test / debug) is uniform across libraries, services, and tools.

When to load this skill

Load this skill when the user is — or the agent needs to — drive the DOCA Socket Relay on a real host or BlueField Arm with DOCA installed (or inside the public NGC DOCA container with the right device passthrough). Concretely:

• Migrating a socket-based application off a same-host peer onto a BlueField-side terminator without rewriting the application.
• Picking the relay's deployment shape (in-process beside the app, sidecar process / container, or a service container on the BlueField) for a specific environment.
• Configuring the host-side socket the relay binds and the DPU-side forwarding endpoint the relay points at, before any application client tries to connect.
• Walking the bind → connect → round-trip → admit-fleet loop on a brand-new relay deployment.
• Diagnosing a "host app cannot connect", "connection accepted but no bytes flow", or "first round-trip works, the rest hang" symptom against the relay's layered error surface.
• Cross-checking the relay's view against the host application side and the DPU-side terminator when the three appear to disagree.

Do not load this skill for general DOCA orientation, the comch programming API, RDMA programming, line-rate raw packet I/O, or DOCA install. For those, route to doca-public-knowledge-map, doca-comch, doca-eth, or doca-setup.

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

• CAPABILITIES.md — what the Socket Relay carries and changes: the three-axis configuration model (deployment shape × socket type / protocol × forwarding endpoint), the read-only vs state-changing operation split, the version-availability overlay that redirects to doca-version, the layered error taxonomy (tool-not-installed / relay-not-bound / host-app-not-connecting / DPU-side-terminator-not-reachable / permission / version / cross-cutting), the relay's role as the data-plane counterpart to doca-comch, and the high-stakes safety policy that makes a misconfigured forwarding endpoint a silent data-path break.
• TASKS.md — step-by-step workflows for the in-scope task verbs: configure (the three-axis decision + the precondition probe), build (route to install — the relay is shipped pre-built), modify (refuse — modify the invocation / deployment, not the binary), run (the bind → connect → round-trip flow), test (the smoke-before-bulk eval loop), debug (the layered diagnosis ladder), plus a Deferred task verbs block and a Command appendix that honors the bundle's doca-structured-tools-contract preamble.

The skill assumes a host or BlueField where DOCA is already installed (or the public NGC DOCA container is running with the right device passthrough) and the operator has whatever privileges the public DOCA Socket Relay guide requires for the chosen deployment shape.