You have three options for installing or upgrading NVIDIA DOCA™ on an NVIDIA® BlueField® DPU or SuperNIC:
|
Method |
Option Name |
Description |
|---|---|---|
|
Installation |
This option overwrites the entire boot partition with an Ubuntu 22.04 installation and updates BlueField and NIC firmware. It is installed from the host with the DOCA Installer tool ( |
|
|
Upgrade |
This option upgrades DOCA components without overwriting the boot partition. Use this option to preserve configurations or files on BlueField itself. |
|
|
Installation |
This option overwrites the entire boot partition with an Ubuntu 22.04 installation and updates BlueField and NIC firmware |
Find the DOCA installation files for BlueField on the NVIDIA DOCA Downloads page.
Installing DOCA-Host
Make sure to update DOCA on the host side before installing the BF-Bundle on the BlueField.
Installing the DOCA Installer
Make sure to update DOCA on the host side before installing doca-installer.
|
DEB-based |
|
|---|---|
|
RPM-based |
|
Installing Software on BlueField Using BF-Bundle
The ATF does not boot 150W BlueField-3 platforms if the ATX +12V power supply is not connected. This requirement ensures the proper operation of the BlueField device. For detailed instructions on connecting the external power supply connector, refer to the NVIDIA BlueField-3 Networking Platform User Guide.
You can install DOCA on a BlueField DPU or SuperNIC by upgrading the full DOCA image on the BlueField device. This process overwrites the entire boot partition with an Ubuntu 22.04 installation and updates BlueField and NIC firmware. It also sets up the OVS bridge.
Upgrading DOCA components on BlueField networking platforms, such as DPUs or SuperNICs, using standard Linux tools installs the new doca-eula package at /etc/NVIDIA/doca-license/DOCA-EULA.txt. By installing this package, you accept the NVIDIA DOCA SDK end-user license agreement.
When the BlueField DPU reboots during a BFB installation or upgrade, any SSH session to the host through a DPU out-of-band port is disconnected. The live doca-installer output is no longer available in the disconnected session. After the installation or upgrade is complete, establish a new SSH session to reconnect to the host.
BF-Bundle installation from the host is performed with the DOCA Installer tool (doca-installer). Install it on the host first, as described in Installing the DOCA Installer.
Option 1 – No Pre-defined Password
To change the default Ubuntu password during the BFB bundle installation, proceed to Option 2.
To install a BFB, use the following command:
host# sudo doca-installer -b <image_path.bfb> -r rshim<N>
Where:
-
<N>– the appropriate RShim device identifier. If you have only one BlueField device, usershim0. -
<image_path.bfb>– Replace this with the path to the BFB image file. -
To install on all BlueField devices in the host, omit
-r rshim<N>. For per-PSID runs, exclusions and configuration files, see DOCA Installer Tool.
To list the RShim devices present on your system, run the following command:
host# ls -la /dev/ | grep rshim
doca-installer records the RShim misc log of each device, together with other diagnostics, in its log directory. See Logs and Debuggability.
Option 2 – Set Pre-defined Password
Ubuntu users can set a unique password for the ubuntu user in the bf.cfg configuration file, which is applied automatically at the end of the BlueField BFB bundle installation.
To do this, follow these steps:
-
Generate the hashed password:
host# openssl passwd -1 Password: Verifying - Password: $1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1 -
Add the password hash to the
bf.cfgconfiguration file:host# echo ubuntu_PASSWORD='$1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1' > bf.cfg
-
Use the
-cflag to specify the configuration file when running the installation command:host# sudo doca-installer -b <image_path.bfb> -r rshim<N> -c bf.cfgThe configuration filename must end in
.cfg(bf.cfgformat) or.yaml/.yml(DOCA Installer format). Other extensions are rejected.If
-cis not used, then upon first login to the BlueField device, users will be prompted to update the defaultubuntupassword.BMC, CEC and golden image firmware are updated as part of the BF-Bundle installation. BMC credentials in
bf.cfgare optional. Ifbf.cfgdoes not set them, the installation uses the credentials that the BMC provides to the BlueField. If no credentials are available from either source, the BMC, CEC and golden image updates are skipped. To set the credentials explicitly, or to change the BMC password withNEW_BMC_PASSWORD, add them tobf.cfg:BMC_PASSWORD="<root password>" BMC_USER="root" BMC_REBOOT="yes"Unless previously changed, the default BMC root password is
0penBmc.The installation output of each device, including the BlueField boot messages, is saved in the DOCA Installer log directory. See Logs and Debuggability.
-
doca-installerwaits for each BlueField device to report that it has completed booting (DPU is readyin DPU mode,In Enhanced NIC modein NIC mode) and reports the result in the Upgrade Summary Report. Optionally, re-check manually with the following command:host# sudo cat /dev/rshim<N>/misc ... INFO[MISC]: Linux up INFO[MISC]: DPU is ready -
Retrieve installed packages and their versions as part of BF-Bundle installation, using one of the following:
-
From the host, with the DOCA Installer (DPU mode only, DOCA 3.2.0 or later, not supported on BlueField-2):
host# doca-installer --show-doca-info -r rshim<N>Omit
-r rshim<N>to query all BlueField devices on the host. The output is thebf-infocontent of each device. See Fetch DPU Information. -
From BlueField:
-
Log in to BlueField.
-
Run the following command:
bf# sudo bf-infoExample output:
Firmware: - NIC Firmware: 32.51.0276 - NIC Firmware: 32.51.0382 (pending) - ATF: v2.2(release):4.17.0-5-g103fa9f6c - UEFI: 4.17.0-19-ge07abd0d02 - BSP: 4.17.0.14108 - BMC Firmware: BF-26.10-5 - CEC Firmware: 00.02.0208.0000_n02 Drivers: - dpdk: 'DPDK 26.07.0' - Kernel: 6.8.0-1033-bluefield Tools: - MFT: 4.38.0-124 - mstflint: 4.37.0-1.101.g1ed852f Storage: - virtio-net-controller 26.10.7-1 DOCA: - doca-apsh-config 3.6.0071-1 - doca-bench 3.6.0071-1 - doca-caps 3.6.0071-1 ...
-
-
-
Run the following command to configure the
tmfifo_net0interface over IPv4 for SSH access to the BlueField Arm OS:host# ifconfig tmfifo_net0 192.168.100.1/24Establish an SSH connection to the BlueField Arm OS with 192.168.100.2 (preconfigured default) using the following command:
host# ssh ubuntu@192.168.100.2
DOCA Installer Tool
Overview
DOCA Installer (doca-installer) installs and upgrades BlueField devices from the host, whether the host has one BlueField device or several. It installs a BF-Bundle (bf-bundle-*.bfb, OS and firmware) or a firmware-only bundle (bf-fwbundle-*.bfb) on one device or on several devices in parallel. It supports devices in DPU mode, NIC mode, or a mix of both on the same host. It can also update the firmware of BlueField-3 devices from a PLDM firmware package (--pldm). Customization is supported through bf.cfg or YAML configuration files. It can also report the firmware in an image and on the devices without installing anything.
A run with no target options installs on every BlueField device it finds on the host:
host# doca-installer -b <image_path.bfb>
Selecting Target Devices
|
Target |
Command |
|---|---|
|
All devices on the host |
|
|
One device by RShim |
|
|
Several devices by RShim |
|
|
One device by MST path |
|
|
Devices that share a PSID |
|
Where:
-
-cor--config-file– defines a configuration in abf.cfg(.cfg) or YAML (.yaml,.yml) file. It is optional when no BMC credentials or customizations are needed. BMC credentials are optional, see Option 2. -
<path-to-config>– Path to thebf.cfgor YAML configuration file -
<image_path.bfb>– Path to the BFB image file -
<PSID>– Shared PSID value for the target group. Devices that do not match the provided PSID are not upgraded. -
<N>– RShim device index (for example,0for a single-device setup)
To leave devices out of an all-devices or PSID run, add --exclude with RShim names, MST paths or both:
host# doca-installer -b <image_path.bfb> --exclude rshim1 /dev/mst/mt41692_pciconf1
A device whose RShim is not owned by this host is restricted. By default the run fails when it finds one. Add --skip-restricted to skip such devices and install on the rest.
When the image filename carries an OPN (ordering part number), as in bf-fwbundle-<version>-<build>-<OPN>_<release>_prod.bfb, doca-installer limits the run to the devices whose part number matches that OPN. Devices whose part number cannot be read are excluded with a message. If no device matches, the run exits with code 2 and lists the devices found and their OPNs.
Installation Modes
|
Mode |
Command |
What Happens |
|---|---|---|
|
Immediate (default) |
|
The BlueField device is reset, boots the image, installs it and reboots. |
|
Deferred |
|
The firmware (NIC firmware, ATF/UEFI, BMC, CEC) is staged while the BlueField keeps running. Nothing changes until the new version is applied (see Deferred Mode). |
|
Deferred with live patch |
|
Same as deferred, then the NIC firmware is activated right away with a live firmware patch (LFWP). |
|
Live patch only |
|
No image. Runs the NIC firmware live patch for firmware an earlier deferred run staged. |
|
PLDM firmware package |
|
BlueField-3 only. The firmware in the PLDM package is staged in-band over the RShim, as in deferred mode. See PLDM Firmware Package. |
This applies to every installation mode, immediate, deferred and PLDM alike: a device that runs with pending NIC firmware (burned by an earlier deferred run but not yet activated) is reset with flint -d <pci> ir before the install starts, and the pending firmware is discarded in favor of the firmware in the image. To activate the pending firmware first, run doca-installer --activate 1 (or the reset listed by the previous run) before installing.
Deferred Mode
-
Works in DPU mode and NIC mode. Not supported on BlueField-2.
-
The BlueField must already run BSP 4.13.0 / DOCA 3.2.0 or later.
-
The host must boot in UEFI mode with the BlueField expansion ROM enabled (
EXP_ROM_UEFI_x86_ENABLE=1on x86 hosts,EXP_ROM_UEFI_ARM_ENABLE=1on Arm hosts). -
In DPU mode, BMC and CEC are updated only if the DPU BMC credentials are in
/etc/bf-upgrade.confon the BlueField Arm OS. -
On x86 hosts,
qemu-aarch64-staticis required (packageqemu-user-static). -
A deferred run on a device that still has pending NIC firmware from an earlier deferred run discards that firmware first (see the note in Installation Modes). Activate it with
--activate 1before the new run if it must be kept. -
Deferred mode updates firmware only. In DPU mode, update the DOCA packages on the Arm OS with the standard Linux tools (see Upgrading BlueField Using Standard Linux Tools) before applying.
Applying a deferred update: cold boot of the server, warm reboot of the server, or coordinated server and DPU reset. In DPU mode, shut down the BlueField Arm OS before a cold boot or warm reboot, otherwise the update is not applied. For the coordinated reset steps, see Deferred Update BlueField-3 in the BlueField BSP documentation.
Live Patch (--activate 1)
-
Applies to the NIC firmware only. ATF/UEFI, BMC and CEC still need one of the resets listed in Deferred Mode.
-
Runs only if the device reports live patch support. If it does not, the run for that device fails with "Live Patch NIC Firmware reset not supported". The firmware stays staged and is applied by the next reset.
-
With an image,
--activate 1requires--deferred.
PLDM Firmware Package
Use --pldm to update the firmware of BlueField-3 devices from a PLDM firmware package (bf-fwPLDM-*.pldm) in-band over the RShim:
host# doca-installer --pldm <bf-fwPLDM-<version>-<OPN>_<release>_prod.pldm> [--rshim rshim<N>] [--activate 1]
-
A PLDM update is always a deferred update: the firmware is staged while the BlueField keeps running and is applied by one of the resets listed under Deferred Mode.
--deferredand--runtimeare implied. -
--activate 1applies the NIC firmware right away with a live patch, as with-b --deferred --activate 1. -
--show-target-fw --pldm <file>lists the versions in the package without installing. -
Device selection is the same as with
-b:--rshim,-d,--psid,--exclude,--skip-restrictedand-c. An OPN in the package filename scopes the run as described in Selecting Target Devices. -
Not supported on BlueField-2.
--compareis not supported with--pldm; use--show-running-fwto read the current versions. -
Requires
fwpkg_unpack.pyandmlx-mkbfbfrom the rshim package (2.6.7, or 2.9.1 and later).qemu-aarch64-staticis not needed. -
Pending NIC firmware from an earlier run is discarded before the PLDM update, as for every install (see the note under Installation Modes).
-
Exit codes are those of an install, including 101/102 and 201/202.
Installation Output and Firmware Activation
At the end of each run, doca-installer reads back the firmware versions of each device, prints a summary, and lists the devices that need a reset to activate new firmware, with the commands to run. Until the reset, the device keeps running the previous version.
Example of a BF-Bundle installation without a configuration file, on a BlueField-3 that supports NIC firmware reset level 4 only (end of the output):
...
================================================================================
UPGRADE SUMMARY REPORT
================================================================================
Total Devices: 1
[V] Upgrade Successful: 0
[!] Upgrade Successful - Matching Pending Activation: 1
The following devices passed upgrade successfully:
None
The following devices have correct firmware pending activation:
1. 0000:27:00.0 (PSID: MT_0000000884) (NIC_FW)
================================================================================
FIRMWARE ACTIVATION REQUIRED
================================================================================
[!] Some devices require reset for firmware activation.
DEVICES REQUIRING RESET:
- 0000:27:00.0: Pending NIC_FW
SYSTEM LEVEL RESET (Level 4 - Host Reboot Required)
------------------------------------------------------------
Reason: 1 device(s) don't support Level 3, but all support Level 4
Impact: Host reboot affects ALL devices
Devices that don't support Level 3:
- 0000:27:00.0 (Level 4 only)
STEPS:
1. Execute the mlxfwreset command:
mlxfwreset -d /dev/mst/mt41692_pciconf1 -l 1 -t 4 r
2. Perform a warm reboot of the host:
reboot
Note: Step 1 affects ALL BlueField devices, Step 2 completes the reset process
SUMMARY: Using SYSTEM_LEVEL_RESET (Level 4) for ALL 1 device(s)
================================================================================
Configuration File Options
Pass a configuration file to doca-installer with the -c option. The file can be in YAML format or in bf.cfg format. Both formats support settings shared by all devices and settings for individual devices.
YAML Configuration File
The YAML format supports global and per-device customization using structured keys:
-
global_configs– Shared parameters for all devices (for example, credentials) -
rshim– Device-specific configurations-
Each key under
rshim(for example,rshim1,rshim2) defines variables and methods for that device
-
-
variables– Parameters that control the installation process (for example,WITH_NIC_FW_UPDATE,BMC_REBOOT) -
methods– Custom shell commands run during installation. You can use YAML anchors (&,*) to reuse methods across devices.
When a value is defined both globally and per-device, the per-device value takes precedence.
Per-device Configuration Only Example
rshim:
rshim1:
variables:
BMC_USER: 'root'
BMC_PASSWORD: '<root password>'
methods:
bfb_modify_os:
command: |
sed -i -e "s@192.168.100.2@192.168.101.2@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
sed -i -e "s@192.168.100.1@192.168.101.1@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
Global Configuration Only Example
global_configs:
variables:
BMC_USER: 'root'
BMC_PASSWORD: '<root password>'
Global and Per-device Configuration Example
global_configs:
variables:
BMC_USER: 'root'
BMC_PASSWORD: '<root password>'
rshim:
rshim1:
variables:
WITH_NIC_FW_UPDATE: 'no'
rshim2:
variables:
BMC_PASSWORD: '<rshim2 password>'
Reusing Methods With Anchors Example
global_configs:
variables:
BMC_USER: 'root'
BMC_PASSWORD: '<root password>'
rshim:
rshim1:
variables:
BMC_REBOOT: 'yes'
methods:
bfb_post_install: &default_post_install
command: |
echo "Running post-install on rshim1"
rshim2:
methods:
bfb_post_install: *default_post_install
bf.cfg Configuration File
A bf.cfg file (.cfg extension) is a list of shell variable assignments. Configuration files with an extension other than .cfg, .yaml or .yml are rejected with "Unsupported configuration file format".
Per-device Configuration Example
RSHIM0_BMC_USER="root"
RSHIM0_BMC_PASSWORD="<password>"
RSHIM1_BMC_USER="root"
RSHIM1_BMC_PASSWORD="<password>"
Shared and Per-device Parameters Example
# Shared across all devices
BMC_USER="root"
BMC_PASSWORD="<password>"
NEW_BMC_PASSWORD="<new password>"
# Device-specific (optional)
RSHIM0_NET_RSHIM_MAC=00:1a:ca:ff:ff:01
RSHIM1_NET_RSHIM_MAC=00:1a:ca:ff:ff:03
Logs and Debuggability
For each execution of the doca-installer, a unique log directory is created under:
/var/log/doca_installer_logs/doca_installer_<timestamp>
Each device has its own directory with logs related only to that device. These directories contain detailed diagnostic files, such as:
-
rshimdiagnostics -
lspci -
Installation output (
BF_<PCI>_dpu_deployment_tool_output) -
rshim miscinstallation record output -
mlxconfigoutput -
mlxprivhostoutput -
mstdumpoutput (if applicable) -
flint -
Register reads
The main directory itself holds key summary logs, including:
-
Full execution log of the
doca-installertool -
System services
-
Run result file saved in YAML
The run result is always saved as YAML in the log directory. To save another copy elsewhere, add --export-yaml <dir>.
Querying Without Installing
The following options report information about an image, the BlueField devices, or the host without installing anything.
Fetch Firmware Versions From Image
Use the --show-target-fw flag to display firmware versions embedded in the provided BFB image:
host# doca-installer -b <image_path.bfb> --show-target-fw
Fetch Firmware Versions From Running Devices
Use the --show-running-fw flag to display firmware versions currently installed on each detected BlueField device. Add -r to limit the query to specific devices:
host# doca-installer --show-running-fw
Compare Image Versus Running Firmware Versions
Use the --compare option to compare current firmware versions on each device with those contained in the image:
host# doca-installer -b <image_path.bfb> -r rshim1 --compare
Example output:
Firmware Version Comparison:
================================================================================
Device: 0000:27:00.0 (PSID: MT_0000000884, Type: BF3)
╒═════════════╤═══════════════════════════════════╤═════════════════════════════╤═══════════════════════════╕
│ Component │ Current Version (Running) │ Current Version (Pending) │ Image Version (Offline) │
╞═════════════╪═══════════════════════════════════╪═════════════════════════════╪═══════════════════════════╡
│ ATF │ v2.2(release):4.17.0-5-g103fa9f6c │ N/A │ 4.17.0-5-g103fa9f6c │
├─────────────┼───────────────────────────────────┼─────────────────────────────┼───────────────────────────┤
│ UEFI │ 4.17.0-19-ge07abd0d02 │ N/A │ 4.17.0-19-ge07abd0d02 │
├─────────────┼───────────────────────────────────┼─────────────────────────────┼───────────────────────────┤
│ NIC_FW │ 32.51.0276 │ 32.51.0382 │ 32.51.0382 │
├─────────────┼───────────────────────────────────┼─────────────────────────────┼───────────────────────────┤
│ BMC_FW │ BF-26.10-5 │ N/A │ BF-26.10-5 │
├─────────────┼───────────────────────────────────┼─────────────────────────────┼───────────────────────────┤
│ CEC_FW │ 00.02.0208.0000_n02 │ N/A │ 00.02.0208.0000_n02 │
╘═════════════╧═══════════════════════════════════╧═════════════════════════════╧═══════════════════════════╛
================================================================================
FIRMWARE COMPARISON SUMMARY
================================================================================
Total Devices: 1
[V] Matching: 0
[!] Matching - Pending Activation: 1
[!] MATCHING - PENDING ACTIVATION
0000:27:00.0 MT_0000000884
Pending: NIC_FW
================================================================================
Fetch DPU Information
Use the --show-doca-info option to fetch bf-info content from the running DPUs. This feature is supported for devices running in DPU mode only.
This feature requires DOCA 3.2.0 or later.
host# doca-installer --show-doca-info
List DOCA Packages on the Host
Use the --show-doca-host-info option to list the DOCA packages installed on the host. It does not access the BlueField devices.
host# doca-installer --show-doca-host-info
Exit Codes
|
Code |
Meaning |
|---|---|
|
0 |
All devices installed and their versions were read back |
|
1 |
One or more devices failed to install |
|
2 |
Install succeeded, but reading back the versions failed on one or more devices |
|
101 / 102 |
As 1, and all (101) or some (102) devices were flagged by the post-install hardware fault scan |
|
201 / 202 |
As 2, and all (201) or some (202) devices were flagged by the post-install hardware fault scan |
The 1xx and 2xx codes are returned only by installs (-b and --pldm). The query options return 0 (success), 1 (failure) or 2 (warning).
BlueField-2 Limitations
BlueField-2 is supported with the following features only:
-
Parallel installation (single, global, per-PSID, exclude)
-
Targeting by MST path (
-d) and--skip-restricted -
Configuration files (
-c,bf.cfgand YAML) -
Show target firmware
-
Debuggability (extensive logs collection)
BlueField-2 does not support deferred mode (--deferred, --runtime), live patch (--activate), --pldm, --compare, --show-running-fw or --show-doca-info. On a host with both BlueField-2 and BlueField-3 devices, these options print a warning, ask Continue with the available devices? (y/N) and skip the BlueField-2 devices. Unattended scripts must answer the prompt.
Post-installation version verification is not available on BlueField-2. The tool reports that the device completed installation without verification and the summary shows no versions for it.
Due to firmware limitation, doca-installer cannot present the versions of ATF, UEFI, BMC and CEC.
Upgrading BlueField Using Standard Linux Tools
This procedure allows for upgrading DOCA components on BlueField networking platforms (DPUs or SuperNICs) using standard Linux tools (for example, apt update and yum update). This method uses native package manager repositories to update components without requiring a full reinstallation.
Important!
Although this method lets you update specific DOCA components, the combinations resulting from selective updates are not validated by NVIDIA. NVIDIA only validates the full installation of the BF-Bundle package.
Upgrading DOCA components on BlueField networking platforms using standard Linux tools installs the new doca-eula package located at /etc/NVIDIA/doca-license/DOCA-EULA.txt. By installing this package, you accept the NVIDIA DOCA SDK end-user license agreement.
This process provides the following capabilities and benefits:
-
Selective updates: Only updates components that include modifications.
-
Flexible upgrade paths: You must choose the upgrade option that best fits your deployment needs:
-
DOCA software only: Updates DOCA drivers, libraries, services, and reference applications without upgrading the hardware firmware.
-
DOCA software and firmware: Updates all DOCA software components alongside the BSP (UEFI/ATF), NIC firmware, and BMC components, while maintaining existing configurations.
Firmware may also be updated independently through other supported methods, such as via the out-of-band (OOB) DPU-BMC in a deferred flow.
-
-
Preserves environment: Does not impact user binaries or upgrade non-Ubuntu OS kernels.
-
Post-upgrade activation:
-
If the NIC firmware was not updated, perform a BlueField Arm reset (software reset/reboot).
-
If the NIC firmware was updated, perform a firmware reset (
mlxfwreset) or a graceful shutdown and power cycle.
-
Upgrading DEB-based Distributions
Follow this procedure to upgrade DOCA components on DEB-based BlueField environments, such as Ubuntu, using the APT package manager.
Repository Setup
-
Export
DOCA_REPOwith the relevant URL:<bf> $ export DOCA_REPO="<URL>"-
Latest GA:
https://linux.mellanox.com/public/repo/doca/latest/ubuntu22.04/arm64-dpu -
Latest-3.4-LTS:
https://linux.mellanox.com/public/repo/doca/latest-3.4-LTS/ubuntu22.04/dpu-arm64 -
Latest-3.2-LTS:
https://linux.mellanox.com/public/repo/doca/latest-3.2-LTS/ubuntu22.04/dpu-arm64 -
Latest-2.9-LTS:
https://linux.mellanox.com/public/repo/doca/latest-2.9-LTS/ubuntu22.04/dpu-arm64 -
Latest-2.5-LTS:
https://linux.mellanox.com/public/repo/doca/latest-2.5-LTS/ubuntu22.04/dpu-arm64
-
-
Add the GPG key to the APT trusted keyring:
<bf> $ curl $DOCA_REPO/nvidia-doca-debian-gpg-public-key.asc | gpg --dearmor > /etc/apt/trusted.gpg.d/nvidia-doca-debian-gpg-public-key.gpg -
Add the DOCA online repository and update the index:
<bf> $ echo "deb [signed-by=/etc/apt/trusted.gpg.d/nvidia-doca-debian-gpg-public-key.gpg] $DOCA_REPO ./" > /etc/apt/sources.list.d/doca.list -
Update the index:
<bf> $ apt update
Package Upgrade Selection
Choose one of the following options to upgrade your packages.
Option 1: Upgrade BlueField FW Bundle
This command upgrades the ATF-UEFI, NIC firmware, and BMC firmware only.
<bf> $ apt install bf-fwbundle
Option 2: Update Specific DOCA Components
To skip the firmware update (for example, when updating through DPU-BMC or Redfish), remove the old firmware packages:
-
If your DOCA version is earlier than 3.4.0, run the following command:
<bf> $ apt remove bf2-bmc-fw-signed bf3-bmc-fw-signed bf3-bmc-gi-signed bf3-bmc-nic-fw* bf2-cec-fw-signed bf3-cec-fw-signed -
If your DOCA version is 3.4.0 or later, run the following command:
<bf> $ apt remove bf2-bmc-fw-signed bf3-bmc-fw-signed bf3-bmc-gi-signed bf3-bmc-nic-fw* bf2-cec-fw-signed bf3-cec-fw-signed mlxbf-bootimages-signed
-
Component activation requires
sshpass. Install it if it is missing:<bf> $ command -v sshpass >/dev/null 2>&1 || { apt-get update && apt-get install -y sshpass; } -
If you are upgrading from DOCA 3.2 or earlier, install the
dpdk-communitypackages. DOCA 3.3 replacedmlnx-dpdkwithdpdk-community, andapt upgradedoes not make this replacement. Without this step, DOCA Flow and DPDK packages stay at their earlier versions and no error is reported.<bf> $ apt install --purge -y 'dpdk-community*' -
Upgrade the installed packages:
<bf> $ apt upgrade
Firmware Configuration and Activation
Skip this phase if you do not want to update firmware.
-
Configure BMC parameters by adding the BMC user and password to
/etc/bf-upgrade.conf(format is identical tobf.cfg):<bf> $ cat > /etc/bf-upgrade.conf << EOF BMC_USER="<username>" BMC_PASSWORD="<password>" WITH_NIC_FW_UPDATE="yes" BMC_REBOOT="yes" EOFBMC_REBOOT="yes"causes a warm boot to the BMC, temporarily losing connectivity. -
Activate the components:
<bf> $ dpu-bmc-upgradeThe upgrade process takes up to 20 minutes. The script performs an
fwresetif supported.
Apply Changes
For the upgrade to take effect, perform a BlueField system reboot to apply the new changes, NIC firmware, and UEFI/ATF.
This step triggers immediate reboot of the BlueField Arm cores.
Upgrading RPM-based Distributions
Follow this procedure to upgrade DOCA components on RPM-based BlueField environments using the DNF or YUM package managers.
Repository Setup
-
Export
DOCA_REPOwith the relevant URL:<bf> $ export DOCA_REPO="<URL>"-
Latest GA:
https://linux.mellanox.com/public/repo/doca/latest/openeuler22.03sp3/arm64-dpu/ -
Latest-3.4-LTS:
https://linux.mellanox.com/public/repo/doca/latest-3.4-LTS/openeuler22.03sp3/dpu-arm64/ -
Latest-3.2-LTS:
https://linux.mellanox.com/public/repo/doca/latest-3.2-LTS/openeuler22.03sp3/dpu-arm64/ -
Latest-2.9-LTS:
https://linux.mellanox.com/public/repo/doca/latest-2.9-LTS/openeuler22.03sp3/dpu-arm64/ -
Latest-2.5-LTS:
https://linux.mellanox.com/public/repo/doca/latest-2.5-LTS/anolis8.6/dpu-arm64/
-
-
Add the DOCA online repository:
<bf> $ echo "[doca] name=DOCA Online Repo baseurl=$DOCA_REPO enabled=1 gpgcheck=0 repo_gpgcheck=1 gpgkey=$DOCA_REPO/nvidia-doca-rpm-gpg-public-key.asc priority=10 cost=10" > /etc/yum.repos.d/doca.repo -
Update the index:
<bf> $ yum makecache
Package Upgrade Selection
Choose one of the following options to upgrade your packages.
Option 1: Upgrade BlueField FW Bundle
This command upgrades the ATF-UEFI, NIC firmware, and BMC firmware only.
<bf> $ dnf install bf-fwbundle
Option 2: Update Specific DOCA Components
To skip the firmware update (for example, when updating through DPU-BMC or Redfish), remove the old firmware packages:
-
If your DOCA version is earlier than 3.4.0:
<bf> $ dnf remove bf2-bmc-fw-signed bf3-bmc-fw-signed bf3-bmc-gi-signed bf3-bmc-nic-fw* bf2-cec-fw-signed bf3-cec-fw-signed -
If your DOCA version is 3.4.0 or later:
<bf> $ dnf remove bf2-bmc-fw-signed bf3-bmc-fw-signed bf3-bmc-gi-signed bf3-bmc-nic-fw* bf2-cec-fw-signed bf3-cec-fw-signed mlxbf-bootimages-signed
-
Remove the deprecated
hcollpackage:<bf> $ rpm -e --nodeps hcoll -
Manage kernel version locks: Ensure the correct kernel is applied.
-
For non-Anolis OS:
-
Install the version lock plugin:
<bf> $ dnf install -y 'dnf-command(versionlock)' -
Clear existing kernel locks:
<bf> $ dnf versionlock delete kernel*
-
-
For Anolis OS:
-
Install the version lock plugin:
<bf> $ dnf install -y 'dnf-command(versionlock)' -
Add specific kernel locks:
<bf> $ dnf versionlock add \ kernel-5.10.134-13.1.an8.aarch64 \ kernel-core-5.10.134-13.1.an8.aarch64 \ kernel-rpm-macros-129-1.0.2.an8.noarch \ kernel-headers-5.10.134-13.1.an8.aarch64 \ kernel-modules-5.10.134-13.1.an8.aarch64 \ kernel-modules-extra-5.10.134-13.1.an8.aarch64 \ kernel-devel-5.10.134-13.1.an8.aarch64 \ anolis-release-8.6-4.an8.aarch64 \ anolis-repos-8.6-4.an8.aarch64 \ anolis-gpg-keys-8.6-4.an8.noarch
-
-
-
Install firmware packages:
<bf> $ dnf install -y bf2-bmc-fw-signed bf3-bmc-fw-signed bf3-bmc-gi-signed bf3-bmc-nic-fw* bf2-cec-fw-signed bf3-cec-fw-signed -
Ensure
sshpassis installed (required for component activation):<bf> $ command -v sshpass >/dev/null 2>&1 || { dnf install -y sshpass || yum install -y sshpass; } -
Perform the OS upgrade:
-
For non-Anolis OS:
-
Run the standard upgrade command:
<bf> $ dnf upgrade --nobest -
Lock the kernel packages to the current version:
<bf> $ dnf versionlock kernel* -
Update the GRUB configuration to ensure the correct default boot entry:
<bf> $ sed -i 's/^GRUB_DEFAULT=.*/GRUB_DEFAULT=0/' /etc/default/grub -
Rebuild the GRUB configuration file (replace
<OS_NAME>with your OS directory name, for example,rocky,openEuler):<bf> $ grub2-mkconfig -o /boot/efi/EFI/<OS_NAME>/grub.cfg
-
-
For Anolis OS:
-
Remove the deprecated gRPC package:
<bf> $ dnf -y remove doca-grpc -
Remove OpenMPI and OpenSM dependencies:
<bf> $ rpm -e --nodeps openmpi opensm opensm-devel opensm-static opensm-libs -
Upgrade while excluding specific trace and daemon packages:
<bf> $ dnf --exclude='libtraceevent*,rasdaemon*' upgrade -
Verify if an
.rpmsaveGRUB backup exists:<bf> $ ls /boot/efi/EFI/anolis/grub.cfg.rpmsave -
If the file exists, rename it to restore the correct configuration:
<bf> $ mv /boot/efi/EFI/anolis/grub.cfg.rpmsave /boot/efi/EFI/anolis/grub.cfg
-
-
Firmware Configuration and Activation
Skip this phase if you do not want to update firmware.
-
Configure BMC parameters by adding the BMC user and password to
/etc/bf-upgrade.conf(format is identical tobf.cfg):<bf> $ cat > /etc/bf-upgrade.conf << EOF BMC_USER="<username>" BMC_PASSWORD="<password>" WITH_NIC_FW_UPDATE="yes" BMC_REBOOT="yes" EOFBMC_REBOOT="yes"causes a warm boot to the BMC, temporarily losing connectivity. -
Activate the components:
<bf> $ dpu-bmc-upgradeThe upgrade process takes up to 20 minutes. The script performs an
fwresetif supported.
Apply Changes
For the upgrade to take effect, perform a BlueField system reboot to apply the new changes, NIC firmware, and UEFI/ATF.
This step triggers an immediate reboot of the BlueField Arm cores.
Building Custom BFB Installation Image
To build a customized BlueField OS image, use the BFB build environment. For more details, refer to the bfb-build project in GitHub.
To boot a customized BlueField OS image on a UEFI secure-boot-enabled BlueField (the default secure boot setting), the following conditions must be met:
-
The OS image must be signed with a key already present in the UEFI DB (for example, the Microsoft key)
-
If this is not possible, UEFI secure boot must be disabled to allow booting of an unsigned or differently signed image
For detailed instructions on managing UEFI secure boot, refer to the "Secure Boot" page in the BlueField Platform SW Documentation.
Last updated: