DOCA Documentation v3.1.0

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.

Warning

DOCA Management Service is currently in alpha stage. Exercise caution when running dmsd over an external interface, as it may pose security risks. Apply appropriate mitigations and restrict access to the DMS accordingly. Use at your own risk.

DOCA Management Service (DMS) is a centralized solution for configuring and operating NVIDIA® BlueField® and ConnectX® devices.

DMS consolidates NVIDIA’s internal scripts and tools under a streamlined, industry-standard API based on OpenConfig. Users can configure BlueField or ConnectX devices either locally (via SSH) or remotely (via gRPC).

DMS exposes configurable parameters for BlueField and ConnectX over the external interface, enabling automated configuration from a management station. The interface offers a consistent and unified approach to device configuration while abstracting away the underlying tools used to manage individual features.

DMS follows a client-server architecture. The server component, DMS Daemon (dmsd), is responsible for resource discovery and for processing incoming commands from clients. These clients can be either the provided DMS Client (dmsc) or a custom-built client using the same API.

Open Config and YANG Models

  • OpenConfig is a standard that defines and implements a common, vendor-independent software layer for managing and monitoring network devices.

    It utilizes YANG data models to represent device configurations and operational states in a consistent and standardized format.

    Most gNMI/gNOI protocols used in DMS are aligned with the OpenConfig community and rely on the gRPC protocol for command transmission.

  • YANG (Yet Another Next Generation) is a data modeling language used to describe the structure and content of network configuration and state data.

    It represents data hierarchically, similar to an XML tree, and defines schemas for configuration, operational state, and remote procedure calls (RPCs). YANG models serve as the foundation for implementing the OpenConfig standard.

Note

The DOCA YANG model is currently experimental.

Note

The gNMI Subscribe mechanism for streaming telemetry is not yet supported

Info

DMS can run either on the host machine where BlueField or ConnectX devices are installed, or directly on the BlueField Arm cores when operating in DPU mode .


To operate the DMS, DOCA must be installed on the system where DMS will run.

  • DMS on Host – The DOCA for Host package must be installed on the host system. It should be installed using either the doca-networking or doca-all profile.

  • DMS on DPU (BlueField Arm) – A compatible DOCA image must be installed on the BlueField Arm processor.

Info

Consult the DOCA Installation Guide for Linux to correctly set up the required DOCA components prior to deploying DMS.

Note

Supported operating systems are Linux-based environments.

DMS has 3 major components:

  • DMSD – Server – DMS server can run on the BlueField ARM or on the host with an NVIDIA PCIe device

  • DMSC – Client – DOCA provided OpenConfig client. Customers can choose to use this client, any other open-source client, or develop their own (gRPC-based) client.

  • Yang files – Yang model files contain the data model used to configure the device, using NVIDIA-specific extension to common OpenConfig YANG Models.

OpenConfig consists of 2 main protocols:

  • gNMI – gRPC Network Management Interface, protocol to configure of network device.

  • gNOI – gRPC Network Operations Interface, a protocol to perform operational commands on network devices (i.e., provision, upgrade, reboot).

Service Connectivity

The following is an architectural diagram of DMS:

Screenshot_2024-04-07_095621-version-1-modificationdate-1747568281917-api-v2.png

The following diagram presents the DMS modes of operation, as the DMS client can operate from different location:

  1. Both DMS client and server components are deployed on the Host.

  2. Both DMS client and server components are deployed on DPU (BlueField Arm).

  3. DMS server component is deployed on the Host, while DMS client is deployed remotely (connecting to DMS server over management network).

  4. DMS server component is deployed on DPU (BlueField Arm), while DMS client is deployed remotely (connecting to DMS server over management network).

dms_modes_for_confluence-version-1-modificationdate-1747568279603-api-v2.png

DMS Daemon Launch Options

Option 1: SystemD Service (Recommended)

On the DPU, the DMS Daemon (dmsd) runs as a systemd service and comes pre-installed with the BlueField BFB-Bundle.

