北向映射器检查工具 MapperCheck

一、设计背景

iBMC V3通过映射器配置来完成redfish、web-rest、cli、snmp接口的开发，接口适配主要是json文件，存在代码量大、人工检视难、出现问题难定位等困难。因此开发了映射器配置检查工具，该工具可以为映射器配置的门禁检查工具，可以对映射器语法、接口逻辑进行检查，拦截低级错误和常见问题，提升调试效率，同时规范映射器用法。

二、配置及检查范围

rackmount
├── ...
├── interface_config
│   ├── cli                      # cli命令配置
│   │   ├── ipmcget              # cli get类型命令json配置
│   │   ├── ipmcset              # cli set类型命令json配置
│   │   ├── plugins              # cli命令实现调用的插件
│   │   └── script               # cli命令实现调用的脚本
│   ├── redfish                  # redfish命令配置
│   │   ├── mapping_config       # redfish命令json配置
│   │   ├── plugins              # redfish命令实现调用的插件
│   │   └── script               # redfish命令实现调用的脚本
│   ├── snmp                     # snmp命令配置
│   │   ├── mapping_config       # snmp命令json配置
│   │   ├── plugins              # snmp命令实现调用的插件
│   │   └── script               # snmp命令实现调用的脚本
│   └── web_backend              # web_backend命令配置
│       ├── mapping_config       # web_backend命令json配置
│       ├── plugins              # web_backend命令实现调用的插件
│       └── script               # web_backend命令实现调用的脚本
├── mapper_check                 # 北向映射器检查工具
│   ├── PrivilegeMapUriChecker   # 检查工具拓展组件-PrivilegeMap检查类
│   ├── data_mapping_schema.json # 语法检查json配置
|   ├── ErrorlogPrinter.py       # 检查工具错误信息打印类
|   └── MapperCheck.py           # 检查工具核心代码
└── build.py                     # rackmount构建脚本

运行方法

检查工具脚本已集成至构建脚本build.py中，执行python3 build.py构建时会自动先运行检查工具。若检查失败报错，会终止构建；若无报错，则开始构建。

文件结构

执行检查及构建时，请按照上方的文件结构，尽量不要做改动！！

build.py从mapper_check文件下引入了MapperCheck模块，而MapperCheck模块检查时会依赖于data_mapping_schema.json语法检查配置文件，代码中规定了该配置文件的相对位置在mapper_check文件下，因此请勿移动build.py、MapperCheck.py、data_mapping_schema.json的位置。

同样的，在检查命令json配置、命令调用的插件、脚本合法性过程中，依赖于各组件mapping_config（cli的为ipmcget和ipmcset）下的配置文件、plugins下的插件和script下的脚本，而在代码中规定了这些文件的相对位置都在interface_config下的各自组件下，因此请勿移动这些文件的相对位置。

此外，获取绝对位置时会搜索/rackmount所在位置，因此也请不要将代码移出rackmount仓。

检查范围

分类	编号	名称	规则描述	状态
语法检查	1-1	映射器配置文件语法检查	映射器配置必须满足数据映射器规定的语法	已支持
引用合法性	2-1	被引用数据来源检查	数据引用来源只能是Uri、ReqBody、Query、ProcessingFlow[].Destination、Statements、Context	已支持
	2-2	数据引用位置检查	数据引用只能在以下配置项中使用：Statements、ResourceExist、RspBody、ProcessingFlow[].Path、ProcessingFlow[].Interface、ProcessingFlow[].Name、ProcessingFlow[].Params、ProcessingFlow[].Source、ProcessingFlow[].CallIf、ProcessingFlow[].Foreach	未支持
	2-3	Uri动态槽位号的名称大小写检查	Uri中表示动态槽位号必须是冒号+全小写字符，不能包括大写字符，否则引用的时候拿不到正确值。	已支持
	2-4	Uri被引成员存在性检查	被引用的Uri槽位号必须在Uri中声明了，例如Uri声明如下，则只能使用${Uri/managerid}和${Uri/id}，不能有其他形式的引用/redfish/v1/Managers/:managerid/NetworkProtocol/:id	已支持
	2-5	ReqBody被引成员存在性检查	被引用的ReqBody成员必须在ReqBody中声明了	已支持
	2-6	Query被引成员存在性检查	被引用的Query成员必须在Query中声明了	已支持
	2-7	ProcessingFlow被引成员存在性检查	1.被引用的ProcessingFlow数组下标必须合法 2.被引用的成员必须在对应Destination下有定义	已支持
	2-8	Statements被引成员存在性检查	被引用的Statements方法必须在Statements中有定义	已支持
	2-9	Context被引成员存在性检查	1.CLI支持的字段有：Interface(固定取值CLI)、UserName、ClientIp 2.Redfish支持的字段有：Interface(固定取值Redfish)、UserName、ClientIp、Privilege、AccountId。以上为用户名密码方式支持的字段，如果是会话Token鉴权，还额外支持以下字段RoleId、AuthType、Token 3.web_backend支持的字段有：Interface(固定取值WEB)、UserName、ClientIp、Privilege、AccountId、RoleId、AuthType、Token	已支持
	2-10	全局变量有效性检查失败	被引用的全局变量必须在config.json中有定义	已支持
