Getting started

Hewlett Packard Enterprise implements a Redfish RESTful API service in most of its compute nodes and servers (ProLiant, Synergy compute nodes, Edgeline, Superdome Flex 280....). Concerning HPE iLO based servers, customers can use this service with the iLO Standard license, although some features or data might not be available without an Advanced license. Features and data requiring Advanced license are listed in the HPE iLO User Guide.

Prior to the first Redfish standard publication (August 2015) and the HPE spin-off from HP, iLO based servers were providing a proprietary RESTful interface. Since then, HPE is conformant to the Redfish standard and provides backward compatibilities as well as documentation to minimize the impact of this evolution in programs and scripts. Refer to Adapting from pre-Redfish and pre-HPE paragraph for detail.

Tips for Using the Redfish RESTful API

To access the Redfish RESTful API service, you need an HTTPS-capable client, such the Postman development platform, cURL (a popular command line HTTP utility), PowerShell or a web browser with a REST client extension. This video presents several Redfish clients, including script languages like Ansible.

The Redfish data model introduces a level of abstraction that may not exists in other RESTful APIs: Data types also called resource types or just types. Each data type contains a set of resources and properties. Each resource or property belongs to a single data type mentioned in a @odata.type key.

Dats types are divided in two classes:

  • Collections: Contain a Members array with links to the URI of each member URI.
  • Regular data types: contain resources, property values and links to other data resources.
INFO

Data types prefixed with Hpe are HPE added value extensions to the DMTF Redfish specification.

The following example retrieves the ChassisCollection data type of an HPE Synergy computer node. Among other properties, the response body contains an @odata.type key and a Members array with two items pointing to the URI of the members. It contains as well a @odata.id with the URI of the resource.

generic GET requestResponse body
Copy
Copied
GET /redfish/v1/Chassis/
Copy
Copied
{
    "@odata.context": "/redfish/v1/$metadata#ChassisCollection.ChassisCollection",
    "@odata.etag": "W/\"570254F2\"",
    "@odata.id": "/redfish/v1/Chassis/",
    "@odata.type": "#ChassisCollection.ChassisCollection",
    "Description": "Computer System Chassis View",
    "Name": "Computer System Chassis",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Chassis/1/"
        },
        {
            "@odata.id": "/redfish/v1/Chassis/enclosurechassis/"
        }
    ],
    "Members@odata.count": 2
}

The following example retrieves the properties of the enclosurechassis URI found in the previous example. From the response body, we learn that this resource belongs to the Chassis data type.

We learn as well that it contains an Oem.Hpe object of type HpeServerChassis containing HPE specific properties not part of DMTF schemas.

GET requestResponse body
Copy
Copied
GET /redfish/v1/Chassis/enclosurechassis
Copy
Copied
{
    "@odata.context": "/redfish/v1/$metadata#Chassis.Chassis",
    "@odata.etag": "W/\"C4732762\"",
    "@odata.id": "/redfish/v1/Chassis/enclosurechassis",
    "@odata.type": "#Chassis.v1_10_2.Chassis",
    "Id": "enclosurechassis",
    "ChassisType": "Enclosure",
    "IndicatorLED": "Off",
    "Manufacturer": "HPE",
    "Oem": {
        "Hpe": {
            "@odata.context": "/redfish/v1/$metadata#HpeServerChassis.HpeServerChassis",
            "@odata.type": "#HpeServerChassis.v2_3_1.HpeServerChassis",
            "EnclosureIndicatorLED": "Off",
            "EnclosureModel": "Synergy 12000 Frame",
            "EnclosureUUID": "P06011CZ212406H0",
            "OnboardAdministrator": {
                "IPv4Address": null,
                "IPv6": {},
                "MacAddress": null
            }
        }
    },
    "PCIeDevices": {},
    "PCIeSlots": {},
    "PowerState": "Off",
    "SerialNumber": "CZ212406H0",
    "Status": {
        "Health": "OK"
    }
}
TIP

The data type list of HPE iLO based servers can be easily obtained with the types command of the iLOrest free command line tool.ss

Copy
Copied
ilorest login <ilo-ip> -u <ilo-user> -p <password>
ilorest types
ilorest logout

Adapting from pre-Redfish and pre-HPE

The following paragraphs provide information on the behavior and evolution of the HPE Redfish implementation and schemas in iLO based servers.

URI Remapping from /rest to /redfish

Access to the /rest/v1/x URI pattern results in HTTP 308 redirect to /redfish/v1/x/. Additionally, access to /redfish/v1/x redirects to /redfish/v1/x/.

Warning

Redfish client code should access the iLO RESTful API starting at /redfish/v1/ and should handle for HTTP 308 redirect. As an example, the cURL utility provides the --location (-L) parameter for this purpose.

OData-Version HTTP Header Requirements

Pre-Redfish REST service implementations behave differently with regard to the presence of an OData-Verion header in HTTP requests.

Redfish conformant implementations assume all requests to Redfish REST resources are Redfish requests. The service does not behave differently based upon the presence or absence of the OData-Version header.

The only required header for HTTPS operations is the authorization (X-Auth-Token or Authorization) header, except for the root resource at /redfish/v1/ which requires no headers. Refer to the [Authorization] (/docs/concepts/redfishauthentication/) section for more detail.

POST Actions

The pre-Redfish form of advertising Available Actions has been replaced Redfish Actions. Refer to the Performing actions section for more information.

Note that the URI of the POST matches the "target" property in "Actions".

On-Service JSON Schema

Pre-Redfish and with iLO 4, the on-service schema collection is at /redfish/v1/schema/ and does not change to the Redfish /redfish/v1/JsonSchema location. Because URIs are opaque before Redfish 1.6.0, this is left where it is without violating the spec and preserving compatibility.

The existing collection of SchemaFileCollection and SchemaFile resources are Redfish conformant using JsonSchemaFileCollection and JsonSchemaFile in iLO 5 and later.

iLO 5 and later
/redfish/v1/schemas: "@odata.type": "#JsonSchemaFileCollection.JsonSchemaFileCollection"
/redfish/v1/schemas/{item}: "@odata.type": “#JsonSchemaFile.v100.JsonSchemaFile"

On-Service Message Registries

Message Registries available in the service conform to Redfish and belonging to the MessageRegistryFileCollection data type.

With the creation of the HPE company, the HpCommon registry is renamed to HpeCommon and has been upgraded to a newer version.

Redfish client request examples and pointers

Example with iLOrest

Although not a requirement, you can use iLOrest, a free HPE RESTful Interface Tool to interact with the HPE iLO Redfish service. This command line tool provides a level of abstraction and convenience above direct access to this RESTful API.

The following example logs into an HPE Synergy iLO, selects the Chassis type and retrieves the enclosure chassis properties (in JSON format) using the iLOrest REST client tool.

iLOrest requestResponse body
Copy
Copied
ilorest login <ilo-synergy-ip> -u <ilo-user> -p <password>
ilorest select Chassis
ilorest get --json --filter ChassisType="Enclosure"
ilorest logout
Copy
Copied
{
  "@odata.context": "/redfish/v1/$metadata#Chassis.Chassis",
  "@odata.etag": "W/\"C4732762\"",
  "@odata.id": "/redfish/v1/Chassis/enclosurechassis/",
  "@odata.type": "#Chassis.v1_10_2.Chassis",
  "ChassisType": "Enclosure",
  "Id": "enclosurechassis",
  "IndicatorLED": "Off",
  "Manufacturer": "HPE",
  "Oem": {
    "Hpe": {
      "@odata.context": "/redfish/v1/$metadata#HpeServerChassis.HpeServerChassis",
      "@odata.type": "#HpeServerChassis.v2_3_1.HpeServerChassis",
      "EnclosureIndicatorLED": "Off",
      "EnclosureModel": "Synergy 12000 Frame",
      "EnclosureUUID": "P06032CX212406B1",
      "OnboardAdministrator": {
        "IPv4Address": null,
        "IPv6": {},
        "MacAddress": null
      }
    }
  },
  "PCIeDevices": {},
  "PCIeSlots": {},
  "PowerState": "Off",
  "SerialNumber": "MZ212406B0",
  "Status": {
    "Health": "OK"
  }
}

Examples with cURL

The following example performs a GET operation using the Redfish RESTful API on the iLO HTTPS port, typically port 443 (although it could be different if you have previously configured iLO to use another port). Redfish services don't offer the possibility to perform requests over non secured HTTP (port 80), so you must use HTTPS. Hence, your Redfish client should be prepared to handle the HTTPS certificate challenge.

Although not recommended, the following example uses the --insecure cURL flag to bypass the validation of the HTTPS certificate.

The GET operation is performed against the /redfish/v1/ URI (with a trailing slash).

NOTE

The Redfish root endpoint (/redfish/v1/) does not require authentication.

Tip

You can use the --location (-L) cURL option to follow HTTP redirect responses. If a new version of the Redfish service changes URI locations for various items, it can indicate to the Redfish client where the new location is and automatically follow the new link.

cURL (insecure)cURL (secure)iLO Response body (truncated)
Copy
Copied
curl --include --insecure --location \
     https://{ip}/redfish/v1/ 

where

    --include returns HTTP response headers
    --insecure bypasses TLS/SSL certification verification
    --location follows HTTP redirect
Copy
Copied
curl --include --location --cacert /tmp/CaCert.crt  https://ilo-ip/redfish/v1/

where

    --include returns HTTP response headers
    --location follows HTTP redirect
    --cacert provides the location of the CA certificate of the
      Certificate Authority who signed the
      remote management controller's certificate
Copy
Copied
{
  "@odata.context": "/redfish/v1/$metadata#ServiceRoot.ServiceRoot",
  "@odata.etag": "W/\"0884A8BC\"",
  "@odata.id": "/redfish/v1",
  "@odata.type": "#ServiceRoot.v1_5_1.ServiceRoot",
  "Id": "RootService",
  "AccountService": {
    "@odata.id": "/redfish/v1/AccountService"
  },
  "CertificateService": {
    "@odata.id": "/redfish/v1/CertificateService"
  },
  "Chassis": {
    "@odata.id": "/redfish/v1/Chassis"
  },
  "ComponentIntegrity": {
    "@odata.id": "/redfish/v1/ComponentIntegrity"
  },
  "EventService": {
    "@odata.id": "/redfish/v1/EventService"
  },
  "JsonSchemas": {
    "@odata.id": "/redfish/v1/JsonSchemas"
  },
  "Links": {
    "Sessions": {
      "@odata.id": "/redfish/v1/SessionService/Sessions"
    },
    "ComponentIntegrity": {
      "@odata.id": "/redfish/v1/ComponentIntegrity"
    }
  },
  "Managers": {
    "@odata.id": "/redfish/v1/Managers"
  },
  "Name": "HPE RESTful Root Service",
  "Oem": {
    "Hpe": {
      "@odata.context": "/redfish/v1/$metadata#HpeiLOServiceExt.HpeiLOServiceExt",
      "@odata.type": "#HpeiLOServiceExt.v2_3_0.HpeiLOServiceExt",
      "DebugCode": true,
      "DevSystem": false,
      "Links": {
        "ResourceDirectory": {
          "@odata.id": "/redfish/v1/ResourceDirectory"
        }
      },
      ...
      
      "System": [
        {
          "Status": {
            "Health": "OK"
          }
        }
      ],
      "Time": "2022-08-19T08:55:45Z"
    }
  },
  "Product": "Synergy 480 Gen11",
  "RedfishVersion": "1.6.0",
  "UUID": "de86625c-4b01-5b4b-9f82-9f50805bd400",
  "Vendor": "HPE"
}

The output of the previous example is formatted in JSON (JavaScript Object Notation).

JSON does not mandate strong ordering of property names. Hence, Redfish services may return properties in any order. Likewise, Redfish services cannot assume the order of properties in any submitted JSON queries.

This is why the best scripting data structure for a Redfish client is a dictionary: a simple set of unordered key/value pairs. This lack of ordering is also the reason you see embedded structure within objects (objects within objects). This allows to keep related data together that is more logically organized, aesthetically pleasing to view, and helps avoid property name conflicts or ridiculously long property names. It also allows the use identical blocks of JSON in many places in the data model, like status.

NOTE

It is possible to receive an error JSON object from a successful operation. See example below.

The Redfish protocol is OData conformant. This conformance implies the use of an error JSON block even for successful requests.

The following example sets the next reboot of a remote server to stop at the UEFI Shell. The PATCH request is successful (200 OK) and the response body contains an error JSON object mentioning a successful message Id.

PATCH requestSuccessful response headersResponse body
Copy
Copied
curl --insecure --include --location \
     --request PATCH 'ilo-ip/redfish/v1/Systems/1/' \
     --header 'Content-Type: application/json' \
     --header 'X-Auth-Token: cbc01435d62796cca15b9cba3813d39' \
     --data-raw '{
         "Boot":
           {"BootSourceOverrideTarget": "UefiShell",
           "BootSourceOverrideEnabled": "Once"}
      }'
Copy
Copied
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-type: application/json; charset=utf-8
Date: Tue, 08 Nov 2022 16:58:05 GMT
ETag: W/"02C2D1BB"
OData-Version: 4.0
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Copy
Copied
{
    "error": {
        "code": "iLO.0.10.ExtendedInfo",
        "message": "See @Message.ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "MessageId": "Base.1.12.Success"
            }
        ]
    }
}

Python and Ansible

The Python eco-system provides several HTTP libraries. Popular ones are:

You can use those libraries to write your Redfish clients. However, authentication, session management, and other pure Redfish related requests may quickly become cumbersome. For this reason, some organization like the DMTF and HPE publish specific Python Redfish libraries. The DMTF Python Redfish library is based upon the Pypi requests module and used by all the DMTF Redfish projects.

The HPE Python Redfish library is based upon the Pypi urllib3 module and used by the HPE iLOrest command line tool. Many examples of common Redfish operations, mostly targeted against iLO based servers, can be freely downloaded from the HPE GitHub.

Although very similar in usage and features, the HPE Python Redfish library provides some specificities like the possibility to access the local iLO Redfish service via the HPE CHIF Driver or authenticate with user certificates.

Before accessing Redfish resources and properties, Redfish Python scripts must create an instance of a "Redfish Client Object". In a Python environment, the class constructor name used to create that object depends on the library you use: redfish_client with the DMTF Redfish Python library, RedfishClient with the HPE Redfish Python library.

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 or use a specific environment for each of them.

The class constructor of both Python Redfish libraries takes the Redfish service hostname/IP address, login username, and password or valid certificate as arguments (HPE Python library only). The class also initializes a login session, gets system resources and message registries as shown in the simple example below derived from this one.

This example uses a basic authentication method to log into an HPE iLO based management controller and retrieves its ComputerSystem resources. Refer to the Authentication and sessions section for other authentication methods.

Generic requestHPE Python Redfish LibraryDMTF Python Redfish LibraryResponse (Truncated)
Copy
Copied
GET /redfish/v1/Systems/1/
Copy
Copied
# -*- coding: utf-8 -*-
"""A quickstart example for a Redifh client calling the RedfishClient HPE class.

NOTE: Make sure the DMTF Python Redfish library is not installed when loading 
      the HPE Redfish Python library:

      pip uninstall redfish
      pip install python-ilorest-library

"""

import sys
import json
from redfish import RedfishClient

# When running on the server locally and the iLO in a "Production security State",
# use the following commented values
# HOST = "blobstore://."
# LOGIN_ACCOUNT = "None"
# LOGIN_PASSWORD = "None"

# When running remotely connect using the iLO address, iLO account name,
# and password to send https requests
SYSTEM_URL = "https://<ilo-ip>"
LOGIN_ACCOUNT = "<ilo-user>"
LOGIN_PASSWORD = "password"

# Populate the following variables if you want to verify the SSL connection. Otherwise,
# set them to None.
#
# NOTE: The HPE Redfish Python library uses the 'urllib3.connection.HTTPSConnection' constructor
# described at: https://urllib3.readthedocs.io/en/latest/reference/urllib3.connection.html. Refer
# to this documentation for a description of all possible **client_kwargs for establishing the 
# HTTPS connection.
cert_file="/cert/CaCert.crt"    # Certificate Authority certificate of CA who signed the remote Management Controller's certificate
key_file="/cert/CaCert.key"     # CA secret key associated to the above CA certificate.
key_password="password"         # Password to read the above CA secret key.

