Updated: October 2019

Scope of this article

This article describes the Redfish Event Subscription service implemented in HPE iLO 5 with a firmware version of 1.40 or later. The implementation of this service in iLO 4 may differ slightly.

The Event Receiver program presented in this blog is an alternative to the DMTF Redfish-Event-Listener tool.

Traps versus event subscriptions

The Simple Network Management Protocol (SNMP) uses a "trap" mechanism to report asynchronous events generated by managed nodes toward pre-configured management consoles. All events are sent on the network and then processed by the management consoles. This approach may saturate the network and/or the management console in case of a storm of unsolicited events.

Another approach consists in filtering the events at the source, so only selected events are sent on the network toward specified event receivers (i.e. management consoles). Practically, the event receivers send a subscription request to the managed nodes containing the types of event that they are prepared to receive and process.

The Web-Based Enterprise Management (WBEM) standard uses this subscription paradigm, as well as the DMTF Redfish standard. Both of them define management web services but Redfish is much simpler for a common human being to understand, prototype and implement.

Do it yourself, it doesn't hurt

If you want to quickly prototype a Redfish event receiver, you need first to configure your favorite web server (Apache, IIS) to listen on port 443 (https) for asynchronous events coming from the managed nodes.

The following example is based on a simple PHP event receiver program installed in an Apache server. Any other web server (i.e. IIS) and language (i.e. JavaScript or cgi-bin) are possible alternatives.

Start to configure the Web Server and let it know the location of the EventReceiver.php program; the code below added in the Apache configuration file (httpd.conf) tells Apache to redirect requests to directory /opt/hpe/RedFishEventService. You may want to better secure this configuration entry to suite your security policy.

Alias /RedfishEvents** "/opt/hpe/RedfishEventService"
<Directory "/opt/hpe/RedfishEventService">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
    AddHandler server-parsed .shtml
    AddType text/html .shtml
    Options +Includes
</Directory>

In the /opt/hpe/RedFishEventService directory of the Web Server, create the EventReceiver.php file with the following content. This code is triggered by the Web Server when an event comes from a managed node. Then event, which is an HTTPS POST message, is written to a text file so you can read it or submit it to other applications for further processing.

Read the comments enclosed in /*..*/ or following // to get a detailed explanation:

<?php
// Version 0.9999
/** This PHP script receives RESTful POST events from an iLO or a Superdome Flex RMC.
*   It reformats the JSON message with indentations and sends
*   it to a file in the current directory
**/

/*
* The JSON format functions.php comes from:
* https://github.com/GerHobbelt/nicejson-php
*/
include 'functions.php';

// iLO events will be written to $out_file
$out_file = "Redfish_events.txt" ;

// Read the Content of the POST message:
$body = file_get_contents("php://input");


// Read the headers values:
$headers = getallheaders() ;

// Get IP address of managed node
$IP_MANAGED = getenv ('REMOTE_ADDR') ;


// Write IP_MANAGED in $outfile:
file_put_contents($out_file, "IP Address of Managed node: $IP_MANAGED \n", FILE_APPEND) ;

// Display headers and values
foreach ($headers as $header => $value) {
    file_put_contents($out_file, "$header: $value \n", FILE_APPEND) ;
}

//Insert new line to separate headers from body
file_put_contents($out_file, "\n", FILE_APPEND);


// Format message in nice and human readable format
file_put_contents($out_file, json_format($body) . "\n\n", FILE_APPEND);

?>

Once the event receiver program is in place and Apache restarted, it waits for solicitations on the /RedfishEvents alias. We can now ask one or several iLOs to send one or more event types toward this Web Server. In our case, we subscribe to all possible events proposed by an iLO 5.

The exhaustive list of possible events to subscribe to is present at: https://<ilo-IP>/redfish/v1/EventService/