功能检查	3-1	Uri合法性校验存在性检查	如果Uri中声明了动态槽位号，则必须定义ResourceExist关键字进行Uri合法性检查	已支持
	3-2	@odata.context属性格式检查	V3 @odata.context必须使用规范新格式，参考如下： "@odata.context": "/redfish/v1/$metadata#SessionCollection.SessionCollection" "@odata.context": "/redfish/v1/$metadata#ServiceRoot.ServiceRoot"	已支持
	3-3	Uri重复性检查	某类接口（redfish、web-rest）映射器配置中声明的Uri必须全局唯一，不能重复声明	已支持
	3-4	Uri动态槽位号合法性检查	Uri中表示Managers、Systems、Chassis的动态槽位号必须是冒号+全小写字符，不能将其写死为固定数值。	已支持
	3-5	厂商定制正确性检查	redfish接口厂商名须统一用{{OemIdentifier}}表示，snmp接口中oid的厂商名需统一替换为{{SnmpOemIdentifier}}	已支持
	3-6	ActionResponseBody字段配置协议检查	ActionResponseBody字段只有redfish协议支持配置	已支持
	3-7	ActionResponseBody字段配置对应URI检查	只有Actions类型的UrI才允许配置ActionResponseBody字段	已支持
	3-8	ActionResponse与RspBody冲突检查	ActionResponse不能与RspBody共同使用	已支持
脚本和插件检查	4-1	被调用的脚本存在性检查	映射器中Script关键字下引用的脚本文件必须存在	已支持
	4-2	被调用的插件存在性检查	映射器中Plugin关键字下引用的插件代码文件必须存在	已支持
	4-3	被调用的插件函数存在性检查	映射器中Plugin关键字下引用的插件函数必须存在	已支持
	4-4	被调用的插件函数入参个数检查	映射器中Plugin关键字下引用的插件函数所传入的参数必须与插件中定义的函数入参个数相同	已支持
mdb资源树定义检查	5-1	被引用的资源树定义检查	映射器中引用的资源树Path、Interface、Property、Method必须已定义	未支持
接口配套资源校验	6-1	redfish接口PrivlegeMap校验	redfish接口必须在PrivlegeMap中添加权限声明	已支持
6-2	web_rest接口新增DELETE操作的白名单校验	新增WebRest接口的DELETE操作时，需要配置AllowHttpDelete的校验后，再到白名单中添加新增的接口的URI	已支持
6-3	AutoPagingEnabled只允许在redfish接口中配置	AutoPagingEnabled只能在redifsh获取集合资源的接口中配置	已支持

三、修改建议

问题打印

MapperCheck.py中定义了errorlog_printer类用于打印错误信息，成员函数print_errorlog2file()将错误信息打印至interface_config/error_log.txt，每次运行都会删除上一次的错误信息文件；成员函数print_errorlog2tmn()将错误信息打印至终端。

若仅需要其中一种打印方式，在类中注释掉该函数对应调用即可。

错误信息会按照

=============reference errors found in file: <文件所在路径>
[Rule x-x]: 错误提示，错误值，错误位置: URI, Type, location

的格式打印。

问题定位

在定位错误位置时，可以直接粘贴文件所在路径找到出错位置所在文件->粘贴错误值索引到错误内容。若在同文件中定位到多处错误值匹配，可根据错误位置精细定位。

常见错误

本节仅对扫描、定位出的常见问题举例，提供快速查找定位的参考。实际排查过程中请具体问题具体分析。

[Rule 2-1]: 被引用数据来源检查失败

错误提示示例：

