Mojo - Firmware Bundles

Configuration and documentation for the firmwares available in the Mojo platform.

Prerequisites

This repo uses git-lfs to store the firmware files. Be sure to install it first.

https://github.com/git-lfs/git-lfs

Definitions are stored in .gitattributes

Firmwares

Firmwares are organized according to the following directory structure:

firmwares/
├── [manufacturer]/
│   └── [model]/
│       └── [type]/
|           └── [more_types]/  # For organization, you can nest more directories here
|               └── [version]
|                   |── [firmware file]
|                   |── [firmware file].sha256 (automatically generated)
|                   |── README.md
|                   └── def.yaml

These are organized for use in this this repository only and do not necessarily match the manufactuer, model, type and version as seen in Mojo. Although, if they do match, it makes it a whole heck of a lot easier.

The README.md file should be used to document where and when you download the firmware files in the directory. This is useful for auditing purposes and for others to know where to get the originals.

The def.yaml file is responsible for mapping the firmwares found in this repository to the Mojo Platform. It contains the specific manufactuer, model, type and version that Mojo will use to identify the firmware as valid for a particular platform.

It goes in firmwares/[manufacturer]/[model]/[type]/[optional-more-type]/[version]/def.yaml

# def.yaml
---
# The firmware image file name, local to the directory of this def.yaml file.
name: "smc3108.rom"
# Checksum of the file. This is generated automatically when running `make checksums` and building
# bundles. You should not change this manually unless you know what you are doing/
sha256_checksum: "b0180538745732e8f0681bc301af44b014b9b12453ffd966da2d2cf38731b7b8"
# The Mojo "type"
type: "lsi_3108"
# The Mojo "version"
version: "4.680.00-8465"
# The Mojo "manufacturer". This will need to match the manufacturer name in Mojo exactly.
manufacturer: "Supermicro"
# All of the Mojo "models" this firmware is valid for.
# This will need to match the model name in Mojo exactly.
models:
  - "SYS-1029U-TR25M"

Adding a new firmware

Create the directory structure as defined above and create a def.yaml file. Download the firmware files from the vendor website and all them to the folder. Be sure to checksum the files and make sure the file in this directory has the correct checksum. Fill out all of the fields. Run make bundle to generate the bundles. Commit the changes and open a pull request.

make update-env should be run first to set up poetry requirements make bundle runs poetry run python bundle.py $(ARGS). Depending on your OS python installation, you may need to add the path to your preferred python ie poetry run /usr/local/bin/python3 bundle.py $(ARGS)

Bundles

Bundle are the final product of this repository. They are the files that are uploaded to a Mojo installation and used in the firmware update process. Bundles are generated by running make bundle command. Bundle definitions are in the bundles/ directory as yaml files. All YAML files will generate a series of bundles that contain any number of firmware binaries. Bundle definition files include a list versions which is comprised of three fields: version, include and exclude. These keys are used to include or exclude firmware binaries based on the directory structure and save the resulting bundle as version.

Bundles are organized according to the following directory structure:

bundles/
├── [organization]/
│   └── [name].yaml

For example, a firmware bundle definition file specifically for MLB might include only the firmwares for MLB.

# bundles/mlb/all.yaml
---

versions:

  - version: "latest"
    include:
      - ".*/firmwares/supermicro/SYS-1029U-TR25M/BIOS/4.0/.*$"
      - ".*/firmwares/supermicro/SYS-5018D-FN4T/BMC/01.74.13/.*$"
    exclude: []

  - version: "all"
    include:
      - ".*/firmwares/supermicro/SYS-1029U-TR25M/.*$"
      - ".*/firmwares/supermicro/SYS-5018D-FN4T/.*$"
    exclude: []

In addition, a firmware bundle for all Dell might look like this:

# bundles/dell/all.yaml
---

versions:

  - version: latest
    include:
      - ".*/firmwares/dell/.*$"
    exclude: []

Or a firmware bundle a specific Cisco model, C240M5, might look like this:

---

versions:

  - version: all
    include:
      - ".*/firmwares/cisco/C240M5/.*$"

  - version: latest
    include:
      - ".*/firmwares/cisco/C240M5/BIOS/4.3.2.240053/.*$"
      - ".*/firmwares/cisco/C240M5/CIMC/4.3.2.240053/.*$"
    exclude: []

The include and exclude fields are lists of regular expressions to apply to the absolute path to each firmware filename. Check the examples in tests/examples/bundles for more information. A special keyword all can be used to include all firmwares and then the exclude list can be used filter those if it is easier to exclude. The include filters are run first, and then that list is filtered by the exclude fields.

After you have created new bundle tarballs with make bundle you can upload them to the repository. Log in to https://download.metify.io/ and browse to "firmware-external", "bundles", "[vendor]" etc to determine the destination you want. Then click "Upload component" and select your file from ie firmware-bundles/dist/dell/r740xd/latest/firmware.tar.gz. Then enter destination Directory: /bundles/<manufacturer>/<product>/<all-or-latest>/ ie /bundles/dell/r740xd/latest/. The repository will create missing directories for you, so no need (or way) to create them yourself.
You may need to click the "Refresh" button in the upper right corner of the Nexus Sonatype repo to see your new uploads.

These files will then be available via mojo-manage --firmware.