Networking DOCA SDK Documentation

DOCA Management Service Guide

NVIDIA DOCA™ provides the DOCA Management Service (DMS) for supported operations on the NVIDIA® BlueField® networking platform and NVIDIA® ConnectX® SmartNICs.

If you used the legacy OpenConfig-based DMS, see Legacy OpenConfig-Based DOCA Management Service.

Introduction

Without DMS, configuration tasks use separate tools: mlxconfig for firmware parameters, devlink for E-switch settings, and mlnx_qos for traffic priorities.

DMS provides one CLI, dms-cli, for supported BlueField and ConnectX device operations.

Goals and Use Cases

Use DMS to:

  • Install firmware on a ConnectX NIC or a BFB image on a BlueField DPU.

  • Set port speed, enable or disable a port, and configure bonding.

  • Configure RoCE congestion control, QoS priorities, and adaptive routing.

  • Reset a device: chip/firmware-level reset (reboot, NIC-only, or Arm-only).

  • Apply consistent configuration across a fleet by using scripts.

System Components

dms-cli

dms-cli is the single entry point for all DMS operations. You run it directly on the host or Arm side. no server or daemon is required.

When you run a command, it:

  1. The CLI reads the YANG model to validate the command and determine the operation type.

  2. It runs the corresponding operation on the device hardware.

Backend-operation examples require root privileges or active dmsgroup membership. see Required Permissions.

For example:

JavaScript
# Read the current DPU operating mode
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode

# Switch to DPU mode (changes the BlueField operating mode, takes effect after a power cycle, plan a maintenance window)
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode dpu

# Reset the device (mlxfwreset-driven chip/firmware reset).
# Disruptive: the device leaves the PCIe bus and traffic and management sessions through it are interrupted. Run only in a maintenance window.
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/reset/execute level=driver-reset

The mode and reset examples change device state. Run them only on a device you intend to modify, not as part of a read-only check.

YANG Models

YANG models define the paths that dms-cli can use, the types those paths accept, and the supported operations (Get, Set, or Action).

/opt/mellanox/doca/services/dms/dms-cli --tree /nvidia                  # browse all available paths
/opt/mellanox/doca/services/dms/dms-cli --describe /nvidia/mode         # explain a specific path

DMS uses NVIDIA-native YANG models. Paths follow the /nvidia/... structure rather than the OpenConfig conventions used in the legacy interface.

For the full list of supported models and paths, see YANG Models.

OS Tools

DMS runs device operations through tools such as mlxconfig, devlink, and dcb. For operations that require direct hardware access, it uses the DOCA Management SDK.

image-20260809-091723.png

Before You Begin

DMS requires a Linux-based environment with DOCA for Host installed using either the doca-networking or doca-all profile.

Refer to the DOCA-Host Installation and Upgrade for setup instructions.

Required Permissions

Local operations that invoke the DMS backend, including device reads, writes, actions, and list-targets, require root privileges or membership in dmsgroup.

Users can run commands with sudo, for example:

sudo /opt/mellanox/doca/services/dms/dms-cli list-targets

Alternatively, an administrator can grant an authorized user access with the command below. Warning: dmsgroup membership lets the user run privileged device operations through the DMS backend, including firmware and BFB install, reset and mode changes. Add only trusted administrators.

sudo usermod -aG dmsgroup USERNAME

Replace USERNAME with the intended account. The user must log out and back in afterward.

Backend-operation examples without sudo assume root or active dmsgroup membership. Local --help, --tree, --describe, and list-xpaths do not require these privileges.

The following table lists packages and tools used by DMS. Requirements depend on the operation.

dms-cli itself has no runtime dependencies. The packages below are invoked by the OS Tools layer when executing specific operations.

Category

Packages or Tools

Purpose

Availability

DOCA SDK

doca-common, doca-mgmt

The packages provide the DOCA core runtime, including memory and platform abstractions, and the DOCA Management API for dispatching Get, Set, and Action operations.

Required

MFT (NVIDIA Firmware Tools)

mlxconfig, mlxreg, flint, mst

The tools read and set NIC firmware parameters, access registers directly, query firmware versions, flash ConnectX firmware, and enumerate devices for provisioning.

These tools are required for relevant operations. mst is required for provisioning.

Network Tools (iproute2)

devlink, dcb

E-switch mode, flow steering, NIC device parameters, and QoS trust-mode get/set. The dcb tool is preferred over mlnx_qos.

These tools are required for relevant operations.

MLNX_OFED

mlnx_qos, mlnx-tools / mlnx_fw_updater

DCB trust-mode fallback when dcb is unavailable, and the NIC firmware update path.

mlnx_qos provides a fallback. Firmware tools are required for firmware updates.

Provisioning (BlueField Only)

doca-installer, rshim (kernel driver), mlx-mkbfb

BFB and PLDM DPU provisioning, local BlueField-3 BFB installations, and BFB repackaging when injecting a configuration file.

These tools are required for relevant operations.

Runtime Libraries

libyaml, libpam

These libraries provide YAML parsing for YANG-to-tool mapping files and PAM authentication for agent-based mode.

libyaml is required. libpam is required for agent-based mode.

Optional

jq

JSON pretty-printing in reset tools.

The tool is optional. operations degrade gracefully if it is absent.

Discover Targets and Paths

Identify the device target and use the installed YANG schema to find supported paths and values before running an operation.

Key Concepts

YANG: The Configuration Map

YANG models define the management paths supported by DMS.

The schema organizes features and parameters as containers, lists, leaves, and actions. Use it to inspect supported paths and values.

For example, the DPU mode configuration model looks like this:

container mode {
   leaf operating-mode {
     type enumeration {
       enum nic;   // Standard NIC, ARM cores disabled
       enum dpu;   // DPU mode, ARM cores enabled
    }
  }
}

The model defines what DMS can read, write, or trigger for each path.

XPath: The Path to a Parameter

Paths in the YANG model identify parameters such as /nvidia/mode/operating-mode. For lists, include the key in brackets to identify a unique entry.

When a feature has multiple instances, such as CC algorithm slots or ports, its YANG model represents them as a list.

The model defines how list entries are selected. For CC algorithm slots, [0] and [1] select slot IDs 0 and 1. The enabled leaf is directly under the slot. there is no config level here:

/nvidia/cc/algo/slot/[0]/enabled    # slot ID 0
/nvidia/cc/algo/slot/[1]/enabled    # slot ID 1

To view all available paths in the installed model, run:

/opt/mellanox/doca/services/dms/dms-cli --tree /nvidia

Target: The Device to Manage

Use -t or --target to identify a device by its PCIe BDF (Bus:Device.Function) address. To manage a virtual function (VF) or scalable function (SF), append its representor suffix:

/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode        # target a specific device by BDF
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0,pf0vf5 /nvidia/icm/quota           # target VF5 on PF0
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0,pf0sf3 /nvidia/icm/quota           # target SF3 on PF0