=============reference errors found in file: <path>
[Rule 2-1]: 被引用数据来源检查失败, 错误值:${ProcessingFlow[2].Destination.NetMode}, 出错位置:xxx

数据引用中的索引应用斜杠/分隔，其余符号都会无法解析导致引用失败。修改示例：

- ${ProcessingFlow[2].Destination.NetMode}
+ ${ProcessingFlow[2]/Destination/NetMode}

[Rule 2-x]: xxx引用有效性检查失败

错误提示示例：

=============reference errors found in file: <path>
[Rule 2-4]: Uri引用有效性检查失败, 错误值:${Uri/controllerid}, 错误位置: URI:/redfish/v1/Systems/:systemid/EthernetInterfaces/:ethernetinterfaceid/VLANs/:vlanid/xxx

URI中的动态槽位号可以自行命名，请在引用时检查对应数据体中是否含有需要引用的数据名。修改示例：

- ${Uri/controllerid}
+ ${Uri/systemid}

当引用ProcessingFlow中的返回值时，引用有效性检查失败还有一种比较经典的错误：错误认为ProcessingFlow索引从数组下标0开始。资源树是用Lua代码实现的，Lua中数组是从1开始索引的，因此请检查是否是ProcessingFlow索引下标出错。修改示例：

- ${ProcessingFlow[0]/Destination/Value}
+ ${ProcessingFlow[1]/Destination/Value}

[Rule 3-4]: URI中的动态槽位号合法性检查失败

错误提示示例：

=============reference errors found in file: <path>
[Rule 3-4]: URI中的动态槽位号合法性检查失败, 错误值:/redfish/v1/Chassis/1/xxx, 错误位置:xxx

Systems/Chassis/Managers后不能绑定数字，需绑定动态槽位号。修改示例：

- /redfish/v1/Chassis/1/xxx
+ /redfish/v1/Chassis/:chassisid/xxx

[Rule 3-5]: 厂商定制正确性检查失败

错误提示示例：

=============reference errors found in file: <path>
[Rule 3-5]: 厂商定制正确性检查失败, 错误值:xxx, 错误位置: xxx

请检查对应文件中是否未用{{OemIdentifier}}替换redfish接口中的Huawei字段，以及是否未用{{SnmpOemIdentifier}}替换snmp接口中oid中的Huawei厂商名2011.2.235.1.1。修改示例：

- "Uri": "/redfish/v1/Chassis/:chassisid/PowerSubsystem/Oem/Huawei/PowerConverters",
+ "Uri": "/redfish/v1/Chassis/:chassisid/PowerSubsystem/Oem/{{OemIdentifier}}/PowerConverters",

[Rule 3-6]: ActionResponseBody只有redfish协议支持配置

错误提示示例：

=============reference errors found in file: <path>
[Rule 3-6]:ActionResponseBody只有redfish协议支持配置, 错误值:xxx, 错误位置: xxx

请检查错误位置对应URI是否为redfish接口，只有redfish协议支持配置ActionResponseBody字段。修改示例：

- "ActionResponseBody": {},
+ "RspBody": {},

[Rule 3-7]: ActionResponseBody只允许配置到Actions的URI中

错误提示示例：

=============reference errors found in file: <path>
[Rule 3-7]: ActionResponseBody只允许配置到Actions的URI中, 错误值:xxx, 错误位置: xxx

请检查Url是否为Actions类型。修改示例：

- "Uri": "/redfish/v1/CertificateService/CertificateService.GenerateCSR",
+ "Uri": "/redfish/v1/CertificateService/Actions/CertificateService.GenerateCSR",

[Rule 3-8]: 不允许同时定义ActionResponseBody和RspBody

错误提示示例：

=============reference errors found in file: <path>
[Rule 3-8]: 不允许同时定义ActionResponseBody和RspBody, 错误值:xxx, 错误位置: xxx

请检查该接口是否同时定义了RspBody和ActionResponseBody。修改示例：

- "RspBody": {},

[Rule 4-3]: 被调用的插件函数存在性检查失败

错误提示示例：

=============reference errors found in file: <path>
[Rule 4-3]: 被调用的插件函数存在性检查失败, 错误值:orchestrator.systems.get_Volume_health(xxx), 出错位置:xxx

调用插件中的函数名注意需全部小写。修改示例：#### [Rule 4-3]: 被调用的插件函数存在性检查失败

- orchestrator.systems.get_Volume_health(xxx)
+ orchestrator.systems.get_volume_health(xxx)

[Rule 4-4]: 被调用的插件函数入参个数检查失败

错误提示示例：

=============reference errors found in file: <path>
[Rule 4-4]: 被调用的插件函数入参个数检查失败, 错误值:orchestrator.thermal.liquid_cooling_level_set_supported(Input, ReqBody.Oem.Huawei.LiquidCoolingUnitsLevel), 出错位置:xxx

请检查对应文件中的函数定义的入参个数与实际入参是否一致。修改示例：

- orchestrator.thermal.liquid_cooling_level_set_supported(Input, ReqBody.Oem.Huawei.LiquidCoolingUnitsLevel)
+ orchestrator.thermal.liquid_cooling_level_set_supported(ReqBody.Oem.Huawei.LiquidCoolingUnitsLevel) # 调用函数只有1个入参

[Rule 6-1]: redfish接口PrivlegeMap校验检查失败

错误提示示例：

==================================================
PrivilegeMap检查不通过，错误详情如下：
==================================================
PATCH接口：xxx，类型：xxx 未配置PrivilegeMap
==================================================

=============reference errors found in file: NULL
[Rule 6-1]: redfish接口PrivlegeMap校验检查失败, 错误值:NULL, 出错位置:NULL

请检查对应接口权限是否在PrivilegeMap中配置。

[Rule 6-2]: web_rest接口DELETE操作白名单检查失败

错误提示示例：

=============reference errors found in file:  <path>
[Rule 6-2]: web_rest接口DELETE操作白名单检查失败, 错误值:xxx, 错误位置: xxx, Type:DELETE, location:None

1、请确认是否配置了AllowHttpDelete属性的校验，参考配置：

{
    "Uri": "/UI/Rest/Maintenance/WorkRecord/:workrecord_id",
    "Interfaces": [
        {
            "Type": "DELETE",
            "ResourceExist": {
                "${Statements/IsAllowHttpDelete()}": true
            },
            "Statements": {
                "IsAllowHttpDelete": {
					"Input": "${ProcessingFlow[1]/Destination/AllowHttpDelete}",
					"Steps": [
						{
							"Type": "Script",
							"Formula": "check_http_delete.lua"
						}
					]
                }
            },
            "ProcessingFlow": [
                {
                    "Type": "Property",
                    "Path": "/bmc/kepler/Managers/1/WebService",
                    "Interface": "bmc.kepler.Managers.WebService",
                    "Destination": {
                        "AllowHttpDelete": "AllowHttpDelete"
                    },
                    "CallIf": "CheckUri"
                }
            ]
        }
    ]
}

2、新增的 WebRest DELETE 接口 URI 必须添加到白名单中。 请将 URI 添加到 mapper_check/web_rest_delete_whitelist.json 文件中。 白名单文件格式示例：

{
    "whitelist": [
        "/UI/Rest/Maintenance/WorkRecord/:workrecord_id",
        "/UI/Rest/Systems/:systemid/xxx"
    ]
}

[Rule 6-3]: AutoPagingEnabled只允许在redfish接口中配置

错误提示示例：

=============reference errors found in file: /root/.conan2/p/b/rackm55e3b7a6c947c/b/interface_config/web_backend/mapping_config/JobService/Jobs.json
[Rule 6-3]: AutoPagingEnabled只允许在redfish接口中配置, 错误值:AutoPagingEnabled, 错误位置: URI:/UI/Rest/JobService/Jobs, Type:GET, location:Resources[1].Interfaces[1]

请检查对应AutoPagingEnabled属性是否在Redfish接口中配置。

四、语法更新

Time: 2024-07-20 ReqBody格式整改

更新ReqBody的声明：

"ReqBody": {
	"Type": "object",
	"Required": true,
	"Properties": {
		"Name": {
			"Required": xxx,
			"Type": "xxx",
			"Validator": [
				{
					xxx
				}
			],
			"Sensitive": xxx,
			"Description": "xxx"
		}
	}
}

主要整改方向：

• ReqBody类型更改为object
• ReqBody中需要填写的属性都移动至"Properties"属性下，类型为object

整改前ReqBody声明方式（供参考对照）：

"ReqBody": [
	{
		"Name": "xxx",
		"Type": "xxx",
		"Required": xxx,
		"Validator": [
			{
				xxx
			}
		]
		"Sensitive": xxx,
		"Description": "xxx"
	}
]