It should be running locally by default as a systemd service, bound to localhost:9339.

  • To check if dmsd is running:

    Copy
    Copied!
                

    ps -ef | grep dms

  • To manage the service:

    Copy
    Copied!
                

    sudo systemctl status dmsd sudo systemctl start dmsd sudo systemctl stop dmsd

  • To interact with dmsd using the built-in client (requires user-password authentication; the default is the OS root password):

    Copy
    Copied!
                

    dmscli

  • A template systemd service file is included in the DOCA package:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsd.service/dmsd.service

    Note

    dmsd runs automatically as a systemd service only on the DPU, not on the host.

Option 2: Manual Launch

You can start the dmsd daemon manually with a variety of authentication methods.

  1. Localhost with username/password:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsd \ --bind_address localhost:9339 \ --auth credentials \ --username my_username \ --password my_password

  2. Remote host with shadow file:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsd \ --bind_address <ip>:<port> \ --auth shadow \ --username my_username \ --shadow /etc/shadow

  3. TLS certificate-based authentication:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsd \ --bind_address localhost:9339 \ --auth cert \ --ca <ca.pem> \ --tls_key_file <key.pem> \ --tls_cert_file <cert.pem>

  4. Specific PCIe device (for a host with multiple DPUs):

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsd \ --bind_address localhost:9339 \ --auth credentials \ --username my_username \ --password my_password \ --target_pci 0000:08:00

  5. Provide a list of PCIe devices (for a host with multiple DPUs):

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsd \ --bind_address localhost:9339 \ --auth credentials \ --username my_username \ --password my_password \ --target_pci 0000:08:00,0000:09:00

DMS Server Flags

To see the full list of flags, use the help flag (i.e., dmsd --help, dmsd -h).

General Flags

  • --bind_address <string> – Bind to <address>:<port> or just :<port> (default is :9339). Can be localhost for the local use case, or an IP address for the remote use case.

  • -v <value> – log level for V logs

  • --target_pci <string> – One or multiple target PCIe addresses (i.e., 0000:03:00, 0000:03:00,0000:04:00). Auto-select if only one NVIDIA network device is present; otherwise, one or more PCIe addresses must be specified.

Provisioning Flags

  • --image_folder <string> – Specify the image install folder. Can copy images directly to the folder to avoid transfer over the net. Default create folder: /tmp/dms.

  • --chunk_size_ack <uint> – The chunk size of the image to respond with a transfer response in bytes (default: 12000000)

  • --exec_timeout <uint> – The maximum execution timeout in seconds for a command if not responding (not printing to stdout); 0 (default) is unlimited

Config Flags

  • --init_config <string> – File containing gNMI requests to run on DMS start. By default, DMS adds any gNMI set request to a file (file format is req.json).

Authentication Method Flags

The --auth <string> flag specifies one of the following three authentication methods, each with its own set of required flags:

Shadow

  • Zero-touch setup – no need to create a dedicated DMS user (reuses existing OS user)

  • The server reads the hashed password from the shadow file in real time for each client request

  • Required flags: --username <string> and --shadow <string>

    • Example:

      Copy
      Copied!
                  

      --auth shadow --username root --shadow /etc/shadow

  • To disable authentication:

    Copy
    Copied!
                

    --noauth

Credentials

  • Requires the admin to define a strong password.

  • Required flags: --username <string> and optionally --password <string>

    • Example:

      Copy
      Copied!
                  

      --auth credentials --username root --password 123456

  • To prompt for password input interactively at startup, leave the --password flag empty.

  • To disable authentication:

    Copy
    Copied!
                

    --noauth

Certificate (TLS)

  • The most secure option, using Transport Layer Security (TLS) for both encryption and mutual authentication.

  • Authentication is based on digital certificates, ensuring only trusted clients can connect.

    • Required flags:

      --auth cert

      --ca <path/to/ca.crt>

      --tls_key_file <path/to/target.key>

      --tls_cert_file <path/to/target.crt>

    • Example:

      Copy
      Copied!
                  

      --auth cert --ca /path/to/certs/ca.crt --tls_key_file /path/to/certs/target.key --tls_cert_file /path/to/certs/target.crt

  • To disable TLS:

    Copy
    Copied!
                

    --tls_enabled=false 

