文档中心
Introduction to the Equipment Customization Access Mechanism
更新时间： 2025/12/05
在Gitcode上查看源码

Introduction to Equipment Customization ​

Customization Purpose ​

Equipment customization aims to achieve the following objectives:

  1. Customized configuration: After a customer places an order, the server is customized during the equipment testing phase based on specific configuration information provided by the customer. For example, set the server model name and BMC user name.

  2. Clearance and restoration of faulty equipment configuration: When a customer's server is returned to the factory due to a failure, all customer-related configuration information must be thoroughly cleared. By running a customization script without configuration items, the BMC configuration is restored to factory defaults.

Customization Stage ​

The equipment customization process is deployed as the final stage of the production equipment testing workflow. Its position in the overall production process is shown below.

openUBMC Equipment Customization Workflow ​

Repository Introduction ​

The repository for configuring equipment customization items is the same as the one used for configuration import and export.
Repository location: profile_schema
Repository purpose: The schema files carry the data model (attribute definitions and value constraints) for component configuration import and export. Because these attributes are directly oriented to users, they are part of the external interface of the component. Once data definitions are implemented in the schema repository, the component can use the unified verification mechanism for configuration import and export to verify user data (this capability is implemented by the OMS component).

Repository structure:

shell
├── CHANGELOG.md         # Change information for this repository
├── CMakeLists.txt       # Build configuration, defining the schema installation path
├── README.md            # Repository description
├── build.py             # Build script
├── conanfile.py
├── conaninfo.py
├── mds
│   └── service.json     # Version number of this repository
├── dist
│   └── permissions.ini  # Build permission management file
├── schema               # Main directory containing component schema files
│   ├── account.json     # Component schema file, named after the component. Each component defines its own schema.
│   ├── bios.json
│   └── ...
└── test                 # Test directory

Overall Customization Workflow ​

Relationship between equipment customization and configuration import and export:
Equipment customization reuses the existing configuration import and export channels. Customization items also need to be declared within the component schema to leverage the import and export capabilities for verification, distribution, and collection.

Customization data collection name:
CustomSettings: collection of component customization data instances

openUBMC Extended Keywords:
AttributeType: fixed as ImportAndExport during customization
CustomDefault: default value for configuration data

Based on the nature of configuration items, equipment customization in openUBMC is classified into two types of processing workflows:

  1. Non-sensitive information customization items: These items directly reuse the configuration import and export workflow. New configuration items required for equipment customization are added here to enable batch setting.
  2. Sensitive information customization items: Customization of sensitive information items is achieved by directly calling Intelligent Platform Management Interface (IPMI) commands within customization scripts (located at build/manufacture/customize/function/ in the manifest repository).

Note: The distinction between sensitive and non-sensitive information is primarily to comply with company security requirements and prevent the leakage of sensitive user information, which could lead to critical violations.

The figure shows the interaction workflow for sensitive and non-sensitive information items.

The complete customization script execution workflow involves two core stages: the customization process and the verification process.

The customization process writes configuration data to the BMC and makes the data take effect.
Customization entry script: XXX_config.sh

The verification process resets the BMC after the customization is complete. After the BMC is restarted, the previously set customization items are exported again and compared with the expected values to ensure that the customization is accurate. Verification entry script: XXX_verify.sh

Using Equipment Customization ​

The following describes how to use the equipment customization function in actual application scenarios.

