BF-Bundle Installation and Upgrade
Important! Make sure to update DOCA on the host side before installing the BF-bundle on the BlueField.
Users have three options for installing or upgrading DOCA on 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 | |
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 |
Find the DOCA installation files for BlueField from the NVIDIA DOCA Downloads page.
Make sure to update DOCA on the host side before installing the BF-bundle on the BlueField.
The ATF will 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.
Users can install DOCA on BlueField DPU or SuperNIC by upgrading the full DOCA image on BlueField.
This overwrites the entire boot partition with an Ubuntu 22.04 installation and updates BlueField and NIC firmware.
This installation sets up the OVS bridge.
Upgrading DOCA components on BlueField networking platforms, such as DPUs or SuperNICs, using standard Linux tools will install 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.
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 bfb-install --rshim rshim<N> --bfb <image_path.bfb>
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 list the RShim devices present on your system, run the following command:
host# ls -la /dev/ | grep rshim
By default bfb-install
will clear the RShim log in /dev/rshim<N>/misc
and save it as tmp/bfb-install-rshim[N].log
instead. To preserve the RShim log in /dev/rshim<N>/misc
, provide the --keep-log
argument to the bfb-install
command line.
Option 2 – Set Pre-defined Password
Ubuntu users can set a unique password for the ubuntu
user in the bf.cfg
configuration file
, which will be 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$TlHry93NFUJzg3Nya00rE1Add the password hash to the
bf.cfg
configuration file:host# echo ubuntu_PASSWORD=
'$1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1'
> bf.cfgUse the
--config
flag to specify the configuration file when running the installation command:host# sudo bfb-install --rshim rshim<N> --bfb <image_path.bfb> --config bf.cfg
NoteIf
--config
is not used, then upon first login to the BlueField device, users will be prompted to update the defaultubuntu
password.NoteOptionally, to upgrade the BlueField integrated BMC firmware using BFB bundle, please provide the current BMC root credentials in a
bf.cfg
file, as shown in the following:BMC_PASSWORD=
"<root password>"
BMC_USER="root"
BMC_REBOOT="yes"
Unless previously changed, the default BMC root password is
0penBmc
.The following is an example output of Ubuntu-22.04 BFB bundle installation (version may vary in the future):
host# sudo bfb-install --rshim rshim0 --bfb bf-bundle-2.7.0_24.04_ubuntu-22.04_prod.bfb --config bf.cfg Pushing bfb 1.41GiB 0:02:02 [11.7MiB/s] [ <=> ] Collecting BlueField booting status. Press Ctrl+C to stop INFO[PSC]: PSC BL1 START INFO[BL2]: start INFO[BL2]: boot mode (rshim) INFO[BL2]: VDDQ: 1120 mV INFO[BL2]: DDR POST passed INFO[BL2]: UEFI loaded INFO[BL31]: start INFO[BL31]: lifecycle GA Secured INFO[BL31]: VDD: 850 mV INFO[BL31]: runtime INFO[BL31]: MB ping success INFO[UEFI]: eMMC init INFO[UEFI]: eMMC probed INFO[UEFI]: UPVS valid INFO[UEFI]: PMI: updates started INFO[UEFI]: PMI: total updates: 1 INFO[UEFI]: PMI: updates completed, status 0 INFO[UEFI]: PCIe enum start INFO[UEFI]: PCIe enum end INFO[UEFI]: UEFI Secure Boot INFO[UEFI]: PK configured INFO[UEFI]: Redfish enabled INFO[UEFI]: exit Boot Service INFO[MISC]: Found bf.cfg INFO[MISC]: Ubuntu installation started INFO[MISC]: Installing OS image INFO[MISC]: Changing the default password for user ubuntu INFO[MISC]: Ubuntu installation completed INFO[MISC]: Updating NIC firmware... INFO[MISC]: NIC firmware update done INFO[MISC]: Installation finished
To verify that the BlueField device has completed booting, wait 90 seconds after the installation process finishes and run 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:
Log into BlueField.
Run the following:
bf# sudo bf-info
Example output:
Firmware: - ATF: v2.2(release):4.11.0-31-g3cc9f6506 - UEFI: 4.11.0-44-gb67dfb4a53 - BSP: 4.11.0.13582 - NIC Firmware: 32.45.0350 - BMC Firmware: 25.04-3 - CEC Firmware: 00.02.0195.0000 Drivers: - mlnx-dpdk: 'MLNX_DPDK 22.11.2504.0.2' - Kernel: 5.15.0-1064-bluefield Tools: - MFT: 4.32.0-94 - mstflint: 4.29.0-1 Storage: - mlnx-libsnap 1.6.0-1 - spdk 23.01.5-24 - virtio-net-controller 24.10.15-1 DOCA: - doca-apsh-config 2.9.0064-1 - libdoca-sdk-urom-dev 2.9.0064-1 ... FlexIO: - flexio-samples 24.10.2447 - flexio-sdk 24.10.2447 ... SoC Platform: - mlxbf-gige-modules 1.0-0.kver.6.1.0-11-arm64 - sdhci-of-dwcmshc-modules 1.0-0.kver.6.1.0-11-arm64 ... OFED: rdma-core 2410mlnx54-1.2410051 ucx 1.18.0-1.2410051 ...
To configure the
tmfifo_net0
interface over IPv4 for SSH access to the BlueField Arm OS:host# ifconfig tmfifo_net0
192.168
.100.1
/24
InfoSSH into the BlueField Arm OS with 192.168.100.2 (preconfigured default):
host# ssh ubuntu
@192
.168.100.2
This procedure allows for upgrading DOCA components on BlueField networking platforms (DPUs or SuperNICs) using standard Linux tools (e.g., apt update
and yum update
). It leverages native package manager repositories to update components without requiring a full reinstallation.
While this approach enables updating specific DOCA components, the combinations created by 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 will install 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 has the following benefits :
Only updates components that include modifications
Includes upgrade of:
DOCA drivers and libraries
DOCA reference applications
BSP (UEFI/ATF) upgrade while maintaining the configuration
NIC firmware upgrade while maintaining the configuration
BMC components upgrade
Does not:
Impact user binaries
Upgrade non-Ubuntu OS kernels
After completion of BlueField upgrade:
If NIC firmware was not updated, perform BlueField Arm reset (software reset/reboot BlueField )
If NIC firmware was updated, perform firmware reset (
mlxfwreset
) or perform a graceful shutdown and power cycle
DEB-based
Action | Instructions |
Export the desired distribution | Export
|
Add GPG key to APT trusted keyring |
|
Add DOCA online repository |
|
Update index |
|
Choose one of the two options for packages upgrade | Option-1 Upgrade BlueField FW Bundle package ( including ATF-UEFI, NIC firmware, and BMC firmware ):
|
Option-2 System upgrade (install all packages):
| |
Configure BMC parameters | Add the BMC user and password to config file
|
Components activation |
Info
The upgrade process should take up to 20 minutes. |
Apply the new changes, NIC firmware, and UEFI/ATF | For the upgrade to take effect, perform BlueField system reboot. Note
This step triggers immediate reboot of the BlueField Arm cores. |
RPM-based
Action | Instructions |
Export the desired distribution | Export
|
Add DOCA online repository |
A file is created under |
Update index |
|
Choose one of the two options for packages upgrade | Option-1 Upgrade BlueField FW Bundle package ( including ATF-UEFI, NIC firmware, and BMC firmware ):
|
Option-2
| |
Configure BMC parameters | Add the BMC user and password to config file
|
Components activation |
Info
The upgrade process should take up to 20 minutes. |
Apply the new changes, NIC firmware, and UEFI/ATF | For the upgrade to take effect, perform BlueField system reboot. Note
This step triggers immediate reboot of the BlueField Arm cores. |
The DOCA Installer is a utility for installing or upgrading one or more BlueField DPUs in parallel. It supports both bf-bundle
and bf-fw-bundle
image types and is compatible with multiple BlueField operation modes, including NIC mode, DPU mode, or both on the same host. Customization is supported through INI or YAML configuration files.
Prerequisites
Make sure to update DOCA on the host side before installing doca-installer
.
DEB-based |
|
RPM-based |
|
DOCA Installer Operation Modes
The installer supports the following execution modes:
Global run (applies to all devices):
host# doca-installer -b <image_path.bfb> -c <path-to-config>
Per PSID group (targets devices sharing the same PSID):
host# doca-installer -b <image_path.bfb> --psid <PSID> -c <path-to-config>
InfoTo exclude devices when using global or per-PSID runs, use
--exclude rshim<X>
.Per RShim device (targets a specific RShim interface):
host# doca-installer -b <image_path.bfb> --rshim rshim<N> -c <path-to-config>
Where:
-c
or--config-file
– defines a configuration via INI or YAML filesNoteTo upgrade BMC, CEC, or Golden Image firmware, include
BMC_USER
andBMC_PASSWORD
in thebf.cfg
orbf.yaml
file.<path-to-config>
– Path to the INI or YAML configuration file<image_path.bfb>
– Path to the BFB image file<PSID>
– Shared PSID value for the target groupNoteDevices that do not match the provided PSID will not be upgraded.
<N>
– RShim device index (e.g.,0
for a single-device setup)
The doca-installer
script attempts to load the new NIC firmware automatically, but if that fails, it will print out the following message:
INFO: At least one device requires a host power cycle for
new
NIC Firmware to be loaded.
If the script discovers that one or more of the devices did not have BMC_REBOOT
set to 'yes'
as part of the configuration file, it will print out the following message:
WARNING: BMC_REBOOT is not configured for
all devices or is not set to 'yes'
.
BMC firmware updates will only take effect after a BMC reboot.
Configuration File Options
YAML Configuration File
The YAML format supports global and per-device customization using structured keys:
global_configs
– Shared parameters for all devices (e.g., credentials)rshim
– Device-specific configurationsEach key under
rshim
(e.g.,rshim1
,rshim2
) defines variables and methods for that device
variables
– Parameters that control the installation process (e.g.,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/etc/sysconfig/network-scripts/ifcfg-tmfifo_net0
sed -i -e "s@192.168.100.1@192.168.101.1@"
/mnt/etc/sysconfig/network-scripts/ifcfg-tmfifo_net0
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
INI Configuration File
Per-Device Configuration ini Copy Edit 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>"
BMC_NEW_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
The DOCA Installer tool provides extended logging and improved debuggability compared to the legacy bfb-install
tool.
For each execution of the doca-installer
, a unique log directory is created under:
/var/log/doca_installer_logs/doca_installer_<timestamp>
This directory includes comprehensive logs and outputs such as:
Full execution log of the
doca-installer
toolrshim
diagnostics (per device)lspci
output (per device and full system)bfb-install
outputmlxconfig
outputmlxprivhost
outputmstdump
output (if applicable)flint
image retrieval logs (if applicable)
DOCA Installer Standalone Flags
The doca-installer
tool introduces enhanced capabilities for comparing target image firmware versions with those currently running on devices. This allows for safer, more controlled upgrade decisions.
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
Example output:

Fetch Firmware Versions from Running Devices
Use the --show-running-fw
flag to display firmware versions currently installed on each detected BlueField device:
host# doca-installer --show-running-fw
Example output:

Compare Image vs. 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> --compare
Example output:

Supported DOCA-Host OS for DOCA Installer
The following OSs on the host machine are supported for doca-installer
:
Operating System | Architecture |
debian10.13 | x86_64 |
aarch64 | |
debian12.1 | x86_64 |
aarch64 | |
debian12.5 | x86_64 |
aarch64 | |
openeuler24.03 | x86_64 |
aarch64 | |
ol8.4 | x86_64 |
ol8.6 | x86_64 |
ol8.7 | x86_64 |
ol8.8 | x86_64 |
ol8.10 | x86_64 |
ol9.1 | x86_64 |
ol9.2 | x86_64 |
ol9.4 | aarch64 |
rhel8.2 | x86_64 |
aarch64 | |
rhel8.4 | x86_64 |
aarch64 | |
rhel8.6 | x86_64 |
ppc64le | |
aarch64 | |
rhel8.8 | x86_64 |
ppc64le | |
aarch64 | |
rhel8.9 | x86_64 |
ppc64le | |
aarch64 | |
rhel8.10 | x86_64 |
ppc64le | |
aarch64 | |
rhel9.0 | x86_64 |
ppc64le | |
aarch64 | |
rhel9.2 | x86_64 |
ppc64le | |
aarch64 | |
rhel9.4 | x86_64 |
ppc64le | |
aarch64 | |
rhel9.5 | x86_64 |
aarch64 | |
ppc64le | |
rhel9.6 | x86_64 |
aarch64 | |
ppc64le | |
ubuntu22.04 | x86_64 |
ppc64le | |
aarch64 | |
ubuntu24.04 | x86_64 |
aarch64 | |
ppc64le | |
ubuntu24.10 | x86_64 |
ubuntu25.04 | x86_64 |
aarch64 | |
azurelinux3.0 | x86_64 |
aarch64 |
Users wishing to build their own customized BlueField OS image can use the BFB build environment. For more details, refer to the bfb-build project in this GitHub webpage.
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 (e.g., the Microsoft key)
If the above 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.