Security Flags

TLS Encryption and Authentication

DMS uses TLS (Transport Layer Security) by default to secure communication. TLS is a widely adopted cryptographic protocol that provides the following guarantees:

  • Encryption – Protects transmitted data from eavesdropping.

  • Authentication – Verifies the identity of the server and optionally the client via digital certificates.

  • Integrity – Ensures transmitted data is not tampered with.

TLS relies on a public/private key pair and a digital certificate issued by a Certificate Authority (CA). These elements ensure secure, authenticated communication.

DMS supports TLS for both gNMI and gNOI interfaces, and works with either self-signed or CA-signed certificates.

To enable TLS, both server and client must provide:

  • --ca <string> – Path to the CA certificate used to validate the remote party’s certificate.

  • --tls_cert_file <string> – Path to the public certificate presented during the TLS handshake.

  • --tls_key_file <string> – Path to the corresponding private key used to sign the handshake and decrypt messages.

    Note

    The private key must be protected. If compromised, it can be used to impersonate the server or client.

TLS Communication Modes

Mutual TLS Authentication (mTLS)

Both the server and client present certificates and verify each other during the TLS handshake.

Copy
Copied!
            

# Server: /opt/mellanox/doca/services/dms/dmsd <flags> --auth cert \ --ca /path/to/certs/client_ca.crt \ --tls_cert_file /path/to/certs/target.crt \ --tls_key_file /path/to/certs/target.key   # Client: /opt/mellanox/doca/services/dms/dmsc <flags> \ --tls-ca /path/to/certs/target_ca.crt \ --tls-cert /path/to/certs/client.crt \ --tls-key /path/to/certs/client.key <command>

Highlights:

  • Provides the highest level of security.

  • Ensures both sides are authenticated and trusted.

  • All traffic is encrypted.

TLS (Server Authentication Only)

Only the server presents its certificate during the handshake. The client verifies the server but does not present a certificate.

Copy
Copied!
            

# Server: /opt/mellanox/doca/services/dms/dmsd <flags> --auth cert \ --tls_cert_file /path/to/certs/target.crt \ --tls_key_file /path/to/certs/target.key   # Client: /opt/mellanox/doca/services/dms/dmsc <flags> \ --tls-ca /path/to/certs/target_ca.crt \ --skip-verify <command>

Highlights:

  • Client authenticity is not verified.

  • Use --skip-verify if a root CA is not provided.

  • Traffic remains encrypted.

Insecure Mode (No TLS)

TLS is disabled entirely on both server and client. No encryption or authentication is performed.

Copy
Copied!
            

# Server: /opt/mellanox/doca/services/dms/dmsd <flags> --auth cert --tls_enabled=false   # Client: /opt/mellanox/doca/services/dms/dmsc <flags> --insecure <command>

To achieve insecure communication (no encryption), configure:

  • Server – use --tls_enabled=false param

  • Client – use --insecure flag'

Highlights:

  • Not recommended for production.

  • Use only in fully isolated, trusted environments for testing or development.

To see the full list of flags, use the help flag (i.e., dmsc --help, dmsc -h).

DMS Client Flags

General Flags

  • --address <string> – Bind to <address>:<port> or just :<port> (default is :9339). Can be localhost for the local use case, or an IP address for the remote use case.

  • --target <string> – Target PCIe address to interact with. Mandatory if the server is running for multiple PCIe addresses.

  • -d, --debug – Debug mode.

Authentication Flags

  • -u, --username <string> – username.

  • -p, --password <string>– password.

Security Flags

  • --tls-ca <string> – path to server CA certificate.

  • --tls-key <string> – path to the client TLS private key.

  • --tls-cert <string> – path to the client TLS certificate, containing the public key.

  • --skip-verify – tells the client to skip verifying the server's certificate during the TLS handshake. TLS is enabled, and the connection is encrypted.

  • --insecure – Disable TLS. The client connects over plain TCP, with no encryption or authentication.

