doca-socket-relay

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills