doca-dms git:20260717.f64fa0eA

Immutable. This exact content is served forever at /api/v1/blob/304164f90adb3f60.

---
license: Apache-2.0
name: doca-dms
description: >
  SAFETY: several gNOI operations here — reboot, OS install,
  factory-reset — are DESTRUCTIVE and IRREVERSIBLE and can take a
  production BlueField or ConnectX offline; confirm the target device
  and require explicit user confirmation before issuing any, and never
  invoke them speculatively. Use this skill for operating NVIDIA DOCA
  Management Service (DMS) on a BlueField, Arm/x86 host, or K8s pod —
  bringing up `dmsd` frontend + `dmspe` backend, picking deployment
  shape and auth, wiring `-allowed_users` + `dmsgroup`, issuing gNMI
  Get/Set on YANG paths, gNMI Subscribe for streaming telemetry, gNOI
  for reboot/OS install/factory-reset/file transfer/`mlxconfig`/`containerz`,
  or debugging frontend-vs-backend errors and logs. Trigger even
  without "DMS" — e.g. "manage a remote BlueField over gRPC", "gNOI
  reboot from orchestrator", "OS install over gRPC to a SmartNIC".
  Refuse and route for DOCA install, library-API / sample-build
  questions, and the DOCA Telemetry Service (DTS) turnkey
  aggregator-side stream consumer.
metadata:
  kind: service
compatibility: >
  DOCA service shipped with the DOCA install at /opt/mellanox/doca
  on the management endpoint (x86 host (non-DPU), BlueField Arm, or
  Kubernetes pod) on Linux (Ubuntu 22.04/24.04 or RHEL/SLES); `dmsd`
  + `dmspe` run there, and DMS is also pulled as an NGC container
  image. Verify the public DMS guide version matches the installed
  DOCA release before quoting flags or YANG paths.
---

# DOCA Management Service (DMS)

> **⚠️ Destructive operations.** The gNOI `reboot`, `OS install`, and
> `factory-reset` operations are **irreversible** and **service-impacting**
> — they can take a production BlueField or ConnectX offline or wipe its
> configuration. Before issuing any of them the agent MUST: (1) verify the
> target device identity, and (2) obtain explicit user confirmation for
> that specific destructive action. Never invoke them speculatively or as
> a side effect of another task. See the public DMS guide's safety
> guidance for these operations.

