BF-Bundle Installation and Upgrade

Users have three options for installing or upgrading DOCA on BlueField DPU or SuperNIC:

Make sure to update DOCA on the host side before installing the BF-bundle on the BlueField.

Users can install DOCA on BlueField DPU or SuperNIC by upgrading the full DOCA image on BlueField.

Option 1 – No Pre-defined Password

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, use rshim0.

• <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
        

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:

1. Generate the hashed password:

   Copy

   Copied!

               
   
               
   host# openssl passwd -1
   Password:
   Verifying - Password:
   $1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1
           

2. Add the password hash to the bf.cfg configuration file:

   Copy

   Copied!

               
   
               
   host# echo ubuntu_PASSWORD='$1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1' > bf.cfg
           

3. Use the --config flag to specify the configuration file when running the installation command:

   Copy

   Copied!

               
   
               
   host# sudo bfb-install --rshim rshim<N> --bfb <image_path.bfb> --config bf.cfg
           

   Note

   If --config is not used, then upon first login to the BlueField device, users will be prompted to update the default ubuntu password.

   Note

   Optionally, 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:

   Copy

   Copied!

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

   Collapse Source

   Copy

   Copied!

               
   
               
   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 
           

4. To verify that the BlueField device has completed booting, wait 90 seconds after the installation process finishes and run the following command:

   Copy

   Copied!

               
   
               
   host# sudo cat /dev/rshim<N>/misc
   ...
    INFO[MISC]: Linux up
    INFO[MISC]: DPU is ready
           

5. Retrieve installed packages and their versions as part of BF-Bundle installation:

   1. Log into BlueField.

   2. Run the following:

      Copy

      Copied!

                  
      
                  
      bf# sudo bf-info
              

      Example output:

      Collapse Source

      Copy

      Copied!

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

6. To configure the tmfifo_net0 interface over IPv4 for SSH access to the BlueField Arm OS:

   Copy

   Copied!

               
   
               
   host# ifconfig tmfifo_net0 192.168.100.1/24
           

   Info

   SSH into the BlueField Arm OS with 192.168.100.2 (preconfigured default):

   Copy

   Copied!

               
   
               
   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.

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

            

            
<bf> $ export DOCA_REPO="<URL>"
        

            

            
<bf> $ curl $DOCA_REPO/GPG-KEY-Mellanox.pub | gpg --dearmor > /etc/apt/trusted.gpg.d/GPG-KEY-Mellanox.pub
        

            

            
<bf> $ echo "deb [signed-by=/etc/apt/trusted.gpg.d/GPG-KEY-Mellanox.pub] $DOCA_REPO ./" > /etc/apt/sources.list.d/doca.list
        

            

            
<bf> $ apt update
        

            

            
<bf> $ apt install bf-fwbundle
        

            

            
<bf> $ apt upgrade
        

            

            
<bf> $ cat > /etc/bf-upgrade.conf << EOF
BMC_USER="<username>"
BMC_PASSWORD="<password>"
EOF
        

            

            
<bf> $ dpu-bmc-upgrade
        

RPM-based

            

            
<bf> $ export DOCA_REPO="<URL>"
        

            

            
echo "[doca] 
name=DOCA Online Repo 
baseurl=$DOCA_REPO 
enabled=1 
gpgcheck=0 
priority=10 
cost=10" > /etc/yum.repos.d/doca.repo
        

            

            
<bf> $ yum makecache
        

            

            
<bf> $ dnf install bf-fwbundle
        

            

            
<bf> $ sed -i 's/^GRUB_DEFAULT=.*/GRUB_DEFAULT=0/' /etc/default/grub
<bf> $ grub2-mkconfig -o /boot/efi/EFI/<OS_NAME>/grub.cfg
        

            

            
<bf> $ cat > /etc/bf-upgrade.conf << EOF
BMC_USER="<username>"
BMC_PASSWORD="<password>"
EOF
        

            

            
<bf> $ dpu-bmc-upgrade
        

