Metadata-Version: 2.1
Name: doca-installer
Version: 1.2.10
Summary: DOCA Installer is a tool to manage BFB installation across DPUs in parallel
Author: Networking Support
Author-email: Networking Support <networking-support@nvidia.com>
Maintainer: Networking Support
Maintainer-email: Networking Support <networking-support@nvidia.com>
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# DOCA Installer

This project is a utility for installing and upgrading BlueField bundle.

This tool allows parallel installation of BF Bundles or BF Firmware Bundles on your DPUs.

## Features

- Supports parallel installation for all available devices
- One configuration file per host
- Support multiple DPU operation modes
- Query Bundle image firmware components
- Compare current device firmware versions with bundle image versions without installation
- Display current running firmware versions of all available devices



## How to run
Make sure you have installed the doca-installer package on your host

Local run
```bash
  doca-installer -b /path/to/bf-bundle.bfb
```


## System requierments


| Tool | Version |
| :-------- | :---- |
| `Python` |  **Minimum** 3.8 |
| `MFT` |  Rel 1B 2025 / October LTS 2024 |
| `RSHIM` |  Rel 1B 2025 / October LTS 2024 |


## Bundle support

```
  The tool supports the installation of BF Bundles or BF Firmware Bundles starting from the following versions
```

| Release | Version                       |
| :-------- | :-------------------------------- |
| `GA`      | Rel 1B 2025 |
| `LTS`      | October LTS 2024​ |

#### Bundle support
| Bundle type | NIC Mode | DPU Mode |
| :-------- | :--------------- |:------------------ |
| `BF Firmware Bundle`      | ✅ | ✅ |
| `BF Bundle`      | ✅​ | ✅ |



## Customized run

This tool support running in few modes that are being controlled by arguments

```bash
    `-c` or `--config-file`: The path to the configuration file to use.
    `-p` or `--psid`: The PSID of the specific BlueField device to upgrade.
    `-r` or `--rshim`: The rshim device to install on.
    `--exclude`: List of RSHIM devices to exclude from the installation (e.g. --exclude rshim0 rshim2 rshim3).
    `--show-target-fw`: Extract and display target firmware versions from the image bundle and exit.
    `--compare`: Compare current device firmware versions with the provided image bundle versions and exit (no installation performed).
    `--show-running-fw`: Display current running firmware versions of all available devices and exit (no bundle required). This flag is ignored if a bundle is provided.
    `--lfwp`: Enable LFWP (Live-Firmware-Patch). Same flow as runtime with automatic L0 NIC_FW reset with best effort. Report error in case of failures.
    `--activate`: Activation flag (0 or 1) for use with --lfwp. LFWP enables activation by default unless --activate=0 is specified.
```

#### LFWP (Live-Firmware-Patch) Mode

The `--lfwp` flag enables Live-Firmware-Patch mode, which provides the same functionality as runtime mode with the addition of automatic L0 NIC_FW reset with best effort. This mode will report errors in case of failures.

When using `--lfwp`, the activation behavior can be controlled with the `--activate` flag:
- By default, LFWP performs activation
- Use `--activate=0` to disable activation
- Use `--activate=1` to explicitly enable activation (same as default)

**Note**: These flags are only supported in newer versions of bfb-install. The tool will automatically check for compatibility and report an error if the installed version doesn't support these features.

Examples:
```bash
# Enable LFWP with default activation
doca-installer -b /path/to/bf-bundle.bfb --lfwp

# Enable LFWP without activation
doca-installer -b /path/to/bf-bundle.bfb --lfwp --activate=0

# Enable LFWP with explicit activation
doca-installer -b /path/to/bf-bundle.bfb --lfwp --activate=1
```


## Customization of DPU Enviroment

Using a configuration file, a user can customize the DPU environment

In order to do so, you can chose between the option to specify each customization for each device, or provide customization settings for all devices.
The tool supports configuration files in both legacy INI style and YAML formats.

##### Please note - in order to upgrade BMC / CEC / Golden image version, BMC_USER and BMC_PASSWORD variable must be defined in the configuration file

#### Customization per device

To enable per-device configuration, you must specify the RSHIM device that each variable or method targets.
```
RSHIM0_BMC_USER="root"
RSHIM0_BMC_PASSWORD="AdminPass_123"

RSHIM1_BMC_USER="root"
RSHIM1_BMC_PASSWORD="AdminPass_456!"
```