gNMI Command

gNMI (gRPC Network Management Interface) is a standardized network management protocol to configure and monitor network devices via gRPC and Protocol Buffers. It enables interaction with devices using models such as OpenConfig.

Core gNMI commands:

  • Get – Retrieves device data (e.g., operational state, configuration).

  • Set – Modifies device configuration.

  • Capabilities – Queries the device’s capabilities (e.g., supported models, versions, encodings).

  • Subscribe – Streams data from the device to the client.

    Note

    DMS currently does not support the Subscribe command.

In DMSC, the gNMI functionality is powered by the GNMIC project. For additional details, refer to the GNMIC documentation.

Prompt mode with autocomplete can be invoked using the prompt command. To access it, run dmscli and authenticate with the dmsd user password (by default, the root OS password).

Get Request

Get requests happen in real-time without a cache. Get command requires providing the YANG Xpath as described in the following:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> get --path /interfaces/interface[name=p0]/config/mtu [ { "source": "localhost:9339", "timestamp": 1712485149723248511, "time": "2024-04-07T10:19:09.723248511Z", "updates": [ { "Path": "interfaces/interface[name=p0]/config/mtu", "values": { "interfaces/interface/config/mtu": "1500" } } ] } ]

Info

To insert params in the path, as an indication of the interface name (p0).

Get request also work on subtree (subPath) as follows:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> get --path /nvidia/roce [ { "source": "127.0.0.1:9339", "timestamp": 1728471432988295603, "time": "2024-10-09T13:57:12.988295603+03:00", "updates": [ { "Path": "nvidia/roce", "values": { "nvidia/roce": { "config": { "adaptive-routing": "false", "multipath-dscp": "MULTIPATH_DSCP_DEFAULT", "tx-sched-locality-mode": "TX_SCHED_LOCALITY_ACCUMULATIVE" } } } } ] } ]

Info

Failing to provide a mandatory parameter for decoding a leaf leads to that leaf being skipped. The entire request fails when the first leaf fails.


Set Request

Set requests happen immediately, invoking tools to configure the OS.

Set commands require providing Yang Xpath as described in the following:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> set --update /interfaces/interface[name=p0]/config/mtu:::int:::9216 { "source": "localhost:9339", "time": "1970-01-01T00:00:00Z", "results": [ { "operation": "UPDATE", "path": "interfaces/interface[name=p0]/config/mtu" } ] }

Info

To insert params in the path, as an indication of the interface name (p0).

Note

The value provided must be separated by value type and char.

Note

Currently, only the --update flag is supported in Set.

Note

The update of some leaves only takes effect after the system reboot. Refer to gNOI system reboot for information.

It is also possible to invoke a command JSON list:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> set --request-file req.json

req.json example:

Copy
Copied!
            

{ "updates": [ { "path": "/interfaces/interface[name=p0]/config/mtu", "value": 9216, "encoding": "uint" }, { "path": "/interfaces/interface[name=p0]/config/enabled", "value": true, "encoding": "bool" } ] }


List of DMS Supported Path Entries for Get/Set Commands

To get the list of supported paths for get/set commands, run the following command:

Copy
Copied!
            

dmsc --file /opt/mellanox/doca/service/dms/yang path --types --descr

Path

Type

Description

/interfaces/interface[name=*]/config/enabled

boolean

This leaf contains the configured, desired state of the

interface.

Systems that implement the IF-MIB use the value of this

leaf in the 'running' datastore to set

IF-MIB.ifAdminStatus to 'up' or 'down' after an ifEntry

has been initialized, as described in RFC 2863.

Changes in this leaf in the 'running' datastore are

reflected in ifAdminStatus, but if ifAdminStatus is

changed over SNMP, this leaf is not affected.

/interfaces/interface[name=*]/config/mtu

uint16

Set the maximum transmission unit size in octets

for the physical interface. If this is not set, the mtu is

set to the operational default -- e.g., 1514 bytes on an

Ethernet interface.

/interfaces/interface[name=*]/config/name

string

The name of the interface.