Use pf<N>vf<M> for a VF and pf<N>sf<M> for an SF, where N is the PF index and M is the VF or SF index. Optional target query parameters include ?port=N and ?scope=S.

Scope

Target

System-Level

Not Required

Device or Port

pci/<BDF>

VF

pci/<BDF>,pf<N>vf<M>

SF

pci/<BDF>,pf<N>sf<M>

list-targets

Enumerate the device targets present on the local host.

The target field in each record is the value to supply to -t / --target. Use --json for machine-readable output suitable for scripting.

# List all available devices on the host

> /opt/mellanox/doca/services/dms/dms-cli list-targets

Device 1:
    chip_type=BF3
    func_type=PF
    iface_name=p0
    target=pci/0000:03:00.0
    ...
Device 2:
    chip_type=CX7
    func_type=PF
    iface_name=p1
    target=pci/0000:81:00.0
    ...

Introspection

Use the schema commands to discover paths and valid values without accessing device hardware. --tree, --describe, and list-xpaths read the installed YANG models. --json does not apply to them. list-targets enumerates local devices and supports JSON output.

tree

Use --tree to print the schema below a path as an indented tree of containers, lists, leaves, and actions.

Use --depth N with --tree to limit the output depth. The default, 0, is unlimited. --depth applies only to --tree.

# Full tree for path /nvidia/mode

> /opt/mellanox/doca/services/dms/dms-cli --tree /nvidia/mode
+--rw mode
   +--ro caps
      +--rw operating-mode   boolean
   +--rw operating-mode   device-mode
   +--ro operating-mode-pending   device-mode

describe

Use --describe to inspect a node's YANG type, accepted values, read or write status, model description, and constraints such as a required reset. For actions, it also shows input parameters.

You cannot combine --tree and --describe.

# Leaf with enums + annotation (power-cycle required)

> /opt/mellanox/doca/services/dms/dms-cli --describe /nvidia/mode
+--rw mode
   +--ro caps
      +--rw operating-mode (boolean)?
   +--rw operating-mode (enumeration)? [reset] [cap-mode-operating-mode]
   |     Values: nic, dpu
   +--ro operating-mode-pending (enumeration)? [cap-mode-operating-mode]
   |     Values: nic, dpu

list-xpaths

Print every leaf XPath reachable under PATH (default: the full schema root).

Each line is a readable or writable leaf path or path template. Supply list-key values in any template before using it. Use the command to discover all settable and readable parameters in a feature area without reading the YANG model files.

# List leaf paths under /nvidia/qos

> /opt/mellanox/doca/services/dms/dms-cli list-xpaths /nvidia/qos
/nvidia/qos/caps/both-trust-supported
/nvidia/qos/caps/dscp-trust-supported
/nvidia/qos/caps/pcp-trust-supported
/nvidia/qos/ets/prio-tc-map
/nvidia/qos/ets/tc-mapping/[<tc-index>]/tc-index
/nvidia/qos/ets/tc-mapping/[<tc-index>]/traffic-class
/nvidia/qos/pfc/enabled-priorities
/nvidia/qos/trust-mode

Operations

dms-cli does not use get / set / action subcommands. Operation type is deduced from the path and arguments:

Operation

Pattern

GET

The path ends at a container or leaf and has no =.

SET

The path or arguments contain = (leaf=value).

ACTION

The path points to a YANG action node.

Most device operations need -t / --target. Use dms-cli list-targets to discover BDFs.

DMS uses a flat /nvidia/... tree: writable leaves are configuration data. Read-only leaves use YANG config false (often named *-pending, oper-status, caps, etc.).

Some containers are still named config (for example, /nvidia/cc/config/). That is a feature name, not a configuration/state axis.

Default output is plain key: value. Add --json for structured JSON on GET/SET/ACTION (introspection ignores --json).

Get

Use one of the following forms:

dms-cli -t pci/<BDF> <path>                  # container: all readable leaves
dms-cli -t pci/<BDF> <path> <leaf> [...]     # container + leaf filter
dms-cli -t pci/<BDF> <path>/<leaf>           # single leaf

For example:

# Container
dms-cli -t pci/0000:03:00.0 /nvidia/mode
# operating-mode: dpu
# operating-mode-pending: dpu

# Single leaf
dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode
# operating-mode: dpu

# JSON
dms-cli --json -t pci/0000:03:00.0 /nvidia/mode/operating-mode
# { "operating-mode": "dpu" }

Subtree GET returns all readable leaves under that container. Leaf GET returns one value. There is no separate timestamp field in the CLI response envelope.

Set

Use one of the following forms:

dms-cli -t pci/<BDF> <path>/<leaf>=<value>              # single leaf
dms-cli -t pci/<BDF> <path> <leaf>=<value> [<leaf>=…]   # multi-leaf under container
dms-cli -t pci/<BDF> ... --dry-run                      # validate only

For example:

# MTU (netdev)
dms-cli -t pci/0000:03:00.0 /nvidia/link/netdev/mtu=9000

# QoS: trust-mode + PFC priorities
dms-cli -t pci/0000:03:00.0 /nvidia/qos trust-mode=dscp
dms-cli -t pci/0000:03:00.0 /nvidia/qos/pfc enabled-priorities=3,4,5

# Mode (BlueField)
dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode=dpu
# status: ok

Many NVConfig-backed changes remain pending until a device reset or power cycle.

After a SET operation, the running value can remain unchanged while its *-pending leaf shows the next-boot value. Query both leaves and, when applicable, /nvidia/reset/required. Use --describe to see the available leaves.

Example: After setting the BlueField operating mode to dpu, query /nvidia/mode to compare the running and pending values. A power cycle is required to activate the change:

dms-cli -t pci/0000:03:00.0 /nvidia/mode
# operating-mode: nic
# operating-mode-pending: dpu

CC Algorithm Slots and Counter Groups

CC algorithm slots use separate identifiers for slots and counter groups. A slot ID identifies an algorithm slot. A counter-group ID identifies a counter group. these are different identifiers.

Field

GET meaning

SET behavior

enabled

Whether the algorithm slot is enabled

Enable or disable the slot

counter-group-id

The slot’s stored main counter-group ID

Attach the requested group and enable counters

bound-counter-group-id

The list of groups currently owned by the slot

Read-only

The stored main counter-group ID does not prove ownership. It can remain stored after the slot loses ownership of that group. Use bound-counter-group-id to check current ownership.

The ownership list includes the main group when owned and any additional owned groups. It excludes histogram groups. A successful query with no owned groups returns []. a failed or unsupported query returns an error.

Setting counter-group-id attaches the requested group and enables counters. It does not necessarily replace the stored main ID:

  • If the slot still owns its existing main group, that main ID stays unchanged.

  • Otherwise, the requested group becomes the main group.

  • Ownership is exclusive: assigning a group owned by another slot transfers ownership.

  • Verify an assignment by checking that the requested ID appears in bound-counter-group-id. Do not require counter-group-id GET to equal the ID just written.

