The standard Redfish BIOS data model

This section presents the standard Redfish UEFI/BIOS data model. Refer to the HPE Bios section for detail on BIOS/UEFI resources in HPE iLO based servers.

UEFI/BIOS resources are formatted differently than most other resources. BIOS resources do conform to a schema type as all Redfish objects do (Redfish data model specification).

However, BIOS settings vary widely across server types and BIOS revisions, so it is extremely difficult to publish a standard schema defining all the possible BIOS setting properties. Furthermore, it is not possible to communicate some advanced settings such as inter-setting dependencies, and menu structure in json-schema. Therefore, BIOS resources are defined in specific schemas called Registries.

BIOS attribute registry overview

The BIOS URI entry point (/redfish/v1/Systems/{ComputerSystemId}/Bios) contains the AttributeRegistry property. This property indicates the name and version of a registry file that defines the properties in the BIOS configuration. It also includes information about interdependencies between settings.

Registry file links are listed in the MessageRegistryFileCollection which standard URI is /redfish/v1/registries/. In order to provide an easy reading to human beings, registry files can be localized in several languages. Links contained in the MessageRegistryFileCollection point to a location holding pointers to the localized registry files. See example below.

Due to their size, BIOS Attribute Registries are compressed JSON resources(gzip), so the returned HTTP headers indicate a Content-Encoding of gzip. Redfish clients need to decompress the resource. This is done automatically in many clients, like the Postman API platform.

The following example follows the different steps to retrieve the BIOS Attribute Registry of an HPE Gen11 server. The first step retrieves the value of the AttributeRegistry filename property.

GET /redfish/v1/systems/1/bios/?$select=AttributeRegistry

{
    "AttributeRegistry": "BiosAttributeRegistryA56.v1_1_10"
}

The second step retrieves the corresponding link provided by the MessageRegistryFileCollection. The response body provides the list of available languages for this file as well as their location.

GET /redfish/v1/Registries/BiosAttributeRegistryA56.v1_1_10

{
    "@odata.context": "/redfish/v1/$metadata#MessageRegistryFile.MessageRegistryFile",
    "@odata.etag": "W/\"8DC519F4\"",
    "@odata.id": "/redfish/v1/Registries/BiosAttributeRegistryA56.v1_1_10",
    "@odata.type": "#MessageRegistryFile.v1_0_4.MessageRegistryFile",
    "Id": "BiosAttributeRegistryA56.v1_1_10",
    "Description": "Registry Definition File for BiosAttributeRegistryA56.v1_1_10",
    "Languages": [
        "en",
        "ja",
        "zh"
    ],
    "Location": [
        {
            "Language": "en",
            "Uri": "/redfish/v1/registrystore/registries/en/biosattributeregistrya56.v1_1_10"
        },
        {
            "Language": "ja",
            "Uri": "/redfish/v1/registrystore/registries/ja/biosattributeregistrya56.v1_1_10"
        },
        {
            "Language": "zh",
            "Uri": "/redfish/v1/registrystore/registries/zh/biosattributeregistrya56.v1_1_10"
        }
    ],
    "Name": "BiosAttributeRegistryA56.v1_1_10 Message Registry File",
    "Registry": "BiosAttributeRegistryA56.v1_1_10"
}

The last step consists of following the link to the desired language. The following example retrieves the English version of the Bios Attribute registry and prints the response headers including the Content-Encoding header. The response body of this example is in the next paragraph.

GET /redfish/v1/registrystore/registries/en/biosattributeregistrya56.v1_1_10

HTTP/1.1 200 OK
Allow: GET, HEAD
Cache-Control: no-cache
Content-Encoding: gzip
Content-type: application/json; charset=utf-8
Date: Thu, 15 Dec 2022 18:09:54 GMT
ETag: W/"49B2C84485480B0B0BF5B97395B586E1"
OData-Version: 4.0
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block

BIOS attribute registry structure

The BIOS attribute registry contains four top-level arrays (see example below):

• Menus: Array containing the BIOS attributes menus and their hierarchy.
• This can be used to build a user interface that resembles the local BIOS
• Setup, or to group properties that are related (i.e. ProcessorOptions and UsbOptions ).
• Attributes: Array containing BIOS attributes and information about the attributes such as type, values, etc.
• Dependencies: Array containing a list of dependencies of BIOS attributes. This includes inter-setting dependencies that might cause one BIOS setting to change its value or its ReadOnly property based on the value of another BIOS setting.
• SupportedSystems array containing a list of systems that this attribute registry supports.

Each BIOS attribute in the attribute registry includes:

• a type (enum, string, numeric, or Boolean).
• possible values for enum type attributes.
• display strings (localized to the registry language) for the attributes and their possible values.
• help and warning text (localized).
• a location and a display order information, including menu hierarchy for an attribute.
• value limits, including maximum, minimum, and step values for numeric attributes, and minimum and maximum character lengths, as well as regular expressions for string attributes.
• other meta-data.

