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

Introduction to White Box Packages ​

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

White Box Package Customization Method ​

Creating a Code Repository for Storing Customization 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:

{
  "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=10

[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

• [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 are fixed. You can customize them 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 ​

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

(1) Determine the build code, such as WBD. (2) Determine the package name package_name. (3) Determine the build type. (4) 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.

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:

bingo publish -z WBD -b openUBMC, where the -z option is the white box package build code and the -b option is the model.

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.

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