doca-dms

# DOCA Management Service (DMS)

> **⚠️ Destructive operations.** The gNOI `reboot`, `OS install`,
> `factory-reset`, and managed-file deletion 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 confirmation bound to
> that target and action. In an interactive session this is an explicit
> user reply naming/accepting both; in unattended execution it must be an
> approved-system authorization artifact bound to both. Otherwise stop
> with `confirmation_required`. 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 th