Example:

Before: stored main ID = 0, owned groups = [0]
After SET counter-group-id=1: stored main ID = 0, owned groups = [0,1]

This is a successful assignment: group 1 was added, while group 0 remained the main group.

Requirements:

  • The slot must already be enabled, or enabled=true must be included in the same SET request.

  • When using separate commands, enable the slot first.

  • Do not combine group assignment with enabled=false or counters-enabled=false.

  • The requested group ID must be supported by the selected application/device and must not exceed its reported max-counter-group-id.

  • Assigning counter-group-id enables counters, so a separate counters-enabled=true argument is unnecessary.

The following examples use slot 0 as an illustrative user-algorithm slot. They assume the algorithm is loaded and the requested group ID is supported. Replace the example PCI address as appropriate.

# Read only the slot’s enabled status
dms-cli -t pci/0000:03:00.0 '/nvidia/cc/algo/slot/[0]' enabled

# Read the stored main counter-group ID
dms-cli -t pci/0000:03:00.0 '/nvidia/cc/algo/slot/[0]' counter-group-id

# Read all counter groups currently owned by the slot
dms-cli -t pci/0000:03:00.0 '/nvidia/cc/algo/slot/[0]' bound-counter-group-id

# Enable the slot and attach group 1
dms-cli -t pci/0000:03:00.0 '/nvidia/cc/algo/slot/[0]' enabled=true counter-group-id=1

After the SET, use the ownership-list GET above to verify that group 1 appears. Do not expect a fixed ownership list for every starting state.

Reading enabled only requires the slot’s enabled status. it does not require the counter-group list. Request bound-counter-group-id when ownership information is needed.

Slot 15 is the special internal DCQCN slot. It supports enable, disable, and enabled-status queries, but the owned-group-list query is unsupported. Do not use slot 15 in counter-group assignment examples or describe its unsupported query as an empty list.

Actions

Use the following form:

dms-cli -t pci/<BDF> <action-path> [<param>=<value> ...]

Actions are one-shot operations with side effects (not leaf read/write).

For example:

# Install a staged firmware image, BFB, or BlueField-4 NIC-mode PLDM package
dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install source=staged:<name>

# Version queries
dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/fw/get-version
dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/image/get-versions

Other actions include /nvidia/blueprints/plan, /nvidia/blueprints/install, /nvidia/blueprints/verify, and the /nvidia/artifacts actions to list, delete, or inspect cached artifacts.

Batch Operations and Target Scoping

To set multiple leaves in one container, pass several leaf=value arguments on one path. DMS sends them in one backend call.

Cross-container batch: separate groups with ; (escape as \; in the shell). All groups must be the same type (all GET or all SET). Mixed GET+SET in one batch is rejected. All groups share one -t.

# Multi-container GET
dms-cli -t pci/0000:03:00.0 /nvidia/roce \; /nvidia/cc/np \; /nvidia/link

# Multi-container SET
dms-cli -t pci/0000:03:00.0 /nvidia/roce adaptive-routing=true \; /nvidia/cc/config user-programmable=true

There is no --request-file flag. Partial batch failure returns a partial-success result (status: partial with successes/failures).

One invocation addresses one -t target. To manage multiple NICs or DPUs, run a command for each target or script over list-targets:

dms-cli list-targets
# pci/0000:03:00.0
# pci/0000:81:00.0

dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode
dms-cli -t pci/0000:81:00.0 /nvidia/mode/operating-mode

For representor suffixes and target query parameters, see Target: The Device to Manage.

Provision Devices

Use DMS for device configuration, firmware or software image staging and installation, running and pending version queries, and reset checks and execution on BlueField and ConnectX devices. These operations can support deployment pipelines and fleet scripts.

DMS invokes external tools for installation and reset. These operations can run for several minutes and may temporarily remove the device from the PCIe bus.

Warning: install and reset are disruptive. Run them in a maintenance window, with out-of-band access (console or BMC) available, because the device can disappear from the PCIe bus and a management session that depends on that device, including SSH over a BlueField or ConnectX interface, can drop. Do not interrupt an operation that is in progress. Do not start a second install or reset on the same adapter. Poll /nvidia/operation/get-status until it reaches completed or failed.

The following API paths support these tasks:

Area

Path

Scope

Behavior

Artifact Cache

/nvidia/artifacts

System

Stages, lists, inspects, and deletes local files. These actions complete before returning.

Provisioning

/nvidia/provisioning

Device

Install ConnectX firmware, BlueField-3 BFBs, and BlueField-4 ISO or PLDM payloads. Installation is asynchronous.

Operation Status

/nvidia/operation/get-status

Device

Reports the latest install or reset operation for the selected physical adapter.

Reset

/nvidia/reset

Device

Reports reset state and capabilities and starts an asynchronous device reset.

The /nvidia/reset API performs a firmware or device reset through mlxfwreset.

It does not restore factory-default configuration.

Supported Hardware Flows

Device or Mode

Install Payload

Install Path

Version or Comparison

Activation Notes

ConnectX

Firmware Image (fw)

Local, Target-Scoped Firmware Burn

/nvidia/provisioning/fw/get-version

Query reset state after installation.

BlueField-3 DPU Mode

BFB with Optional Configuration File

Local, In-Band Through the Target's RShim Device

/nvidia/provisioning/image/get-versions and /nvidia/provisioning/image/diff

Query reset state after installation.

BlueField-4 DPU Mode

ISO, PLDM, or Both

Out-of-Band Through the DPU BMC

/nvidia/provisioning/image/get-versions with BMC inputs

PLDM activation requires an external full card power cycle.

BlueField-4 NIC Mode

PLDM

Local, Target-Scoped Update

Backend-Dependent

The local device must be resolvable through MFT/MST.

BlueField-2

None in This Release API

Not Applicable

Image version and diff operations return UNSUPPORTED when BlueField-2 is detected.

Use a supported legacy workflow where required. For the legacy interface, see Legacy OpenConfig-Based DOCA Management Service.

Reset support is determined at runtime by mlxfwreset for the selected device.

Query /nvidia/reset/capabilities before selecting reset parameters.

Lifecycle Workflow

The common lifecycle flow for provisioning and resetting a device:

  1. Discover the target PCI address with list-targets.

  2. Stage each local payload in /nvidia/artifacts.

  3. Start /nvidia/provisioning/install on one target.

  4. Poll /nvidia/operation/get-status on the same target until the operation reaches completed or failed.

  5. Query /nvidia/reset/required, and read /nvidia/reset/message.

  6. Run /nvidia/reset/execute when a device reset is appropriate. Follow /nvidia/reset/message when it calls for an external host reboot or platform power cycle instead.

  7. Verify running versions after activation.

Use the installed client in all examples:

Bash
/opt/mellanox/doca/services/dms/dms-cli

Discover available targets:

Bash
> /opt/mellanox/doca/services/dms/dms-cli list-targets