A device MAY restrict the allowed values for this leaf,

possibly depending on the type of the interface.

For system-controlled interfaces, this leaf is the

device-specific name of the interface. The 'config false'

list interfaces/interface[name]/state contains the currently

existing interfaces on the device.

If a client tries to create a configuration for a

system-controlled interface that is not present in the

corresponding state list, the server MAY reject the request if the implementation does not support pre-provisioning of interfaces or if the name refers to an interface that can never exist in the system.

A NETCONF server MUST reply with an rpc-error with the

error-tag 'invalid-value' in this case.

The IETF model in RFC 7223 provides YANG features for the

following (i.e., pre-provisioning and arbitrary names),

However they are omitted here:

If the device supports pre-provisioning of the interface

configuration, the 'pre-provisioning' feature is

advertised.

If the device allows an arbitrarily named user-controlled

interfaces, the 'arbitrary-names' feature is advertised.

When a configured user-controlled interface is created by the system, it is instantiated with the same name in the

/interfaces/interface[name]/state list.

/interfaces/interface[name=*]/config/type

identityref

The type of the interface.

When an interface entry is created, a server MAY

initialize the type leaf with a valid value, e.g., if it is possible to derive the type from the name of the

interface.

If a client tries to set the type of an interface to a

value that can never be used by the system, e.g., if the

type is not supported, or if the type does not match the name of the interface, the server MUST reject the request.

A NETCONF server MUST reply with an rpc-error with the

error-tag 'invalid-value' in this case.

/interfaces/interface[name=*]/ethernet/nvidia/config/inter-packet-gap

uint8

Inter packet gap configuration, in 4B unit

/interfaces/interface[name=*]/ethernet/nvidia/config/rate-limit

uint16

The percentage of bandwidth, in permile units, to be used on the port.

/interfaces/interface[name=*]/name

leafref

References the name of the interface

/interfaces/interface[name=*]/nvidia/cc/config/priority[id=*]/id

leafref

/interfaces/interface[name=*]/nvidia/cc/config/priority[id=*]/np_enabled

boolean

Enable CC NP for a given priority on the interface

/interfaces/interface[name=*]/nvidia/cc/config/priority[id=*]/rp_enabled

boolean

Enable CC RP for a given priority on the interface

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/config/counter_enable

boolean

Enable the counter while enabling tha CC algo according to the algo_slot

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/config/enabled

boolean

Enable a CC algo slot execution.

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/config/id

algo_slot_id

CC algo slot id.

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/id

leafref

CC algo slot ID.

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/param[id=*]/config/id

algo_param_id

CC algo param id.

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/param[id=*]/config/value

algo_param_value

Parameter value within the CC algo slot.

/interfaces/interface[name=*]/nvidia/cc/slot[id=*]/param[id=*]/id

leafref

Parameter ID within the CC algo slot.

/interfaces/interface[name=*]/nvidia/qos/config/pfc

boolean

Enables PFC

/interfaces/interface[name=*]/nvidia/qos/config/priority[id=*]/id

prio

Priority ID.

/interfaces/interface[name=*]/nvidia/qos/config/trust-mode

identityref

Trust mode for the interface QoS.

/interfaces/interface[name=*]/nvidia/roce/config/adaptive-retransmission

boolean

Enable adaptive retransmission

/interfaces/interface[name=*]/nvidia/roce/config/adaptive-routing-force

boolean

Force adaptive routing even if the feature was not negotiated between the requestor and responder.

/interfaces/interface[name=*]/nvidia/roce/config/rtt-resp-dscp

uint8

Defines the DSCP fixed value used if mode is set to FIXED.

/interfaces/interface[name=*]/nvidia/roce/config/rtt-resp-dscp-mode

identityref

Defines the method for setting DSCP in RTT response packets.

/interfaces/interface[name=*]/nvidia/roce/config/slow-restart

boolean

Enable slow restart when congestion

/interfaces/interface[name=*]/nvidia/roce/config/slow-restart-idle

boolean

Enable slow restart when idle

/interfaces/interface[name=*]/nvidia/roce/config/tos