## Create a REDFISH object
REDFISH_OBJ = RedfishClient(base_url=SYSTEM_URL, username=LOGIN_ACCOUNT,\
                password=LOGIN_PASSWORD,
                cert_file=cert_file, key_file=key_file, key_password=key_password)

# Login into the server and create a session
REDFISH_OBJ.login()

# Do a GET on a given path
RESPONSE = REDFISH_OBJ.get("/redfish/v1/systems/1/")

# Print out the response
print(json.dumps(RESPONSE.dict, indent=4, sort_keys=True))

# Logout of the current session
REDFISH_OBJ.logout()
Copy
Copied
# -*- coding: utf-8 -*-
"""A quickstart example for a Redifh client calling the redfish_client DMTF class.

NOTE: Make sure the DMTF Python Redfish library is not installed when loading 
      the HPE Redfish Python library:

      pip uninstall python-ilorest-library
      pip install redfish

"""

import sys
import json
from redfish import redfish_client

# When running remotely connect using the iLO address, iLO account name,
# and password to send https requests
SYSTEM_URL = "https://<ilo-ip>"
LOGIN_ACCOUNT = "ilo-user"
LOGIN_PASSWORD = "password"

# Populate the following variable if you want to validate the SSL connection.
#cafile="c:\\cygwin64\\tmp\\CaCert.crt"
cafile=None

## Create a REDFISH object
REDFISH_OBJ = redfish_client(base_url=SYSTEM_URL, username=LOGIN_ACCOUNT,\
                                    password=LOGIN_PASSWORD,
                                    cafile=cafile)

# Login into the server and create a session
REDFISH_OBJ.login()

# Do a GET on a given path
RESPONSE = REDFISH_OBJ.get("/redfish/v1/systems/1/")

# Print out the response
print(json.dumps(RESPONSE.dict, indent=4, sort_keys=True))

# Logout of the current session
REDFISH_OBJ.logout()
Copy
Copied
{
    "@odata.context": "/redfish/v1/$metadata#ComputerSystem.ComputerSystem",
    "@odata.etag": "W/\"2AE0E11D\"",
    "@odata.id": "/redfish/v1/Systems/1/",
    "@odata.type": "#ComputerSystem.v1_17_0.ComputerSystem",
    "Actions": {
        "#ComputerSystem.Reset": {
            "ResetType@Redfish.AllowableValues": [
                "On",
                "ForceOff",
                "GracefulShutdown",
                "ForceRestart",
                "Nmi",
                "PushPowerButton",
                "GracefulRestart"
            ],
            "target": "/redfish/v1/Systems/1/Actions/ComputerSystem.Reset/"
        }
    },
    "AssetTag": "",
    "Bios": {
        "@odata.id": "/redfish/v1/systems/1/bios/"
    },
    "BiosVersion": "A56 v1.20 (11/17/2022)",
    "Boot": {
        "BootOptions": {
            "@odata.id": "/redfish/v1/Systems/1/BootOptions/"
        },
        "BootOrder": [
            "Boot000E",
            "Boot000F",
            "Boot0010",
            "Boot0011",
            "Boot0012",
            "Boot0017",
            "Boot0018",
            "Boot0013",
            "Boot0014",
            "Boot0019",
            "Boot001A",
            "Boot0015",
            "Boot0016"
        ],
        "BootSourceOverrideEnabled": "Disabled",
        "BootSourceOverrideMode": "UEFI",
        "BootSourceOverrideTarget": "None",
        "BootSourceOverrideTarget@Redfish.AllowableValues": [
            "None",
            "Cd",
            "Hdd",
            "Usb",
            "SDCard",
            "Utilities",
            "Diags",
            "BiosSetup",
            "Pxe",
            "UefiShell",
            "UefiHttp",
            "UefiTarget"
        ],
        ...
        ...
    "UUID": "32343550-3630-5754-4132-323534354132"
}

In addition to the above Python Redfish libraries,the DMTF and HPE provide Ansible playbooks and roles part of the Ansible galaxy.

The HPE Ansible Redfish playbooks and roles extend the generic DMTF's playbooks with HPE OEM Redfish extensions.

The documentation for both Ansible playbooks (DMTF and HPE) is in the Ansible community general documentation portal.