DOCA-Host install and profiles

1Two packages, five profiles

DOCA ships as two packages. DOCA-Host is “the software package installed on the host server which includes different DOCA installation profiles”; the BlueField Software Bundle (BF-Bundle) is what goes on the Arm cores: the DOCA runtime, the Arm OS, and the platform firmware and UEFI.^[11] A profile is a meta-package name you hand to apt or yum. Installing one pulls both doca-runtime (production libraries, drivers, tools) and doca-devel (headers, reference applications, compilers) by default.^[9]

DOCA 3.5.0 defines five profiles. Older documentation listed four; doca-host-basic is the addition.^[2]

The page recommends doca-all for BlueField and calls doca-networking the preferred choice for ConnectX; the rest of the “installer” column follows from the contents.^[2] All five profiles support BlueField-3, BlueField-2, ConnectX-8, ConnectX-7, the ConnectX-6 variants, ConnectX-5 and ConnectX-4 Lx.^[2] The install page also names doca-libvma, doca-libxlio and doca-extra as installable targets alongside the profiles.^[1]

Installing a profile is not a passive act. It replaces kernel modules (mlx5_core and the OFED stack), adds udev rules, and with doca-all installs services that may auto-start.^[7] Plan it like a driver change, because it is one.

2Install, upgrade, remove: the documented commands

Prerequisites first. The kernel headers must match the running kernel (/lib/modules/$(uname -r)/build must exist), GCC must match the kernel build, and RPM systems need DKMS 3.2 or newer.^[1] Supported hosts for 3.5.0 include Ubuntu 24.04.x and 22.04.x, RHEL and Rocky 9.x and 10.x, RHEL 8.10, Debian 12 and 13, SLES 15 and 16 and Oracle Linux 8 and 9.^[3]

The repository package comes from the DOCA downloads page; everything after that is the distribution’s package manager.^[1]

# DEB (Ubuntu, Debian)
sudo dpkg -i <repo_file>.deb
sudo apt-get update
sudo apt install -y doca-all          # or doca-networking / doca-ofed / doca-roce / doca-host-basic
sudo apt install -y mlnx-fw-updater   # optional firmware updater package

# RPM (RHEL, Rocky, Oracle Linux)
sudo rpm -Uvh <repo_file>.rpm
sudo yum makecache                    # SLES: zypper --gpg-auto-import-keys refresh
sudo yum install -y doca-all          # SLES: zypper install -y doca-all

# post-install, both families
sudo /etc/init.d/openibd restart
sudo mst restart

Upgrade is the same verb with the profile name: apt install <doca-profile>, yum upgrade <doca-profile> or zypper update <doca-profile>.^[1] Removal is a loop over every DOCA package, then the OFED uninstaller:^[1]

# DEB
for f in $(dpkg --list | grep -E 'doca|flexio|dpa-gdbserver|dpa-stats|dpa-resource-mgmt|dpaeumgmt|dpdk-community' | awk '{print $2}'); do sudo apt remove --purge $f -y; done
sudo /usr/sbin/ofed_uninstall.sh --force
sudo apt-get autoremove

# RPM
for f in $(rpm -qa | grep -i doca); do sudo yum -y remove $f; done
sudo /usr/sbin/ofed_uninstall.sh --force
sudo yum autoremove

Two more tools live under /opt/mellanox/doca/tools/. doca-kernel-support rebuilds the DOCA-Host kernel modules for a custom kernel, but the script ships in the doca-extra package, so the documented procedure is apt/yum install -y doca-extra first and then /opt/mellanox/doca/tools/doca-kernel-support; the page also notes it is no longer required for non-default kernels, because DKMS rebuilds the modules during a normal install. With Secure Boot, enrol the DKMS key first (mokutil --import /var/lib/dkms/mok.pub) or sign the rebuilt modules with MODULE_SIGN_PUB_KEY=/path/to/pub_key.der MODULE_SIGN_PRIV_KEY=/path/to/priv_key.priv WITH_MOD_SIGN=1 /opt/mellanox/doca/tools/doca-kernel-support.^[1] doca-info prints the host’s DOCA and driver state; attach its output to every escalation.^[1] Storage extras (mlnx-nvme-dkms, mlnx-nvme-kmp-default, mlnx-nfsrdma-dkms) are separate packages found with apt search mlnx-nvme or the yum, dnf or zypper equivalent.^[1]

