The Redfish® Event Service
Redfish standardizes an event subscription service that enables monitoring applications to receive notifications when the REST data changes or when certain alerts occur. These notifications are HTTPS POST operations sent to a listener URL of your choice.
The EventService resource type is located in the Redfish data model at /redfish/v1/EventService/. This resource includes a link to the collection of subscriptions referred as EventDestinationCollection and located at the /redfish/v1/EventService/Subscriptions URI.
Event subscription
In order to receive events, you must identify the URL of an HTTPS server accepting POST requests and accessible to the BMC management network. Event POST operations generated by the BMC will be sent to this event listener URL after successful subscription.
TIP
If needed, The DMTF provides a Redfish Event Listener on GitHub.
To subscribe to an event, you need to construct a JSON object and POST it to the EventDestinationCollection URI of the managed BMC. Upon success, you receive an HTTP 201 Created response and a new subscription has been added in the collection.
NOTE
Most of the BMC Redfish event services (including iLO and OpenBMC) does not test the event listener destination URL during the subscription phase. It is your responsibility to verify that the BMC can post HTTPS requests in the listener destination.
The following example creates an event subscription in an iLO 6, with the Destination and Context properties as the only properties part of the request body. If not provided, the default value for EventFormatType is set to Event. Use the MetricReport value when subscribing to metric reports.
POST /redfish/v1/EventService/Subscriptions/{
"Destination": "https://{{EventListener}}/path/to/listener.app",
"Context": "Some context"
}{
"error": {
"code": "iLO.0.10.ExtendedInfo",
"message": "See @Message.ExtendedInfo for more information.",
"@Message.ExtendedInfo": [
{
"MessageId": "Base.1.17.Created"
}
]
}
}NOTE
If the creation request does not provide any value for the RegistryPrefixes and the Oem resources, the Redfish service may fill them up with default values. This is the case for HPE iLO 6; the previous example does not provide any detail concerning the subscription but RegisryPrefixes and Oem/Hpe objects have been automatically supplied by the service. Refer to the response body of the following example.
Once the subscription is created, its URI appears in the EventDestinationCollection collection. The following example retrieves the subscription entry created by the previous example.
GET /redfish/v1/EventService/Subscriptions/{item}/{
"@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
"@odata.etag": "W/\"F8B2DF36\"",
"@odata.id": "/redfish/v1/EventService/Subscriptions/2/",
"@odata.type": "#EventDestination.v1_13_0.EventDestination",
"Id": "2",
"Context": "Some context",
"Description": "iLO Event Subscription",
"Destination": "https://10.124.107.98/path/to/listener.app",
"EventFormatType": "Event",
"HttpHeaders": [],
"MetricReportDefinitions": [],
"Name": "Event Subscription",
"Oem": {
"Hpe": {
"@odata.context": "/redfish/v1/$metadata#HpeEventDestination.HpeEventDestination",
"@odata.type": "#HpeEventDestination.v2_1_0.HpeEventDestination",
"DeliveryRetryAttempts": 3,
"DeliveryRetryIntervalInSeconds": 30,
"MutualAuthenticationEnabled": false,
"RequestedMaxEventsToQueue": 3,
"RetireOldEventInMinutes": 10
}
},
"Protocol": "Redfish",
"RegistryPrefixes": [
"NetworkDevice",
"StorageDevice",
"ResourceEvent",
"iLOEvents",
"iLOResourceEvents"
],
"SubscriptionType": "RedfishEvent"
}The RegistryPrefixes property is a list of message registry prefixes to subscribe to. They correspond to the prefix of the error messages of the form <RegistryPrefix>.<MajorVersion>.<MinorVersion>.<MessageKey>.
If you subscribe to the the StorageDevice registry prefix, the destination event listener will receive all the error messages starting with "StorageDevice". Refer to the Event interpretation paragraph for more information.
The following example retrieves the list of possible RegistryPrefixes from an HPE iLO 6.
GET /redfish/v1/EventService/?$select=RegistryPrefixesilorest login <ilo-ip> -u <ilo-user> -p password
ilorest get RegistryPrefixes --json --selector EventService.
ilorest logout{
"@odata.context": "/redfish/v1/$metadata#EventService.EventService",
"@odata.etag": "W/\"3015330F\"",
"@odata.id": "/redfish/v1/EventService/",
"@odata.type": "#EventService.v1_7_2.EventService",
"RegistryPrefixes": [
"iLOEvents",
"ResourceEvent",
"NetworkDevice",
"StorageDevice",
"iLOResourceEvents"
]
}The following example retrieves the list of event subscriptions from an HPE iLO 6.
GET /redfish/v1/EventService/Subscriptions/{
"@odata.context": "/redfish/v1/$metadata#EventDestinationCollection.EventDestinationCollection",
"@odata.etag": "W/\"AA6D42B0\"",
"@odata.id": "/redfish/v1/EventService/Subscriptions/",
"@odata.type": "#EventDestinationCollection.EventDestinationCollection",
"Description": "iLO User Event Subscriptions",
"Name": "EventSubscriptions",
"Members": [
{
"@odata.id": "/redfish/v1/EventService/Subscriptions/6/"
}
],
"Members@odata.count": 1
}The following example shows an event subscription with specific HttpHeaders and Context properties. The HttpHeaders property contains a list of HTTP headers that the Redfish service will use when sending events to the event listener. This property could be used to perform an authentication in the event listener.
NOTE
The Redfish specification advises to return an empty HttpHeaders array upon GET requests of subscription details. Refer to the Subscription detail tabulation of the following example.
The Context property is a string that will be part of the event sent to the listener. With this information the listener could dispatch the event to a specific service able to act accordingly.
POST /redfish/v1/EventService/Subscriptions/{
"Destination": "https://{{EventListener}}/",
"Context": "Some context",
"RegistryPrefixes": [
"StorageDevice",
"NetworkDevice",
"iLOEvents",
"ResourceEvent"
],
"HttpHeaders":{
"Header1": "HeaderValue1",
"Header2": "HeaderValue2"
}
}{
"@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
"@odata.etag": "W/\"71734713\"",
"@odata.id": "/redfish/v1/EventService/Subscriptions/3/",
"@odata.type": "#EventDestination.v1_13_0.EventDestination",
"Id": "3",
"Context": "Some context",
"Description": "iLO Event Subscription",
"Destination": "https://192.168.1.46/",
"EventFormatType": "Event",
"HttpHeaders": [],
"MetricReportDefinitions": [],
"Name": "Event Subscription",
"Oem": {
"Hpe": {
"@odata.context": "/redfish/v1/$metadata#HpeEventDestination.HpeEventDestination",
"@odata.type": "#HpeEventDestination.v2_1_0.HpeEventDestination",
"DeliveryRetryAttempts": 3,
"DeliveryRetryIntervalInSeconds": 30,
"MutualAuthenticationEnabled": false,
"RequestedMaxEventsToQueue": 3,
"RetireOldEventInMinutes": 10
}
},
"Protocol": "Redfish",
"RegistryPrefixes": [
"StorageDevice",
"NetworkDevice",
"iLOEvents",
"ResourceEvent"
],
"SubscriptionType": "RedfishEvent"
}TIP
More event examples are presented in the HPE iLO specific supplement documents.
Testing the Event service
The Redfish Event Service offers the possibility to trigger test events from managed BMCs. The following test event, with MessageId containing iLOResourceEvents, will be forwarded to all the subscription destinations having iLOResourceEvents in its RegistryPrefixes list. Refer to the next paragraph for the interpretation of this event.
POST /redfish/v1/EventService/Actions/EventService.SubmitTestEvent{
"EventID": "myEventId",
"EventTimestamp": "2023-02-13T14:49:20Z",
"Severity": "Warning",
"Message": "This is a test event message",
"MessageId": "iLOResourceEvents.1.3.DrvArrLogDrvErasing",
"MessageArgs": [ "1", "slot 3" ],
"OriginOfCondition": "/redfish/v1/Systems/1/Storage"
}{
"error": {
"code": "iLO.0.10.ExtendedInfo",
"message": "See @Message.ExtendedInfo for more information.",
"@Message.ExtendedInfo": [
{
"MessageId": "Base.1.12.Success"
}
]
}
}Event interpretation
When an event occurs in a server, a MessageId property is associated to it. Its value is a message reference (i.e. iLOResourceEvents.1.3.DrvArrLogDrvErasing) described in the message registry. Only event destinations containing the message registry prefix of the MessageId property are notified. Upon reception, they can consult the related message registry file to get more detail and optionally resolution actions.
TIP
Registry file URIs are listed in the MessageRegistryFileCollection collection at /redfish/v1/Registries.
Upon reception of an event, the event listener can use the prefix of the MessageId property to retrieve the URI of the corresponding message registry URI. In the test event example above, the message registry prefix contained in the MessageId property is iLOResourceEvents. A GET of /redfish/v1/registries/iLOResourceEvents leads to /redfish/v1/RegistryStore/registries/en/iLOResourceEvents.json. A GET of this URI retrieves the entire message registry. This file contains an entry for the DrvArrLogDrvErasing error message.
Refer to the Error responses section for more information on this subject.