# Abbreviated output:
Device 1:
    ...
    target=pci/0000:03:00.0
Device 2:
    ...
    target=pci/0000:61:00.0

Use the value of the target attribute with -t. For automation, use list-targets with --json and read targets[].target.

The examples below use pci/0000:03:00.0. Replace it with the target returned for the device in the deployment.

A BMC hostname does not identify the DMS target. BlueField-4 out-of-band operations still use -t pci/<BDF> for DMS operation tracking, while bmc-host identifies the BMC used by the backend. The caller must supply the BMC that belongs to the selected device.

Use --describe to view the exact inputs supported by the installed version:

Bash
/opt/mellanox/doca/services/dms/dms-cli --describe /nvidia/provisioning/install
/opt/mellanox/doca/services/dms/dms-cli --describe /nvidia/reset/execute

Artifact Management

The /nvidia/artifacts actions manage the local cache used by provisioning. They are system-scoped, so they do not take -t.

The default cache directory is /var/lib/dms/artifacts, but callers use artifact keys rather than this internal path.

Artifact keys are names, not paths. They cannot contain path separators or traversal sequences.

A staged artifact is addressed by its key: staged:<name>

For example, an artifact staged as bf3.bfb is installed as source=staged:bf3.bfb.

An absolute input path refers to a file visible on the host where DMS executes, not a path on a remote client machine.

Staging is recommended for repeatable operation and inspection.

Obtain BFB, firmware, ISO and PLDM files only from NVIDIA or your trusted internal repository, and verify the checksum or signature published with the download before staging. DMS validation at stage time (mlx-mkbfb for BFB, flint for firmware) checks image integrity. do not rely on it as a substitute for verifying the source. Restrict write access to the directories that hold the source files and to the artifact cache.

Supported artifact types are:

Type

Purpose

bfb

BlueField Boot File for BlueField-3 Installation

iso

BlueField-4 Operating System ISO or CIDATA Seed ISO

fw

ConnectX Firmware Image

cfg

Optional BlueField-3 BFB Configuration File

pldm

BlueField-4 PLDM Firmware Package

other

Cached File Without a Provisioning-Specific Type

Stage an Artifact

/nvidia/artifacts/stage validates the request and copies a local file into the artifact cache.

The copy is committed atomically, so a partially copied file is not exposed as a completed artifact.

Input

Required

Description

input-file

Yes

Provide an absolute source path on the DMS execution host.

staged-file

No

The artifact key defaults to the base name of input-file.

type

No

Optionally specify bfb, iso, fw, cfg, pldm, or other. If omitted, DMS infers the type from the extension when possible.

force

No

Set force=true to replace an artifact with the same key. The default is false.

Stage a BlueField-3 BFB:

Bash
> /opt/mellanox/doca/services/dms/dms-cli --json /nvidia/artifacts/stage \
  input-file=/images/bf-bundle.bfb \
  staged-file=bf3.bfb \
  type=bfb

# output:
{
  "status": "completed",
  "type": "bfb",
  "error-message": ""
}

Without --json, successful local staging prints human-readable fields, such as status: completed and type: bfb.

Stage a ConnectX firmware image:

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/firmware/connectx.bin \
  staged-file=connectx.bin \
  type=fw

Stage BlueField-4 ISO and PLDM payloads:

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/images/bf4-os.iso \
  staged-file=bf4.iso \
  type=iso

/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/firmware/bf4.fwpkg \
  staged-file=bf4.fwpkg \
  type=pldm

Status

Meaning

completed

The file was validated as applicable and committed to the cache.

use-cached

The key already existed and force was not set. DMS kept the existing artifact.

failed

Validation, copying, type detection, or cache registration failed. The error-message describes the immediate error.

To replace an existing artifact:

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/images/bf-bundle-new.bfb \
  staged-file=bf3.bfb \
  type=bfb \
  force=true

DMS performs native non-destructive validation before copying installable BFB and ConnectX firmware images:

Type

Validation During Stage

Validation Before Install

bfb

Checks BFB integrity with mlx-mkbfb.

DMS repeats the check before starting doca-installer.

fw

Verifies the image with flint.

DMS repeats the check before starting the firmware burn.

iso, pldm, cfg, other

Checks the file, path, type, and cache.

Payload-specific validation is performed by the applicable backend tool.

Repeating BFB and firmware validation before install protects against a cached file being modified after staging.

List Artifacts

/nvidia/artifacts/list returns the artifact key, recorded type, and size in bytes for every valid cached artifact.

Bash
/opt/mellanox/doca/services/dms/dms-cli --json /nvidia/artifacts/list

For example, a response can contain:

JSON
{
  "files": [
    {
      "name": "bf3.bfb",
      "type": "bfb",
      "size": 1560281088
    },
    {
      "name": "connectx.bin",
      "type": "fw",
      "size": 4194304
    }
  ]
}

Get Artifact Information

/nvidia/artifacts/get-info inspects one cached artifact. name is the artifact key without the staged: prefix.

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/get-info name=bf3.bfb

Type

Information

bfb

The response includes size, BFB image versions, available firmware components, and raw doca-installer inspection output.

fw

The response includes size, firmware version, PSID, component versions, and raw flint output.

iso, pldm, cfg, other

The response includes type and size. Detailed ISO and PLDM validation occurs during installation.

The firmware-component entries use name, running-version, and pending-version. For a static artifact, running-version is the version reported by the inspection tool and pending-version is normally N/A because the file itself has no running/pending state.

Delete an Artifact

/nvidia/artifacts/delete removes one cached artifact and its type metadata.

Bash
/opt/mellanox/doca/services/dms/dms-cli --json /nvidia/artifacts/delete name=bf3.bfb

Example response:

JSON
{
  "success": true,
  "error-message": ""
}

Deletion fails when the key is invalid or the artifact does not exist.

Provisioning Install

/nvidia/provisioning/install starts one installation on one target. The supported CLI flow is local: the CLI runs on the DMS execution host, uses local artifact staging or host-visible paths for local payloads, and can pass BMC inputs for supported BlueField-4 out-of-band platform operations.

Install Inputs and Source Rules

Input

Mode

Description

source

Local

Use a staged artifact key (staged:<name>) or an absolute local path.

config-source

Local BlueField-3 BFB Only

Use a staged key or absolute path for an optional BFB configuration file.

bmc-host

BlueField-4 OOB

Specify the DPU BMC hostname or IP address. This value is required for out-of-band installation.

bmc-user

BlueField-4 OOB

Specify a BMC username, the default is admin.

bmc-password

BlueField-4 OOB

Specify the BMC password for out-of-band installation.

iso-source

BlueField-4 OOB

Provide a local or staged ISO. doca-installer temporarily serves it to the BMC.

iso-cidata-source

BlueField-4 OOB Local ISO

Provide an optional local or staged cloud-init CIDATA ISO.

iso-url

BlueField-4 OOB