{
"AsrTimeoutMinutes": "TimeOut10",
"SerialConsoleBaudRate": "Baud115200",
}

The following example retrieves the English version of the BIOS registry of an HPE ProLiant Gen11 system (response body truncated).

GET /redfish/v1/registrystore/registries/en/biosattributeregistrya56.v1_1_20

{
    "@odata.type": "#AttributeRegistry.v1_2_1.AttributeRegistry",
    "Id": "BiosAttributeRegistryA56.v1_1_10",
    "Name": "A56 BIOS Attribute Registry",
    "Language": "en",
    "OwningEntity": "HPE",
    "RegistryVersion": "v1_1_10",
    "Description": "This registry defines a representation of BIOS Attribute instances",
    "RegistryEntries": {
        "Menus": [
            {
                "MenuName": "BiosMainMenu",
                "DisplayName": "BIOS/Platform Configuration (RBSU)",
                "DisplayOrder": 1,
                "ReadOnly": false,
                "GrayOut": false,
                "MenuPath": "./"
            },
            {
                "MenuName": "SystemOptions",
                "DisplayName": "System Options",
                "DisplayOrder": 2,
                "ReadOnly": false,
                "GrayOut": false,
                "MenuPath": "./SystemOptions"
            },
            .......
        ],
        "Attributes": [
            ....
            {
                "AttributeName": "AdminName",
                "DisplayName": "Administrator Name",
                "HelpText": "Enter the server administrator's name text.",
                "ReadOnly": false,
                "GrayOut": false,
                "MaxLength": 28,
                "MinLength": 0,
                "Type": "String",
                "MenuPath": "./SystemOptions/ServerAssetText/AdminInfo",
                "DisplayOrder": 29,
                "ValueExpression": "^[\\ -\\~]*$",
                "DefaultValue": ""
            },
                    ........
        ],
        "Dependencies": [
            {
                "DependencyFor": "MicrosoftSecuredCoreSupport",
                "Type": "Map",
                "Dependency": {
                    "MapFrom": [
                        {
                            "MapFromAttribute": "TpmState",
                            "MapFromProperty": "CurrentValue",
                            "MapFromCondition": "EQU",
                            "MapFromValue": "NotPresent"
                        }
                    ],
                    "MapToAttribute": "MicrosoftSecuredCoreSupport",
                    "MapToProperty": "GrayOut",
                    "MapToValue": true
                }
            },
            .......
        ],
        "SupportedSystems": [
        {
            "ProductName": "ProLiant DL345 Gen11",
            "SystemId": "A56",
            "FirmwareVersion": "A56 v1.10"
        }
    ]
}

BIOS current and pending areas

BIOS resources are located under the BIOS entry point, part of the ComputerSystem data type as per the DMTF specification.

The following example retrieves the BIOS end point using cURL and iLOrest from an HPE iLO 6 management controller.

curl --insecure --location --silent \
     --user <ilo-user>:<password>        \
     'https://ilo-ip/redfish/v1/Systems/1/?$select=Bios' | \
     jq .

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest get --json Bios --select ComputerSystem.
ilorest logout

{
  "@odata.context": "/redfish/v1/$metadata#ComputerSystem.ComputerSystem",
  "@odata.etag": "W/\"8470AEE1\"",
  "@odata.id": "/redfish/v1/Systems/1/",
  "@odata.type": "#ComputerSystem.v1_17_0.ComputerSystem",
  "Bios": {
    "@odata.id": "/redfish/v1/systems/1/bios/"
  }
}

This BIOS entry point is also called the current settings area or just the current area because it contains the BIOS attribute values in the running system. All BIOS attributes name/value pairs that are referenced in the Attribute Registry are grouped under an Attributes Redfish object under the BIOS end point.

The next example retrieves the current AdminName BIOS attribute of an HPE Gen11 server.

GET /redfish/v1/systems/1/bios/?$select=Attributes/AdminName

{
    "@odata.context": "/redfish/v1/$metadata#Bios.Bios",
    "@odata.etag": "W/\"7D4F1B0E2903D1D1D138C05A3D0806B2\"",
    "@odata.id": "/redfish/v1/systems/1/bios/",
    "@odata.type": "#Bios.v1_0_4.Bios",
    "Attributes": {
        "AdminName": "John Deuf"
    }
}

The BIOS entry point contains a SettingsObject}{} resource containing a link to a location called the BIOS Pending settings area or just pending area. In an HPE Gen11 server, this link points to /redfish/v1/Systems/1/Bios/Settings. In an HPE CrayXD 255v it points toward /redfish/v1/Systems/Self/Bios/SD. This pending area is used to change BIOS attributes and described in the next paragraph.