3BlueField-3 runs DOCA-Host, not MLNX_OFED

The 3.5.0 General Support page states that BlueField-2 and ConnectX-7 are the last generation supported by MLNX_OFED.^[3] Read that from the other side: a BlueField-3 has no MLNX_OFED host driver, so DOCA-Host is the only supported host path for it. The transition guide gives the timeline: “Following the last release of MLNX_OFED, no new features will be added to MLNX_OFED. All new features will only be included as part of DOCA-OFED.” The last standalone MLNX_OFED shipped in October 2024, its LTS line (critical fixes and security only) runs to October 2027, and support ends then.^[4]

doca-ofed is the replacement: “an equivalent package of MLNX_OFED, providing the same functionality … including the same kernel drivers, user space libraries, and management tools”, installed with the package manager (sudo dnf -y install doca-ofed) instead of the old installer script.^[4] That is why a driver-only customer moving off MLNX_OFED lands on doca-ofed, not on doca-all.

The profile you pick also fixes your compatibility guarantee. The dependency policy defines Level 1 (perpetual forward and backward binary compatibility; either layer may be upgraded independently) and Level 2 (limited; breaking changes may land with the October GA, and compatibility holds October to July inside one annual cycle).^[5] The DOCA-OFED profile against firmware or a BF-Bundle is Level 1; every other profile against firmware or a BF-Bundle is Level 2, as are DOCA services against either.^[5] A doca-ofed host tolerates a firmware skew that a doca-all host does not.

4The four-way version match

The version skill’s four-way match is four reads of one DOCA release: build-time pkg-config --modversion doca-common, the install tree’s /opt/mellanox/doca/applications/VERSION, runtime doca_caps --version, and, on a BlueField host, the BFB-image release on the Arm (cat /etc/mlnx-release plus bfver). All four must match within a release; “any disagreement means the install is partial”. NIC firmware is a separate, fifth anchor with its own rule: it is out of window when its major.minor predates the level the host DOCA requires, or its FW Release Date predates the DOCA release by more than 12 months. Read each anchor from its own source and never infer one from another.^[6]

# (a) build-time: what pkg-config will link against
PKG_CONFIG_PATH=/opt/mellanox/doca/infrastructure/lib/pkgconfig pkg-config --modversion doca-common
# (b) install tree: the applications release string
cat /opt/mellanox/doca/applications/VERSION            # 3.5.0098 at tag 3.5.0
# (c) runtime: doca_caps is off PATH since DOCA 3.3
/opt/mellanox/doca/tools/doca_caps --version
# (d) NIC firmware: the separate anchor; read the FW Version and FW Release Date lines
sudo mst start
sudo flint -d /dev/mst/mt41692_pciconf0 q
# (e) Arm side: the BFB-image release, over the rshim network
ssh ubuntu@192.168.100.2 'cat /etc/mlnx-release; bfver'

At tag 3.5.0 the samples repository’s applications/VERSION reads 3.5.0098.^[10] Alternatives to flint q for the firmware read are mlxfwmanager --query and mst status -v.^[6] For 3.5.0 the General Support table lists BlueField-3 firmware 32.50.1002.^[3]

Three anti-patterns the version skill calls out: bfb-info is not a real NVIDIA tool (the Arm-side dump is bf-info); mlxprivhost is a privilege tool, not a version probe; and mlxconfig -d <bdf> q reports configuration, not firmware version.^[6]

One trap deserves its own paragraph. If /etc/apt/sources.list.d/doca.list points at one channel (latest or 3.5) while the installed packages are pinned to another (3.1.0105), an apt upgrade silently moves the host and not the card. The setup skill calls this “the most common cause of ‘my BlueField was rolled back to 3.1, but my host packages came back as 3.5’”.^[8]