USB 近端运维功能使用指导 ​

概述 ​

本文档介绍 openUBMC USB 近端运维功能的使用方法。usb_entry 组件主要提供近端运维功能，包括手机和便携运维、U 盘配置导入导出功能，以及在插入 USB 设备和执行任务时的近端运维点灯功能。

认识 USB 近端运维 ​

USB 近端运维简介 ​

USB 近端运维是通过 USB Type-C 接口实现 BMC 管理的功能，包括：

• U 盘配置导入导出 - 通过 U 盘导入配置文件、导出系统配置
• 手机和便携运维 - 通过 Type-C 口连接手机或笔记本电脑访问 BMC
• 近端运维点灯 - USB 设备插入和任务执行时的 LED 指示灯控制

应用场景 ​

环境要求 ​

BMC 环境支持近端运维功能需要满足两个条件：

1. 单板支持（Supported）- 硬件层面支持 Type-C 接口
2. 挂耳在位（Presence）- 挂耳在位（部分机型没有挂耳，不支持近端运维功能）

这两个属性需要在 sr 文件中的 UsbLocalOMService 类配置，可在资源树上查看。

USB 设备识别 ​

认识 USB 设备识别 ​

usb_entry 组件通过读写 USB CC 芯片上的寄存器值来识别插入的 USB 设备和进行后续的近端运维操作。

CC 芯片类型 ​

当前有多种厂商的 USB CC 芯片，不同厂商的 CC 芯片读取设备在位状态的操作有所不同，一台服务器只可能使用一种芯片，usb_entry 初始化时会遍历多种设备以确认当前的芯片类型。

设备在位状态轮询 ​

usb_entry 每秒读取一次 USB 设备在位状态，功能包括：

1. 及时更新当前 USB 设备的接入情况
2. 在插入 U 盘时反复进入 U 盘配置导入导出流程来执行控制文件中的下一步骤

U 盘配置导入导出 ​

认识 U 盘配置导入导出 ​

U 盘配置导入导出功能允许通过 U 盘与 BMC 交换配置数据：

• 配置导入 - 从 U 盘导入配置文件到 BMC
• 配置导出 - 将 BMC 配置导出到 U 盘
• 加密支持 - 支持加密的压缩包文件

USB 挂载卸载和读写 ​

挂载流程 ​

1. 插入 U 盘后，usb_entry 读取 USB CC 芯片获取 USB 设备是否在位。
2. 更新 USB 设备在位状态（USBDevicePresence）。
3. 若 USB 管理使能（Enabled）打开，判断 USB 设备类型。
4. 若是 USB device 设备，BMC 作为主机侧，USB DRD 角色设为 HOST。
5. 自动进行 U 盘的挂载及后续的配置导入导出操作。

挂载过程 ​

1. 判断装备模式是否为 ft（单板测试），是则不进行 U 盘操作直接退出。
2. 获取 USB 设备名和设备路径。
3. 通过 mount 命令将其挂载到 BMC 内存中的固定路径：/dev/shm/usb_control。
4. 通过对该路径的读写实现对 U 盘设备的读写。

卸载流程 ​

1. 拔出 U 盘后，usb_entry 检测到 USB 设备不在位。
2. 更新 USB 设备在位状态。
3. 通过 umount 命令卸载。
4. 清除配置导入导出产生的残余文件。

U 盘配置导入导出流程 ​

设置解压密码 ​

通过 Redfish 接口设置 USB 解压密码：

PATCH https://{bmc_ip}/redfish/v1/Managers/{ManagerId}/USBMgmtService

# 请求体
{
    "USBUncompressPassword":"xxxxxx"
}

资源树接口：

busctl --user call bmc.kepler.iam /bmc/kepler/Managers/1/USBPorts bmc.kepler.Managers.USBAuthentication SetDecryptPassword a{ss}s 0 "xxxxxx"

压缩包准备 ​

预先在 U 盘内配置压缩包，压缩包具体要求如下：

1. 压缩包名称：ServerOperateFile.tar.gz。
2. 加密方式：使用此前设置的 USB 解压密码加密压缩。
3. 控制文件：压缩包内应包含一个控制文件 control.json。
4. 配置文件：如果需要进行配置导入，需要包含配置文件 import/config.json。

控制文件格式 ​

control.json 文件说明了近端运维操作的动作及执行顺序：

{
    "ImportConfigurationParameter": {
        "ImportConfigurationEnabled": true,
        "ActiveMode": ["Immediately", "ResetBMC", "ResetOS"]
    },
    "ExportConfigurationParameter": {
        "ExportConfigurationEnabled": true,
        "AutoTag": ["sn", "model", ""]
    }
}

配置导入参数说明 ​

ActiveMode 取值说明：

配置导出参数说明 ​

AutoTag 取值说明：

配置导入导出执行流程 ​

插入 U 盘后，执行 USB 挂载卸载和读写动作后：