For testing and prototyping, the subscription can be done manually using the POSTMAN API development platform , PowerShell, or curl. In a production environment, I would recommend to use iLOrest (former hprest) the HPE iLO RESTful Interface Tool or an application using the best practices to crawl and parse remote managed nodes schemas.

Before posting the following payload toward your managed node at https://<IP>/redfish/v1/EventService/EventSubscriptions/ you must edit and replace the Destination attribute with the <IP> address of the event receiver and its location. Optionally you can add or remove EventTypes:

{
   "Destination": "https://<IP>/RedfishEvents/EventReceiver.php",
   "EventTypes": [
       "StatusChange",
       "ResourceUpdated",
       "ResourceAdded",
       "ResourceRemoved",
       "Alert"
   ],
   "HttpHeaders": {
       "Content-Type": "Application/JSON",
       "OData-Version": "4.0"
   },
   "Context": "Public",
   "Oem": {
       "Hp": {
           "DeliveryRetryIntervalInSeconds": 30,
           "RequestedMaxEventsToQueue": 20,
           "DeliveryRetryAttempts": 5,
           "RetireOldEventInMinutes": 10
       }
    }
}

A successful subscription returns a status code 201 as shown in the picture below. Note that this successful notification is part of an error object. Hence as a human being, you should always read the entire content of error objects as they can carry good news.

Moreover, the status message mentions as well in its Location header the location of the subscription in the managed node's Redfish tree. In this case the subscription has been posted at /redfish/v1/EventService/Subscriptions/32/.

To avoid un-wanted network traffic or overloaded Redfish engine, HPE implemented an Oem.Hpe section containing attributes regulating subscriptions. In case a managed node continuously fails to post events at its destination, the subscription is deleted automatically after a certain amount of time (DeliveryRetryAttempts * DeliveryRetryIntervalSeconds seconds). Otherwise, a subscription has a infinite life time until it is deleted using a HTTPs DELETE request to it Location URI.

Fake events

To test our event receiver PhP code, Redfish provides an URI in the managed node to simulate an event and send an alert to the subscribers.

POST the following JSON body to trigger a fake event in the managed node:

{
    "EventType": "StatusChange",
    "EventID": "myEventId",
    "EventTimestamp": "2016-10-11T09:42:59Z",
    "Severity": "OK",
    "Message": "This is a test message",
    "MessageID": "iLOEvents.0.9.ResourceStatusChanged",
    "MessageArgs": [ "arg0", "arg1" ],
    "OriginOfCondition": "/rest/v1/Chassis/1/FooBar"
}

Check your Event Receiver, you should find an entry like the following in the Redfish_events.txt file:

IP Address of Managed node: 192.168.1.111
Host: 192.168.0.99
Transfer-Encoding: chunked
Content-Type: application/json, Application/JSON
Cache-Control: no-cache
Date: Mon, 10 Oct 2016 14:28:36 GMT
X_HP-CHRP-Service-Version: 1.0.3

{
    "@odata.type": "#Event.1.0.0.Event",
    "Events": [
        {
            "EventTimestamp": "2016-10-11T09:42:59Z",
            "EventType": "StatusChange",
            "Message": "This is a test message",
            "MessageID": "iLOEvents.0.9.ResourceStatusChanged",
            "MessageId": "iLOEvents.0.9.ResourceStatusChanged",
        "Oem": {
            "Hp": {
            "@odata.type": "#HpEvent.1.0.0.HpEvent",
            "Resource": null
        }
    },
    "OriginOfCondition":
    "/rest/v1/Chassis/1/FooBar",
    "Severity": "OK"
    }
    ],
    "Name": "Events"
}

Conclusion

SNMP is still the preferred management protocol and may stay as such for a long time. However, modern alternatives like this Redfish Event Subscription exist for compute nodes and the upcoming Swordfish. Swordfish is the extension of Redfish for storage devices from the SNIA proposing as well this Event Service in its Specification version 1.0.

Don't forget to check out some of my other blog posts on the HPE Developer portal to learn more about Redfish tips and tricks.