Provide an HTTPS URL that the BMC downloads directly.

pldm-source

BlueField-4 OOB

Provide a local or staged PLDM firmware package. You can combine it with an ISO.

pldm-force

BlueField-4 OOB PLDM

This option requests backend ForceUpdate behavior when supported. The default is false.

The install action enforces these input rules:

  • source cannot be combined with BMC or OOB payload inputs.

  • iso-source and iso-url are mutually exclusive.

  • iso-cidata-source is valid only with iso-source. It cannot be used with iso-url.

  • OOB mode requires bmc-host, bmc-password, and at least one of iso-source, iso-url, or pldm-source.

  • config-source is valid only with a BFB source.

  • Generic URLs and PXE are not valid source values. Remote ISO is supported only through HTTPS iso-url.

  • Absolute paths bypass the artifact cache and must be visible on the DMS execution host. Staging is recommended for repeatable operation and inspection.

bmc-password is a plaintext input passed to the backend tool as a command-line argument. Any local user who can read process information (ps, /proc) can see it while the command runs.

  • Do not type the password inline. Read it into a shell variable (read -rs) so it stays out of shell history, and unset the variable afterward.

  • Use a dedicated BMC account with minimum required permissions instead of the default admin.

  • Do not commit commands containing the password to scripts, CI configuration or automation logs.

  • Treat DMS operation logs (/var/lib/dms/operations/logs) as sensitive and restrict access to them and to process information on the execution host.

Asynchronous Start Behavior

A successful install request starts the backend and returns immediately:

JSON
{
  "status": "in-progress",
  "log-ref": "/var/lib/dms/operations/logs/install-pci_0000_03_00.0-<timestamp>-<pid>.log",
  "message": ""
}

in-progress means that DMS accepted the request and created the backend process. It does not mean that installation succeeded. The final result is available through /nvidia/operation/get-status.

A request rejected before asynchronous work starts returns a nonzero command exit code. In plain mode, the CLI displays an error message. With --json, a normalized rejection uses status: error and error_msg. Earlier argument or schema validation failures may be reported differently. do not assume every rejection has the same JSON fields.

JSON
{
  "status": "error",
  "error_msg": "<reason the request was rejected>"
}

Only one install or reset can run on a physical adapter at a time.

Install ConnectX Firmware

ConnectX firmware installation uses a firmware artifact and a target-scoped flint burn.

Stage and inspect the image:

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/firmware/connectx.bin \
  staged-file=connectx.bin \
  type=fw

/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/get-info \
  name=connectx.bin

Start the installation:

Bash
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install source=staged:connectx.bin

DMS verifies the firmware image again immediately before starting the target-scoped firmware burn. After completion, query the running firmware version and reset state.

Install a BFB on BlueField-3

BlueField-3 BFB installation is a local, in-band operation and replaces the OS on the DPU. Back up the DPU configuration first. See the warning under Provision Devices. DMS maps the selected PCI target to its RShim device and starts doca-installer with the staged BFB.

Stage the BFB:

Bash
/opt/mellanox/doca/services/dms/dms-cli \
  /nvidia/artifacts/stage \
  input-file=/images/bf-bundle.bfb \
  staged-file=bf3.bfb \
  type=bfb

Start the installation:

Bash
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/provisioning/install \
  source=staged:bf3.bfb

To include an optional configuration file, stage it and provide config-source in the same action:

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/configs/bf.cfg \
  staged-file=bf3.cfg \
  type=cfg

/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  source=staged:bf3.bfb \
  config-source=staged:bf3.cfg

DMS checks BFB integrity during staging and again before starting doca-installer. A missing or invalid RShim mapping rejects the request before installation begins.

Install on BlueField-4

BlueField-4 supports several install flows depending on the device mode and payload type. Use --describe /nvidia/provisioning/install to see exact inputs for your installed version.

DPU Mode: Local ISO

BlueField-4 DPU-mode OS installation is out-of-band. The controller running DMS communicates with the BMC, and the BMC performs the platform operation.

Before starting, verify that:

  • The selected BMC belongs to the PCI target used with -t.

  • The DMS host can reach the BMC management interface.

  • The BMC can reach the DMS host for a locally supplied ISO.

  • The BMC firmware and ISO meet the requirements of the installed doca-installer release.

  • The BMC credentials are valid.

    Warning: bmc-password is passed as a command-line argument, so it is visible to other local users in ps and /proc/<pid>/cmdline while the command runs, and it is stored in shell history if typed literally. Do not type it inline. Read it into a shell variable instead, use a dedicated BMC account with minimum permissions, and avoid sharing the command output or logs. See the note under Install Inputs and Source Rules.

Bash
# Stage the ISO:
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/images/bf4-os.iso \
  staged-file=bf4.iso \
  type=iso

# Read the BMC password without echo (keeps it out of shell history):
read -rsp 'BMC password: ' BMC_PW; echo

# Start the OOB installation:
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  iso-source=staged:bf4.iso \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

The backend flow:

  1. DMS resolves the staged key to the local cached file.

  2. doca-installer starts a temporary HTTP service on the DMS host for the ISO.

  3. The BMC downloads the ISO from the DMS host and mounts it as virtual media.

  4. The BMC boots the installation media and reports progress through Redfish.

  5. doca-installer follows progress, ejects the media when appropriate, and stops the temporary service.

  6. DMS records the final backend result for /nvidia/operation/get-status.

The BMC must have a network route to the address and port selected on the DMS host.

Security note: while the service runs, any host that can reach that address and port can download the ISO. Do not put secrets, such as credentials or private keys, in the ISO or in a CIDATA seed. Use a dedicated, isolated management network between the DMS host and the BMC, and restrict that port with a firewall to the BMC address.

DPU Mode: With cloud-init Seed (CIDATA)

Stage the CIDATA ISO alongside the OS ISO and add iso-cidata-source:

Bash
# To provide a cloud-init seed, stage the CIDATA ISO and include it with the local OS ISO:

/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/images/cidata.iso \
  staged-file=cidata.iso \
  type=iso

read -rsp 'BMC password: ' BMC_PW; echo
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  iso-source=staged:bf4.iso \
  iso-cidata-source=staged:cidata.iso \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

The seed image must satisfy the CIDATA format and volume-label requirements of the installed provisioning tool.

The seed is served to the BMC like the OS ISO (see the security note above). Do not put passwords, SSH private keys or other secrets in it.

DPU Mode: ISO from HTTPS

When the ISO is already hosted at an HTTPS URL reachable by the BMC, staging is not required.

The BMC downloads the ISO directly - DMS does not download, stage, or serve it.

Bash
# ISO from HTTPS (BMC downloads directly, no staging needed):

read -rsp 'BMC password: ' BMC_PW; echo
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  iso-url=https://images.example.com/releases/bf4-os.iso \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

The URL must use HTTPS. The BMC must be able to resolve and reach the URL host. Do not rely on HTTPS alone to establish that the ISO is authentic. publish and verify the ISO checksum or signature from a trusted source. Do not embed credentials or long-lived tokens in the URL.

