DOCA Management Service Guide

This guide explains how to use the DOCA Management Service (DMS) with the NVIDIA® BlueField® networking platform or NVIDIA® ConnectX® SmartNICs.

1. Introduction

Configuring a BlueField DPU or ConnectX NIC requires a different tool for each task: mlxconfig for FW parameters, devlink for E-switch settings, and mlnx_qos for traffic priorities. Each tool has its own syntax and quirks. Managing hundreds of devices this way is painful.

DOCA Management Service (DMS) is a centralized solution for configuring and operating BlueField and ConnectX devices.
It replaces the fragmented toolset with a single CLI (dms-cli) and a unified interface: one tool, one syntax, every feature, and every device.

1.1. Goals and Use Cases

DMS is built around two goals:

• Unified interface: One tool and one syntax replace the fragmented toolset, regardless of the feature or operation.

• Works at scale: Every command returns structured JSON, making it easy to script and automate across a fleet of devices.

What can you do with DMS?

• Install firmware or a BFB image: Update a ConnectX NIC or provision a BlueField DPU.

• Configure network settings: set port speed, enable or disable a port, configure bonding.

• Tune RoCE and QoS parameters: congestion control, priorities, and adaptive routing.

• Reset a device: factory reset or reboot.

• Automate at scale: script consistent configuration across a fleet of devices.

1.2. Key Concepts

1.2.1. Yang - the configuration map

DMS describes everything a device can do using YANG model files.
Think of YANG as a structured configuration map of your device. It is a tree-based data modeling language (XML syntax). Each feature is a branch, and each parameter is a leaf. The model is expressed in a human-readable format, making it easy to browse and understand what a device supports.
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
    }
  }
}

Every parameter DMS supports is defined this way - the YANG model is the single source of truth for what you can read, write, or trigger on a device.

1.2.2. XPath - your address in the map

Each parameter in the YANG tree has a unique path: an XPath.
It directly reflects the structure of the model: start from a feature area and navigate down to the specific parameter.
For example, the mode model above translates directly to: /nvidia/mode/operating-mode.

Lists: When a feature has multiple instances - for example, several CC algorithm slots or multiple ports, the YANG model represents them as a list.
The key name (id, name, etc.) is defined by the YANG model for that list.
You select a specific entry by adding a key in brackets:

/nvidia/cc/slot[id=0]/config/enabled    # slot 0
/nvidia/cc/slot[id=1]/config/enabled    # slot 1

To explore all the available paths on your device, use the command

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

1.2.3. Target - which device you are talking to

Use -t / --target to specify the target device by its PCIe BDF (Bus:Device.Function) address. When managing a VF or SF, append the 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

The representor suffix format is pf<N>vf<M> for virtual functions and pf<N>sf<M> for scalable functions, where N is the PF index and M is the VF/SF index.

2. System Components

2.1. 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. Reads the YANG model to validate the command and determine the operation type.

2. Runs the appropriate operation on the device HW.

Examples:

# 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
/opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 /nvidia/mode/operating-mode dpu

# Reset the device to factory defaults
/opt/mellanox/doca/services/dms/dms-cli /nvidia/reset/factory-reset

2.2. Yang Models