DOCA installer is a utility designed to install and upgrade BFB and BlueField firmware bundle images across multiple DPUs in parallel.

It supports multiple DPU operation modes, including NIC mode, DPU mode, and both modes on the same host. It offers extensive customization through configuration files in INI and YAML formats.

DOCA Installer Running Modes

DOCA installer supports 3 installation running modes:

            

            
host# doca-installer -b <image_path.bfb>
        

            

            
host# doca-installer -b <image_path.bfb> --psid <PSID>
        

            

            
host# doca-installer -b <image_path.bfb> --rshim rshim<N>
        

Where:

• <N> – the appropriate RShim device identifier. If your environment has only one BlueField device, use 0.
• <image_path.bfb> – Replace this with the path to the BFB image file

• <PSID> – the group shared PSID identifier

  Note

  Other cards who do not share this PSID will not be upgraded.

Run DOCA Installer with Configuration File

DOCA installer supports 2 configuration files in the format of either INI or YAML.

Running DOCA installer with configuration file requires providing -c <path-to-config> or --config-file <path-to-config>.

            

            
host# doca-installer -b <image_path.bfb> -c <path-to-config>
        

            

            
host# doca-installer -b <image_path.bfb> --psid <PSID> -c <path-to-config>
        

            

            
host# doca-installer -b <image_path.bfb> --rshim rshim<N> -c <path-to-config>
        

Where:

• <N> – the appropriate RShim device identifier. If your environment has only one BlueField device, use 0.
• <image_path.bfb> – Replace this with the path to the BFB image file

• <PSID> – the group shared PSID identifier

  Note

  Other cards who do not share this PSID will not be upgraded.

• <path-to-config> – Path to configuration file (INI or YAML)

  Note

  The YAML configuration file uses a few key sections to organize settings:

  • global_configs – Defines variables that are common to all devices. Under this key, the variables sub-key is used to specify shared parameters such as BMC_USER and BMC_PASSWORD. These settings apply globally unless overridden by device-specific configurations.

  • rshim – Contains configuration for individual devices. Within the rshim section, each key (e.g., rshim1, rshim2) represents a specific device's configuration.

    Note

    When rshim<N> and global_configs share the same configuration, the script prioritizes rshim<X> settings.

  • variables – Specifies device-specific configuration parameters (e.g., UPDATE_DPU_OS, WITH_NIC_FW_UPDATE) that control the installation and upgrade process for that device

  • methods – Contains commands or steps (often multi-line shell commands) that are executed to customize the device. YAML anchors (e.g., &default_post_install) can be used here to reuse common command blocks across multiple devices.

INI Configuration File Customization

            

            
RSHIM0_BMC_USER="root"
RSHIM0_BMC_PASSWORD="<root password>"
 
RSHIM1_BMC_USER="root"
RSHIM1_BMC_PASSWORD="<root password>"
        

            

            
# Shared variables
BMC_USER="root"
BMC_PASSWORD="<root password>"
BMC_NEW_PASSWORD="<new root BMC password>"
 
# Not shared variables - optional
RSHIM0_NET_RSHIM_MAC=00:1a:ca:ff:ff:01
RSHIM1_NET_RSHIM_MAC=00:1a:ca:ff:ff:03
        

YAML Configuration File Customization

            

            
rshim:
  rshim1:
    variables:
      BMC_USER: 'root'
      BMC_PASSWORD: '<root password>'
    methods:
      bfb_modify_os:
        command: |
          log ===================== bfb_modify_os =====================
          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
  rshim2:
    variables:
      BMC_USER: 'root'
      BMC_PASSWORD: '<root password>'
    methods:
      bfb_modify_os:
        command: |
          log ===================== bfb_modify_os =====================
          sed -i -e "s@192.168.100.2@192.168.102.2@" /mnt/etc/sysconfig/network-scripts/ifcfg-tmfifo_net0
          sed -i -e "s@192.168.100.1@192.168.102.1@" /mnt/etc/sysconfig/network-scripts/ifcfg-tmfifo_net0
        

            

            