**Where to start:** This skill is for *operating* DMS, not for
*linking against* a library. If the user wants to *deploy* or *run*
the daemon, open [`TASKS.md`](TASKS.md) and start at
[`## configure`](TASKS.md#configure). If the question is *what shape
of service is DMS and what protocols does it speak*, start at
[`CAPABILITIES.md`](CAPABILITIES.md). If DOCA is not installed on the
management endpoint yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first.

## Example questions this skill answers well

The CLASSES of DMS 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.

- **"Where should DMS run for my target topology?"** — worked example:
  *"I have a host without a DPU; can I still manage a remote
  ConnectX?"*. Answered by the deployment-shape decision in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + [`TASKS.md ## configure`](TASKS.md#configure).
- **"Which authentication mode should I pick for my security
  posture?"** — worked example: *"a multi-tenant production env vs a
  single-tenant lab"*. Answered by the auth-mode trade-off table in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the auth-wiring step in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"How do I issue a gNMI `Get` / `Set` against a modeled path?"** —
  worked example: *"set `/interfaces/interface/config/mtu` on a remote
  interface"*. Answered by the gNMI/gNOI surface in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the request-shape workflow in
  [`TASKS.md ## run`](TASKS.md#run).
- **"How do I run a gNOI operation (reboot, OS install, file
  transfer)?"** — worked example: *"trigger a clean reboot of the
  target via gNOI"*. Answered by the gNOI catalog in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the run workflow in [`TASKS.md ## run`](TASKS.md#run).
- **"My DMS request returned an error — was it the frontend or the
  backend?"** — worked example: *"`mlxconfig` failed under DMS but
  works on the shell"*. Answered by the frontend-vs-backend split in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + the layered ladder in
  [`TASKS.md ## debug`](TASKS.md#debug).
- **"Where do I read DMS logs and how do I rotate them?"** — worked
  example: *"persistent log directory + journald + log-rotation
  policy"*. Answered by the logging surface in
  [`CAPABILITIES.md ## Observability`](CAPABILITIES.md#observability)
  + the log-rotation step in
  [`TASKS.md ## configure`](TASKS.md#configure).

## Audience

This skill serves **external operators and platform teams who deploy and
operate DMS** to manage NVIDIA® BlueField® networking platforms or
NVIDIA® ConnectX® SmartNICs from a centralized control plane. Concretely:
people running `dmsd`, integrating gNMI/gNOI clients against it, choosing
an authentication mode, or wiring DMS into a Kubernetes deployment.

It is **not** for NVIDIA developers contributing to DMS itself, and it
is **not** a programming guide for *building applications on top of*
DOCA libraries (that is `doca-programming-guide` plus the matching
library skill under `libs/`). DMS is a **service**, not a library: the
user invokes it as a daemon and talks to it over gRPC; they do not link
against `libdms.so` to write their own program.

**Status note.** Per the public DMS guide, DMS is currently in **beta**,
with General Availability scoped to SPC-X use cases. The skill reflects
the public guide's posture: prescribe the documented launch / auth /
deployment paths, follow the documented security best practices, and
defer roadmap and GA-scope questions to the live public guide rather
than guessing.

## When to load this skill

Load this skill when the user is doing **hands-on DMS operation work**
against a BlueField or ConnectX target where DOCA is already installed
on the management endpoint (host, DPU, or pod). Concretely:

- Deciding *where* DMS should run (host non-DPU / BlueField Arm /
  Kubernetes pod) for a given target topology.
- Bringing up the `dmsd` daemon — choosing SystemD vs manual launch,
  selecting an authentication mode, wiring `-allowed_users` (the gRPC
  client authorization boundary) and, if needed, `dmsgroup` (the
  `dmspe` backend-helper Unix group).
- Issuing `gNMI` `Get` / `Set` requests against modeled paths
  (e.g. `/interfaces/interface/config/mtu`).
- Issuing `gNOI` operations: OS install, reboot, file transfer,
  factory-reset, `mlxconfig`, containerz.
- Choosing an authentication mode (localhost / PAM / credentials / mTLS)
  and understanding the security trade-offs the public guide calls out.
- Reading or rotating DMS logs, configuring config persistency, or
  recovering from a crashed daemon.
- Debugging a DMS request that returned an error — separating
  "frontend rejected before reaching backend" from "backend executed and
  the underlying tool (e.g. `mlxconfig`) failed".

Do **not** load this skill for general DOCA orientation, install of
DOCA itself, or library-API questions. For those, route via
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md),
[`doca-setup`](../../doca-setup/SKILL.md), or the matching
`libs/<library>` skill.

## What this skill provides

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

- `CAPABILITIES.md` — DMS architecture (frontend `dmsd` / privileged
  backend `dmspe`), management protocols (gNMI, gNOI), the YANG-based
  unified configuration dictionary, deployment shapes, authentication
  modes with their security trade-offs, the configuration-persistency
  model, the logging surface, and DMS's documented security posture.
- `TASKS.md` — step-by-step workflows for the in-scope DMS verbs:
  `configure`, `build`, `modify`, `run`, `test`, `debug`, plus a
  `Deferred task verbs` block routing out-of-scope questions.

The skill assumes a host where DOCA is already installed and the
operator has root / `sudo` access where the public guide says it is
required. It does not cover installing DOCA — that path goes through
[`doca-setup`](../../doca-setup/SKILL.md).

## What this skill deliberately does not ship

This skill is **agent guidance**, not a templates or sample-config
bundle. To keep the boundary clean, it deliberately does not contain —
and pull requests should not add:

- **Pre-baked DMS configuration files** (YANG instance documents,
  full-stack example configs, ready-to-run `dmsd` flag bundles)
  intended to be copy-pasted into production. Configs are deployment-
  specific and the safe answer for an external operator is to derive
  them from the public guide against their own target. The agent's
  job is to prescribe the *procedure* and quote the documented flags
  and paths, not to ship a config the user might run unmodified.
- **Pre-written gNMI / gNOI client programs in any language.** The
  client surface is standard gNMI / gNOI (publicly documented); the
  skill describes which paths and operations DMS supports, not how to
  build a gRPC client in language X.
- **TLS material, credentials, or PAM stanzas.** These are
  user-environment artifacts; the skill points at the documented
  configuration knobs and the documented security best practices and
  stops there.
- **A `samples/`, `templates/`, or `reference/` subtree** of any
  kind. A mock or incomplete artifact in this skill's tree, even one
  labeled "reference", is misleading: operators will read it as
  production-ready.

## Loading order

1. Read this `SKILL.md` first to confirm the user's question is in scope.
2. **For the DMS architecture, deployment shapes, auth modes,
   protocol/path inventory, persistency, logging, and security
   posture, see [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run, test,
   debug — see [TASKS.md](TASKS.md).**

## Related skills

- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
  — the routing table to the public DMS guide and the rest of the
  public DOCA documentation set.
- [`doca-setup`](../../doca-setup/SKILL.md) — env preparation and
  install verification on the host where `dmsd` will run, including
  the *I have no install yet* path via the public NGC DOCA container.
  This skill assumes its preconditions are satisfied at the management
  endpoint.
- [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) —
  general DOCA patterns. DMS is service-shaped not library-shaped, so
  the build / modify / first-app pattern there does not apply directly,
  but the cross-library `DOCA_ERROR_*` taxonomy and the
  layered-debug order remain useful when DMS reports errors that
  originated in a DOCA library it called.