This document describes how to configure and build white box packages.

Introduction to White Box Packages ​

A white box package is essentially an HPM package that contains only white box information.It provides customization capabilities through firmware updates. The range of customization includes image customization, web page style customization, configuration customization, and SSL certificate customization. The following table lists the supported customization items.

White Box Package Customization Method ​

Creating a Code Repository for Storing Customization Files ​

Create a code repository for storing white box files, or create a folder in an existing code repository to store these files.

Before creating a white box package, prepare the customization files. White box package customization files include the main page style description file, various customized images, configuration file web_custom.xml, and file list configuration filelist.conf.

• Customized image names must match those in the item customization table above.
• The main page style supports beautiful, simple, and standard. You need to create a style_config.json file.

The file configuration example is as follows:

Creating A style_config.json File ​

{
  "pageStyle": "beautiful"
}

Configuring filelist.conf ​

The filelist.conf file describes white box package configuration items. The following is an example:

[Basic]
Version=2.00

[Filelist]
FileNum=11

[File0]
Name=code1.png
Path=/data/opt/pme/web/htdocs/theme/custom/img

[File1]
Name=favicon.ico
Path=/data/opt/pme/web/htdocs

[File2]
Name=web_custom.xml
Path=/data/opt/pme/web/conf

[File3]
Name=header_logo.png
Path=/data/opt/pme/web/custom

[File4]
Name=login.png
Path=/data/opt/pme/web/custom

[File5]
Name=login_logo.png
Path=/data/opt/pme/web/custom

[File6]
Name=img_01.png
Path=/data/opt/pme/web/custom

[File7]
Name=img_02.png
Path=/data/opt/pme/web/custom

[File8]
Name=img_03.png
Path=/data/opt/pme/web/custom

[File9]
Name=style_config.json
Path=/data/opt/pme/web/htdocs

[File10]
Name=customize.pfx
Path=/data/opt/bmc/conf

• [Basic]: describes the filelist.conf file version.
• [Filelist]: describes the number of configuration files.
• [Filex]: describes configuration file names and file paths.

The value of FileNum must match the actual number of File entries configured below. File names and file paths have a one-to-one correspondence and cannot be paired randomly. Contact the product contact to obtain the generation method for customize.pfx. You can customize the file as required.

Configuring web_custom.xml ​