DPU Mode: PLDM Out-of-Band

In BlueField-4 DPU mode, PLDM firmware is staged through the BMC.

Bash
read -rsp 'BMC password: ' BMC_PW; echo
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  pldm-source=staged:bf4.fwpkg \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

Add pldm-force=true to request ForceUpdate behavior from the backend.

DPU Mode: ISO and PLDM Combined

An OOB PLDM package can be combined with either a local or staged ISO supplied through iso-source, or an HTTPS ISO supplied through iso-url. The HTTPS ISO input is part of the supported local CLI provisioning flow; it is not remote CLI mode. The backend stages PLDM first, then installs the OS.

Bash
read -rsp 'BMC password: ' BMC_PW; echo
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  pldm-source=staged:bf4.fwpkg \
  iso-source=staged:bf4.iso \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

Alternatively, combine the PLDM package with an HTTPS ISO:

Bash
read -rsp 'BMC password: ' BMC_PW; echo
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  pldm-source=staged:bf4.fwpkg \
  iso-url=https://images.example.com/releases/bf4-os.iso \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

iso-source and iso-url are mutually exclusive. iso-cidata-source is supported only with local iso-source. The documented PLDM activation requirement still applies.

The ISO flow can reset the Arm subsystem but does not activate the staged PLDM firmware. A full card power cycle is required after the combined operation completes. The currently running BMC must already satisfy the ISO installation requirements.

The PLDM activation reminder appears in the initial install response. It is not carried forward into the persisted operation-status message. Reset queries independently report mlxfwreset status and do not track the OOB PLDM activation requirement. Retain the activation requirement from the installation flow, perform the required platform action, and verify running/pending versions afterward. A later completed operation or a host reset-status result is not proof that the staged PLDM firmware has become active. DMS does not perform the external power cycle automatically.

NIC Mode: Local PLDM

In BlueField-4 NIC mode, the DPU BMC is not used. DMS resolves the PCI target to its local MST device and invokes the target-scoped in-band backend.

Bash
/opt/mellanox/doca/services/dms/dms-cli /nvidia/artifacts/stage \
  input-file=/firmware/bf4.fwpkg \
  staged-file=bf4.fwpkg \
  type=pldm

/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/install \
  source=staged:bf4.fwpkg

This flow requires the target to be available through the local MFT/MST device inventory.

Verify and Reset Devices

Monitor operations, inspect reported versions, and follow the device's reset guidance.

Monitor Operations

Both /nvidia/provisioning/install and /nvidia/reset/execute are asynchronous. The selected target is the operation handle. There is no separate operation ID.

Poll the same target used to start the action:

Bash
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/operation/get-status

Example responses:

JSON
# While an install is running:
{
  "status": "in-progress",
  "op-type": "install",
  "message": "",
  "log-ref": "/var/lib/dms/operations/logs/install-pci_0000_03_00.0-<timestamp>-<pid>.log"
}

# Completed reset
{
  "status": "completed",
  "op-type": "reset",
  "message": "",
  "log-ref": "/var/lib/dms/operations/logs/reset-pci_0000_03_00.0-<timestamp>-<pid>.log"
}

Status

op-type

Meaning

idle

none

No operation has been recorded for this target.

in-progress

install or reset

The backend process is still running.

completed

install or reset

The operation reached the completed state. inspect message for completion warnings. For installations performed by doca-installer, backend exit code 2 is recorded as completed with a warning that one or more components were skipped or could not be fetched or verified. Therefore, completed does not always mean every component was installed and verified. The exit-code-2 exception applies only to doca-installer installations. nonzero exits from flint and mlxfwreset are treated as failures. Inspect message, the operation log, and running/pending versions before accepting the result.

failed

install or reset

The backend failed, exited unexpectedly, or is no longer running. Read message and log-ref.

The log is stored on the DMS execution host. Use the exact log-ref returned by the action or status response:

Bash
tail -f /var/lib/dms/operations/logs/<operation-log>.log

For automation, evaluate the returned status field. /nvidia/operation/get-status is a successful query even when it reports status: failed, so the command itself can return exit code 0. By contrast, an install or reset request rejected before asynchronous work starts returns a nonzero command exit code.

Version Queries

Version queries answer different questions depending on what you need to inspect:

Operation

Question Answered

/nvidia/artifacts/get-info

What versions or metadata are present in this cached file?

/nvidia/provisioning/fw/get-version

What firmware is running on this ConnectX target?

/nvidia/provisioning/image/get-versions

What image or firmware components are running on this BlueField target?

/nvidia/provisioning/image/diff

How does a staged BlueField-3 BFB differ from the running BlueField-3 image?

These operations cover device firmware and image versions only. they do not cover host software packages such as MFT or the Linux kernel.

Get the Running ConnectX Firmware Version

Bash
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/fw/get-version

The response includes:

  • psid: Identifies the device Parameter Set ID.

  • fw-version: Reports the running firmware version.

  • firmware-component: Lists extensible firmware components.

  • raw-output: Provides complete flint output for diagnostics.

  • error-message: Is empty on success.

Get BlueField-3 Image Versions

Bash
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/image/get-versions

The response includes the classic bsp, doca, uefi, and atf fields, an extensible firmware-component list, raw-output, and error-message.

A value can be unknown or N/A when the backend does not report that component.

Use error-message and the command exit code to distinguish unavailable metadata from an operation failure.

Get BlueField-4 OOB Inventory

BlueField-4 inventory is read through its BMC:

Bash
read -rsp 'BMC password: ' BMC_PW; echo
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/provisioning/image/get-versions \
  bmc-host=bf4-bmc.example.com \
  bmc-user=admin \
  bmc-password="$BMC_PW"

unset BMC_PW

For BlueField-4 OOB inventory, the bsp, doca, uefi, and atf compatibility fields currently always return unknown. Use the firmware-component list for running and pending component versions.

Each component contains its running version and a pending version when the BMC reports one, otherwise pending-version is N/A.

DMS does not verify that bmc-host belongs to the selected PCI target. Check bmc-host before running; a wrong value sends the credentials to that host.

Compare a BlueField-3 BFB with the Running Image

/nvidia/provisioning/image/diff is a synchronous BlueField-3-only comparison. The BFB must already be staged, and image-name is the artifact key without staged:.

In the current implementation, the staged artifact key used for image/diff must retain a .bfb extension. The comparison identifies the image type from the cached filename rather than the recorded artifact type. Setting type=bfb during staging is insufficient if the staged key has no .bfb extension. This filename requirement is a current comparison limitation and does not apply to all artifact operations.

Bash
/opt/mellanox/doca/services/dms/dms-cli --json \
  /nvidia/artifacts/stage \
  input-file=/images/bf-bundle-new.bfb \
  staged-file=bf3-new.bfb \
  type=bfb