tos

ToS value for RoCE traffic.

/interfaces/interface[name=*]/nvidia/roce/config/tx-window

boolean

Enable transmission window

/interfaces/interface[name=*]/state/admin-status

enumeration

The desired state of the interface. In RFC 7223, this leaf

has the same read semantics as ifAdminStatus. Here, it

reflects the administrative state as set by enabling or

disabling the interface.

/interfaces/interface[name=*]/state/oper-status

enumeration

The current operational state of the interface.

This leaf has the same semantics as ifOperStatus.

/nvidia/cc/config/user-programmable

boolean

Enables user-programmable CC functionality.

/nvidia/command[run=*]/run

string

The command to run.

/nvidia/mode/config/mode

identityref

Mode can take one of several predefined

values representing operational modes of DPU.

/nvidia/roce/config/adaptive-routing

boolean

Enable adaptive routing between a requestor and responder.

/nvidia/roce/config/multipath-dscp

identityref

Multipath on transmit, set the DSCP bit to hold the MP eligible info

/nvidia/roce/config/tx-sched-locality-mode

identityref

Transmission scheduler adaptation to locality

/interfaces/interface[name=*]/nvidia/roce/config/cc-per-plane

boolean

Enable\Disable congestion control per plane (when multi plane is supported)

/nvidia/device/config/module[module-id=*]/module-id

/nvidia/device/config/module[module-id=*]/port[port-id=*]/port-id

int

read only, get the module/port id for setting port splitting

/nvidia/physical-functions/config/num-of-pf

int

set\get the number of pfs when configuring a NIC to sport multiplane and port splitting

/nvidia/device/config/module[module-id=*]/port[port-id=*]/lanes

string

set\ get the lanes defined for a specific module and port when defining port splitting.

/nvidia/roce/config/cc-steering-ext

string

2 bit field for controling cc steering extension, could be: default, disabled, enabled or reserved

/interfaces/interface[name=*]/nvidia/qos/config/priority-to-tc

string

priority to traffic class mapping, should have 8 entries for all tcs.

/interfaces/interface[name=*]/nvidia/roce/adp-retx-profiles*

includes a lot of paths here that can each be accessed separately

json file

DMS to configure adaptive-retransmission timeouts via ROCE_ACCL command register.

gNOI Commands

gNOI (gRPC Network Operations Interface) is a protocol for operational tasks such as installing software, managing certificates, and troubleshooting. It complements gNMI by focusing on administrative and system-level functions.

Within DMSc, gNOI support is provided by the GNOIC project. For full documentation, refer to the GNOIC project documentation.

To invoke a gNOI command, run:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc -a localhost --port 9339 --tls-cert client.crt --tls-key client.key <command>

To use interactive mode with autocompletion, enter:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc prompt

Note

All commands are blocked by default unless explicitly enabled. gNOI commands are currently supported only on the host system—not on the BlueField.

OS Commands

The following commands support provisioning of DOCA images (BFB) or firmware on BlueField devices.

Install

Transfers and authenticates the specified package file. If the file is valid, it is saved to the server’s image folder (default: /tmp/dms). If the file already exists in that folder with the expected version and extension, the server skips the file transfer and proceeds with authentication only.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> os install \ --version <version_string> \ --pkg <path_to_bfb_or_cfg_or_fw>

Examples:

  • Install a BFB image:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsc <flags> os install \ --version 2_9_0 \ --pkg DOCA_2.9.0_Ubuntu.bfb

  • Install a config file:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsc <flags> os install \ --version 0_0_1.cfg \ --pkg bf.cfg

  • Install firmware:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsc <flags> os install \ --version 24_29_0046.fw \ --pkg fw-BlueField.bin

The file extension is autodetected based on the provided package. If omitted from the --version string, it is inferred automatically. Users can also copy the file manually to the image folder and run the command to authenticate it without triggering a transfer.

The file is saved to the folder specified in the -image_folder flag (default /tmp/dms) given to the server, if the file authenticates successfully.

Activate