The web_custom.xml file contains attribute configurations. The following is an example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Description: Currently official website, copyright information, independent KVM download link information, and document QR code display flags are used in the web page. -->
<CUSTOM_CONFIG>
    <!-- System contact (Example: VALUE="https://openubmc.com") -->
    <SysContact VALUE="CustomSysContact" />
    <!-- Preset SSL certificate information. When the issuer information of the currently installed SSL certificate matches the preset information, the certificate is considered a preset certificate, and the web page will prompt the user to install a new certificate. -->
    <PreSSLSeverCommonName VALUE="CustomCommonName"/>
    <PreSSLSeverOrgName VALUE="CustomOrgName"/>
    <PreSSLSeverCountry VALUE="Country"/>
    <!-- Official website -->
    <OfficalWeb VALUE="CustomOfficalWeb"/>
    <!-- Copyright -->
    <Copyright VALUE="CustomCopyright"/>
    <!-- Technical support website -->
    <SupportWeb VALUE="CustomSupportWeb"/>
    <!-- Email -->
    <Email VALUE="CustomEmail"/>
    <!-- Phone -->
    <Phone VALUE="CustomPhone"/>
    <!-- Independent KVM client download link -->
    <DownloadKVMLink VALUE="CustomDownloadKVMLink"/>
    <!-- Whether to display the QR code. (Example: VALUE="1", where "0" or "1" are valid values. Other values default to "0", indicating that the OR code is not displayed. -->
    <DocSupportFlag VALUE="CustomDocSupportFlag"/>
    <!-- Software name, used for customizing the BMC name in logs and the CLP prompt. -->
    <SoftwareName VALUE="openUBMC"/>
    <!-- Host name -->
    <HostName VALUE="CustomHostName"/>
    <!-- Security advisories -->
    <dBannerContent VALUE="CustomdBannerContent"/>
    <!-- Customer name -->
    <Customer VALUE="CustomerName"/>
</CUSTOM_CONFIG>

You can select appropriate customization items to put into web_custom.xml as required. Replace VALUE content with your customized content. You can delete unnecessary customization items.

Configuring manifest.yml for the Corresponding Product in the manifest Repository ​

Note: The files configuration in manifest.yml in this section must be the same as that in filelist.conf. The value of FileNum must be equal to the number of customization files in files.

After preparing the white box package customization files, start the build and packaging phase. The configuration steps are as follows:

(1) Open manifest/build/product/BMC/ProductName/manifest.yml. (2) Determine the build code, such as WBD. (3) Determine the package name package_name. (4) Determine the build type. (5) Configure settings related to the white box package.

Build example:

manufacture:
    # Build code.
    WBD:
        # package_name is the storage path and name of the white box package.
        package_name: wbd/wbd_output.zip
        # Build type. See bingo build types for optional values.
        build_type: release
        # White box package-related configuration.
        wbd_hpms:
            # repo is the repository address where white box package customization files are stored. Use the HTTPS download address.
            - repo: https://test.git
              # tag is the branch tag number where customization files are stored.
              tag: 0.0.0
              files:
                # path is the storage path for white box package customization files. The dst path cannot be modified and must follow the format "wbd_up_file/filename" as shown in the following example.
                - file: {path}/favicon.ico
                  dst: wbd_up_file/favicon.ico
                - file: {path}/login_logo.png
                  dst: wbd_up_file/login_logo.png
                - file: {path}/header_logo.png
                  dst: wbd_up_file/header_logo.png
                - file: {path}/filelist.conf
                  dst: wbd_up_file/filelist.conf
                - file: {path}/web_custom.xml
                  dst: wbd_up_file/web_custom.xml
                # The following files are required for creating white box packages. Their paths are fixed and cannot be deleted.
                - file: /usr/share/bmcgo/wbd-packet/beforeaction.sh
                - file: /usr/share/bmcgo/wbd-packet/afteraction.sh
                  dst: afteraction.sh
                - file: /usr/share/bmcgo/wbd-packet/CfgFileList.conf
                - file: /usr/share/bmcgo/wbd-packet/firstboot.sh
                - file: /usr/share/bmcgo/wbd-packet/hpm_wbd.config
                - file: /usr/share/bmcgo/wbd-packet/packetwbd.sh
                - file: /usr/share/bmcgo/wbd-packet/update.cfg
        # dst is the name of the final white box package created.
        files:
          - file: ${work_out}/wbd_hpm1.hpm
            dst: WBD-image.hpm
            verify:
              - pss

Note: The number of customization files in files must match the number of files in filelist.conf. Otherwise, the white box package upgrade will fail. {path} is the path for storing the white box files in the code repository.

Running the White Box Build Command in the build Directory of the manifest Repository ​

Go to the manifest/build directory and run the following command:

bmcgo publish -bt release -z WBD -b openUBMC -r openubmc_dev, where the -z option is the white box package build code, the -b option is the model, the -bt option is the build type, and the -r option is the Conan remote repository.

The community edition has only the bingo tool and cannot compile white box packages. White box packages can only be compiled using the bmcgo tool. Contact the product contact to obtain the bmcgo tool.

The package will be created at manifest/output/packet/wbd/wbd_output.zip.

Upgrading the White Box Package ​

Go to the openUBMC home page, navigate to Firmware Upgrade -> Firmware Update -> Upgrade File. If the Customer field is configured in the white box package, it will automatically restart to take effect after the update completes. To check web_custom.xml configuration items in the white box package, go to the openUBMC home page after the restart, navigate to Configuration Update -> Configuration Export, and verify whether the relevant configurations under the product_mgmt component meet expectations.

Clear Branding Package Creation Method ​

After customizing a white box package, if you need to restore the original configuration, you need to update with a clear branding package. A clear branding package is also a white box package, but the configuration in it is the default configuration. You need to create a white box package with the default configuration.

1. For configuration customizations, modify the customization items in web_custom.xml to the desired default values.
2. For style customizations, set the style_config.json file to an empty object.
3. For image customizations, configure filelist.conf, change the original Name to CLEAR_ALL, and then create an empty file named CLEAR_ALL. Note that when configuring the white box package in manifest, you also need to add the CLEAR_ALL file configuration.

filelist.conf example:

# For configurations that need to be restored to default, change Name to CLEAR_ALL.
[Basic]
Version=2.02

[Filelist]
FileNum=9

[File0]
Name=code1.png
Path=/data/opt/pme/web/htdocs/theme/custom/img

[File1]
Name=favicon.ico
Path=/data/opt/pme/web/htdocs

[File2]
Name=web_custom.xml
Path=/data/opt/pme/web/conf

[File3]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File4]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File5]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File6]
Name=CLEAR_ALL
Path=/data/opt/pme/web/custom

[File7]
Name=img_02.png
Path=/data/opt/pme/web/custom

[File8]
Name=img_03.png
Path=/data/opt/pme/web/custom

manifest.yml example:

manufacture:
    # Build code.
    WBD:
        # package_name is the storage path and name of the white box package.
        package_name: wbd/wbd_output.zip
        # Build type. See bingo build types for optional values.
        build_type: release
        # White box package-related configuration.
        wbd_hpms:
            # repo is the repository address where white box package customization files are stored. Use the HTTPS download address.
            - repo: https://test.git
              # tag is the branch tag number where customization files are stored.
              tag: 0.0.0
              files:
                # path is the storage path for white box package customization files. The dst path cannot be modified and must follow the format "wbd_up_file/filename" as shown in the following example.
                - file: {path}/CLEAR_ALL
                  dst: wbd_up_file/CLEAR_ALL
                - file: {path}/style_config.json
                  dst: wbd_up_file/style_config.json
                - file: {path}/filelist.conf
                  dst: wbd_up_file/filelist.conf
                - file: {path}/web_custom.xml
                  dst: wbd_up_file/web_custom.xml
                # The following files are required for creating white box packages. Their paths are fixed and cannot be deleted.
                - file: /usr/share/bmcgo/wbd-packet/beforeaction.sh
                - file: /usr/share/bmcgo/wbd-packet/afteraction.sh
                  dst: afteraction.sh
                - file: /usr/share/bmcgo/wbd-packet/CfgFileList.conf
                - file: /usr/share/bmcgo/wbd-packet/firstboot.sh
                - file: /usr/share/bmcgo/wbd-packet/hpm_wbd.config
                - file: /usr/share/bmcgo/wbd-packet/packetwbd.sh
                - file: /usr/share/bmcgo/wbd-packet/update.cfg
        # dst is the name of the final white box package created.
        files:
          - file: ${work_out}/wbd_hpm1.hpm
            dst: WBD-image.hpm
            verify:
              - pss