/opt/mellanox/doca/services/dms/dms-cli \
  -t pci/0000:03:00.0 --json \
  /nvidia/provisioning/image/diff \
  image-name=bf3-new.bfb

The response includes:

  • has-changes: Indicates whether a difference was found.

  • diff-text: Contains human-readable backend comparison output.

  • component-diff: Contains parsed current and staged component versions when available.

  • error-message: Contains backend or validation failure details.

has-changes: true is a successful comparison result, not an action failure.

Reset

The /nvidia/reset API performs a firmware or device reset through mlxfwreset. It does not restore factory-default configuration.

For BlueField-4 OOB PLDM staging, host reset queries do not confirm PLDM activation or replace the required external full-card power cycle. Follow the PLDM activation instructions and verify running/pending versions afterward.

After an installation reaches completed, follow this order:

  1. Check /nvidia/reset/required to determine whether an activation action is needed.

  2. Read /nvidia/reset/message for the device's recommended action.

  3. Read /nvidia/reset/suggested-reset to see whether DMS can provide a normalized reset.

  4. Check /nvidia/reset/capabilities for the levels and types supported by the device.

  5. Run /nvidia/reset/execute only when a device reset is the appropriate action.

Check Whether Reset Is Required

Bash
> /opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/reset/required

{
  "required": true
}

Value

Meaning

true

The backend reports that a reset, reboot, power cycle, or other activation action is required.

false

The backend explicitly reports that no action is required.

unknown

Status timed out, is unavailable, or cannot be parsed reliably. Read message and do not assume that no reset is required.

Read the Reset Message

Bash
> /opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/reset/message

{
  "message": "Driver restart and PCI reset (Level 3). Pending NVCONFIG parameter change"
}

message contains the guidance DMS was able to extract from the backend. An unsupported backend reset level may be omitted from the normalized suggestion, and the original recommendation is not always preserved in message. Host warm reboot is outside the public DMS reset-level API.

If the suggestion is incomplete or the message does not explain the required action, inspect the backend’s read-only status directly on the DMS execution host:

Bash
mlxfwreset -d <BDF> status --json

<BDF> is the bare PCI address, for example 0000:03:00.0, without the pci/ prefix.

Get the Suggested Reset

Bash
> /opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/reset/suggested-reset

A driver reset stops the NIC driver, resets the device over PCIe, and restarts the driver. The device temporarily disappears from the bus during the sequence.

suggested-reset values may be complete, partial, or empty. Read required, message, and capabilities together before choosing an action.

  • A complete normalized DMS reset can include all fields, for example:

    JSON
    {
      "level": "driver-reset",
      "type": "full",
      "sync": "driver",
      "method": "link-disable"
    }
    
  • A partial suggestion can contain only some fields, such as level without type, sync, or method. Do not infer missing parameters or blindly execute a partial suggestion. Confirm that the selected parameters preserve the backend recommendation.

  • An empty suggestion does not by itself mean an external reboot or power cycle is required. It can occur when no reset is required, status is unavailable, or DMS cannot translate the backend recommendation. Even with required=true, an empty suggestion means DMS did not produce usable normalized parameters. it does not identify the required external action.

Get Reset Capabilities

Bash
> /opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/reset/capabilities

{
  "default-level": "driver-reset",
  "default-type": "full",
  "supported-levels": ["driver-reset"],
  "supported-types": ["full", "phy-less", "arm-only", "arm-os-shutdown"]
}

Capabilities are best-effort and target-specific. DMS exposes device reset levels supported by its public model. Host warm reboot is intentionally outside this API. message contains only the guidance DMS was able to extract from the backend, and unsupported backend recommendations are not always preserved there.

Execute a Reset

Prefer complete values returned by /nvidia/reset/suggested-reset, and verify them against /nvidia/reset/capabilities. Do not blindly execute a partial suggestion: omitted parameters can use DMS defaults that may differ from the original backend recommendation.

Input

Values

Description

level

live-patch, driver-reset

Selects the public reset level.

type

full, phy-less, nic-only, arm-only, arm-os-shutdown

Selects the reset scope. BlueField-only types are available only where applicable.

sync

tool, driver, fw

Selects the component responsible for reset synchronization.

method

link-disable, hot-reset

Selects the PCIe reset method.

force

true, false

Reserved for a future DMS precheck bypass. It does not bypass operation locks or backend validation.

Execute the normalized suggestion from the earlier example:

Bash
> /opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/reset/execute \
  level=driver-reset \
  type=full \
  sync=driver \
  method=link-disable

{
  "status": "in-progress",
  "log-ref": "/var/lib/dms/operations/logs/reset-pci_0000_03_00.0-<timestamp>-<pid>.log",
  "message": ""
}

If level is omitted, DMS selects a type-specific default:

  • arm-only and arm-os-shutdown use the internal immediate level.

  • Other types use driver-reset.

These defaults do not establish that the selected reset satisfies the backend recommendation.

Reset can temporarily remove the target from the PCI bus and can interrupt traffic and management sessions that use the device. Do not interrupt it or power-cycle the host while the status is in-progress. Continue polling /nvidia/operation/get-status with the same target. Operation status remains available from persisted DMS state even while the hardware is absent.

After the reset reaches a terminal state, re-query reset required and running versions:

Bash
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/operation/get-status
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json  /nvidia/reset/required

Troubleshooting and Reference

Use these tables to troubleshoot lifecycle operations and look up supported YANG models, CLI flags, and lifecycle paths.

Troubleshooting

Result

Meaning and Next Check

Artifact Staging Returns use-cached

The existing key was retained. Use get-info, choose another key, or stage with force=true.

backend fork/exec …/dmspe: permission denied

Run with sudo or ask an administrator to add your account to dmsgroup, then log out and back in. Refer to Required Permissions.

Install or Reset Request Is Rejected Before Starting

The request exited nonzero before asynchronous work started. Inspect the CLI error and correct the source, type, target, or required inputs. With --json, a normalized rejection can use status: error and error_msg. earlier validation failures may differ.

Install or Reset Returns in-progress

The operation only started. Poll /nvidia/operation/get-status.

Operation Status Remains in-progress

Inspect log-ref for backend progress. Long BFB and ISO operations may produce lengthy logs.

Operation Status Returns failed

Read message and the operation log. The status query itself can still return command exit code 0.

operation already in progress

Another install or reset owns the physical adapter's operation slot. Wait for its terminal status.

staged source not found

Confirm the artifact key with /nvidia/artifacts/list. Do not include a filesystem path after staged:.

Source Type Mismatch

Use the input that matches the artifact type, such as iso-source for ISO and pldm-source for OOB PLDM.

BlueField-3 Install Cannot Resolve RShim

Verify RShim availability and its PCI mapping on the DMS host.

Local PLDM or Image Query Cannot Resolve MST

Verify MFT/MST installation and that the target appears with a usable MST device.

BlueField-4 OOB Operation Cannot Reach an Image

