DOCA Socket Relay
Examples
- "Can I move my socket app onto BlueField without rewriting
it?" — this is in scope. Pick deployment shape first; do
not port the app onto comch here.
- "The relay is up but the host app gets ECONNREFUSED." —
walk bind / listen before assuming the DPU peer is down.
Quick facts
The authoritative source for the binary name, flags and paths is the public
DOCA Socket Relay guide for your release; confirm them with the installed
tool's --help before quoting any of them. As that guide describes it:
- One relay instance per AF_UNIX server application;
SOCK_STREAM only;
at most 512 client connections.
- The BlueField instance takes a socket path, a Comch service name, the
device PCI address and the representor PCI address, and connects to your
AF_UNIX server; the host instance takes the same without the representor
and binds the socket path your clients connect to. Both sides use the same
Comch name.
ECONNREFUSED on the socket path: nothing is listening there: the
host relay is not running, its socket path differs from the one the client
uses, or a stale socket file is left over. Then check the BlueField instance
is up and both Comch names match; raise the log level (see --help).
- Only the host-side application may terminate connections.
Instructions
Follow Loading order below. Open the tasks companion for
configure / run / debug. Open the capabilities companion for
what the relay carries. Do not open every companion file.
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
the tasks companion and start at ## configure
for the deployment-shape × socket-type × forwarding-endpoint
decision, then ## run for the bind → connect →
round-trip flow. Open the capabilities companion 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/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/SKILL.md — the relay is the
data-plane counterpart to comch.
How to use this skill. Read this file, then search the companion file
for the ## <name> heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in doca-public-knowledge-map. Give
environment checks as commands for the user's DOCA host. For out-of-scope
requests, name the skill that owns them and stop.
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
the capabilities companion
- the deployment-shape decision in
the tasks companion.
- "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
the capabilities companion
- the tasks companion 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
the capabilities companion
layers 1-3 + the bind / accept ladder in
the tasks companion.
- "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
the capabilities companion
layer 4 + the silent-data-path failure mode named in
the capabilities companion.
- "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
the tasks companion (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
the capabilities companion,
which redirects to the canonical
doca-version/SKILL.md rules and adds the
Socket Relay specifics (presence check, host vs BlueField
packaging, agreement with companion libraries).
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/SKILL.md,
doca-comch/SKILL.md,
doca-eth/SKILL.md, or
doca-setup/SKILL.md.
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — 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/SKILL.md,
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/SKILL.md, and the
high-stakes safety policy that makes a misconfigured forwarding
endpoint a silent data-path break.
- the tasks companion — 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/SKILL.md
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.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or scripts bundle.
To keep the boundary clean, it deliberately does not contain — and
pull requests should not add:
- Verbatim binary names, flag inventories, subcommand names,
socket-path defaults, port numbers, or output column names.
The public DOCA Socket Relay guide on
docs.nvidia.com and the
installed --help on the user's version are the joint source
of truth; copying them here pins the skill to one release and
silently rots when the relay evolves. The skill routes the agent
at those sources instead.
- Pre-baked example output. Output is install-, version-, and
deployment-specific. A captured example will mislead an operator
on a different platform / state.
- Wrappers, parsers, or scripts in any language that consume
the relay's output. The output format is documented; users who
want to script against it should read the live guide and write
the parser against their installed version.
- A
samples/ or reference/ subtree. This is a thin loader
for a documented DOCA artifact; substantive material lives on
the public page and in --help.
Loading order
- Read this skill first to confirm the user's question is in
scope (the user wants to bridge a socket-based application onto
the DPU without rewriting it onto the DOCA programming surface,
not learn the comch / eth / RDMA APIs).
- For what the relay carries, the three-axis configuration
model, the read-only vs state-changing split, version
availability, the layered error surface, observability, and
safety posture, see the capabilities companion.
- For the documented invocations and the smoke-before-bulk
workflow —
configure, build, modify, run, test,
debug, plus the Command appendix — see
the tasks companion.
Related skills
doca-comch/SKILL.md — the host ↔ DPU
control-plane primitive (PCIe-based message channel between a
host and a DPU process). The Socket Relay is the data-plane
counterpart for socket-oriented applications: comch is what an
application uses to coordinate across the host ↔ DPU boundary
programmatically; the relay is what an application uses to
carry socket-shaped bytes across that boundary without being
rewritten. Pair the two when an application owner is migrating
in stages — control plane first via comch, data plane via the
relay until a per-library rewrite is justified.
doca-eth/SKILL.md — the line-rate raw
packet I/O surface that sits below the socket level. The relay
presents a socket-shaped interface to the application and rides
the underlying DOCA fabric; doca-eth is the right answer when
the application can be rewritten to operate on packets directly
rather than sockets, and when the throughput / latency profile
the relay achieves is no longer sufficient.
doca-container-deployment/SKILL.md
— the BlueField service-runtime contract (kubelet standalone +
static-pod manifests + per-service config-file mount). Load this
alongside the present skill when the operator's chosen
deployment shape is a relay container running on the BlueField
rather than a host-side process; the runtime contract there owns
the pod-spec / image-pull / static-pod / liveness pieces, this
skill owns the relay-specific config.
doca-comm-channel-admin/SKILL.md
— the operator-side admin CLI for comch channels. The
list → inspect → decide pattern there is the same shape the
Socket Relay uses for its own state: read-only inspection first,
state-changing operations gated on a clean smoke. Both tools are
members of the same family and the same patterns apply.
doca-public-knowledge-map/SKILL.md
— routing to the public DOCA Socket Relay guide and the rest of
the public DOCA documentation set. The canonical URL is reached
via doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools).
doca-version/SKILL.md — canonical DOCA
version-handling rules. The ## Version compatibility section
in the capabilities companion is a concise overlay
that redirects here for the body.
doca-structured-tools-contract/SKILL.md
— the bundle's detect → prefer → fall back → report contract for
structured helper tools. The Command appendix in
the tasks companion honors this contract.
doca-setup/SKILL.md — env preparation,
install verification, representor visibility checks, and the I
have no install yet path with the public NGC DOCA container.
This skill assumes its preconditions are satisfied.
doca-debug/SKILL.md — the cross-cutting
debug ladder. The Socket Relay slots in at the runtime layer
as a data-path bridge whose layered error surface escalates to
the cross-cutting ladder when the cause is below DOCA.
1---2license: Apache-2.03name: doca-socket-relay4description: >5 Use this skill when the operator is driving the DOCA Socket Relay to6 bridge a socket-oriented host application onto a BlueField DPU peer7 without rewriting it — picking the deployment shape (in-process,8 sidecar, or BlueField service container), configuring the host-side9 socket and the DPU-side forwarding endpoint, walking the bind →10 connect → round-trip → admit-fleet smoke, or diagnosing a stuck/silent11 relay. Trigger even when the user does not explicitly mention "DOCA12 Socket Relay" — typical implicit phrasings include "move my socket app13 onto the BlueField without rewriting it", "host app gets ECONNREFUSED14 on the relay", "relay accepts the connection but bytes never arrive on15 the DPU side", "first round-trip works, the rest hang", "bridge an16 AF_UNIX (UDS) socket to a DPU peer over Comch", or "I want a sidecar17 that forwards my socket to the BlueField". Refuse and route elsewhere18 for the comch programming API, line-rate raw packet I/O via doca-eth,19 and DOCA install/bring-up — those belong to other skills.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-socket-relay22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: tool24 doca_version: "3.5"25 tags:26 - doca27 - socket28 - relay29compatibility: >30 Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu31 22.04/24.04 or RHEL/SLES) with a BlueField DPU attached, plus the32 socket-oriented host application that will be migrated onto the33 fabric. Container-shape deployment additionally relies on the34 BlueField kubelet-standalone runtime per doca-container-deployment.35 The validation steps require a live DOCA install.36---3738# DOCA Socket Relay3940## Examples4142- **"Can I move my socket app onto BlueField without rewriting43 it?"** — this is in scope. Pick deployment shape first; do44 not port the app onto comch here.45- **"The relay is up but the host app gets ECONNREFUSED."** —46 walk bind / listen before assuming the DPU peer is down.4748## Quick facts4950The authoritative source for the binary name, flags and paths is the public51DOCA Socket Relay guide for your release; confirm them with the installed52tool's `--help` before quoting any of them. As that guide describes it:5354- One relay instance per AF_UNIX server application; `SOCK_STREAM` only;55 at most 512 client connections.56- The BlueField instance takes a socket path, a Comch service name, the57 device PCI address and the representor PCI address, and connects to your58 AF_UNIX server; the host instance takes the same without the representor59 and binds the socket path your clients connect to. Both sides use the same60 Comch name.61- **`ECONNREFUSED` on the socket path:** nothing is listening there: the62 host relay is not running, its socket path differs from the one the client63 uses, or a stale socket file is left over. Then check the BlueField instance64 is up and both Comch names match; raise the log level (see `--help`).65- Only the host-side application may terminate connections.6667## Instructions6869Follow Loading order below. Open the tasks companion for70configure / run / debug. Open the capabilities companion for71what the relay carries. Do not open every companion file.7273**Where to start:** This is a tool skill for invoking the DOCA Socket74Relay — the host ↔ BlueField bridge that lets a socket-oriented host75application terminate its sockets locally while the relay forwards76the traffic to a DPU-side terminator across the DOCA fabric. Open77the tasks companion and start at `## configure`78for the deployment-shape × socket-type × forwarding-endpoint79decision, then `## run` for the bind → connect →80round-trip flow. Open the capabilities companion when the81question is *what state can the relay carry, what does it report,82and what does its data-path posture imply*. If the user has not83installed DOCA yet, route to84`doca-setup/SKILL.md` first. If the user is85asking about the host ↔ DPU **control plane** rather than the86**data plane** the relay carries, route to87`doca-comch/SKILL.md` — the relay is the88data-plane counterpart to comch.8990**How to use this skill.** Read this file, then search the companion file91for the `## <name>` heading the question needs and read that whole section.92Answer completely from it, quoting only its symbols and commands. Do not93browse docs; use the entry points in `doca-public-knowledge-map`. Give94environment checks as commands for the user's DOCA host. For out-of-scope95requests, name the skill that owns them and stop.9697## Example questions this skill answers well9899The CLASSES of socket-relay questions this skill is built to answer,100each with one worked example. The class is the load-bearing piece;101the worked example is one instance.102103- **"Can I move my existing socket-based application onto a DOCA104 fabric without rewriting it?"** — worked example: *"a host service105 speaks a socket protocol to a peer; I want the peer to live on106 the BlueField DPU instead, but I do not want to port the107 application to the comch programming surface"*. Answered by the108 use-case framing in109 the capabilities companion110 + the deployment-shape decision in111 the tasks companion.112- **"Where does the relay sit, and what runs on the host vs the113 DPU?"** — worked example: *"do I run one relay process on the114 host, a sidecar next to my app, or a relay container on the115 BlueField — and what is on the DPU side that actually terminates116 the connection?"*. Answered by the three-axis configuration model117 (deployment shape × socket type × forwarding endpoint) in118 the capabilities companion119 + the tasks companion step 2.120- **"My relay is up but the host application cannot connect."** —121 worked example: *"the relay process is running but the host app122 reports `ECONNREFUSED` / connect timeout when it tries the123 socket / port the relay should be listening on"*. Answered by the124 layered error taxonomy in125 the capabilities companion126 layers 1-3 + the bind / accept ladder in127 the tasks companion.128- **"Bytes leave the host but never arrive on the DPU side."** —129 worked example: *"the host app's socket connect succeeded, the130 relay reports the connection accepted, but the DPU-side131 terminator never sees the data"*. Answered by the132 forwarding-endpoint layer in133 the capabilities companion134 layer 4 + the silent-data-path failure mode named in135 the capabilities companion.136- **"How do I prove the relay is the right answer before I admit137 the whole fleet onto it?"** — worked example: *"I have N host138 clients; I want to confirm one of them works end-to-end before139 pointing the rest at the relay"*. Answered by the140 smoke-before-bulk loop in141 the tasks companion (bind → confirm one host app142 connects → confirm one round-trip end-to-end → only then admit143 the fleet).144- **"Is this Socket Relay shipped on my installed DOCA, and does145 its version match the comch / eth pieces it sits on?"** — worked146 example: *"is the relay binary present on this host, and does147 it agree with `pkg-config --modversion doca-common`"*. Answered148 by the version overlay in149 the capabilities companion,150 which redirects to the canonical151 `doca-version/SKILL.md` rules and adds the152 Socket Relay specifics (presence check, host vs BlueField153 packaging, agreement with companion libraries).154155## When to load this skill156157Load this skill when the user is — or the agent needs to — drive158the DOCA Socket Relay on a real host or BlueField Arm with DOCA159installed (or inside the public NGC DOCA container with the right160device passthrough). Concretely:161162- Migrating a socket-based application off a same-host peer onto163 a BlueField-side terminator without rewriting the application.164- Picking the relay's deployment shape (in-process beside the app,165 sidecar process / container, or a service container on the166 BlueField) for a specific environment.167- Configuring the host-side socket the relay binds and the DPU-side168 forwarding endpoint the relay points at, before any application169 client tries to connect.170- Walking the bind → connect → round-trip → admit-fleet loop on a171 brand-new relay deployment.172- Diagnosing a *"host app cannot connect"*, *"connection accepted173 but no bytes flow"*, or *"first round-trip works, the rest hang"*174 symptom against the relay's layered error surface.175- Cross-checking the relay's view against the host application176 side and the DPU-side terminator when the three appear to177 disagree.178179Do **not** load this skill for general DOCA orientation, the comch180programming API, RDMA programming, line-rate raw packet I/O, or181DOCA install. For those, route to182`doca-public-knowledge-map/SKILL.md`,183`doca-comch/SKILL.md`,184`doca-eth/SKILL.md`, or185`doca-setup/SKILL.md`.186187## What this skill provides188189This is a **thin loader**. Substantive material lives in two190companion files:191192- the capabilities companion — what the Socket Relay carries and changes:193 the three-axis configuration model (deployment shape × socket194 type / protocol × forwarding endpoint), the read-only vs195 state-changing operation split, the version-availability overlay196 that redirects to `doca-version/SKILL.md`,197 the layered error taxonomy (tool-not-installed / relay-not-bound198 / host-app-not-connecting / DPU-side-terminator-not-reachable /199 permission / version / cross-cutting), the relay's role as the200 data-plane counterpart to201 `doca-comch/SKILL.md`, and the202 high-stakes safety policy that makes a misconfigured forwarding203 endpoint a silent data-path break.204- the tasks companion — step-by-step workflows for the in-scope task verbs:205 `configure` (the three-axis decision + the precondition probe),206 `build` (route to install — the relay is shipped pre-built),207 `modify` (refuse — modify the *invocation / deployment*, not the208 binary), `run` (the bind → connect → round-trip flow), `test`209 (the smoke-before-bulk eval loop), `debug` (the layered210 diagnosis ladder), plus a `Deferred task verbs` block and a211 `Command appendix` that honors the bundle's212 `doca-structured-tools-contract/SKILL.md`213 preamble.214215The skill assumes a host or BlueField where DOCA is already216installed (or the public NGC DOCA container is running with the217right device passthrough) and the operator has whatever privileges218the public DOCA Socket Relay guide requires for the chosen219deployment shape.220221## What this skill deliberately does not ship222223This skill is **agent guidance**, not a samples or scripts bundle.224To keep the boundary clean, it deliberately does not contain — and225pull requests should not add:226227- **Verbatim binary names, flag inventories, subcommand names,228 socket-path defaults, port numbers, or output column names.**229 The public DOCA Socket Relay guide on `docs.nvidia.com` and the230 installed `--help` on the user's version are the joint source231 of truth; copying them here pins the skill to one release and232 silently rots when the relay evolves. The skill routes the agent233 at those sources instead.234- **Pre-baked example output.** Output is install-, version-, and235 deployment-specific. A captured example will mislead an operator236 on a different platform / state.237- **Wrappers, parsers, or scripts** in any language that consume238 the relay's output. The output format is documented; users who239 want to script against it should read the live guide and write240 the parser against their installed version.241- **A `samples/` or `reference/` subtree.** This is a thin loader242 for a documented DOCA artifact; substantive material lives on243 the public page and in `--help`.244245## Loading order2462471. Read this skill first to confirm the user's question is in248 scope (the user wants to bridge a socket-based application onto249 the DPU without rewriting it onto the DOCA programming surface,250 not learn the comch / eth / RDMA APIs).2512. **For what the relay carries, the three-axis configuration252 model, the read-only vs state-changing split, version253 availability, the layered error surface, observability, and254 safety posture, see the capabilities companion.**2553. **For the documented invocations and the smoke-before-bulk256 workflow — `configure`, `build`, `modify`, `run`, `test`,257 `debug`, plus the `Command appendix` — see258 the tasks companion.**259260## Related skills261262- `doca-comch/SKILL.md` — the host ↔ DPU263 **control-plane** primitive (PCIe-based message channel between a264 host and a DPU process). The Socket Relay is the **data-plane**265 counterpart for socket-oriented applications: comch is what an266 application uses to *coordinate* across the host ↔ DPU boundary267 programmatically; the relay is what an application uses to268 *carry* socket-shaped bytes across that boundary without being269 rewritten. Pair the two when an application owner is migrating270 in stages — control plane first via comch, data plane via the271 relay until a per-library rewrite is justified.272- `doca-eth/SKILL.md` — the line-rate raw273 packet I/O surface that sits *below* the socket level. The relay274 presents a socket-shaped interface to the application and rides275 the underlying DOCA fabric; doca-eth is the right answer when276 the application can be rewritten to operate on packets directly277 rather than sockets, and when the throughput / latency profile278 the relay achieves is no longer sufficient.279- `doca-container-deployment/SKILL.md`280 — the BlueField service-runtime contract (kubelet standalone +281 static-pod manifests + per-service config-file mount). Load this282 alongside the present skill when the operator's chosen283 deployment shape is a relay container running on the BlueField284 rather than a host-side process; the runtime contract there owns285 the pod-spec / image-pull / static-pod / liveness pieces, this286 skill owns the relay-specific config.287- `doca-comm-channel-admin/SKILL.md`288 — the operator-side admin CLI for comch channels. The289 list → inspect → decide pattern there is the same shape the290 Socket Relay uses for its own state: read-only inspection first,291 state-changing operations gated on a clean smoke. Both tools are292 members of the same family and the same patterns apply.293- `doca-public-knowledge-map/SKILL.md`294 — routing to the public DOCA Socket Relay guide and the rest of295 the public DOCA documentation set. The canonical URL is reached296 via `doca-public-knowledge-map ## DOCA tools` (`doca-public-knowledge-map/SKILL.md#doca-tools`).297- `doca-version/SKILL.md` — canonical DOCA298 version-handling rules. The `## Version compatibility` section299 in the capabilities companion is a concise overlay300 that redirects here for the body.301- `doca-structured-tools-contract/SKILL.md`302 — the bundle's detect → prefer → fall back → report contract for303 structured helper tools. The Command appendix in304 the tasks companion honors this contract.305- `doca-setup/SKILL.md` — env preparation,306 install verification, representor visibility checks, and the *I307 have no install yet* path with the public NGC DOCA container.308 This skill assumes its preconditions are satisfied.309- `doca-debug/SKILL.md` — the cross-cutting310 debug ladder. The Socket Relay slots in at the *runtime* layer311 as a data-path bridge whose layered error surface escalates to312 the cross-cutting ladder when the cause is below DOCA.