Skip to content
Guides
/
Examples

Redfish examples

This section provides several standard Redfish and HPE OEM specific examples. Other examples can be found throughout the document like in the performing action and in the supplement documents sections.

BIOS Redfish examples

This section presents standard Redfish requests related to the BIOS/UEFI subsystem. HPE specific BIOS/UEFI examples are presented in the HPE BIOS section of the supplement documents.

Reading BIOS current settings

The following example retrieves the current BIOS configuration of an iLO based server using cURL and Python.

Warning

As mentioned in the Getting Started section, the DMTF Redfish Python library and the HPE Redfish Python library cannot co-exist in the same Python environment. You should uninstall one before installing the other one.

curl --insecure -u username:password --location \
     https://{iLO}/redfish/v1/systems/1/bios/

Update of a BIOS attribute

On an iLO based server, the minimum required session ID privileges is Configure. The following example modifies the AdminName, AdminEmail and AdminPhone BIOS attributes on an iLO based server.

TIP

When using iLOrest to set properties, you can include special characters (including spaces) by surrounding both the key and the value with double quotes.

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest select Bios.
ilorest set "AdminName=John D'euf" AdminEmail="john.deuf@koulapic.com" AdminPhone="+3367890123"
ilorest commit
ilorest reboot ColdBoot
ilorest logout

Python Redfish example

BIOS UEFI Secure Boot enablement

The standard Redfish SecureBootEnable property is part of the SecureBoot data type. A reboot of the system is required to enable this property.

The following example enables Secure Boot on an iLO based server. The minimum required session privilege is Configure.

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest select SecureBoot.
ilorest set SecureBootEnable=True --commit
ilorest reboot ColdBoot
ilorest logout

For a full Python example click here: enable_secure_boot.py

Reset BIOS settings to defaults

The following example resets BIOS attributes in an iLO 6 based server using the Redfish standard action. HPE provides alternate methods with added value to achieve a similar goal.

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

Server reset

Server power control belongs to the global ComputerSystem resource. It is not part of the Chassis resource. The reason is because some systems can be configured with multiple Operating Systems, each of them spanning one or several chassis. The HPE Superdome Flex is one of them. With this model, you can control the power of each operating system independently of each other by performing an HTTP operation on the desired Computer System item.

The standard method to reset a server, is to use the ComputerSystem.Reset Redfish standard action. Refer to the Performing actions section for detail on the Actions object.

The following example resets an HPE iLO 6 based server using the standard Redfish method. The Minimum required session privilege is Configure.

GET /redfish/v1/Systems/1/?$select=Actions

Management Controller reset

The following example lists the possible standard Redfish actions against an HPE iLO 5 (or later) management controller with cURL and the HPE iLOrest Redfish client.

NOTES

By design, a Management Controller reset has no impact on the Operating System running in the server. You can safely restart (abruptly or gracefully) the Management Controller while th Operating System is up and running.

GET https://ilo-ip/redfish/v1/Managers/1/?$select=Actions

The above example returns ForceRestart and GracefulRestart for possible Manager Controller reset parameters, as mentioned in the resource definition section . Use the GracefulRestart value to wait for Management Controller running tasks to complete or to be gently stopped before restarting. Use ForceRestart to restart the Management Controller abruptly.

NOTE

HPE iLO does not have the possibility to stop running tasks before triggering its restart. As a consequence, the GracefulRestart action is implemented as a ForceRestart.

The following example resets an HPE iLO 5 (or later) using the standard Redfish Manager.Reset action with cURL and the ilorest iloreset macro-command.

TIP

Refer to the Authentication and sessions to learn how to create a session token like the one used by cURL in the next example.

POST /redfish/v1/Managers/1/Actions/Manager.Reset/

Body:
{
    "ResetType": "ForceRestart"
}

GET MAC address of a Management Controller

The goal of this example is to explain the workflow to retrieve the MAC address of the active management controller Ethernet interface of a server, connected to a physical network. MAC addresses of other network interfaces (ComputerSystem, HostInterfaces) are excluded. With this methodology, you should be able to write a long term Redfish client that works against any Redfish service implementation, including non-HPE.

NOTE

The following methodology targets Redfish services compliant with version 1.6.0 or above.

Redfish services compliant with earlier versions must start browsing the Redfish tree at /redfish/v1.

The Redfish schema specification, provides, in table 5.2, the exhaustive list of the standard collections with their associated URIs. One of them is the EthernetInterfaceCollection.

The URIs related to EthernetInterfaceCollection subordinate the following major subsystems: Chassis, CompositionService ResourceBlocks, Systems and Managers. Considering the goal of this exercise, you need to focus on the URIs below the Managers subsystem: /redfish/v1/Managers/{ManagerId}/EthernetInterfaces and /redfish/v1/Managers/{ManagerId}/HostInterfaces/{HostInterfaceId}/HostEthernetInterfaces.

The second URI relates to HostInterfaces (i.e. virtual NIC on iLO based servers) allowing the access to the Management Controller from the operating system of the server. This type of ethernet interface is not relevant to this exercise as mentioned in the fist paragraph. Hence, the only relevant URI for this exercise is: /redfish/v1/Managers/{ManagerId}/EthernetInterfaces.

This URI is compliant with the Redfish Resource URI pattern definition (paragraph 7.5.4) as it contains the {ManagerId} string. Long term and portable Redfish clients must discover the list of possible Manager Identifiers and chose the most relevant one. The discovery of the Management Identifiers is performed with a GET operation toward the ManagerCollection URI.

The following example provides portable methods to retrieve controller manager Identifiers.

GET /redfish/v1/Managers

Once the Manager identifier URI is discovered, you can list the collection of Ethernet Interfaces attached to this particular manager:

The following example retrieves the collection of Ethernet interfaces of an iLO based server.

GET /redfish/v1/Managers/1/EthernetInterfaces
TIP

In the above iLOrest example, you have to select only Managers* interfaces. This is because iLOrest uses the EthernetInterface data type which owns several instances (URIs).

Failure to do so retrieves also Systems interfaces.

The last step is to identify the interface physically connected to the management network among the URIs discovered in the previous step. This can be done with the LinkUp property and the following pseudo code:

create list of Managers Ethernet interface URIs
for each interface in list ; do
   if LinkStatus == LinkUp then
      print MacAddress
   fi
endfor
NOTE

It is possible that Redfish services include Host Interfaces (also called vNICs) in the Manager EthernetInterfaceCollection (i.e. iLO Redfish). If at least one is enabled, the above script will print its MAC address in addition to the MAC address of the physical interface.

In that case, you will have to find a property common to all your computer vendors and use it to filter out undesirable interfaces. This property could belong to the OEM extension.

For a full Redfish example click here: find_ilo_mac_address.py

Configuring user-defined temperature threshold

iLO 6 offers the possibility to configure user-defined temperature thresholds using a Redfish action, and resulting in IML log entries generation if exceeded.

NOTE

System defined temperature threshold cannot be modified. User defined temperature thresholds provide finer granularity to temperature thresholds.

The following example is similar to this one in the performing actions section. It configures a user-defined temperature warning threshold on sensor 1 (Inlet-Ambient) of an iLO 6 based server. If the ambient temperature is exceeded, a warning IML entry is created.

TIP

Replace AlertType=Warning with AlertType=Critical to create a CriticalUserTempThreshold property in the sensor entry. If the ambient temperature is exceeded, a warning IML entry is created.

POST /redfish/v1/Chassis/1/Thermal/Actions/Oem/Hpe/HpeThermalExt.SetUserTempThreshold/

Once a user defined temperature threshold is created, it is possible to retrieve the corresponding properties as shown in the following example.

GET /redfish/v1/Chassis/1/Thermal/?$select=Temperatures/Oem/Hpe/

Server Thermal Configuration

Both BIOS and iLO/Chassis Redfish subsystems are able to manage the thermal configuration (fan cooling) of iLO based HPE servers. This paragraph provides detailed examples using both methods.

Fan management using BIOS

Fan cooling management can be performed with the ThermalConfig BIOS attribute .

NOTE:

A reboot of the server is required to take BIOS attribute modifications, including ThermalConfi, into account.

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest info ThermalConfig --select Bios
ilorest logout

Fan management using Thermal

Fan cooling management can also be performed with the ThermalConfiguration property.

NOTE

A reboot of the server is not required to take Thermal modifications into account.

PATCH /redfish/v1/Chassis/1/Thermal
TIP

The possible values for the ThermalConfiguration property are listed in the resource definition section:

  • OptimalCooling
  • IncreasedCooling
  • MaximumCooling
  • EnhancedCooling
ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest set Oem/Hpe/ThermalConfiguration="EnhancedCooling" --commit
ilorest logout

Fallback sensors

Temperature fallback sensors are activated when main sensor fails. This activation ensures that HPE iLO can still drive fans using the fallback sensor input, at least in a degraded mode. In some cases (i.e. when the main sensor of a third party OCP or optional card is not recognized by HPE iLO), there could be a need to disable fallback sensor(s).

When a fallback sensor is disabled, it does not send any temperature input to HPE iLO. Read the note in the changelog file be informed of the consequences of disabling fallback sensors.

The following example disables a specific fallback sensor using a PATCH request. The Oem.Hpe.FallbackOverride property serves as a prerequisite condition that allows modification to the HpeFallbackSensorCollection schema.

PATCH /redfish/v1/Chassis/1/Sensors/25

Body:
{
    "Oem": {
      "Hpe": {
        "FallbackOverride": true,
        "FallBackDisabled": true
      }
    }
}
NOTE

Fall back sensor management requires a minimal ROM version. Check for its support in the ROM release notes.

Redfish iSCSI configuration example

NOTE

Some examples in this section use a pseudo-code syntax for clarity. JSON pointer syntax is used to indicate specific properties.

Warning

The DMTF Redfish Python library and the HPE Redfish Python library cannot co-exist in the same Python environment. You should uninstall one before installing the other one.

Before accessing Redfish resources and properties, you must create an instance of RedfishObject. The class constructor takes the Redfish service hostname/IP address, login username, and password or valid certificate as arguments. The class also initializes a login session, gets systems resources, and message registries as shown in this simple example.

Example iSCSI Software Initiator configuration

The iSCSI Software Initiator allows you to configure an iSCSI target device to be used as a boot source. The BIOS current configuration object contains a link to a separate resource of type HpeiSCSISoftwareInitiator. The BIOS current configuration resource and the iSCSI Software Initiator current configuration resources are read-only. To change iSCSI settings, you need to follow another link to the Settings resource, which allows PUT and PATCH operations.

The iSCSI target configurations are represented in an iSCSISources property, that is an array of objects, each containing the settings for a single target. The size of the array represents the total number of iSCSI boot sources that can be configured at the same time. Many mutable properties exist, including iSCSIAttemptInstance, which can be set to a unique integer in the range [1, N], where N is the boot sources array size. By default, this instance number is 0 for all objects, indicating that the object should be ignored when configuring iSCSI.

Each object also contains two read-only properties—StructuredBootString and UEFIDevicePath, which are only populated after the target has been successfully configured as a boot source. More information about each property is available in the corresponding schema. The iSCSI initiator name is represented by the iSCSIInitiatorName property.

An additional read-only property, iSCSINicSources, is only shown in the iSCSI current configuration resource. This property is an array of strings representing the possible NIC instances that can be used as targets for iSCSI boot configuration. To confirm which NIC device each string corresponds to, it is recommended to cross-reference two other resources:

  • A resource of type HpeBiosMapping can be found through a Mappings link in the BIOS current configurations resource. Within its BiosPciSettingsMappings property is an array of mappings between BIOS-specific device strings (such as the NIC source string) and a CorrelatableID string that can be used to refer to the same device in non-BIOS contexts.
  • A collection of HpeServerPciDevices may be found through a PCIDevices link in the ComputerSystem resource. The specific PCI device corresponding to the NIC instance can be found by searching for the CorrelatableID that will usually match a UEFIDevicePath. Once the HpeServerPciDevice resource is found, you have access to all the human-readable properties useful for describing a NIC source.

Changing the iSCSISources and iSCSIInitiatorName settings can be done through PATCH operations, very similar to how HpeBios settings are changed. However, whereas all BIOS settings are located in a single flat object, iSCSI settings are nested into arrays and sub-objects. When doing a PATCH operation, use empty objects ({}) in place of those boot source objects that you do not want to alter.

The following example covers a situation where you have configured two iSCSI boot sources, and you would like to edit some existing settings, and add a third source.

  1. Iterate through /redfish/v1/Systems and choose a member ComputerSystem. Find a child resource of type HpeiSCSISoftwareInitiator that allows PATCH operations.

    • {ilo-address}/redfish/v1/Systems/1/BIOS/iSCSI/Settings/

  2. Inspect the existing iSCSIBootSources array. You need to inspect the iSCSIBootAttemptInstance property of each object to find the boot sources you are prefer to change.

  3. Create a new JSON object with the iSCSIBootSources property.

    • Use an empty object in the position of instance 1 to indicate that it should not be modified.

    • Use an object in the position of instance 2 containing the properties that should be modified—all omitted properties will remain unmodified.

    • To add a new boot source, find any position of instance 0 and replace it with an object containing all the new settings, and most importantly, a new unique value of iSCSIBootAttemptInstance.

  4. Change the iSCSI software initiator settings.

    • PATCH {ilo-address}/redfish/v1/Systems/1/BIOS/iSCSI/Settings/
{
    "iSCSISources": [
        {
             "iSCSIAttemptInstance": 1,
             ...
        },
        {
             "iSCSIAttemptInstance": 2,
             ...
        },
        {
             "iSCSIAttemptInstance": 0,
             ...
        },
        {
             "iSCSIAttemptInstance": 0,
             ...
        }
    ],
    ...
}
Previous page
Next page