Verify controller-to-BMC connectivity and, for local ISO, BMC-to-controller connectivity. For iso-url, verify BMC-to-URL connectivity.

Reset required Is unknown

Read message, check mlxfwreset availability and target support. Do not interpret unknown as false.

Reset Suggestion Is Partial or {}

Read required, message, and capabilities together. An empty suggestion does not by itself prove that an external reboot or power cycle is required, even when required=true. Do not infer missing reset parameters or execute an incomplete suggestion unless you have confirmed the selected parameters preserve the backend recommendation. If needed, inspect read-only backend status on the DMS host with mlxfwreset -d <BDF> status --json.

YANG Models

Each NVIDIA-native YANG model covers one functional area under /nvidia/. These models do not use OpenConfig conventions.

Use --tree to browse supported paths in the installed schema:

/opt/mellanox/doca/services/dms/dms-cli --tree /nvidia                # browse all available paths
/opt/mellanox/doca/services/dms/dms-cli --describe /nvidia/cc         # explain a specific container

The following tables list supported models by category.

Networking and Interfaces

Model

Path

Covers




nvidia-root

/nvidia

Root Container and Entry Point for All Paths

nvidia-link

/nvidia/link

Link Administrative and Operational State, Netdev MTU, Physical Port (PAOS), Link Type, Keep-Link-Up Policy, IPG, and Breakout

nvidia-lag

/nvidia/lag

LAG Resource Allocation Strategy (HWLB Prerequisite, Not Classic Bonding Configuration)

nvidia-eswitch

/nvidia/eswitch

E-Switch Mode (legacy/switchdev), Flow-Steering Mode, Multiport, and Flex Parser Profile

nvidia-multiplane

/nvidia/multiplane

Multi-Plane or Multipath: Number of Planes and Load-Balance Mode

nvidia-qos

/nvidia/qos

QoS Trust Mode, PFC Priorities, and ETS Priority-to-TC Mapping

nvidia-roce

/nvidia/roce

RoCE Adaptive Routing, Multipath DSCP, RTT, ToS, and ACCL (slow-restart, tx-window, selective-repeat, and Related Settings)

nvidia-cc

/nvidia/cc

Congestion Control: User-Programmable CC, Shaper Coalesce, Algorithm Slots and Parameters, NP/RP Global Status, and NP CNP Settings

nvidia-data-direct

/nvidia/data-direct

VF/SF Data-Direct Enable/Disable

nvidia-icm

/nvidia/icm

ICM (Initiator Connection Manager) Quota Settings

Device and Platform

Model

Path

Covers

nvidia-platform

/nvidia/platform

Platform and Orchid system-conf Operations

nvidia-mode

/nvidia/mode

BlueField Operating Mode (nic or dpu) and Pending Next-Boot Value

nvidia-pci

/nvidia/pci

PCIe and SR-IOV: Enablement, Maximum VFs, Runtime VF Count, BAR Size, and PF Count

nvidia-nvconfig

/nvidia/nvconfig

Bulk NVConfig Apply: Typed DMS Intent and Optional Raw TLVs via mlxconfig

nvidia-emulation

/nvidia/emulation

Typed Emulation-Manager Controls (virtio-net and NVMe) for Delegated PF Targets

nvidia-misc

/nvidia/misc

Miscellaneous Device Settings (for example, Flex Parser Profile)

nvidia-raw

/nvidia/raw

Raw Register Access, HCA Capabilities, and Raw NVConfig Query or Modification

Lifecycle and Operations

Model

Path

Covers

nvidia-artifacts

/nvidia/artifacts

Local Artifact Cache: Stage, List, Get-Info, and Delete (BFB, FW, ISO, PLDM, and CFG)

nvidia-provisioning

/nvidia/provisioning

Firmware, BFB, and Image Installation and Version Queries (ConnectX and BlueField)

nvidia-blueprints

/nvidia/blueprints

Profile-Based NIC Provisioning Plans (for example, Spectrum-X or MRC): Plan, Install, Verify, and Cleanup

nvidia-reset

/nvidia/reset

Device Reset: Required and Suggested Status, Capabilities, and execute Action

nvidia-operation

/nvidia/operation

Looks up asynchronous install or reset status by selected target.

nvidia-diagnostics

/nvidia/diagnostics

Diagnostics Data Interface (Multi-Domain Diagnostic Ownership)

Paths shown at runtime may be filtered by target and device capability. Use -t with --tree / --describe to see what applies to a specific device.

DMS-CLI Flags

The default CLI path is /opt/mellanox/doca/services/dms/dms-cli; dmsc is an installed alias in the same directory. DMS infers GET, SET, or ACTION from the path and arguments, so there are no --get, --set, or --action flags.

Common Flags

Flag

Short

Description

--target

-t

Specifies the device target. Format: pci/<BDF>[,<rep-suffix>][?port=N&scope=S].

--json


Outputs GET, SET, and ACTION results as JSON,it does not apply to schema introspection.

--dry-run


Validates the request without writing or executing it.

--verbose

-v

Shows debug information.

--help

-h

Shows usage information.

Introspection Flags

--json applies to list-targets output but not to --tree, --describe, or list-xpaths, which read the installed YANG schema without contacting a device.

For examples of these operations, see Introspection.

Flag

Description

--describe

Describe the node or leaf at PATH.

--depth

Set the maximum subtree depth with --tree (0 means unlimited).

--tree

Print the schema subtree for PATH.

For the legacy OpenConfig-based workflow and older tooling, see the Legacy OpenConfig-Based DOCA Management Service.

Lifecycle Path Reference

Path

Operation

Scope

Purpose

/nvidia/artifacts/stage

Action

System

Validate as applicable and cache a local artifact.

/nvidia/artifacts/list

Action

System

List artifact keys, types, and sizes.

/nvidia/artifacts/get-info

Action

System

Inspect one artifact's metadata and available versions.

/nvidia/artifacts/delete

Action

System

Delete one artifact.

/nvidia/provisioning/install

Action, Asynchronous

Device

Start ConnectX, BlueField-3, or BlueField-4 provisioning.

/nvidia/provisioning/fw/get-version

Action

ConnectX Device

Query running ConnectX firmware.

/nvidia/provisioning/image/get-versions

Action

BlueField Device

Query BlueField-3 local or BlueField-4 OOB image and firmware inventory.

/nvidia/provisioning/image/diff

Action

BlueField-3 Device

Compare a staged BFB with the running image.

/nvidia/operation/get-status

Action

Device

Query the latest asynchronous install or reset state for the adapter.

/nvidia/reset/required

Get

Device

Return true, false, or unknown.

/nvidia/reset/message

Get

Device

Return reset reasons and platform guidance.

/nvidia/reset/suggested-reset

Get

Device

Return a normalized reset command when available.

/nvidia/reset/capabilities

Get

Device

Return supported and default reset levels and types.

/nvidia/reset/execute

Action, Asynchronous

Device

Start a target-scoped device reset.

Last updated: