1# Redfish EventService design 2 3Author: AppaRao Puli 4 5Other contributors: None 6 7Created: 2019-07-24 8 9## Problem description 10 11Redfish in OpenBMC currently supports sending response to the clients which 12requests for data. Currently there is no service to send asynchronous message to 13the client about any events, error or state updates. 14 15The goal of this design document is to give resource overview of redfish event 16service and its implementation details in OpenBMC. 17 18## Background and references 19 20- [Redfish specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf) 21- [DMTF Redfish school events](https://www.dmtf.org/sites/default/files/Redfish_School-Events_2018.2.pdf) 22- [Redfish event logging](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md) 23- [Telemetry service](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/) 24- [Beast async client](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async/) 25- [Beast async-ssl client](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async-ssl/) 26- [EventService schema](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml) 27- [EventDestinationCollection schema](https://redfish.dmtf.org/schemas/v1/EventDestinationCollection_v1.xml) 28- [EventDestination schema](https://redfish.dmtf.org/schemas/v1/EventDestination_v1.xml) 29- [Upgrade connection for SSE](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/13948/) 30 31## Requirements 32 33High level requirements: 34 35- BMC shall support send asynchronous event notification to external subscribed 36 clients over network using redfish(http/https) protocol, instead of regular 37 querying mechanism. 38- BMC shall provide mechanism to the users to configure event service with 39 specific filters and accordingly send the event notifications to all the 40 registered clients. 41- BMC shall preserve the event service configuration across reboots, and shall 42 reset the same, when factory defaults applied. 43- BMC shall have provision to disable the EventService. 44- The BMC Redfish interface shall support the EventService, EventDestination and 45 EventDestinationCollection schemas. 46- BMC can provide functionality to send out test events(SubmitTestEvent). 47- Must allow only users having 'ConfigureManager' to create, delete or updated 48 event service configuration, subscriptions and restrict other users. Must 49 allow users with 'Login' privileges to view the EventService configuration and 50 subscription details. 51- EventService shall be specific to Redfish Interface alone. i.e No other 52 service can add/modify/delete configuration or subscriptions. 53- Either the client or the service can terminate the event stream at any time. 54 The service may terminate a subscription if the number of delivery error's 55 exceeds preconfigured thresholds. 56- For Push style event subscription creation, BMC shall respond to a successful 57 subscription with HTTP status 201 and set the HTTP Location header to the 58 address of a new subscription resource. Subscriptions are persistent and shall 59 remain across event service restarts. 60- For Push style event subscription creation, BMC shall respond to client with 61 http status as 62 - 400: If parameter in body is not supported. 63 - 404: If request body contains both RegistryPrefixes and MessageIds. 64- SSE: BMC shall respond to GET method on URI specific in "ServerSentEventUri" 65 in EventService schema with 201(created) along with subscription information. 66 BMC shall open a new https connection and should keep connection alive till 67 subscription is valid. BMC shall respond with https code 400, if filter 68 parameters are not supported or 404 if filter parameter contains invalid data. 69 Also SSE subscription data cannot be persistent across service resets/reboots. 70- Clients shall terminate a subscription by sending an DELETE message to the URI 71 of the subscription resource. 72- BMC may terminate a subscription by sending a special "subscription 73 terminated" event as the last message. Future requests to the associated 74 subscription resource will respond with HTTP status code 404. 75- BMC shall accept the "Last-Event-ID" header from the client to allow a client 76 to restart the event/metric report stream in case the connection is 77 interrupted. 78- To avoid exhausting the connection resource, BMC shall implement a restriction 79 of maximum 20 connections (Maximum of 10 SSE connections). BMC shall respond 80 with 503 Service Unavailable server error response code indicating that the 81 server is not ready to handle the request. 82- BMC shall log an redfish event message for subscription addition, deletion and 83 modification. 84- Services shall not send a "push" event payload of size more than 1 MB. 85 86## Proposed design 87 88Redfish event service provides a way to subscribe to specific kinds of Events, 89MetricReport and asynchronously send subscribed type of events or reports to 90client whenever it occurs. 91 92Two styles of events are supported OpenBMC EventService. 93 941. Push style events (https): When the service detects the need to send an 95 event, it uses an HTTP POST to push the event message to the client. Clients 96 can enable reception of events by creating a subscription entry in the 97 EventService. 98 992. Server-Sent Events (SSE): Client opens an SSE connection to the service by 100 performing a GET on the URI specified by the "ServerSentEventUri" in the 101 Event Service. 102 103This document majorly focuses on OpenBMC implementation point of view. For more 104details specific to EventService can be found in 105["Redfish Specification"](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf) 106sections:- 107 108- Eventing (Section 12.1) 109- Server Sent-Events (Section 12.5) 110- Security (Section 12 & 13.2.8) 111 112```text 113+------------------------------------------------------------------------------------+ 114| CLIENT | 115| EVENT LISTENER | 116| | 117+-----------------------------------------------------------------^---------^--------+ 118CONFIGURATION| |SSE(GET) NETWORK PUSH STYLE | |SSE 119SUBSCRIPTION | | EVENTS | POST | 120+------------------------------------------------------------------------------------+ 121| | | | | | 122| +--------+---------+---+ +---------------------------------------------------+ | 123| | REDFISH | | EVENT SERVICE MANAGER | | | | 124| | SCHEMA | | +-------------------------------+---------+--+ | | 125| | RESOURCES | | | EVENT SERVICE | | | 126| | | | | SENDER | | | 127| | | | +------^----------------------------+--------+ | | 128| | +-------------+ | | | | | | 129| | |EVENT SERVICE| | | +------+--------+ +------+--------+ | | 130| | +-------------+ | | | METRICSREPORT | | EVENT LOG | | | 131| | | | | FORMATTER | | FORMATTER | | | 132| | | | +------^--------+ +------^--------+ | | 133| | +-------------+ | | | | | | 134| | + |SUBSCRIPTIONS+--------------------+------------------------------+ | | 135| | + | +-------------+ | | | | | | | | 136| | | +--------------+ | | +------+---+----+ +------+-----+--+ | | 137| | +--------------| | | | METRCISREPORT | | EVENT LOG | | | 138| | | | | MONITOR/AGENT | | MONITOR | | | 139| | | | +---------------+ +---------------+ | | 140| +----+-----------------+ +---------------------------------------------------+ | 141| | | | | 142+------------------------------------------------------------------------------------+ 143 | | | 144 | | |INOTIFY 145 | | | 146+--------+----------+ +---------+----------+ +-----------------------+ 147| | | | | +-----------------+ | 148| REDFISH | | TELEMETRY | | | REDFISH | | 149| EVENT SERVICE | | SERVICE | | | EVENT LOGS | | 150| CONFIG | | | | +-----------------+ | 151| PERSISTENT STORE | | | | |RSYSLOG | 152| | | | | +-----------------+ | 153| | | | | | JOURNAL | | 154| | | | | | CONTROL LOGS | | 155| | | | | +-----------------+ | 156+-------------------+ +--------------------+ +-----------------------+ 157 158``` 159 160Push style events(HTTPS) flow diagram: 161 162```text 163+-------------+ +------------+ +-------------------------------------+ +-----------------+ 164| | | CLIENT | | BMCWEB | | EVENT LOG/ | 165| CLIENT | | LISTENERS | |RESOURCE SENDER FORMATTER MONITOR | |TELEMETRY SERVICE| 166+-----+-------+ +-----+------+ +--+--------+--------+---------+------+ +-----+-----------+ 167 | | | | | | | 168+---------------------------------------------------------------------------------------------------- 169|SUBSCRIBE FOR EVENT| | | | | | | 170+-------------------+ | | | | | | 171 | | | | | | | 172 | | | | | | | 173 | | EVENT SUBSCRIPTION | | | | | 174 +------------------------------------------>+ | | | | 175 | | PUSH STYLE EVENT | | | | | 176 | | |-------------------------> | | 177 | | | SEND SUBSCRIPTION INFO | | 178 | | |----------------------------------------->| 179 | | | LOG REDFISH EVENT LOG | | 180 | | | | | | | 181+---------------------------------------------------------------------------------------------------- 182|SEND EVENTS/METRICS WHEN GENERATED | | | | | | 183+-----------------------------------+ | | | | | 184 | | | | | | | 185 | | | | | | +----+ 186 | | | | | | |LOOP| 187 | | | | | | +<---+ 188 | | | | | +<------------>+ 189 | | | | | | NOTIFY EVENT/TELEMETRY 190 | | | | | | DATA | 191 | | | | | +--------------> 192 | | | | | | READ DATA | 193 | | | | | +<-------------+ 194 | +-----+--------------------------------------------------------------------------+ 195 | |LOOP | | | | | | | | 196 | +-----+ | | | | | | | 197 | | | | | | +-----------+ | | 198 | | | | | | | MATCH | | | 199 | | | | | | |SUBSCRIPTION | | 200 | | | | | | |WITH DATA | | | 201 | | | | | | +-----------+ | | 202 | | | | | | | | | 203 | | | | | +<--------+ | | 204 | | | | | | SUBSCRIPTION | | 205 | | | | | | AND DATA | | 206 | | | | | | | | | 207 | | | | +<-------+ | | | 208 | | | | |SUBSCRIPTION AND | | | 209 | | | | |FORMATTED DATA | | | 210 | | | | | | | | | 211 | | +--------------------------------------------------------------------+-+ 212 | | |FIRST TIME, CREATE CONNECTION | | | | | | 213 | | +------------------------------+ | | | | | 214 | | <----------------------------------> | | | | 215 | | | ESTABLISH HTTP/HTTPS | +-----+ | | | | 216 | | | CONNECTION | |STORE| | | | | 217 | | | | |CONN-SUBS | | | 218 | | | | |MAP | | | | | 219 | | | | |<----+ | | | | 220 | | | | | | | | | 221 | | | | +----+| | | | | 222 | | | | |PUSH QUEUE | | | 223 | | | | |INCOMING| | | | 224 | | | | |DATA | | | | | 225 | | | | |<---+| | | | | 226 | | | | | | | | | 227 | | +------+-----------------------------------------+ | | | | 228 | | |RETRY ||<---------------------------------+ | | | | | 229 | | |LOOP || SEND FORMATTED DATA | | | | | | | 230 | | |-+----+| | | | | | | | 231 | | | +----------------------------------------------------------------------------- 232 | | | |SEND FAILED | | | | | | | | 233 | | | +------------+ | | | | | | | 234 | | | | | | | | | | | | 235 | | | | <----------------------------------> | | | | | 236 | | | | | ESTABLISH HTTP/HTTPS | +----+| | | | | 237 | | | | | CONNECTION | |REOPEN | | | | 238 | | | | | | |CONN&| | | | | 239 | | | | | | |UPDATE STORE | | | 240 | | | | | | |<---+| | | | | 241 | | | +------------REPEAT SEND LOOP------------------| | | | | 242 | | | +----------------------------------------------------------------------------- 243 | | | |SEND SUCCESS | | | | | | | | 244 | | | +-------------+ | | | | | | | 245 | | | | | |---+ | | | | | 246 | | | | | |POP| | | | | | 247 | | | | | |QUEUE| | | | | 248 | | | | | |<--+ | | | | | 249 | | | | | | | | | | | 250 | | | | | +----+| | | | | 251 | | | | | |SEND NEXT | | | 252 | | | | | |QUEUEED | | | | 253 | | | | | |DATA|| | | | | 254 | | | | | |<---+| | | | | 255 | | | | | | | | | | | 256 | | | +----------------------------------------------------------------------------- 257 | | | |REACHED THRESHOLD LIMIT | | | | | | | | 258 | | | +------------------------+ | | | | | | | 259 | | | | | |----+| | | | | 260 | | | | | |DELETE | | | | 261 | | | | | |STORE| | | | | 262 | | | | | |&QUEUE | | | | 263 | | | | | |<--+ | | | | | 264 | | | | |<-------| | | | | | 265 | | | | |REMOVE RESOURCE | | | | 266 | | | | +------+ | | | | | | 267 | | | | |REMOVE| | | | | | | 268 | | | | |SUBSCRIPTION | | | | | 269 | | | | |& CONNECTION | | | | | 270 | | | | |<-----+ | | | | | | 271 | | | | |-------------------------->| | | 272 | | | | | UPDATE SUBSCRIPTION | | | 273 | | | | |----------------------------------------->| | 274 | | | | | LOG REDFISH EVENT LOG | | | 275 | | | | | | | | | | | 276 | | +-------+----------------------------------------+ | | | | 277 | | | | | | | | | 278 | +--------------------------------------------------------------------------------+ 279 | | | | | | | 280+-------------------------------------------------------------------------------------------------- 281|DELETE EVENT SUBSCRIPTIONS | | | | | | 282+---------------------------+ | | | | | 283 | | | | | | | 284 +-----------------+------------------------>+ | | | | 285 | DELETE SUBSCRIPTION | | | | | 286 | | +------+ | | | | 287 | | |REMOVE| | | | | 288 | | |SUBSCRIPTION | | | 289 | | <------+ | | | | 290 | +<------------------------| | | | | 291 | | CLOSE CONNECTION | | | | | 292 | | |---------------------------> | 293 | | | UPDATE SUBSCRIPTION | | 294 | | |----------------------------------------->| 295 | | | LOG REDFISH EVENT LOG | | 296 | | | | | | | 297 298``` 299 300SSE flow diagram: 301 302```text 303+-------------+ +------------+ +-------------------------------------+ +-----------------+ 304| | | CLIENT | | BMCWEB | | EVENT LOG/ | 305| CLIENT | | LISTENERS | |RESOURCE SENDER FORMATTER MONITOR | |TELEMETRY SERVICE| 306+-----+-------+ +-----+------+ +--+--------+--------+---------+------+ +-----+-----------+ 307 | | | | | | | 308+-------------------------------------------------------------------------------------------------------- 309|SUBSCRIBE FOR EVENT| | | | | | | 310+-------------------+ | | | | | | 311 | | | | | | | 312 | | | | | | | 313 | | EVENT SUBSCRIPTION | | | | | 314 | |-------------------------| | | | | 315 | | SSE(ON ESTABLISHED CONNECTION) | | | 316 | | | | | | | 317 | | +-----+ | | | | 318 | | |KEEP | | | | | 319 | | |CONN | | | | | 320 | | |HANDLE | | | | 321 | | +<----+ | | | | 322 | | | | | | | 323 | | |---------------------------> | 324 | | | SEND SUBSCRIPTION INFO | | 325 | | | | | | | 326+----------------------------------------------------------------------------------------------------- 327|SEND EVENTS/METRICS WHEN GENERATED | | | | | | 328+-----------------------------------+ | | | | | 329 | | | | | | | 330 | | | | | | +----+ 331 | | | | | | |LOOP| 332 | | | | | | +<---+ 333 | | | | | +<------------>+ 334 | | | | | | NOTIFY EVENT/TELEMETRY 335 | | | | | | DATA | 336 | | | | | +--------------> 337 | | | | | | READ DATA | 338 | | | | | +<-------------+ 339 | | | | | | | 340 | | | | | +-----------+ | 341 | | | | | | MATCH | | 342 | | | | | |SUBSCRIPTION | 343 | | | | | |WITH DATA | | 344 | | | | | +-----------+ | 345 | +-----+--------------------------------------------------------------------------+ 346 | |LOOP | | | | +<--------+ | | 347 | +-----+ | | | | SUBSCRIPTION | | 348 | | | | | | AND DATA | | 349 | | | | | | | | | 350 | | | | +<-------+ | | | 351 | | | | |SUBSCRIPTION AND | | | 352 | | | | |FORMATTED DATA | | | 353 | | | | | | | | | 354 | | | | +----+| | | | | 355 | | | | |PUSH QUEUE | | | 356 | | | | |INCOMING| | | | 357 | | | | |DATA | | | | | 358 | | | | |<---+| | | | | 359 | | | | | | | | | 360 | | +------+-----------------------------------------+ | | | | 361 | | |RETRY ||<---------------------------------+ | | | | | 362 | | |LOOP || SEND FORMATTED DATA | | | | | | | 363 | | |+-----+| | | | | | | | 364 | | |+------------------------------------------------------------------------------- 365 | | ||SEND FAILED | | | | | | | | 366 | | |+------------+ | | | | | | | 367 | | || | | | | | | | | 368 | | |+-------------REPEAT SEND LOOP------------------| | | | | 369 | | | | | | | | | | | 370 | | |+------------------------------------------------------------------------------- 371 | | ||SEND SUCCESS | | | | | | | | 372 | | |+-------------+ | | | | | | | 373 | | | | | |---+ | | | | | 374 | | | | | |POP| | | | | | 375 | | | | | |QUEUE| | | | | 376 | | | | | |<--+ | | | | | 377 | | | | | +----+| | | | | 378 | | | | | |SEND NEXT | | | 379 | | | | | |QUEUEED | | | | 380 | | | | | |DATA ON | | | | 381 | | | | | |<---+| | | | | 382 | | | | | | | | | | | 383 | | |+------------------------------------------------------------------------------- 384 | | ||REACHED THRESHOLD LIMIT | | | | | | | | 385 | | |+------------------------+ | | | | | | | 386 | | | | | |----+| | | | | 387 | | | | | |DELETE | | | | 388 | | | | | |STORE| | | | | 389 | | | | | |& QUEUE | | | | 390 | | | | | |<---+| | | | | 391 | | | | |<-------| | | | | | 392 | | | | |REMOVE RESOURCE | | | | 393 | | | | +------+ | | | | | | 394 | | | | |REMOVE| | | | | | | 395 | | | | |SUBSCRIPTION | | | | | 396 | | | | |& CONNECTION | | | | | 397 | | | | |<-----+ | | | | | | 398 | | | | |-------------------------->| | | 399 | | | | | UPDATE SUBSCRIPTION | | | 400 | | | | |----------------------------------------->| | 401 | | | | | LOG REDFISH EVENT LOG | | | 402 | | | | | | | | | | | 403 | | +-------+----------------------------------------+ | | | | 404 | | | | | | | | | 405 | +--------------------------------------------------------------------------------+ 406 | | | | | | | 407+-------------------------------------------------------------------------------------------------- 408|DELETE EVENT SUBSCRIPTIONS | | | | | | 409+---------------------------+ | | | | | 410 | | | | | | | 411 +-----------------+------------------------>+ | | | | 412 | DELETE SUBSCRIPTION | | | | | 413 | | +------+ | | | | 414 | | |REMOVE| | | | | 415 | | |SUBSCRIPTION | | | 416 | | <------+ | | | | 417 | +<------------------------| | | | | 418 | | CLOSE CONNECTION | | | | | 419 | | |---------------------------> | 420 | | | UPDATE SUBSCRIPTION | | 421 | | |----------------------------------------->| 422 | | | LOG REDFISH EVENT LOG | | 423 | | | | | | | 424+-------------------------------------------------------------------------------------------------- 425|CLIENT CLOSE CONNECTION | | | | | | 426+------------------------+ | | | | | 427 | | | | | | | 428 | | CLIENT CLOSED | | | | | 429 | |------------------------>| | | | | 430 | | +-------+| | | | 431 | | |REMOVE || | | | 432 | | |SUBSCRIPTION | | | 433 | | +<------+| | | | 434 | | |---------------------------> | 435 | | | UPDATE SUBSCRIPTION | | 436 | | |----------------------------------------->| 437 | | | LOG REDFISH EVENT LOG | | 438 | | | | | | | 439 v v v v v v v 440``` 441 442EventService design includes below major blocks. 443 4441. Redfish resources (Schema based) 445 1. EventService 446 2. Subscription Collections (EventDestination collection) 447 3. Subscriptions (EventDestination) 4482. Event Service Manager 449 1. Event log monitor 450 2. Event log formatter 451 3. MetricReport monitor/agent 452 4. MetricReport formatter 453 5. Event service Sender (Common) 4543. EventService config store ( Persistent) 455 456This document also covers the description of below modules. 457 4581. Server-Sent Event(SSE): It covers details on what is SSE and how connection 459 open, close are handled in different cases. 4602. Push style events(HTTP/HTTPS): It covers how to subscribe for Push style 461 events and how the http/https connections are handled in bmcweb. 4623. SubmitTestEvent: Details on submit test event action. 463 464This document doesn't cover below component design. 465 4661. Redfish Event Logs: This is existing implementation. In OpenBMC, All events 467 will be logged to Journal control logs and RSyslog service, monitors event 468 logs associated with "REDFISH_MESSAGE_ID" and write the required information 469 to "/var/log/redfish" for persisting the event logs. 470 471 So EventService design is hooked to Redfish Event Logs majorly for below two 472 reasons. 473 - Get the notification whenever new event is logged to Redfish event Logs. 474 - Way to read the Redfish event log information. 475 476 This document covers one example Redfish Event Log implementation covered 477 under below design. As part of it, it uses inotify for getting notification 478 about new event log and read the log information by accessing the redfish 479 event log file. 480 481 Refer below link for more information on same. 482 [Redfish Logging](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md) 483 484 If other OEM's has different implementation for Redfish EventLogs, they can 485 satisfy above mentioned two requirement and can hook it to EventService 486 design specified here. For example, If xyz OEM uses D-Bus based Redfish Event 487 logs, They can use 'signal' for notifying the new redfish event log and event 488 log information. They can replace 'inotify' with 'signal' and hook their OEM 489 specific Redfish event log to this Redfish EventService design. 490 4912. Telemetry service: Redfish telemetry service is used to gather all the 492 metrics reports associated with different resources such as Power metrics, 493 thermal metrics, memory metrics, processor metrics etc... Monitoring service 494 in telemetry supports different modes along with aggregated 495 operations(Single, average, max, min, sum etc..). 496 497 Refer below link for design document of telemetry service. 498 [Telemetry Service](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/) 499 500### Redfish resource schema's 501 502Redfish will have three major resources to support EventService. 503 5041. Event Service 5052. Subscription Collections 5063. Subscriptions 507 508All the configuration and subscriptions information data will be cached on 509bmcweb webserver and synced with config json file for restoring and persisting 510the data. 511 512**EventService** Contains the attributes of the service such as Service Enabled, 513status, delivery retry attempts, Event Types, Subscriptions, Actions URI etc. 514 515- URI : `/redfish/v1/EventService` 516- SCHEMA : 517 [EventService](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml) 518- METHODS : `GET, PATCH` 519 520Refer Testing for supported properties and example. 521 522**Subscription Collections** This resource is used to get collection of all 523subscriptions and also used to configure the new subscriptions for automatic 524events. 525 526- URI : `/redfish/v1/EventService/Subscriptions` 527- SCHEMA : 528 [EventDestinationCollection](https://redfish.dmtf.org/schemas/v1/EventDestinationCollection_v1.xml) 529- METHODS : `GET, POST` 530 531Refer Testing section for example. 532 533**Subscriptions** This resource contains the subscription details. Used to get 534each individual get subscription information, update & Delete existing 535subscription information. 536 537- URI : `/redfish/v1/EventService/Subscriptions/<ID>` 538- SCHEMA : 539 [EventDestination](https://redfish.dmtf.org/schemas/v1/EventDestination_v1.xml) 540- METHODS : `GET, PATCH, DELETE` 541 542Refer Testing section for supported properties and example. 543 544### Event service manager 545 546Event Manager is main block which does monitor the events, format the request 547body and send it to the subscribed destinations. It shall support for two types 548of event formats which are define in redfish specification. 549 5501. Event: Resource type 'Event' is used to receive alerts in the form of json 551 body to subscribed clients when the subscription details matches for those 552 event logs. 553 5542. MetricReport: It is used to receive alerts in the forms of json body to 555 subscribed clients when the subscription details matches for the collected 556 telemetry data by telemetry service. 557 558The "Event service sender" is common entity for both type of resources. The 559formatter and monitor entities are different for each type of resources. 560 561#### Event log monitor 562 563In OpenBMC, all the redfish event logs are currently logged to persistent area 564of BMC filesystem("/var/log/redfish"). The "Event log monitor" service under 565"Event service manager" will use **inotify** to watch on redfish event log file 566to identify the new events. Once it identifies the new events, it will read all 567logged events information from redfish event file and pass it to 'Event log 568formatter' for further processing. The last processed event data timestamp will 569be cached in bmcweb to identify the new events in redfish event log file. 570 571It monitors the live events for sending asynchronously and does not send the 572events logged before bmcweb service start. 573 574#### Event log formatter 575 576It is used to format the request body by reading event logs passed from 'Event 577log monitor' and filter the data by reading subscription information. It will 578fetch all the subscription information from "Redfish event service store" and 579filter the events by checking severity, event type against the user subscribed 580information. It formats the http "request body" along with CustomText, 581HttpHeaders and send the Events over network using http protocol for the 582filtered subscribers. 583 584Refer Tested section for example request body. 585 586#### MetricReport monitor 587 588Telemetry monitoring service ( Not covered in this document) is responsible for 589gathering metrics from D-Bus sensors and exposing them as D-Bus objects. 590Monitoring service supports different monitoring modes (periodic, on change and 591on demand) along with aggregated operations such as single, average, max min, 592sum etc... This service periodically collects the metrics report depending on 593Telemetry service configuration such as 'Metric Definitions', 'Metric Report 594Definitions' and 'Metric Triggers'. 595 596The telemetry monitor shall emit a signal when there is a collection of report. 597MetricReport monitor/agent shall implement the listener for telemetry signal and 598using the subscription information, it should match, filter the desired metric 599report to pass it on to 'MetricReport formatter'. Since 'MetricReport monitor' 600is tightly coupled with 'Telemetry monitor' which already does the monitoring 601loop, its responsibility of 'Telemetry monitor' to match the subscriptions rules 602and provide it to MetricReport formatter. The EventService should provide a way 603to communicate the subscriptions data whenever user creates or updates or delete 604subscription. 605 606#### MetricReport formatter 607 608The 'MetricReport formatter' is responsible for formatting the data which comes 609from 'MetricReport monitor/agent' by checking subscriptions information such as 610HttpHeaders, Custom text strings along with Telemetry report data. 611 612#### Event service sender 613 614The "Event service sender" is used to send the formatted request body which is 615passed from 'Event log formatter' or 'Telemetry formatter' to all filtered 616subscribers. It supports sending both https and http requests by using beast 617library. The http/https connections handling (open/close) differs for both 618subscription types such as 'Push style events' and 'SSE' and more detailed are 619covered in respective sections. 620 621Beast is a C++ header-only library serving as a foundation for writing 622interoperable networking libraries by providing low-level HTTP/1, WebSocket, and 623networking protocol vocabulary types and algorithms using the consistent 624asynchronous model of Boost.Asio. For more information on beast, refer 625[Beast](https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/introduction.html) 626 6271. PUSH style eventing: BMC uses the boost::beast for asynchronously sending 628 events to the subscribed clients. Here is the Beast client Examples for 629 sending the synchronous and asynchronous requests over encrypted and 630 un-encrypted channels. 631 [Beast Async](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async/) 632 [Beast AsyncSSL](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async-ssl/) 633 6342. Server-Sent Events (SSE): The EventDestination resource of the subscription 635 data shall contains the opaque of opened client SSE stream connection. After 636 receiving the formatted event associated with specific subscription 637 information, EventSender writes the formatted event data on open SSE 638 connection with specific ID so that client can receive the event. 639 640In case of push style eventing, https connection will be established during 641first event. If the connection is already established with subscription ID, then 642it uses same connection handle for sending events. This connection handle and 643subscription map will be stored in event service sender. Users can have multiple 644subscriptions coming from single destination and BMC will have separate 645connection handle associated with each subscription. Event listeners (web 646servers) has capability to accept multiple connections from same client(BMC) and 647depending on routing rules, the received events will be parsed on event listener 648side. 649 650In case of SSE, connection handle will be read from resource and used by sender 651for sending events. 652 653Received formatted data will be pushed to queue maintained under sender, against 654the connection-subscription map. Upon successful sending of event data, 655formatted data entry will be pop-ed from queue and next formatted data will be 656attempted for send and so on. 657 658If send event(logs or metric reports) fails, then it will retry for number of 659attempts configured in Event Service "DeliveryRetryAttempts" with an interval of 660"DeliveryRetryIntervalSeconds". In case of Push Style Events if send fails due 661to some reasons, https connection will be re-established and first send will be 662re-attempted. If the failure persist even after the configured retry attempts, 663subscription information will be deleted and same will be updated to 664consumers(Telemetry service or event log service). In SSE connection, bmcweb 665would only retry sending events in the case of network 666failure/timeout/congestion. If there is error like connreset/badf, bmcweb will 667delete the subscription as specified above. In such scenario's, user can 668re-subscribe for events. This is requirement as per current redfish 669specification. 670 671Any temporary network failure during event notification, and the failure persist 672till threshold limit, subscription entry will be remove. This may be security 673concern as client may not know about subscription termination, once network 674comes back. Note: Redfish specification says, Event destination subscription 675should be terminated after reaching threshold limit. This is known security 676concern. TBD: Need to work with Redfish forum for resolution. 677 678### Redfish event service store 679 680Redfish event service store is used to store the all configuration related to 681EventService and subscriptions information. This does below operations: 682 683- During bmcweb service start, it gets all the configuration and subscriptions 684 information from config json file and populates the internal structures data. 685 686- Redfish EventService resources will get/update this event store for any user 687 activities via redfish(Like Get/Add/Update/Delete subscriptions etc.) 688 689- It will sync the "event config store" with configuration Json file for 690 persisting the information when there is update. **Note**: Configuration json 691 file will be updated only for Push style event subscription information. SSE 692 events subscription information is volatile and will not get updated to json 693 file. 694 695- It will be used for getting all the subscription information to the "Event 696 service manager" for filtering event data. 697 698The bmcweb service will update the config store data including EventService 699configuration and subscription information to the json file(location: 700/var/lib/bmcweb/eventservice_data.json). This will be persistent across the 701bmcweb service restarts or bmc reboots and loads this while initializing bmcweb 702EventService class. 703 704Note: 705 7061. In case of SSE, Client is initiator of connection and so SSE stream 707 connection can't be re-established when bmcweb service or BMC goes for 708 reboot. Hence subscription information related to SSE will not be persistent 709 and Client must re-subscribe for SSE events using "ServerSentEventUri", 710 whenever bmc comes out of reset. 711 712 Limitation: If bmcweb server closes abruptly due to some reasons like 713 watchdog trigger, then bmcweb can't send close connection event to SSE 714 client(For notifying SSE client to re-establishing connection). 715 716Cache implementation includes below major blocks: 717 718- EventServiceStore Class: It holds the map of all subscriptions with unique key 719 and methods to Create/Delete/update subscription information. It also holds 720 the high level configuration information associated with EventService schema. 721 722- Configuration structure: It holds the configuration associated with 723 EventService schema properties. 724 725- Subscription structure: It holds the data associated with each 726 EventDestination schema properties along with established connection handle. 727 728### Server-Sent Events (SSE) 729 730Server-Sent Events (SSE) is a server push technology enabling a browser to 731receive automatic updates from a server via HTTP connection. The Server-Sent 732Events EventSource API is standardized as part of HTML5 by the W3C. 733 734Server-Sent Events is a standard describing how servers can initiate data 735transmission towards clients once an initial client connection has been 736established. They are commonly used to send message updates or continuous data 737streams to a browser client and designed to enhance native, cross-browser 738streaming through a JavaScript API called EventSource, through which a client 739requests a particular URL in order to receive an event stream. 740 741The "EventService" resource contains a property called "ServerSentEventUri". If 742a client performs a GET on the URI specified by the "ServerSentEventUri", the 743bmcweb server keep the connection open and conform to the HTML5 Specification 744until the client closes the socket. The bmcweb service should sent the response 745to GET URI with following headers. 746 747```text 748'Content-Type': 'text/event-stream', 749'Cache-Control': 'no-cache', 750'Connection': 'keep-alive' 751``` 752 753Events generated by the OpenBMC will be sent to the clients using the open 754connection. Response of event message should contain the "data: " prefix and 755postfix "\n" on each line. For representing the end of data, it should end with 756"\n\n". Example sending json response should look like 757 758```text 759data: {\n 760data: "msg": "hello world",\n 761data: "id": 12345\n 762data: }\n\n 763``` 764 765Open connection: When a client performs get on 'ServerSentEventUri' with desired 766filters, bmcweb create an EventDestination instance in the subscriptions 767collection. Once bmcweb receives the SSE stream request, the open connection 768will be upgraded to WebSocket by checking the request Content-Type 769header(matches to 'text/event-stream') and keep the connection alive till the 770client/server closes the connection. Please refer to 771[code review](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/13948/) for 772details on how to upgrade the connection for SSE. The "Context" property in the 773EventDestination resource shall be an opaque string generated by the service. 774 775Note: since its GET operation on existing open connection(which is authenticated 776and authorized as normal operation), there is no special security breach with 777it. All bmcweb related security threat model applies here. 778 779Close connection: Either the client or the server can terminate the event stream 780at any time and close the connection. The bmcweb server can delete the 781corresponding EventDestination instance when the connection is closed. 782 783Connection can be closed by, 784 785- Client by sending DELETE method on subscribed id URI. 786- Server(bmcweb) can close connection and send notification to client with 787 'event: close' request body. 788 789Since SSE is uni-directional, if client closes connection/browser abruptly, 790bmcweb service doesn't know the client connection state. This is limitation on 791SSE connection. In such scenario bmcweb service may delete a subscription, if 792the number of delivery errors exceeds preconfigured thresholds. 793 794Note: 795 796- The SSE subscription data is not persistent in nature. When bmcweb restarts or 797 BMC reboots, client should re-establish the SSE connection to bmcweb to listen 798 for events. 799- In case of SSE, client can send the "Last-Event-ID" as header. Monitor service 800 will fetch all the event or metric report stream captured after that specified 801 "Last-Event-ID" and send to client after formatting. If it fails to find the 802 specified event ID, it will start streaming only live events/metric reports. 803 804The service should support using the $filter query parameter provided in the URI 805for the SSE stream by the client to reduce the amount of data returned to the 806client. 807 808Supported filters are: 809 810- RegistryPrefix 811- ResourceType 812- EventFormatType 813- MessageId 814- OriginResource 815 816Example for subscribing SSE with filters: 817 818```text 819MessageId based filter: 820METHOD: GET 821URI: https://<BMCIP>/redfish/v1/EventService/SSE?MessageId='Alert.1.0.LanDisconnect' 822 823RegistryPrefix based filter: 824https://sseuri?$filter=(RegistryPrefix eq Resource) or (RegistryPrefix eq 825Task) 826 827ResourceType based filter: 828https://sseuri?$filter=(ResourceType eq 'Power') or (ResourceType eq 829'Thermal') 830``` 831 832### Push style events (HTTP/HTTPS) 833 834Unlike the SSE (where bmcweb act as server) push style events works in different 835way. In this case, BMC acts as HTTP client and send the data to webserver 836running on external system. In case of SSE, connection will be kept alive till 837stream closes but in push style events, connections are opened on need and 838closes immediately after pushing event/report data. 839 840By using POST method on '/redfish/v1/EventService/Subscriptions' URI with 841desired request body (mandatory fields: Destination, Protocol), user can 842subscribe for the events. The monitor and formatter resources (both Event log 843and MetricReport) uses the subscribed data for match rules, when there is event 844log or Telemetry data available. The 'Event service sender' uses the destination 845field in subscribed data for opening the connection and pushing data to 846webserver running externally. 847 848It shall support both http and https (https is not defined in Redfish 849specification) connections which will be created using the boost::beast library. 850For https connection it uses the self-signed certificates which are loaded in 851certificate store. If establishing connection fails, it retries for configured 852retry attempts (DeliveryRetryAttempts) and delete the subscription if it reaches 853threshold limit. If SSL negotiation fails, it will not retry for connection 854establishment. Users can upload new certificates. More details about certificate 855can be found at 856[TLS design](https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md) 857 858Example for created Push style event is documented in testing section of same 859document. 860 861### SubmitTestEvent 862 863This action shall add a test event to the event service with the event data 864specified in the action parameters. This message should then be sent to any all 865subscribed Listener destination targets depending on subscription data. 866 867- URI: `/redfish/v1/EventService/Actions/EventService.SubmitTestEvent` 868- SCHEMA: 869 [EventService](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml) 870- METHODS : `POST` 871 872Note: EventService.v1_3_0 was updated to deprecate the EventType parameter in 873SubmitTestEvent, and add the EventGroupId parameter in SubmitTestEvent. 874 875Example POST Request body: 876 877```json 878{ 879 "Message": "Test Event for validation", 880 "MessageArgs": [], 881 "EventId": "OpenBMC.0.1.TestEvent", 882 "EventGroupId": "", 883 "Severity": "OK" 884} 885``` 886 887## Alternatives considered 888 889### HTTP POLLING 890 891Polling is a traditional technique where client repeatedly polls a server for 892data. The client makes a request and waits for the server to respond with data. 893BMC provides a way to pool the event logs (using Events schema). Client can run 894continuously http GET on Events LogService and get the all the events from BMC. 895But in HTTP protocol fetching data revolves around request/response which is 896greater HTTP overhead. 897 898Push style(https) eventing or SSE will avoid the http overhead of continuous 899polling and send the data/events when it happens on server side to the 900subscribed clients. 901 902### WEBSOCKET 903 904WebSocket provides a richer protocol to perform bi-directional, full-duplex 905communication. Having a two-way channel is more attractive for some case but in 906some scenarios data doesn't need to be sent from the client(Client just need 907updates from server errors/events when it happens.) 908 909SSE provides uni-directional connection and operates over traditional HTTP. SSE 910do not require a special protocol or server implementation to get working. 911WebSocket on the other hand, require full-duplex connections and new Web Socket 912servers to handle the protocol. 913 914### IPMI PEF 915 916Platform Event Filtering (PEF) provides a mechanism for configuring the BMC to 917take selected actions on event messages that it receives. This mechanism is IPMI 918centric which has its own limitation in terms of security, scalability etc. when 919compared with Redfish. 920 921## Implementation design alternatives 922 923- Direct journal logs vs Redfish event log file using inotify 924 925Considered reading direct journald logs using `sd*journal*<xyz>` api's but that 926seems to be in-efficient because 927 9281. sdjournal has multiple logs currently( not just event logs) and so this 929 become very inefficient to monitor and process data to identify just for 930 redfish event logs. 931 9322. Some hooks need to be added to sdjournal to emit signals whenever messages 933 are logged to sdjournal. 934 935To overcome above challenges currently redfish event logs are filtered and 936logged to separate file using rsyslog. Same file is used by EventService by 937monitor the file using inotify. 938 939- D-Bus service vs Event Service config store 940 941Considered creating separate D-Bus service for storing EventService 942configuration and subscriptions data. Also considered using settings D-Bus 943service for persisting the data across the reboots. But since EventService is 944specific to redfish/bmcweb and not consumed/updated by any other processes in 945system, there is no real gain with having D-Bus service. 946 947## Impacts 948 949Security issue with Push style events: 950 951Push style events also support HTTP protocol which is not secured and is 952susceptible to man-in-the-middle attacks and eavesdropping which may lead to 953virus injections and leak sensitive information to attackers. The push style 954event subscription or changes to the BMC will be done over the secure HTTPS 955channel with full authentication and authorization. So, BMC side security is NOT 956compromised. Event Listener on client may get hacked data in-case of 957man-in-the-middle attacks. To avoid such attacks, it is recommended to use SSE 958event mechanism or https-based push style events. 959 960SSE works on HTTPS protocol which is encrypted and secured. SSE EventService 961subscriptions can be created or updated over HTTPS protocol along with proper 962authentication and authorization on BMC users. Please refer security details 963(section 13) in DSP0266 for more information. 964 965SSE connections: 966 967When client opens the SSE HTTPS connection, it will be on open state until 968client or server closes the connection. On Linux, there is a limit on each file 969descriptor(Of course this is very huge number > 8K). Multiple open http 970connections on bmcweb can slow down the performance. 971 972Since open SSE client connection is proxied under multiple level of BMC side 973protection (like Authentication is required, User should have proper privilege 974level to establish the SSE connection etc.), these impacts are mitigated. Also 975BMC will have support for maximum of 10 SSE subscriptions which will limit the 976number of http connections exhaust scenario. This can be compile time option. 977 978## Testing 979 980User should cover below functionalists. 981 982- View and update EventService configuration using GET and PATCH methods and 983 validate the functionality. 984- Subscribe for Events (Both "Push style event" and "SSE") as described below 985 and validate http status code for positive and negative use cases (Body 986 parameter invalid, Invalid request, improper privilege - forbidden etc.). 987- Validate all subscription collections and each individual subscription. 988- Using delete method on subscription URI specific to ID and see connection 989 closing properly on client side and subscription data clear on server side. 990- Enable and disable EventService, generate events and validate whether Events 991 are sending properly to all subscriptions when its enabled and stopped sending 992 when disabled. 993- Use SubmitTestEvent for generating Test Events. Also cover negative cases with 994 invalid body data. 995- Validate the functionality of retry attempts and retry timeout with both 996 positive and negative cases. 997- Client connection close: Close client connection which are listening for SSE 998 and check server-side connection closes after configured retry attempts and 999 clears the subscription information. 1000- Reboot BMC or reset bmcweb service and check all "push style events" 1001 subscription is preserved and functional by generating and checking events. 1002- Reboot BMC or reset bmcweb service and check all "SSE" subscription data is 1003 not preserved and client-side connection is closed properly. 1004- Create user with multiple privileges and check create/delete/update 1005 subscription and configuration data are performed only for user having 1006 'ConfiguredManager' privilege and view EventService information works only for 1007 'Login'. 1008- Create new subscription and check is the event message logged in redfish event 1009 logs or not. Also modify, delete subscription and see Redfish events are 1010 logged or not. 1011- Validate the authenticity of events sent to client on subscription with proper 1012 filtered data(Ex: If RegisteryPrefixes is set to "OpenBMC.0.1", it should not 1013 send events with prefixes "OpenBMC.0.2") should be validated. 1014- For security, validate GET on URI specified in "ServerSentEventUri" with 1015 un-authorized users and see it responds with properly http status code and 1016 should not create any subscription or open any http connection. 1017- Max limit check: Creates max supported event subscriptions and validate. 1018 1019### Push style events 1020 10211. EventListner: Client should configure the web service for listening the 1022 events (Example: `http://192.168.1.2/Events`). 1023 10242. Subscription: Client can subscribe for events on BMC using below 1025 1026 ```text 1027 URI: /redfish/v1/EventService/Subscriptions 1028 METHOD: POST 1029 REQUEST BODY: 1030 { 1031 "Destination":"http://192.168.1.2/Events", 1032 "Context":"CustomText", 1033 "Protocol":"Redfish", 1034 } 1035 ``` 1036 1037 On successful event subscription client will receive 201(Created) http status 1038 code along with created subscription ID. At this point onwards, client will 1039 receive events associated with subscribed data. 1040 1041 Client can use "SubmitTestEvent" (Documented above) to test the working 1042 state. 1043 10443. ViewSubscription: Client can get the subscriptions details using 1045 1046 ```text 1047 URI: /redfish/v1/EventService/Subscriptions/<ID> 1048 METHOD: GET 1049 ``` 1050 10514. UpdateSubscription: At any point client can update the subscription 1052 information. 1053 1054 ```text 1055 URI: /redfish/v1/EventService/Subscriptions/<ID> 1056 METHOD: PATCH 1057 REQUEST BODY: 1058 { 1059 "Destination":"http://192.168.1.2/Events", 1060 "Context":"Changed Custom Text", 1061 "RegistryPrefix": "OpenBMC.0.2" 1062 } 1063 ``` 1064 10655. DeleteSubscription: Client can unsubscribe and stop receiving events by 1066 deleting the subscription. 1067 1068 ```text 1069 URI: /redfish/v1/EventService/Subscriptions/<ID> 1070 METHOD: DELETE 1071 ``` 1072 1073### Server-Sent events subscription 1074 10751. EventListner and Subscription: Client can open latest browser (chrome) and 1076 fire GET URI on "ServerSentEventUri" along with filters. 1077 1078 ```text 1079 URI: /redfish/v1/EventService/SSE?RegistryPrefix='OpenBMC.0.2'&MessageId='OpenBMC.0.2.xyz" 1080 METHOD: GET 1081 ``` 1082 1083 On successful event subscription client will receive 200(Created) http status 1084 code, subscription id along with below response headers for streaming. 1085 1086 ```text 1087 'Content-Type': 'text/event-stream', 1088 'Cache-Control': 'no-cache', 1089 'Connection': 'keep-alive' 1090 ``` 1091 1092 At this point onwards, client browser will receive events associated with 1093 subscribed data. 1094 1095 Client can use "SubmitTestEvent" (Documented above) to test the working 1096 state. 1097 10982. ViewSubscription: Client can get the subscriptions details using 1099 1100 ```text 1101 URI: /redfish/v1/EventService/Subscriptions/<ID> 1102 METHOD: GET 1103 ``` 1104 11053. UpdateSubscription: At any point client can update the subscription 1106 information. Note Client can't change the destination as that is opaque 1107 associated with opened SSE connection. 1108 1109 ```text 1110 URI: /redfish/v1/EventService/Subscriptions/<ID> 1111 METHOD: PATCH 1112 REQUEST BODY: 1113 { 1114 "Context":"Changed Custom Text", 1115 "RegistryPrefix": "OpenBMC.0.2" 1116 } 1117 ``` 1118 11194. DeleteSubscription: There are two ways to close the connection from client. 1120 - Client can close the browser directly which will close the SSE http 1121 connection and so bmcweb service can close and delete the subscription 1122 data. 1123 - Client can also unsubscribe and stop receiving events by deleting the 1124 subscription. 1125 1126 ```text 1127 URI: /redfish/v1/EventService/Subscriptions/<ID> 1128 METHOD: DELETE 1129 ``` 1130 1131### EventListner 1132 1133Push style Events: 1134 1135To listen the push style events, client can have web server running on any 1136external system and subscribe to BMC with the subscription details along with 1137destination URI. 1138 1139There are multiple EventListners exist and here is simple node js server, which 1140can be run using "node server.js". 1141 1142```js 1143// server.js 1144const http = require("http"); 1145var displayResponse; 1146 1147http 1148 .createServer((request, response) => { 1149 console.log("Requested url: " + request.url); 1150 const { headers, method, url } = request; 1151 1152 if (method.toLowerCase() == "post" && url.toLowerCase() === "/events") { 1153 let body = []; 1154 request 1155 .on("error", (err) => { 1156 console.error(err); 1157 }) 1158 .on("data", (chunk) => { 1159 body.push(chunk); 1160 }) 1161 .on("end", () => { 1162 body = Buffer.concat(body).toString(); 1163 1164 console.log(body); 1165 displayResponse.write(body); 1166 displayResponse.write("\n\n"); 1167 1168 response.statusCode = 200; 1169 response.end(); 1170 }); 1171 } else if ( 1172 method.toLowerCase() == "get" && 1173 url.toLowerCase() === "/display_events" 1174 ) { 1175 response.writeHead(200, { 1176 Connection: "keep-alive", 1177 "Content-Type": "text/event-stream", 1178 "Cache-Control": "no-cache", 1179 "Access-Control-Allow-Origin": "*", 1180 }); 1181 1182 displayResponse = response; 1183 } else { 1184 response.writeHead(404); 1185 response.end(); 1186 } 1187 }) 1188 .listen(5000, () => { 1189 console.log( 1190 "Use 'http://<IP>:5000/events' as destination to subscribe for BMC events", 1191 ); 1192 console.log("Open 'http://<IP>:5000/display_events' URL on browser\n"); 1193 }); 1194``` 1195 1196Server-Sent Events (SSE): 1197 1198Client can open an SSE connection to the service by performing a GET on the URI 1199specified by the "ServerSentEventUri" in the Event Service along with filters. 1200Browser automatically prompt for credentials and upon successful completion of 1201authentication and authorization, client connection will be established for 1202listening events. 1203 1204You can also refer below link for details on Server-Sent events. 1205<https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events> 1206 1207Another simple python script for testing SSE using EventSource. Run it using 1208"python sse-client.py". 1209 1210```python 1211// sse-client.py 1212import requests, json, sys, time, re, os 1213import sseclient 1214from requests.packages.urllib3.exceptions import InsecureRequestWarning 1215requests.packages.urllib3.disable_warnings(InsecureRequestWarning) 1216from sseclient import SSEClient 1217 1218try: 1219 bmc_ip = sys.argv[1] 1220 username = sys.argv[2] 1221 password = sys.argv[3] 1222 1223except: 1224 print "FAIL: Usage: <ScriptName> <BMC_IP> <Username> <Password>" 1225 print "Example: python sseClient.py 10.223.244.145 root root\n" 1226 sys.exit() 1227 1228 1229url = 'https://%s/redfish/v1/EventService/SSE?<filters>' %bmc_ip 1230 1231try: 1232 messages = SSEClient(url, verify=False, auth=(username, password)) 1233 1234 for msg in messages: 1235 print(json.dumps(msg.data)) 1236 1237except Exception as exc: 1238 print("\nERROR: Error in subscribing the SSE events\n") 1239``` 1240 1241#### EventService 1242 1243Supported properties: 1244 1245| PROPERTY NAME | TYPE | DESCRIPTION | 1246| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 1247| ServiceEnabled | Boolean | This indicates whether event service is enabled. Default: True | 1248| DeliveryRetryAttempts | Integer | This is the number of attempts an event posting is retried before the subscription is terminated. Default: 3 | 1249| DeliveryRetryIntervalSeconds | Integer | This represents the number of seconds between retry attempts for sending any given Event. Default: 30 | 1250| EventFormatTypes | Array(string) | Indicates the content types of the message that this service can send to the event destination. **Event:** Resource types of 'Event' sent to subscribed destination. This is default value if nothing is specified. **MetricReport:** Resource types of 'MetricReport' only sent to subscribed destination. | 1251| RegistryPrefixes | Array(string) | A list of the Prefixes of the Message Registries that can be used for the RegistryPrefix property on a subscription. If this property is absent or contains an empty array, the service does not support RegistryPrefix-based subscriptions. | 1252| ResourceTypes | Array(string) | A list of the Prefixes of the message registries that can be used for the RegistryPrefix property on a subscription. If this property is absent or contains an empty array, the service does not support RegistryPrefix-based subscriptions | 1253| ServerSentEventUri | String | The value of this property shall be a URI that specifies an HTML5 Server-Sent Event conformant endpoint. URI: /redfish/v1/EventService/SSE | 1254| Subscriptions | Object | The value of this property shall contain the link to a collection of type EventDestinationCollection. | 1255| Actions | Object | This action shall add a test event to the event service with the event data specified in the action parameters. More details on TestEvents captured below. | 1256 1257Note: EventService.v1_3_0 was created to deprecate the EventTypesForSubscription 1258and SSEFilterPropertiesSupported\EventType properties. 1259 1260Example GET Response: 1261 1262```json 1263{ 1264 "@odata.context": "/redfish/v1/$metadata#EventService.EventService", 1265 "@odata.id": "/redfish/v1/EventService", 1266 "@odata.type": "#EventService.v1_3_0.EventService", 1267 "Actions": { 1268 "#EventService.SubmitTestEvent": { 1269 "target": "/redfish/v1/EventService/Actions/EventService.SubmitTestEvent" 1270 } 1271 }, 1272 "DeliveryRetryAttempts": 3, 1273 "DeliveryRetryIntervalSeconds": 30, 1274 "EventFormatTypes": ["Event"], 1275 "Id": "EventService", 1276 "Name": "Event Service", 1277 "RegistryPrefixes": ["Base", "OpenBMC"], 1278 "ServerSentEventUri": "/redfish/v1/EventService/SSE", 1279 "ServiceEnabled": true, 1280 "Subscriptions": { 1281 "@odata.id": "/redfish/v1/EventService/Subscriptions" 1282 } 1283} 1284``` 1285 1286#### Subscription Collections 1287 1288Example GET output: 1289 1290```json 1291{ 1292 "@odata.type":"#EventDestinationCollection.EventDestinationCollection", 1293 "@odata.context":"/redfish/v1/$metadata#EventDestinationCollection.EventDestinationCollection", 1294 "@odata.id":"/redfish/v1/EventService/Subscriptions" 1295 "Id":"Event Subscription Collection", 1296 "Name":"Event Subscriptions Collection", 1297 "Members@odata.count": 2, 1298 "Members": [ 1299 { 1300 "@odata.id":"/redfish/v1/EventService/Subscriptions/1", 1301 "@odata.id":"/redfish/v1/EventService/Subscriptions/2" 1302 } 1303 ], 1304} 1305``` 1306 1307#### Subscriptions 1308 1309Supported properties: 1310 1311| PROPERTY NAME | TYPE | DESCRIPTION | 1312| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | 1313| Destination | String | The URI of the destination Event Service. | 1314| Context | String | A client-supplied string that is stored with the event destination subscription. Default: null | 1315| Protocol | Enum | The protocol type of the event connection. Default: redfish | 1316| HttpHeaders | array(string) | This is for setting HTTP headers, such as authorization information. Default: null | 1317| RegistryPrefixes | String | A list of the Prefixes for the Message Registries that contain the MessageIds that will be sent to this event destination. Default: null | 1318| ResourceTypes | Array(String) | A list of Resource Type values (Schema names) that correspond to the OriginOfCondition. The version and full namespace should not be specified. Default: null | 1319| EventFormatType | String | Indicates the content types of the message that will be sent to the EventDestination. Supported types are 'Event' and 'MetricReport'. Default: Event | 1320 1321Example GET Request: 1322 1323```json 1324{ 1325 "@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination", 1326 "@odata.id": "/redfish/v1/EventService/Subscriptions/1", 1327 "@odata.type": "#EventDestination.v1_5_0.EventDestination", 1328 "Context": "143TestString", 1329 "Destination": "http://test3.domain.com/EventListener", 1330 "EventFormatTypes": ["Event"], 1331 "HttpHeaders": ["X-Auth-Token:XYZABCDEDF"], 1332 "Id": "1", 1333 "MessageIds": ["InventoryAdded", "InventoryRemoved"], 1334 "Name": "EventSubscription 1", 1335 "Protocol": "Redfish", 1336 "RegistryPrefixes": ["Base", "OpenBMC"], 1337 "SubscriptionType": "Event" 1338} 1339``` 1340 1341- Event log formatted response body looks like: 1342 1343```text 1344id: 1 1345data:{ 1346data: "@odata.type": "#Event.v1_1_0.Event", 1347data: "Id": "1", 1348data: "Name": "Event Array", 1349data: "Context": "ABCDEFGH", 1350data: "Events": [ 1351data: { 1352data: "Created": "2019-08-13T06:25:31+00:00", 1353data: "EntryType": "Event", 1354data: "Id": "1565677531", 1355data: "Message": "F1UL16RISER3 Board with serial number BQWK64100593 was installed.", 1356data: "MessageArgs": [ 1357data: "F1UL16RISER3", 1358data: "Board", 1359data: "BQWK64100593" 1360data: ], 1361data: "MessageId": "OpenBMC.0.1.InventoryAdded", 1362data: "Name": "System Event Log Entry", 1363data: "Severity": "OK" 1364data: "Context": "ABCDEFGH" 1365data: } 1366data: ] 1367data:} 1368``` 1369 1370- Configuration structure pseudo code: 1371 1372```cpp 1373struct EventSrvConfig 1374{ 1375 bool enabled; 1376 uint32_t retryAttempts; 1377 uint32_t retryTimeoutInterval; 1378}; 1379``` 1380 1381- Subscription structure pseudo code: 1382 1383```cpp 1384struct EventSrvSubscription 1385{ 1386 std::string destinationUri; 1387 std::string customText; 1388 std::string subscriptionType; 1389 std::string protocol; 1390 std::vector<std::string> httpHeaders; // key-value pair 1391 std::vector<std::string> registryMsgIds; 1392 std::vector<std::string> registryPrefixes; 1393 std::vector<std::string> eventFormatTypes; 1394}; 1395``` 1396