The activate command deploys BFB bundles and/or firmware to the hardware.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> os activate --version <version_string>

Examples:

  • Activate all files under a version prefix:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsc <flags> os activate --version 2_9_0

  • Activate specific files by name (use semicolon to separate multiple components):

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsc <flags> os activate --version "2_9_0.bfb;0_0_1.cfg;24_29_0046.fw"

  • Auto-detect and install the appropriate firmware:

    Copy
    Copied!
                

    /opt/mellanox/doca/services/dms/dmsc <flags> os activate --version auto

Behavior:

  • The --version flag specifies which files to activate from the directory defined by the --image_folder flag (default: /tmp/dms).

  • If no file extensions are included, the command activates all files matching the base version name.

  • When using --version auto, the mlnx-fw-updater.pl script runs automatically. This script:

    • Detects the connected device type.

    • Identifies the appropriate firmware version.

    • Installs it accordingly.

Note

Deploying BFB bundles is supported only when the command runs from the host system.

Note

After firmware activation, a firmware reset is automatically triggered.


Verify

The verify command retrieves the currently installed firmware and BFB bundle versions from the target device.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> os verify

The response includes the firmware and BFB versions, separated by a semicolon:

Copy
Copied!
            

+-----------------+---------------------------------------------------------------+-----------------------------+ | Target Name | Version | Activation Fail Msg | +-----------------+---------------------------------------------------------------+-----------------------------+ | 127.0.0.1:19999 | FW: 32.42.1000;BFB: bf-bundle-2.8.0-98_24.07-ubuntu-22.04_dev | | +-----------------+---------------------------------------------------------------+-----------------------------+

Notes:

  • The Version column lists both the firmware (FW) and BFB versions if available.

  • The Activation Fail Msg column displays error messages if activation fails.

  • The BFB bundle version is displayed only if it was installed via DMS.

System

The following subsections describe actions related to rebooting the BFB bundle or firmware on BlueField.

Reboot Status

Use the following command to check whether a reboot is currently in progress:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> system reboot-status [--reboot_status_check <string>]

The returned value indicates the system status:

  • false – The system is active and not rebooting.

  • true – The system is in the process of rebooting.

  • If the status cannot be retrieved, the result appears as failure, and the message field provides additional details.

The flag --reboot_status_check <string> checks if firmware reboot is needed:

Value

Description

fast

Default. Performs a quick but imprecise check. Any configuration may trigger a reboot.

strict

Performs a slower but more accurate check.

none

Skips the firmware reboot check entirely.


Reboot

To reboot the BlueField Arm and firmware, use the following command:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> system reboot --delay <seconds> [--subcomponent <component>] [--method <type>]

This command is non-blocking and returns immediately after it is issued.

Flag

Description

--delay <uint>

Specifies the number of seconds to wait before triggering the reset.

--subcomponent

Optional. Specifies which component to reset. Currently supports ARM.

--method

Optional. Specifies the reset method. Supported values: WARM, POWERDOWN.

By default, if subcomponent and method are not specified, the command executes the lowest-level reset available for the system.

Factory-reset

Performs a factory reset on the target node by resetting all PFs (Physical Functions) to their default configurations.

Start

Resets device configurations to their default values for each PF on the specified target:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> factory-reset start

Or using the alias:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> reset start

Note

Reset to the Golden Image (a pre-configured, ideal-state version) is not supported.

File

Performs operational tasks related to files on the target device.

Stat

Retrieves metadata for a specified file or directory.

Copy
Copied!
            

# Single file /opt/mellanox/doca/services/dms/dmsc <flags> file stat --path /path/to/file   # Directory with recursive listing /opt/mellanox/doca/services/dms/dmsc <flags> file stat --path /path/to/dir --recursive

Example output:

Copy
Copied!
            

+----------------+---------------------+----------------------+------------+------------+------+ | Target Name | Path | LastModified | Perm | Umask | Size | +----------------+---------------------+----------------------+------------+------------+------+ | 127.0.0.1:9339 | /path/to/dir/file_1 | 2025-04-10T09:05:37Z | -rw-r--r-- | -----w--w- | 0 | | | /path/to/dir/file_2 | 2025-04-10T09:05:37Z | -rw-r--r-- | -----w--w- | 0 | +----------------+---------------------+----------------------+------------+------------+------+