The configuration map that dms-cli reads to understand which paths exist, what types they accept, and which operations they support (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.

2.3. OS Tools

DMS runs the appropriate operation on the device according to the command sent, either by invoking system tools such as mlxconfig, devlink, and dcb, or via the DOCA Management SDK for operations that require direct hardware access (more on that in DOCA Management SDK).

3. YANG Models

Each YANG model covers one functional area under the flat /nvidia/ tree. All models are NVIDIA-native (not OpenConfig).
The YANG schema is the single source of truth for what you can read, write, or trigger. Explore it using the --tree command:

/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

Each YANG model covers one functional area under the flat /nvidia/ tree.
The table below lists all supported models grouped by category.

3.1. Networking & Interfaces

3.2. Device & Platform

3.3. Lifecycle & Operations

Note: 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.

4. DMS-CLI Flags

dms-cli is path-centric: GET, SET, and ACTION are deduced from the path and arguments (no --get / --set / --action flags).
dmsc is an installed alias for dms-cli (same binary invocation).

Default install path: /opt/mellanox/doca/services/dms/dms-cli (and dmsc beside it).

4.1. Common flags

4.2. Introspection flags

Introspection lets you explore what DMS supports without touching any device hardware.
All introspection operations read the installed YANG schema only. No device communication occurs, and --json has no effect.

More about introspection operations: https://nvidia.atlassian.net/wiki/spaces/docadevDOCS/pages/3473940710/DOCA+Management+Service+Guide#6.4.-Introspection

For the legacy OpenConfig-based workflow and older tooling, see the legacy DMS tool guide.

5. Operations

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

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

DMS uses a flat /nvidia/... tree: writable leaves are config. 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 config/state axis.

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

5.1. Get

Syntax

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

Examples

# 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.

5.2. Set

Syntax

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

Examples

# 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

Pending / reset-required leaves:

Note: Many NVConfig-backed leaves take effect only after device reset (or power cycle).
After SET, the running value may be unchanged while the companion *-pending leaf shows the next-boot value.
Check with GET on both the base leaf and *-pending, and with /nvidia/reset/required when applicable (Use --describe on a path to see the available leaves)

Example: Changing BlueField operating mode:
Switching from NIC to DPU mode requires a power cycle to take effect. To read the current mode and the pending value:

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

5.3. Actions

Syntax

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

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

Examples:

# Install an image/FW on a device (ConnectX FW / BlueField BFB / BF4 flows - see model inputs)
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 common actions: /nvidia/blueprints/plan|install|verify|..., /nvidia/artifacts/list|delete|get-info

5.4. Batch operations & target scoping

Single-container multi-leaf: several leaf=value arguments on one path (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).

Target scoping: one invocation addresses one -t. For multiple NICs/DPUs, run once per 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

Representors: -t pci/<BDF>,pf<N>vf<M> or pf<N>sf<M>. Optional query tail: ?port=N / ?scope=S - see https://nvidia.atlassian.net/wiki/spaces/docadevDOCS/pages/3473940710/DOCA+Management+Service+Guide#1.2.3.-Target---which-device-you-are-talking-to

6. Introspection

DMS lets you explore the YANG schema directly from the command line.
Discover what paths are available, understand what a specific parameter does, and see what values it accepts.
No hardware access is involved. introspection reads the schema only.
--json does not apply.

6.1. tree

Print the YANG schema subtree rooted at PATH as an indented tree.
Use it to browse which containers, lists, leaves, and actions are available under a given feature area.

Use --depth N together with --tree to limit how many levels deep the output goes (0 = unlimited, which is the default).

--depth requires --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

6.2. describe

Describe a single node or leaf: its YANG type, enumerated values, whether it is read-only or writable, and any descriptive text from the model.
Use --describe when you know a path but want to understand which values are valid before reading or writing it.
It is also the best way to see the input parameters of an action before running it.

--tree and --describe are mutually exclusive.

# 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

Use --tree to browse the structure of a path: what containers and leaves exist under it.
Use --describe to understand a specific node: its type, accepted values, and any constraints such as whether a reset is required after a change.

6.3. list-xpaths

Print every leaf XPath reachable under PATH (default: the full schema root).
Each line is a complete, directly addressable path to a readable or writable leaf. Use it to discover all settable and readable parameters in a feature area without reading the YANG model files.

# List all configurable 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

6.4. 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
    ...

7. Provisioning and Reset

When you deploy a new device or update an existing one, you need more than just configuration.
You need to install the right firmware or software image, verify what is currently running, and reset the device to apply changes.

DMS covers the full device lifecycle: staging and installing images, querying running and pending versions, checking whether a reset is needed, and executing it.
These operations are designed for deployment pipelines, fleet management scripts, and anyone bringing up or updating BlueField DPUs and ConnectX NICs at scale.

Unlike Get and Set, install and reset actions invoke external tools that can run for several minutes and may temporarily remove the device from the PCIe bus.
The lifecycle API is divided into four areas:

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

7.1. 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:

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

Discover available targets:

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

pci/0000:03:00.0
pci/0000:61:00.0

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

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

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

7.1.1. Supported Hardware Flows

Reset support is determined at runtime by mlxfwreset for the selected device.
Query /nvidia/reset/capabilities before selecting reset parameters.

7.2. 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.

Note: 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.

Supported artifact types are:

7.2.1. 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.

Stage a BlueField-3 BFB:

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

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

Stage a ConnectX firmware image:

/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:

/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

To replace an existing artifact:

/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:

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

7.2.2. List Artifacts

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

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

output:

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

7.2.3. Get Artifact Information

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

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

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.

7.2.4. Delete an Artifact

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

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

Example response:

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

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

7.3. Provisioning Install

/nvidia/provisioning/install starts one installation on one target. It has two mutually exclusive modes:

• Local mode uses source for ConnectX firmware, BlueField-3 BFB, or BlueField-4 NIC-mode PLDM.

• Out-of-band mode uses BMC credentials together with an ISO, a PLDM package, or both for BlueField-4 DPU mode.

7.3.1. Install Inputs and Source Rules

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.

7.3.2. Asynchronous Start Behavior

A successful install request starts the backend and returns immediately:

{
  "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.

If validation fails before a process is created, the install action returns status: failed, an empty log-ref, a non-empty message, and a nonzero command exit code.

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

7.3.3. Install ConnectX Firmware

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

Stage and inspect the image:

/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:

/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.

7.3.4. Install a BFB on BlueField-3

BlueField-3 BFB installation is a local, in-band operation. DMS maps the selected PCI target to its RSHIM device and starts doca-installer with the staged BFB.

Stage the BFB:

/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:

/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:

/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

The BFB integrity check runs during stage and again before doca-installer is started. A missing or invalid RSHIM mapping rejects the request before installation begins.

7.3.5. 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.

7.3.5.1. 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.

# 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

# 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_PASSWORD>'

The backend flow:

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

2. doca-installer starts a temporary HTTP service 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.

7.3.5.2. DPU mode - With cloud-init seed (CIDATA)

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

# 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

/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_PASSWORD>'

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

7.3.5.3. DPU mode - ISO from HTTP

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.

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

/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_PASSWORD>'

The URL must use HTTPS. The BMC must be able to resolve and reach the URL host.

7.3.5.4. DPU Mode - PLDM Out-of-Band

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

/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_PASSWORD>'

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

7.3.5.5. DPU Mode - ISO + PLDM Combined

An OOB PLDM package can be combined with a local ISO in one action. The backend stages PLDM first, then installs the OS.

/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_PASSWORD>'

▎ 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.

7.3.5.6. NIC Mode - PLDM local

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.

/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.

7.4. Version Queries

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

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

7.4.1. Get the Running ConnectX Firmware Version

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

The response includes:

• psid: device Parameter Set ID.

• fw-version: running firmware version.

• firmware-component: extensible component list.

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

• error-message: empty on success.

7.4.2. Get BlueField-3 Image Versions

/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.

7.4.3. Get BlueField-4 OOB Inventory

BlueField-4 inventory is read through its BMC:

/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_PASSWORD>'

For BlueField-4, use the firmware-component list as the primary inventory. The fixed bsp, doca, uefi, and atf fields are the BlueField-3 compatibility quartet and may be unknown when the OOB backend does not provide them.
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.

7.4.4. 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:.

/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: whether a difference was found.

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

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

• error-message: backend or validation failure detail.

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

7.5. Reset

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

After an installation reaches completed, follow this order:

1. Check required - is a reset needed?

2. Read message - what action does the device recommend?

3. Read suggested-reset - is a normalized DMS reset available?

4. Check capabilities - what levels and types does this device support?

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

7.5.1. Check Whether Reset Is Required

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

{
  "required": true
}

7.5.2. Read the Reset Message

> /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 free-form reasons and platform guidance. This is where DMS reports instructions that cannot be represented as a normalized device reset, including external host reboot or platform power-cycle requirements.

7.5.3. Get the Suggested Reset

> /opt/mellanox/doca/services/dms/dms-cli -t pci/0000:03:00.0 --json /nvidia/reset/suggested-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-resetis filled in only when DMS can derive a concrete reset command from the device status. There are two possible cases:

Case 1: A normalized DMS reset is available.

{
  "level": "driver-reset",
  "type": "full",
  "sync": "driver",
  "method": "link-disable"
}

In this case, verify the returned values against /nvidia/reset/capabilities, then use them with /nvidia/reset/execute.

Case 2: Reset is required, but no normalized DMS reset is available.

suggested-reset returns an empty object {}. This means the required action is not a normalized DMS device reset — for example, the platform may require an external host reboot or a platform power cycle. Follow /nvidia/reset/message instead. Do not invent reset parameters from an empty suggestion.

7.5.4. Get Reset Capabilities

> /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 and is reported as text guidance when applicable.

7.5.5. Execute a Reset

Prefer the values returned by /nvidia/reset/suggested-reset, and verify them against /nvidia/reset/capabilities.

Execute the normalized suggestion from the earlier example:

> /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 chooses a safe type-specific backend level:

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

• Other types use driver-reset.

Reset can temporarily remove the target from the PCI bus. 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:

/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

7.6. 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:

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

Output response:

# 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"
}

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

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.

7.7. Troubleshooting

7.8. Path Reference

8. Prerequisites and Dependencies

DMS requires a Linux-based environment with DOCA for Host installed using either the doca-networking or doca-all profile.
Refer to the DOCA Installation Guide for Linux for setup instructions.

The following packages must be present on the host.
dms-cli itself has no runtime dependencies. the packages below are invoked by the OS Tools layer when executing specific operations.

Last updated: September 01, 2026