UEFI Redfish EDK2 solution is an efficient and secure solution for the end-users to remote configure (in Out-of-band) UEFI platform configurations by leveraging the Redfish RESTful API. It's simple for end-users to access the configurations of UEFI firmware which have the equivalent properties defined in Redfish schema.
Below are the block diagrams of UEFI Redfish EDK2 Implementation. EDK2 Redfish Foundation[1] in the lower part of the figure refers to the EDK2 Redfish Foundation, which provides the fundamental EDK2 drivers to communicate with Redfish service ([19] in the above figure). The Redfish service could be implemented in BMC to manage the system, or on the network for managing multiple systems.
EDK2 Redfish Client[2] in the upper part of the figure refers to the EDK2 Redfish client, which is the EDK2 Redfish application used to configure platform configurations by consuming the Redfish properties. The EDK2 Redfish client can also provision the UEFI platform-owned Redfish properties, consume and update Redfish properties as well. The EDK2 Redfish Feature DXE Drivers [17] is the project in tianocore/edk2-redfish-client repository. Each EDK2 Redfish Feature DXE Driver is designed to communicate with the particular Redfish data model defined in the Redfish schema (e.g. Edk2RedfishBiosDxe driver manipulates the properties defined in Redfish BIOS data model).
Below are the EDK2 drivers implemented on EDK2,
The abstract EDK2 DXE driver to create SMBIOS type 42 record through EFI SMBIOS protocol according to the device descriptor and protocol type data (defined in SMBIOS type 42h [7]) provided by platform level Redfish host interface library. On EDK2 open source implementation (EmulatorPkg), SMBIOS type 42 data is retrieved from EFI variables created by RedfishPlatformConfig.efi [20] under EFI shell. OEM may provide its own PlatformHostInterfaceLib [11] instance for the platform-specific implementation.
The abstract DXE driver which incorporates with RedfishPlatformCredentialLib [10] to acquire the credential of Redfish service. On edk2 EmulatorPkg implementation, the credential is hardcoded using the fixed Account/Password in order to connect to Redfish service established by Redfish Profile Simulator. OEM may provide its own RedfishPlatformCredentialLib instance for the platform-specific implementation.
This is the network-based driver instance of EFI_REST_EX protocol (UEFI spec 2.8, section 29.7.2) for communicating with Redfish service using the HTTP protocol. OEM may have its own EFI REST EX UEFI Driver instance on which the underlying transport to Redfish service could be proprietary.
EFI Redfish Discover Protocol implementation (UEFI spec 2.8, section 31.1). Only support Redfish service discovery through Redfish Host Interface. The Redfish service discovery using SSDP over UDP [18] is not implemented at the moment.
EFI REST JSON Structure DXE implementation (UEFI spec 2.8, section 29.7.3). This could be used by EDK2 Redfish Feature DXE Drivers [17]. The EDK2 Redfish feature drivers manipulate platform-owned Redfish properties in C structure format and convert them into the payload in JSON format through this protocol. This driver leverages the effort of Redfish Schema to C Generator to have the “C Structure” <-> “JSON” conversion.
This is the centralized manager of EDK2 Redfish feature drivers, it initiates EDK2 Redfish feature drivers by invoking init() function of EDK2 Redfish Config Handler Protocol [16] installed by each EDK2 Redfish feature driver. EDK2 Redfish Config Handler driver is an UEFI driver which has the dependency with EFI REST EX protocol and utilizes EFI Redfish Discover protocol to discover Redfish service that manages this system.
The library is incorporated with RedfishLib [13] to encode and decode Redfish JSON payload. This is the platform library to support HTTP Content-Encoding/Accept-Encoding headers. EumlatorPkg use the NULL instance of this library because Redfish Profile Simulator supports neither HTTP Content-Encoding header on the payload returned to Redfish client nor HTTP Accept-Encoding header.
The following libraries are the wrappers of other open source projects used in RedfishPkg
RedfishPkg\PrivateLibrary\RedfishLib [13] This is the wrapper of open source project libredfish, which is the library to initialize the connection to Redfish service with the proper credential and execute Create/Read/Update/Delete (CRUD) HTTP methods on Redfish properties.
RedfishPkg\Library\JsonLib [14] This is the wrapper of open source project Jansson, which is the library that provides APIs to manipulate JSON payload.
RedfishPlatformCredentialLib
The EDK2 Emulator platform implementation of acquiring credential to build up the communication between UEFI firmware and Redfish service. [10]
The Redfish credential is hardcoded in the EmulatorPkg RedfishPlatformCredentialLib. The credential is used to access to the Redfish service hosted by Redfish Profile Simulator.
RedfishPlatformHostInterfaceLib
EDK2 Emulator platform implementation which provides the information of building up SMBIOS type 42h record. [11]
EmulatorPkg RedfishPlatformHostInterfaceLib library consumes the EFI Variable which is created by RedfishPlatformConfig EFI application. RedfishPlatformConfig EFI application stores not all of SMBIOS Type42 record information but the necessary network properties of Redfish Host Interface in EFI Variable.
Server platform with BMC as the server management entity may expose the USB Network Interface Device (NIC) to the platform, which is so called the in-band host-BMC transport interface. The USB NIC exposed by BMC is usually a link-local network device which has two network endpoints at host and BMC ends. The endpoint at host side is connected to the platform USB port, and it is enumerated by edk2 USB BUS driver. The edk2 USB NIC driver then produces the EFI Network Interface Identifier Protocol (EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL_GUID_31) and connected by EFI Simple Network Protocol (SNP) driver and the upper layer edk2 network drivers. The applications can then utilize the network stack built up on top of USB NIC to communicate with Redfish service hosted by BMC.
BMC-exposed USB NIC is mainly designed for the communication between host and BMC-hosted Redfish service. BMC-exposed USB NIC can be public to host through Redfish Host Interface Specification and discovered by edk2 Redfish discovery driver. The Redfish Host Interface Specification describes the dedicated host interface between host and BMC. The specification follows the SMBIOS Type 42 format and defines the host interface as:
RedfishPlatformCredentialLib
RedfishPlatformCredentialLib library instance on the platform with BMC uses Redfish Credential Bootstrapping IPMI commands defined in Redfish Host Interface Specification to acquire the Redfish credential from BMC. edk2 Redfish firmware then uses this credential to access to Redfish service hosted by BMC.
RedfishPlatformHostInterfaceLib
BMC-exposed USB NIC, a IPMI Message channel is reported by BMC as a “IPMB-1.0” protocol and “802.3 LAN” medium channel. edk2 firmware can issue a series of IPMI commands to acquire the channel application information (NetFn App), transport network properties (NetFn Transport) and other necessary information to build up the SMBIOS type 42h record. In order to recognize the specific BMC-exposed USB NIC in case the platform has more than one USB NIC devices attached, the MAC address specified in the EFI Device Path Protocol of SNP EFI handle is used to match with the MAC address of IPMI message channel. Due to the network information such as the MAC address, IP address, Subnet mask and Gateway are assigned by BMC, edk2 Redfish implementation needs a programmatic way to recognize the BMC-exposed USB NIC.
MAC address: Searching for the BMC-exposed USB NIC
The last byte of host-end USB NIC MAC address is the last byte of BMC-end USB NIC MAC address minus 1. RedfishPlatformHostInterfaceLib issues the NetFn Transport IPMI command to get the MAC address of each channel and checks them with the MAC address specified in the EFI Device Path Protocol.
For example:
BMC-end USB NIC MAC address: 11-22-33-44-55-00
Host-end USB NIC MAC address: 11-22-33-44-55-ff
IP Address: Acquiring the host-end USB NIC IP Address
The last byte of host-end USB NIC IPv4 address is the last byte of BMC-end USB NIC IPv4 address minus 1.
For example:
BMC-end USB NIC IPv4 address: 165.10.0.10
Host-end USB NIC IPv4 address: 165.10.0.9
Other Network Properties:
Due to the host-end USB NIC and BMC-end USB NIC is a link-local network. Both of them have the same network properties such as subnet mask and gateway. RedfishPlatformHostInterfaceLib issues the NetFn Transport IPMI command to get the network properties of BMC-end USB NIC and apply it on host-end USB NIC.
IPMI Commands that Used to Build up Redfish Host Interface
Standard IPMI commands those are used to build up the Redfish Host Interface for BMC-exposed USB NIC. The USB NIC exposed by BMC must be reported as one of the message channels as 802.3 LAN/IPMB 1.0 message channel.
| IPMI NetFn | IPMI Command | Purpose | Corresponding Host Interface Field |
|---|---|---|---|
| App (0x06) | 0x42 | Check the message channel's medium type and protocol. Medium: 802.3 LAN Protocol: IPMB 1.0 | None |
| Transport (0x0C) | 0x02 | Get MAC address of message channel. Used to match with the MAC address populated in EFI Device Path of network device | None |
| Group Ext (0x2C) | Group Extension ID: 0x52 Command: 0x02 | Check if Redfish bootstrap credential is supported or not. | In Device Descriptor Data, Credential Bootstrapping Handle |
| Transport (0x0C) | Command: 0x02 Parameter: 0x04 | Get BMC-end message channel IP address source | In Protocol Specific Record Data - Host IP Assignment Type - Redfish Service IP Discovery Type - Generate the Host-side IP address |
| Transport (0x0C) | Command: 0x02 Parameter: 0x03 | Get BMC-end message channel IPv4 address | In Protocol Specific Record Data - Host IP Address Format - Host IP Address |
| Transport (0x0C) | Command: 0x02 Parameter: 0x06 | Get BMC-end message channel IPv4 subnet mask | In Protocol Specific Record Data - Host IP Mask - Redfish Service IP Mask |
| Transport (0x0C) | Command: 0x02 Parameter: 0x12 | Get BMC-end message channel gateway IP address | None, used to configure edk2 network configuration |
| Transport (0x0C) | Command: 0x02 Parameter: 0x14 | Get BMC-end message channel VLAN ID | In Protocol Specific Record Data Redfish Service VLAN ID |
NOTE
Current RedfishPlatformHostInterfaceLib implementation of BMC-exposed USB NIC can only support IPv4 address format.
For example, run shell command "RedfishPlatformConfig.efi -s 192.168.10.101 255.255.255.0 192.168.10.123 255.255.255.0", which means the source IP address is 192.168.10.101, and the Redfish Server IP address is 192.168.10.123.
e.g. %WORKSPACE%/Build/EmulatorX64/DEBUG_VS2015x86/X64
NETWORK_SNP_ENABLE = TRUE NETWORK_HTTP_ENABLE = TRUE NETWORK_IP6_ENABLE = TRUE SECURE_BOOT_ENABLE = TRUE REDFISH_ENABLE = TRUE
NETWORK_ALLOW_HTTP_CONNECTIONS = TRUE
gEfiRedfishPkgTokenSpaceGuid.PcdRedfishRestExServiceDevicePath.DevicePath|{DEVICE_PATH("MAC(000000000000,0x1)")}
# # For Windows based host, use a number to refer to network adapter # gEmulatorPkgTokenSpaceGuid.PcdEmuNetworkInterface|L"1" or # # For Linux based host, use the device name of network adapter # gEmulatorPkgTokenSpaceGuid.PcdEmuNetworkInterface|L"en0"
Execute RedfishPlatformConfig.efi under EFI shell to configure the Redfish service information. The EFI variables are created for storing Redfish service information and is consumed by RedfishPlatformHostInterfaceLib under EmulatorPkg.
Thanks to the below predecessors who contributed to the UEFI EDK2 Redfish Prove of Concept code.
Fu, Siyuan siyuan.fu@intel.com
Ye, Ting ting.ye@intel.com
Wang, Fan fan.wang@intel.com
Wu, Jiaxin jiaxin.wu@intel.com
Yao, Jiewen jiewen.yao@intel.com
Shia, Cinnamon cinnamon.shia@hpe.com