/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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - socket
    - relay
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.
  The validation steps require a live DOCA install.

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 arr