#### Customization shared for all device

In case you wish to customize all of your devices and they all shared same parameters (on those who can be shared)
customization can be done as follow

```
# Shared variables

BMC_USER="root"
BMC_PASSWORD="AdminPass_123"
BMC_NEW_PASSWORD="AdminPass_456"

# Not shared variables - optional

RSHIM0_NET_RSHIM_MAC=00:1a:ca:ff:ff:01
RSHIM1_NET_RSHIM_MAC=00:1a:ca:ff:ff:03
```

#### Advanced – Customized Methods

Just like with customized variables per device, in order to provide a customized method per device, you'll need to specify the RSHIM device that you wish the methods to be executed on
```
RSHIM0_bfb_modify_os()
{
        log ===================== bfb_modify_os =====================
        sed -i -e "s@192.168.100.1@192.168.100.1@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
}

RSHIM1_bfb_modify_os()
{
        log ===================== bfb_modify_os =====================
        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
}
```


### YAML Configuration File

DOCA Installer now also supports specifying configuration via a YAML file as an alternative to the traditional shell variable format. 
### Explanation of YAML Keys
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, rshimX) represents a specific device's configuration.
- **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.
- If both **rshimX** and **global_configs** share the same configuration, the script will prioritize settings specified in the **rshimX** section.
Below are some example YAML configuration files demonstrating various scenarios.

#### Customization per device with no global configs

```yaml
rshim:
  rshim1:
    variables:
      BMC_USER: 'root'
      BMC_PASSWORD: 'AdminPass_123'
    methods:
      bfb_modify_os:
        command: |
          log ===================== bfb_modify_os =====================
          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
  rshim2:
    variables:
      BMC_USER: 'root'
      BMC_PASSWORD: 'AdminPass_456'
    methods:
      bfb_modify_os:
        command: |
          log ===================== bfb_modify_os =====================
          sed -i -e "s@192.168.100.2@192.168.102.2@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
          sed -i -e "s@192.168.100.1@192.168.102.1@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
```

#### Customization for all devices using global configs only

```yaml
global_configs:
  variables:
    BMC_USER: 'root'
    BMC_PASSWORD: '0penBmc'
```

#### Customization all devices using global configs, and specific configs per device

```yaml
global_configs:
  variables:
    BMC_USER: 'root'
    BMC_PASSWORD: '0penBmc'
rshim:
  rshim1:
    variables:
      UPDATE_DPU_OS: 'yes'
      WITH_NIC_FW_UPDATE: 'no'
    methods:
      bfb_post_install:
        command: echo "Executing post-install on rshim1"
  rshim2:
    variables:
      BMC_PASSWORD: 'AdminPass_456'
    methods:
      bfb_modify_os:
        command: |
          log ===================== bfb_modify_os =====================
          sed -i -e "s@192.168.100.2@192.168.102.2@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
          sed -i -e "s@192.168.100.1@192.168.102.1@" /mnt/var/lib/cloud/seed/nocloud-net/network-config
```

#### Advanced example with reusing methods using anchors


```yaml
global_configs:
  variables:
    BMC_USER: 'root'
    BMC_PASSWORD: '0penBmc'
rshim:
  rshim1:
    variables:
      UPDATE_DPU_OS: 'yes'
      WITH_NIC_FW_UPDATE: 'no'
    methods:
      bfb_post_install: &default_post_install
        command: |
          echo "Running post-install on rshim1"
  rshim2:
    variables:
      UPDATE_DPU_OS: 'no'
      WITH_NIC_FW_UPDATE: 'yes'
    methods:
      bfb_post_install: *default_post_install
```

For more details on YAML syntax and best practices, please refer to the official [YAML Specification](https://yaml.org/spec/).


For more information about customization using configuration files please check out [Customizing BlueField Software Deployment Using bf.cfg](https://docs.nvidia.com/networking/display/bluefieldbsp480/customizing+bluefield+software+deployment+using+bf-cfg#:~:text=cfg-,bf.,platforms%20(DPU%20or%20SuperNIC).&text=To%20update%20the%20BMC%20components,the%20BFB%2FISO%20installation%20environment.).