Changing BIOS attributes and understanding "@Redfish.Settings"

The BIOS current settings area is read-only. However, the BIOS pending area described in the previous paragraph is read-write. The Allow response header of a GET request to the the BIOS pending settings area mentions that PATCH requests are valid against this link. PATCHes to pending settings do not take effect until the server is reset. Before the server is reset, the current and pending settings are independently available.

During the server reset process, pending BIOS attributes are verified and applied to the current settings only if they are valid.

After the server is reset, you can view any errors in the @Redfish.Settings property of the current BIOS configuration object.

The following example retrieves the @Redfish.Settings object after a successful transfer of the BIOS settings area to the current area.

GET /redfish/v1/systems/1/bios/?$select=@Redfish.Settings/Messages

{
    "@Redfish.Settings": {
        "Messages": [
            {
                "MessageId": "Base.1.0.Success"
            }
        ]
    },
    "@odata.context": "/redfish/v1/$metadata#Bios.Bios",
    "@odata.etag": "W/\"507C68EC90206D6D6D1F37F655EA55D6\"",
    "@odata.id": "/redfish/v1/systems/1/bios/",
    "@odata.type": "#Bios.v1_0_4.Bios"
}

The following example retrieves the @Redfish.Settings object after an unsuccessful transfer of the BIOS settings area to the current area.

GET /redfish/v1/systems/1/bios/?$select=@Redfish.Settings/Messages

{
    "@Redfish.Settings": {
        "Messages": [
            {
                "MessageId": "Base.1.0.Success"
            },
            {
                "MessageArgs": [
                    "UefiOptimizedBoot"
                ],
                "MessageId": "Base.1.0.PropertyUnknown",
                "RelatedProperties": [
                    "#/UefiOptimizedBoot"
                ]
            }
        ]
    },
    "@odata.context": "/redfish/v1/$metadata#Bios.Bios",
    "@odata.etag": "W/\"7D4F1B0E2903D1D1D138C05A3D0806B2\"",
    "@odata.id": "/redfish/v1/systems/1/bios/",
    "@odata.type": "#Bios.v1_0_4.Bios"
}

There are benefits to handling BIOS settings in this way:

• Enables offline components (for example, BIOS) to process changes to settings in a deferred manner.
• Allows current and pending values to remain available for review until the offline component processes the pending settings.
• Avoids the need for complex job queues.

Refer to the BIOS Redfish examples section for more examples.

BIOS defaults and password

In addition to providing a method for modifying individual BIOS attributes, the Redfish specification allows a quick return to a default and well known BIOS configuration (i.e. factory defaults). This operation cannot be performed with the above method.

Moreover, for security reasons, the BIOS password is an attribute that requires as well, a specific method to be modified.

Both the return to a default BIOS configuration and the change of the BIOS password use special POST operations called Redfish actions.

Reset Bios settings action

The following example resets BIOS attributes to their defaults on an HPE Superdome Flex 280 and an HPE iLO based server using the Bios.ResetBios standard Redfish action.

POST /redfish/v1/Systems/Partition0/Bios/Actions/Bios.ResetBios

POST /redfish/v1/Systems/1/Bios/Actions/Bios.ResetBios/

{
}

Change BIOS password

The following example shows how to modify the UEFI/BIOS password on systems implementing this action.

POST {Base URI of Bios resource}/Actions/Bios.ChangePassword

POST /redfish/v1/Systems/1/Bios/Actions/Bios.ChangePassword

{
  "PasswordName": "Administrator | User",
  "OldPassword" : "OldPasswordText",
  "NewPassword" : "NewPasswordText"
}

UEFI / BIOS Boot Settings

UEFI boot structured name string

This UEFI boot structured name string is unique and represents each UEFI boot option in the system. Software can identify and manipulate devices using the string’s fixed format as defined in this specification. Software can assume that the string unique for each boot device in the UEFI BootOrder.

The UEFI boot structured name string is divided into sections separated by ‘.’ characters, using the following format:

<DeviceType>.<Location>.<Instance>.<Sub-instance>.<Qualifier>

• DeviceType : The first section describes the device type (For example, HD, CD, NIC, and PCI. ).
• Location: The second and the third section together describes the location of the device (For example, Slot.7 or Emb.4 ).
• Instance: The third section is used with the Location section to describe the device location (for example, the slot number or embedded instance number).
• Sub-instance: The fourth section is optional, and is used as a sub-instance number in case of multiple boot options using the same instance. For example, this can be the port number for a multi-port NIC.
• Qualifier: The fifth section is optional, and describes the logical protocol (for example, IPv4, IPv6, and iSCSI).

UEFI boot structured name string examples

Table 1 Examples

Table 2 Examples of currently supported Structured Boot Strings