global_configs:
  variables:
    BMC_USER: 'root'
    BMC_PASSWORD: '<root password>'
        

            

            
global_configs:
  variables:
    BMC_USER: 'root'
    BMC_PASSWORD: '<root password>'
rshim:
  rshim1:
    variables:
      BMC_REBOOT: 'yes'
      WITH_NIC_FW_UPDATE: 'no'
 
  rshim2:
    variables:
      BMC_PASSWORD: '<root password for rshim2 BMC>'
        

            

            
global_configs:
  variables:
    BMC_USER: 'root'
    BMC_PASSWORD: '<root password>'
rshim:
  rshim1:
    variables:
      BMC_REBOOT: 'yes'
      WITH_NIC_FW_UPDATE: 'no'
    methods:
      bfb_post_install: &default_post_install
        command: |
          echo "Running post-install on rshim1"
  rshim2:
    methods:
      bfb_post_install: *default_post_install
        

Logs and Debuggability

The DOCA installer tool will provide extended logs and enhanced debuggability compared to the existing options available with the bfb-install tool.

            

            
/var/log/doca_installer_logs/doca_installer_<time stamp>
        

The following is an example output of Ubuntu-22.04 BFB bundle installation on top of a host with 4 devices (version may vary in the future):

host# doca-installer -b /root/bf-bundle-3.0.0-91_25.04_ubuntu-22.04_prod.bfb -c /root/bf.cfg

Extracting firmware versions from /root/bf-bundle-3.0.0-91_25.04_ubuntu-22.04_prod.bfb Target Firmware Versions of the provided image:

Bundle install of /root/bf-bundle-3.0.0-91_25.04_ubuntu-22.04_prod.bfb image Logs will be saved to /var/log/doca_installer_logs/doca_installer_20250401_104535 directory INFO: Searching for interfering processes: minicom, screen Available DPUs on host: 4 BF DPUs:

The following DPUs are about to be upgrade: 4 BF DPUs:

Generated configuration for 0000:03:00.0 at /tmp/rshim0-bf.cfg Generated configuration for 0000:27:00.0 at /tmp/rshim1-bf.cfg Generated configuration for 0000:83:00.0 at /tmp/rshim3-bf.cfg Generated configuration for 0000:a3:00.0 at /tmp/rshim2-bf.cfg.

Validating new FW on DPUs... Post-installation verification results: Verification for device: 0000:27:00.0 (PSID: MT_0000000884)

--------------------------------------------------------------------------------

Verification for device: 0000:83:00.0 (PSID: MT_0000000884)

--------------------------------------------------------------------------------

Verification for device: 0000:a3:00.0 (PSID: MT_0000000884)

--------------------------------------------------------------------------------

Verification for device: 0000:03:00.0 (PSID: MT_0000000884)

            

            
================================================================================
UPGRADE SUMMARY REPORT
================================================================================
 
The following devices passed upgrade successfully:
      1. 0000:27:00.0 (PSID: MT_0000000884)
      2. 0000:83:00.0 (PSID: MT_0000000884)
      3. 0000:a3:00.0 (PSID: MT_0000000884)
	  4. 0000:03:00.0 (PSID: MT_0000000884)
 
The following devices did not pass upgrades successfully:
      None
        

Important! The script will try to load the new NIC firmware automatically,
but in case it will fail to do so, it will notify the user with the following
message:
INFO: At least one device requires a host power cycle for new NIC Firmware
to be loaded.

Important! In case the script will find that one or more of the devices did not
have BMC_REBOOT set to 'yes' as part of the configuration file, it will notify the
user with 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.

Supported DOCA-Host OS for doca-installer

The following OSs on the host machine are supported for doca-installer:

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.