1. 检查 ServerOperateFile.tar.gz 文件是否存在。
2. 调用 iam 提供的 DecryptFile 方法解压 U 盘中的压缩包到 /dev/shm/usb_files 目录。
3. 解析控制文件 control.json，根据当前动作查找下一动作。
4. 将下一动作更新为当前动作（当前动作为空时下一动作就是第一个动作）。
5. 由于配置导入导出过程中可能包括 BMC 重启操作，当前动作需要持久化保存。
6. 执行当前动作（配置导入/配置导出/平滑重启/强制重启）。
7. 下一次进入 U 盘配置导入导出流程时（重启 BMC 后或下一次轮询），重复步骤 3-7 执行下一动作。

手机和便携运维 ​

认识手机和便携运维 ​

手机或便携笔记本电脑通过 Type-C 口连接到设备上，通过 RNDIS（Remote Network Driver Interface Specification）协议规范为这些设备提供 BMC 的网络服务。

RNDIS 协议 ​

RNDIS（Remote Network Driver Interface Specification）是微软开发的协议，用于在 USB 上传输网络数据。

驱动支持 ​

RNDIS 功能需要有驱动支持，当前 BMC 使用 RTOS 依赖的 Linux Kernel 版本编译这些驱动并加载，保存在：

/opt/bmc/apps/usb_entry/ko

不支持 USB 近端运维功能的环境不加载这些驱动。

便携机近端运维 ​

工作流程 ​

1. 便携笔记本电脑设备的 USB 口是 USB Host 设备。
2. 接入服务器后 BMC 将 USB DRD 角色设为 DEVICE。
3. 启动 RNDIS Device 服务，生成 usb0 网口。
4. 启动 DHCP Server 服务，为笔记本电脑分配 IP 地址。
5. 当前固定分配的 IP 地址为 169.254.1.5。
6. 分配 IP 后需要添加 iptable 转发使其能够访问各个服务。

网络转发 ​

通过调用 bmc_network 的 AddNatRule/UpdateNatRule 函数用于增加和删除近端运维 IP 的转发。

近端运维点灯 ​

认识近端运维点灯 ​

USB 设备插入和拔出，执行挂载卸载任务等动作，都会触发近端指示灯的变化。

指示灯逻辑 ​

LED 控制 ​

usb_entry 通过设置两个控制 LED 灯的 Accessor 来控制近端指示灯变化：

USB 接口说明 ​

接口地址 ​

接口功能 ​

资源树接口 ​

查看资源树 ​

busctl --user tree bmc.kepler.usb_entry

查看 USB LocalOMService ​

busctl --user introspect bmc.kepler.usb_entry /bmc/kepler/Managers/1/LocalOMService

CLI 命令使用 ​

查询 USB 管理状态 ​

ipmcget -t usbmgmt -d info

输出示例：

Service State         : enabled
USB Device Presence   : absent

设置管理使能状态 ​

# 启用 USB 管理服务
ipmcset -t usbmgmt -d state -v enabled

# 禁用 USB 管理服务
ipmcset -t usbmgmt -d state -v disabled

IPMI 命令使用 ​

查询管理使能状态 ​

ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x5b 0x11 0x00 0x00 0x00

设置管理使能状态 ​

# 关闭（最后一位 0x00 表示关闭，0x01 表示打开）
ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x5a 0x11 0x00 0x01 0x00 0x00

环境支持检查 ​

检查条件 ​

BMC 环境支持近端运维功能需要满足两个条件：

1. 单板支持（Supported）。
2. 挂耳在位（Presence）。

检查命令 ​

busctl --user introspect bmc.kepler.usb_entry /bmc/kepler/Managers/1/LocalOMService

两个条件均为 true 才说明该 BMC 环境支持近端运维功能。

常见问题 ​

设置管理使能失败，USB 设备接入状态始终为未接入 ​

可能原因一：sr 未配套 ​

描述：系统资源配置文件未配套或版本过旧

解决方法： 升级到最新的 sr

可能原因二：环境不支持 ​

描述：单板不支持或挂耳不在位

解决方法：

1. 检查单板是否支持 USB 近端运维功能
2. 检查挂耳是否在位
3. 通过资源树查看 Supported 和 Presence 属性

busctl --user introspect bmc.kepler.usb_entry /bmc/kepler/Managers/1/LocalOMService

确保两个属性均为 true。

LED 灯不亮 ​

问题现象：插入 USB 设备后 LED 灯没有反应

可能原因：

1. LED Accessor 配置错误
2. LED 控制接口调用失败
3. 硬件故障

解决方法：

1. 检查 sr 文件中 LED Accessor 配置
2. 检查 UsbLocalOMService 配置
3. 检查 LED 控制接口调用
4. 检查硬件连接

附录 ​

参考资料 ​

• openUBMC 官网：https://www.openubmc.cn/
• Redfish 规范：https://www.dmtf.org/standards/redfish