Using Equipment Customization in an OS ​

  1. Prepare the environment.

    Decompress the customization equipment package to any directory in the operating system (OS) and grant the execute permission on the script files.

    bash
    chmod +x *.sh

  2. Create the configuration file.

    Create the customset.ini and serial.ini files:

    • customset.ini: stores all customization configuration parameters.
    • serial.ini: reserved in the current version, which must be left empty.

  3. Verify the configuration file.

    Run the following command to check the format of the customization configuration file:

    bash
    cat -A customset.ini

    Important notes:

    • Line endings must be Unix/Linux format, displayed as dollar signs (`---

Introduction to Equipment Customization ​

Customization Purpose ​

Equipment customization aims to achieve the following objectives:

  1. Customized configuration: After a customer places an order, the server is customized during the equipment testing phase based on specific configuration information provided by the customer. For example, set the server model name and BMC user name.

  2. Clearance and restoration of faulty equipment configuration: When a customer's server is returned to the factory due to a failure, all customer-related configuration information must be thoroughly cleared. By running a customization script without configuration items, the BMC configuration is restored to factory defaults.

Customization Stage ​

The equipment customization process is deployed as the final stage of the production equipment testing workflow. Its position in the overall production process is shown below.

openUBMC Equipment Customization Workflow ​

Repository Introduction ​

The repository for configuring equipment customization items is the same as the one used for configuration import and export.
Repository location: profile_schema
Repository purpose: The schema files carry the data model (attribute definitions and value constraints) for component configuration import and export. Because these attributes are directly oriented to users, they are part of the external interface of the component. Once data definitions are implemented in the schema repository, the component can use the unified verification mechanism for configuration import and export to verify user data (this capability is implemented by the OMS component).

Repository structure:

shell
├── CHANGELOG.md         # Change information for this repository
├── CMakeLists.txt       # Build configuration, defining the schema installation path
├── README.md            # Repository description
├── build.py             # Build script
├── conanfile.py
├── conaninfo.py
├── mds
│   └── service.json     # Version number of this repository
├── dist
│   └── permissions.ini  # Build permission management file
├── schema               # Main directory containing component schema files
│   ├── account.json     # Component schema file, named after the component. Each component defines its own schema.
│   ├── bios.json
│   └── ...
└── test                 # Test directory

Overall Customization Workflow ​

Relationship between equipment customization and configuration import and export:
Equipment customization reuses the existing configuration import and export channels. Customization items also need to be declared within the component schema to leverage the import and export capabilities for verification, distribution, and collection.

Customization data collection name:
CustomSettings: collection of component customization data instances

openUBMC Extended Keywords:
AttributeType: fixed as ImportAndExport during customization
CustomDefault: default value for configuration data

Based on the nature of configuration items, equipment customization in openUBMC is classified into two types of processing workflows:

  1. Non-sensitive information customization items: These items directly reuse the configuration import and export workflow. New configuration items required for equipment customization are added here to enable batch setting.
  2. Sensitive information customization items: Customization of sensitive information items is achieved by directly calling Intelligent Platform Management Interface (IPMI) commands within customization scripts (located at build/manufacture/customize/function/ in the manifest repository).

Note: The distinction between sensitive and non-sensitive information is primarily to comply with company security requirements and prevent the leakage of sensitive user information, which could lead to critical violations.

The figure shows the interaction workflow for sensitive and non-sensitive information items.

The complete customization script execution workflow involves two core stages: the customization process and the verification process.

The customization process writes configuration data to the BMC and makes the data take effect.
Customization entry script: XXX_config.sh

The verification process resets the BMC after the customization is complete. After the BMC is restarted, the previously set customization items are exported again and compared with the expected values to ensure that the customization is accurate. Verification entry script: XXX_verify.sh

Using Equipment Customization ​

The following describes how to use the equipment customization function in actual application scenarios.

Using Equipment Customization in an OS ​

  1. Prepare the environment.

    Decompress the customization equipment package to any directory in the operating system (OS) and grant the execute permission on the script files.

    bash
    chmod +x *.sh

  2. Create the configuration file.

    Create the customset.ini and serial.ini files:

    • customset.ini: stores all customization configuration parameters.
    • serial.ini: reserved in the current version, which must be left empty.

  3. Verify the configuration file.

    Run the following command to check the format of the customization configuration file:

    bash
    cat -A customset.ini

    Important notes:

    • Line endings must be Unix/Linux format, displayed as dollar signs (). Convert non-Unix formats to Unix format.
    • No space character is allowed before or after the equal sign (=).

    Any of the aforementioned formatting issues will result in a mismatch between the script customization results and the configuration file content.

  4. Execute the customization workflow.

    Perform the following operations in sequence:

    Apply the configuration.

    bash
    ./XXX_config.sh customset.ini serial.ini

    Verify the results.

    bash
    ./XXX_verify.sh customset.ini serial.ini

    Both operations in step 4 (applying the configuration and verifying the results) must be completed for a customization workflow to be considered finished.

Using Equipment Customization Without an OS ​

Because the equipment customization import script actually calls an IPMI command, the items can be imported without an OS. The procedure is as follows:

  1. Create a customset.ini file. You can refer to Server Factory Customization configuration, select the configurations to be customized, and write them into the customset.ini file, for example:
ini
BMCSet_MACHINEALIAS=XX
  1. Upload the customset.ini file to the /tmp directory.
  2. Send the import IPMI command: ipmitool raw 0x30 0x90 0x21 0xf0.
  3. View the customization results: ipmitool raw 0x30 0x90 0x22 0xef.
    A return of 00 indicates customization in progress.
    A return of 01 indicates customization complete.

Customization Development Example ​

If you need to develop new non-sensitive information customization items, refer to the following development process.

Defining Customization Requirements ​

Before development, clarify the list of customization items that the component needs to implement and analyze the corresponding functional points and implementation methods of each item in openUBMC.

Declaring Customization Items ​

Procedure:

(1) Add CustomSettings field declaration: Add the CustomSettings field in the schema file to declare customization items. This field should be at the same level as the configuration import and export items.
(2) Define the data type: The data type must correspond to the attribute type of the component in the resource tree to ensure that target attribute values are set correctly.
(3) Specify the attribute type: Set the attribute type of the equipment customization item. It is fixed as ImportAndExport.
(4) Configure value constraints: Set value constraints for the equipment customization items.
(5) Set default values: Configure a CustomDefault for each customization item. During the full system package build phase, build tools parse these declarations in the schema file of each component to generate a unified global default configuration file default_settings.json.

Schema example:

json
{
    "type": "object",
    "properties": {
        "Description": {
            "const": "Configurations of XXX"
        },
        "ConfigData": {
            "type": "object",
            "properties": {
                "XXX": {                          // Configuration import and export item declaration
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "Attribute1": {
                                "type": "number",
                                "AttributeType": "ImportAndExport"
                            },
                            "Attribute2": {
                                "type": "string",
                                "AttributeType": "ImportAndExport",
                                "enum": ["NoAction", "Reset", "PowerOff"]
                            },
                            "Attribute3": {
                                "type": "string",
                                "AttributeType": "ImportAndExport",
                                "enum": ["NoAction", "Reset"]
                            }
                        }
                    }
                },
                "CustomSettings": {             // Equipment customization item declaration. The name is fixed and must be at the same level as service import and export items.
                    "type": "object",
                    "properties": {
                        "Custom_XXXX1": {       // Name of the equipment customization item
                            "type": "number",   // Data type, corresponding to customization item type in .ini
                            "AttributeType": "ImportAndExport",  // Attribute type, fixed as ImportAndExport
                            "enum": [0, 1, 2],  // Value constraints
                            "CustomDefault": 1  // Default value used to generate default_settings.json during full package build
                        },
                        "Custom_XXXX2": {
                            "type": "string",
                            "AttributeType": "ImportAndExport",
                            "enum": ["on", "off"],
                            "CustomDefault": "on"
                        }
                    }
                }
            }
        }
    }
}

Code Implementation ​

(1) Add equipment customization code file customize_config.lua (the file name can be changed) to the component repository.

(2) Implement import and export code for equipment customization items.

lua
-- customize_config.lua
local m = {}

-- Equipment customization item import
function m.custom_import(ctx, config)
    -- Implement configuration import combined with customization items.
    ...
end

-- Equipment customization item export. The "config" output parameter contains exported customization items for verification. (This is an example. Implementation can also be handled flexibly via return values.)
function m.custom_export(ctx, config)
    -- Implement configuration export combined with customization items.
    ...
end

return m

(3) Integrate the equipment customization workflow into the service import and export entry point.

lua
-- Service configuration import entry function
function c_config_mgmt:import(ctx, config_data)
    local cfg = cjson.decode(config_data)
    -- Equipment customization import workflow access
    local ok, customize_config = pcall(require, 'customize_config')
    if ok and customize_config then
        if cfg.ConfigData.CustomSettings then -- Checks if CustomSettings exists. If not, equipment import is not performed.
            customize_config.custom_import(ctx, cfg)
        end
    end

    -- Service configuration import
    local ok, err = pcall(function ()
        for k, v in pairs(cfg['ConfigData']) do
            if self.config[k] then
                self.config[k]:import(ctx, v)
            end
        end
    end)
    if not ok then
        error(err)
    end
end

-- Service configuration export entry function
function c_config_mgmt:export(ctx)
    local cfg = {}
    cfg.ConfigData = {}

    -- Equipment customization export workflow access
    local ok, customize_config = pcall(require, 'customize_config')
    if ok and customize_config then
        customize_config.custom_export(ctx, cfg)
    end

    -- Service configuration export
    local ok, err = pcall(function ()
        for k, v in pairs(self.config) do
            cfg.ConfigData[k] = v:export()
        end
    end)
    if not ok then
        error(err)
    end
    return cjson.encode(cfg)
end

Model-driven Differentiated Customization ​

Primary Scenarios ​

  • An attribute of product A has different default values. Product A needs to support different default configuration values.

  • Product B has unique customization items. Product B needs to support these items and their default values.

Differentiated Customization Solution ​

Common customization items (independent of model) are defined in the profile_schema repository, while differentiated customization items are defined in the vpd repository. The processing workflow is as follows:

  1. Configure differentiated customization attributes in the corresponding product directory within the vpd repository.
  2. Obtain the corresponding schema files from both profile_schema and vpd repositories during the build.
  3. Integrate product-specific schema configurations into the corresponding schema files.
  4. Generate the default configuration default_settings.json based on the integrated schema files.

Add a schema directory under the corresponding product directory in the vpd repository to store product-specific customization items:

shell
# Planned directory structure for the vpd repository
├── CHANGELOG.md
├── Makefile
├── build.py
├── conanfile.py
├── conaninfo.py
├── mds
├── permissions.ini
└── vendor                  # Vendor information, such as server vendor and component vendor
    ├── Aspeed
    │   └── bmc_soc
    │       ├── ast2500
    │       └── ast2600
    ├── Huawei
    │   ├── BMCSoC
    │   │   └── hi1711
    │   ├── Nic
    │   ├── Raid
    │   ├── Server
    │   │   ├── Ascend
    │   │   ├── Kunpeng
    │   │   │   ├── BM320
    │   │   │   │   ├── PSR
    │   │   │   │   ├── platform
    │   │   │   │   ├── profile.txt
    │   │   │   │   ├── redfish
    │   │   │   │   ├── schema          # Product-specific customization (default values, attributes)
    │   │   │   │   └── web_backend
    │   │   │   └── Nic
    │   │   │       └── Lom
    │   │   ├── Pangea
    │   │   ├── TCE
    │   │   └── public
    │   ├── Ssd
    │   └── TianChi
    ├── Intel
    │   ├── Nic
    │   └── Raid
    ├── Mellanox
    └── Nvidia

See vendor/Huawei/Server/Kunpeng/TaiShan200_DA123C/schema/bmc_network.json.

json
{
    "type": "object",
    "properties": {
        "Description": {
            "const": "Configurations of bmc_network"
        },
        "ConfigData": {
            "type": "object",
            "properties": {
                "CustomSettings":{
                    "type": "object",
                    "properties": {
                        "BMCSet_RackInner_SubNet": {
                            "type": "string",
                            "Import": false,
                            "AttributeType": "ImportAndExport",
                            "CustomDefault": "172.31.0.0"
                        },
                        "BMCSet_RackInner_VLAN_ID": {
                            "type": "integer",
                            "Import": false,
                            "AttributeType": "ImportAndExport",
                            "CustomDefault": 702,
                            "minimum": 1,
                            "maximum": 4094
                        },
                        "BMCSet_Maint_IPv4": {
                            "type": "string",
                            "Import": false,
                            "AttributeType": "ImportAndExport",
                            "CustomDefault": "192.168.240.100"
                        },
                        "BMCSet_Maint_SubnetMask": {
                            "type": "string",
                            "Import": false,
                            "AttributeType": "ImportAndExport",
                            "CustomDefault": "255.255.255.0"
                        }
                    }
                }
            }
        }
    }
}

FAQ ​

  1. How do I use equipment customization?

    For details, see Using Equipment Customization.

  2. Can I use equipment customization without entering the OS? Yes. For details, see Using Equipment Customization Without an OS.

  3. Where can I find the default_settings.json file?

    Take the S920X20 model as an example. You can find the file in the manifest/temp/build_S920X20_debug_dev/buildimg/rtos_with_driver/rootfs/opt/bmc/profile_schema/custom directory of the build environment. Within the BMC system, it can be found in the /opt/bmc/profile_schema/custom directory.