Get

Streams the contents of a file from the target device to the client.

Info

To allow this operation, the DMSD server must be started with a list of directories permitted for read access, using the --allow_list_read flag:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> --allow_list_read <dir1>,<dir2>,<dir3>

Client invocation:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> file get --file /tmp/debug/<file_to_get>


Put

Streams a file from the client to the target device.

Info

To allow this operation, the DMSD server must be started with a list of directories permitted for write access, using the --allow_list_write flag.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> --allow_list_write <dir1>,<dir2>,<dir3>

Client invocation:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsc <flags> file put --file /tmp/debug/file_to_send --dst /tmp/output/path_on_remote_host

Containerz

Containerz supports remote management and monitoring of containers on either the host or the DPU. This deployment model follows the DOCA container methodology described in the DOCA Container Deployment Guide .

Containerz supports the following two backend modes.

Docker Backend (Default)

This mode interacts with the Docker daemon (dockerd) on the host.

Ensure that the Docker daemon is running:

Copy
Copied!
            

systemctl start docker


Kubelet Backend

This mode uses the Kubelet daemon to manage containers on the BlueField DPU using static pod definitions. It does not require a full Kubernetes cluster.

Kubelet automatically handles any manifest files placed in /etc/kubelet.d.

  • Add a pod – Place a YAML manifest in /etc/kubelet.d

  • Remove a pod – Delete the corresponding YAML file

Info

This is the default mode for dmsd when launched by systemd on the DPU.

Note

Notes:

  • The Kubelet daemon is not running by default on the host (DOCA for host).

  • This mode is only supported when dmsd runs on the DPU.

  • For DOCA on the host, use the Docker backend.

image-2025-4-10_11-14-59-version-1-modificationdate-1747568279337-api-v2.png

To specify the container backend mode, use the --container_interface flag:

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> --container_interface <kubelet|docker>


Container Operations

These operations control container lifecycle, image usage, and persistent volumes on the system. Behavior differs based on the selected container backend (Docker or Kubelet).

Container Start

Launches a container using the specified image or configuration file.

  • Docker mode: The image must exist locally.

  • Kubelet mode: Provide a YAML file defining the pod. The file is copied to the Kubelet manifest directory, which triggers container startup.

Copy
Copied!
            

# Docker mode /opt/mellanox/doca/services/dms/dmsd <flags> containerz container start --image <image_name>   # Kubelet mode /opt/mellanox/doca/services/dms/dmsd <flags> containerz container start --image path/to/yaml/file.yaml


Container List

Displays all currently running containers.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz container list


Container Stop

Stops a running container. The container remains available for later restart.

  • Kubelet mode: Stops the container by deleting its manifest YAML from the directory.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz container stop --instance <container name>


Container Remove

Stops and deletes the specified container.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz container remove --instance <container name>

Image Operations

These commands manage container images—pulling from registries, pushing from the client, listing available images, and removing them from the device.

Image Pull

Downloads a container image from a remote registry to the device.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz image pull --image ubuntu


Image Push

Streams a container image (in .tar format) from the client to the device. The image is transferred over gRPC and saved locally.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz image push --file /path/to/tarfile.tar


Image List

Lists all container images currently available on the device.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz image list


Image Remove

Deletes a specific container image from the device.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz image remove --image ubuntu

Volume Operations

These commands manage persistent storage volumes for containers.

Info

In Kubelet mode, all volumes are created under /var/dms/volume.

Volume Create

Creates a new named volume on the device.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz volume create --name my_volume


Volume Remove

Deletes the specified volume by name.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz volume remove --name volume_name


Volume list

Displays all named volumes and their associated mount points.

Copy
Copied!
            

/opt/mellanox/doca/services/dms/dmsd <flags> containerz volume list

© Copyright 2025, NVIDIA. Last updated on Sep 4, 2025.