issue链接
背景
redfish协议中EventDestination资源(/redfish/v1/EventService/Subscriptions)支持redfish、snmp、syslog、smtp四种协议类型事件订阅资源的创建、查询、修改、删除功能。而openUBMC目前仅实现了redfish事件订阅相应的能力，其他能力均由Oem资源承载。
同时，有客户对事件订阅功能提出诉求，需要实现协议中EventDestination资源关于snmp协议事件订阅的相关能力。
现状
-
redfish将各种协议的事件订阅均设定为EventDestination资源，附属于同一集合资源下，且各资源之间互相独立。典型操作为资源的创建与删除，当前openUBMC的redfish事件订阅为该模式。
-
openUBMC事件上报相关OEM资源（例如SyslogService、SnmpService、SmtpService）中，部分资源中包含事件订阅功能（例如SnmpService不仅包含snmp agent管理能力，还包含snmp trap管理能力），此类资源创建多个事件订阅时，多个事件订阅共享一部分公共属性，且无论是否已创建事件订阅，资源中均能查询到4个订阅服务器（默认不使能）。典型操作为使能的开启与关闭与属性的修改，当前openUBMC的snmp trap功能为该模式。
因此，实现EventDestination资源支持snmp trap上报不能复用原有OEM资源中的事件订阅功能，否则会导致创建事件订阅时，造成原有资源的变更。
总体策略：单独维护EventDestination标准snmp事件订阅，标准事件订阅与OEM事件订阅隔离
EventDestination标准snmp事件订阅：由redfish官方规定的满足EventDestination资源能力的snmp事件订阅实例，通过EventDestination资源进行创建与维护。简称为标准snmp事件订阅或标准事件订阅
OEM类型snmp事件订阅：由openUBMC自定义的snmp事件订阅实例，主要通过OEM资源SnmpService进行维护。简称为OEM snmp事件订阅或OEM事件订阅
单独维护EventDestination标准资源snmp事件订阅，该类型事件订阅最多4个。最终形成snmp trap事件订阅由4个标准事件订阅和4个OEM事件订阅组成，共计8个。标准资源由EventDestination资源维护，OEM事件订阅由OEM资源维护。
本次实现的标准资源能力对齐OEM类型snmp事件订阅，并充分考虑后续相关功能（如事件筛选、暂停上报）的扩展能力。后续标准资源会进行相关功能的扩展，OEM资源则停止演进。
决策点
决策点一：Redfish接口 | 标准snmp事件订阅接口uri
uri:/redfish/v1/EventService/Subscriptions/:id
redfish事件订阅中id为1~4，snmp trap事件订阅中，id为Snmp+数字的形式，如/redfish/v1/EventService/Subscriptions/Snmp1
后续syslog与smtp事件订阅的uri也类似于Snmp事件订阅，采用协议名+id
例如：GET /redfish/v1/EventService/Subscriptions
{
"@odata.context": "/redfish/v1/$metadata#EventDestinationCollection.EventDestinationCollection",
"@odata.type": "#EventDestinationCollection.EventDestinationCollection",
"@odata.id": "/redfish/v1/EventService/Subscriptions",
"Name": "Event Subscriptions Collection",
"Members@odata.count": 4,
"Members": [
{
"@odata.id": "/redfish/v1/EventService/Subscriptions/1"
},
{
"@odata.id": "/redfish/v1/EventService/Subscriptions/Snmp1"
},
{
"@odata.id": "/redfish/v1/EventService/Subscriptions/Smtp2" # 暂不支持Smtp事件订阅
},
{
"@odata.id": "/redfish/v1/EventService/Subscriptions/Syslog1" # 暂不支持Syslog事件订阅
}
]
}
决策点二：资源协作接口 | 新增创建标准snmp事件订阅方法
Redfish事件订阅对应的资源协作接口path：
/bmc/kepler/EventService/Subscriptions
Redfish事件订阅对应的资源协作接口interface：bmc.kepler.EventService.Subscriptions
资源path：/bmc/kepler/EventService/Subscriptions/Snmp
资源interface：bmc.kepler.EventService.Subscriptions.SnmpDestinations
变化类型：新增接口
应用场景：创建snmp事件订阅
详细描述：
| 方法名称 | CreateDestination |
|---|---|
| 变化类型 | 新增接口 |
| 请求签名 | a{ss} |
| 请求参数说明 | DestinationValues:事件订阅的请求参数,包括: 必选参数： 1）Destination(事件订阅接收地址) 2）EventFormatType(事件订阅侦听的事件类型) 3）Context(事件订阅上下文信息) 4）Protocol(事件订阅使用的协议) 5）SubscriptionType（事件订阅类型） 可选参数： 6）Severities(告警发送级别) 7） AuthenticationProtocol（snmp鉴权算法） 8）TrapMode（snmp trap模式） 9）ServerIdentity（主机标识） SNMPv1/SNMPv2c可选参数： 10）TrapCommunity（团体名） SNMPv3可选参数： 11）EncryptionProtocol（snmp加密算法） 12）AuthenticationKey（snmp鉴权密码/密钥） 13）EncryptionKey（snmp加密密码/密钥） |
| 响应签名 | y |
| 响应参数说明 | Id:事件订阅标识 |
| 访问权限 | BasicSetting |
请求参数示例：
SNMPv1/SNMPv2c：
{
"Destination": "snmp://1.2.3.4:162",
"EventFormatType": "[\"Event\"]",
"Context": "",
"Protocol": "SNMPv1",
"Severities": "[\"Critical\"]",
"AuthenticationProtocol": "CommunityString",
"TrapCommunity": "CommunityName@example",
}
SNMPv3：
{
"Destination": "snmp://user@1.2.3.4:162",
"EventFormatType": "[\"Event\"]",
"Context": "",
"Protocol": "SNMPv3",
"AuthenticationProtocol": "HMAC384_SHA512",
"EncryptionProtocol": "CBC_DES",
"AuthenticationKey": "AuthenticationKey@example",
"EncryptionKey": "EncryptionKey@example"
}
决策点三：资源协作接口 | 新增标准snmp事件订阅资源
Redfish事件订阅对应的资源协作接口path：
/bmc/kepler/EventService/Subscriptions/:Id
Redfish事件订阅对应的资源协作接口interface：bmc.kepler.EventService.Subscriptions.Destination
资源path：/bmc/kepler/EventService/Subscriptions/Snmp/:Id
备选：/bmc/kepler/EventService/Subscriptions/Snmp/Destinations/:Id
资源interface：bmc.kepler.EventService.Subscriptions.SnmpDestination
变化类型：新增interface
应用场景：snmp事件订阅资源
详细描述：
| 属性名称 | 说明 | 签名 | 访问权限 | 持久化 | 变化通知 | 属性值来源 | 约束 |
|---|---|---|---|---|---|---|---|
| Id | 事件订阅资源Id | y | Read:ReadOnly | 掉电持久化 | false | 初始化生成 | |
| Destination | 事件订阅接收地址 | s | Read:ReadOnly | 掉电持久化 | false | 北向接口创建时指定 | |
| Protocol | 事件订阅使用的协议 | s | Read:ReadOnly | 掉电持久化 | false | 北向接口创建时指定 | Snmp事件订阅取值：SNMPv1;SNMPv2c;SNMPv3 |
| Context | 事件订阅上下文信息 | s | Read:ReadOnly Write:BasicSetting |
掉电持久化 | false | 北向接口 | |
| State | snmp事件订阅的上报状态 | s | Read:ReadOnly | 掉电持久化 | false | 北向接口预留 | 当前仅有"Enabled“一种状态 |
| EventFormatType | 事件订阅侦听的事件类型（redfish事件订阅不使用，当前仅用于snmp事件订阅） | as | Read:ReadOnly | 掉电持久化 | false | 北向接口创建时指定 | 当前仅支持取值[“Event”] |
| Severities | 上报事件的严重程度 | as | Read:ReadOnly | 掉电持久化 | false | 北向接口创建时指定 | 支持指定OK、Warning、Critical三种等级，三种等级可独立设置，Warning等级对应openUBMC事件等级中的Minor与Major两个等级 |
| AuthenticationProtocol | snmp鉴权算法 | s | Read:ReadOnly Write:BasicSetting |
掉电持久化 | false | 北向接口 | |
| AuthenticationKeySet | snmp鉴权密码/密钥是否已设置 | b | Read:ReadOnly | 掉电持久化 | false | 组件内部 | |
| EncryptionProtocol | snmp加密算法 | s | Read:ReadOnly Write:BasicSetting |
掉电持久化 | false | 北向接口 | |
| EncryptionKeySet | snmp加密密码/密钥是否已设置 | b | Read:ReadOnly | 掉电持久化 | false | 组件内部 | |
| TrapMode | snmp trap模式 | s | Read:ReadOnly Write:BasicSetting |
掉电持久化 | false | 北向接口 | 枚举值：PreciseAlarm，OID |
| ServerIdentity | snmp trap主机标识 | s | Read:ReadOnly Write:BasicSetting |
掉电持久化 | false | 北向接口 | 枚举值：BoardSN、ProductAssetTag、HostName |
| 方法名称 | Delete | SetAuthenticationKey | SetEncryptionKey | SetCommunity |
|---|---|---|---|---|
| 方法说明 | 删除Snmp事件订阅 | 设置Snmp事件订阅鉴权密码或密钥 | 设置Snmp事件订阅密码或密钥 | 设置Snmp事件订阅团体名 |
| 请求签名 | 无 | s | s | s |
| 请求参数说明 | 无 | Key:SNMPv3上报用户鉴权密码或密钥 | Key:SNMPv3上报用户加密密码或密钥 | Community:snmp上报的团体名 |
| 响应签名 | 无 | 无 | 无 | 无 |
| 响应参数说明 | 无 | 无 | 无 | 无 |
| 访问权限 | BasicSetting | BasicSetting | BasicSetting | BasicSetting |
决策点四：Redfish接口 | snmp事件订阅资源新增Oem属性TrapMode、ServerIdentity
uri: /redfish/v1/EventService/Subscriptions/:id（snmp协议）
操作类型： GET、PATCH、POST（集合资源/redfish/v1/EventService/Subscriptions）
应用场景：查询、创建snmp事件订阅，修改snmp事件订阅设置
| 属性名称 | 取值类型 | 属性描述 | 取值 | 操作权限 | 是否频繁变化并需要屏蔽变化事件 | 备注 |
|---|---|---|---|---|---|---|
| Oem/{{OemIdentifier}}/SNMP/TrapMode | boolean | snmp trap模式 | 枚举值：PreciseAlarm，OID | GET:ReadOnly PATCH:BasicSetting |
否 | - |
| Oem/{{OemIdentifier}}/ServerIdentity | string | snmp trap主机标识 | 枚举值：BoardSN、ProductAssetTag、HostName | GET:ReadOnly PATCH:BasicSetting |
否 | - |
决策点五：Redfish接口 | EventService资源新增Oem属性SnmpReportType
该决策点已评审通过
uri: /redfish/v1/EventService
变化类型: 新增属性
操作类型： GET
应用场景：查询、设置Snmp事件订阅告警类型
详细描述：
| 属性名称 | Oem/{{OemIdentifier}}/SnmpReportType |
|---|---|
| 取值类型 | string |
| 说明 | snmp事件订阅告警类型 |
| 取值范围 | 枚举值：SEL、OemEvent |
| 操作权限 | GET:ReadOnly PATCH:BasicSetting |
| 是否频繁变化并需要屏蔽变化事件 | 否 |
评审结论
决策点一：同意redfish事件订阅接口新增支持SNMPTrap订阅
uri：/redfish/v1/EventService/Subscriptions/{EventDestinationId}
(1) redfish事件订阅：EventDestinationId保持原来的纯数字风格，如"1"，表示第一个redfish事件订阅者
(2) SNMPTrap订阅：EventDestinationId使用Snmp+数字的风格，如"Snmp1"，表示第一个SNMPTrap订阅者
决策点二：同意新增创建SNMPTrap订阅者的资源协作接口：
新增path：/bmc/kepler/EventService/Subscriptions/Snmp
新增interface：bmc.kepler.EventService.Subscriptions.SnmpDestinations
新增方法：
CreateDestination：用于创建SnmpTrap类型事件订阅，请求签名a{ss}，表示创建订阅者的参数，包括目的地址、协议类型、上下文、事件格式等，响应签名为y，表示订阅者资源Id
决策点三：同意新增描述SNMPTrap订阅者的资源协作接口：
新增path：/bmc/kepler/EventService/Subscriptions/Snmp/:Id
新增interface：bmc.kepler.EventService.Subscriptions.SnmpDestination
新增属性：
| 属性名称 | 说明 | 签名 |
|---|---|---|
| Id | 事件订阅资源Id | y |
| Destination | 事件订阅接收地址 | y |
| Protocol | 事件订阅使用的协议 | s |
| Context | 事件订阅上下文信息 | s |
| State | snmp事件订阅的上报状态 | s |
| EventFormatType | 事件订阅侦听的事件类型（redfish事件订阅不使用，当前仅用于snmp事件订阅） | as |
| Severities | 上报事件的严重程度 | as |
| AuthenticationProtocol | snmp鉴权算法 | s |
| AuthenticationKeySet | snmp鉴权密码/密钥是否已设置 | b |
| EncryptionProtocol | snmp加密算法 | s |
| EncryptionKeySet | snmp加密密码/密钥是否已设置 | b |
| TrapMode | snmp trap模式 | s |
| ServerIdentity | snmp trap主机标识 | s |
新增方法：
| 方法名称 | Delete | SetAuthenticationKey | SetEncryptionKey | SetCommunity |
|---|---|---|---|---|
| 说明 | 删除Snmp事件订阅 | 设置Snmp事件订阅鉴权密码或密钥 | 设置Snmp事件订阅密码或密钥 | 设置Snmp事件订阅团体名 |
| 请求签名 | 无 | s | s | s |
| 响应签名 | 无 | 无 | 无 | 无 |
| 访问权限 | BasicSetting | BasicSetting | BasicSetting | BasicSetting |
决策点四：同意redfish接口/redfish/v1/EventService/Subscriptions/{EventDestinationId}新增Oem属性Oem/{{OemIdentifier}}/SNMP/TrapMode 、Oem/{{OemIdentifier}}/ServerIdentity，具体如下表：
| 属性名称 | 取值类型 | 取值 | 操作权限 | 说明 |
|---|---|---|---|---|
| Oem/{{OemIdentifier}}/SNMP/TrapMode | string | 枚举值：PreciseAlarm，OID | GET:ReadOnly PATCH:BasicSetting |
SNMP Trap报文类型，仅对SNMPTrap订阅有效 |
| Oem/{{OemIdentifier}}/ServerIdentity | string | 枚举值：BoardSN、ProductAssetTag、HostName | GET:ReadOnly PATCH:BasicSetting |
向订阅者发送消息时携带的设备标识 |
决策点五：同意redfish接口/redfish/v1/EventService新增Oem属性Oem/{{OemIdentifier}}/SnmpReportType，具体如下表：
| 属性名称 | Oem/{{OemIdentifier}}/SnmpReportType |
|---|---|
| 取值类型 | string |
| 取值范围 | 枚举值：SEL、OemEvent |
| 操作权限 | GET:ReadOnly PATCH:BasicSetting |
遗留事项
1、决策点一：uri的动态参数要和其它接口的风格保持一致
结论：参考/redfish/v1/Systems/{Systemid}/Processors/{ProcessorId}接口的实例，针对SNMPTrap订阅者的url（/redfish/v1/EventService/Subscriptions/{EventDestinationId}）中的动态参数EventDestinationId使用"Snmp+数字"的格式，如"Snmp1"
2、决策点二：删除BobEnabled
结论：BobEnabled已删除
3、决策点二：新增一个接口实现，不要复用之前的接口
结论：新增interface：bmc.kepler.EventService.Subscriptions.SnmpDestinations