cli

openUBMC 命令行（CLI）组件，提供受限 Shell 命令，以及 ipmcget（查询）/ ipmcset（配置）两套命令。

项目	内容
组件名称	cli
许可证	Mulan PSL v2
最后更新	2026 年 8 月 25 日

---

1. 组件概述

1.1 组件简介

cli 组件是 openUBMC 对外的人机交互入口，向上提供命令行界面，向下屏蔽资源协作接口与后端服务差异。由两部分组成：

部分	语言	说明
受限 Shell（CLP）	C（src/clp/）	登录后进入的命令行环境，仅放行固定命令集
ipmcget / ipmcset	Lua（src/lualib/、src/service/）	将命令解析为 URI，经路由映射器转成后端资源协作接口对象调用

1.2 解决什么问题

1、解决服务器底层管理的标准化、自动化与可追溯性问题。

服务器内部硬件组件众多，配置项复杂。如果缺乏统一的接口，运维将面临配置不一致、批量操作困难、接口随意变更导致自动化脚本失效等问题。

2、CLI 的解决方案：

统一配置与接口，屏蔽硬件差异，允许用户通过简单的命令完成所有管理操作。

支持基于 Shell / Python 的自动化运维，使得大规模服务器集群的批量配置、状态监控成为可能。

接口基线与生命周期管控，解决接口变更导致上下游系统兼容性问题，确保自动化流程的稳定性和可维护性。

1.3 核心功能

1. 受限 Shell：登录提示符、命令历史、会话超时（默认 900 秒，notimeout 可取消）、敏感信息遮蔽；命令集含 help、ipmcget、ipmcset、mdbctl、ping、reboot、rollback、passwd、ssh 等。

2. ipmcget / ipmcset：参数化命令 [-l <location>] [-t <target>] -d <dataitem> [-s <systemid>] [-v <value>]，支持普通/分页/任务三类执行模式、敏感命令二次确认与鉴权、SOL 会话管理、一键日志收集入口（ipmcget -d diaginfo）。

1.4 外部交互边界图

只有Release包才会默认使用clp_commands。本组件不持有数据，所有查询/配置最终通过 D-Bus 用户会话总线（sd_bus）访问资源协作接口对象（path + interface）与后端服务（账号、重启、SOL、任务服务等）。

  flowchart LR
	A1((SSH登录)) -->|release包| B(/usr/bin/clp_commands)
  	A1 -->|debug包| C(/bin/bash)
	A2((Telnet登录)) --> C

---

2. 使用说明和示例

运行help指令可以查看clp_commands下所有可用指令

2.1 ipmcget / ipmcset 命令

作用：ipmcget 查询 BMC 状态、配置、日志等信息；ipmcset 下发配置与控制命令。

语法：

ipmcget/ipmcset [-l <location>] [-t <target>] -d <dataitem> [-s <systemid>] [-v <value>]

参数	必选	说明
-l <location>	否	机框/位置（仅当构建开启 cli_l_supported 时可用，默认关闭）
-t <target>	否	目标资源类型，缺省为 _（通配）
-d <dataitem>	是	数据项，如 version、sensor、sel
-s <systemid>	否	多机形态下的系统 ID
-v <value>	否	附加参数/配置值

可能抛出的异常及触发条件（通过 pcall 捕获，打印到标准输出而非抛堆栈）：

输出	触发条件
Invalid Command	路由映射器响应异常，或命令执行类型未注册
Request failed.	后端服务返回错误（errs 非空）
Request failed, the echo profile does not exist.	回显模板文件缺失
Invalid input	鉴权提示后，密码输入失败
内部错误消息	Lua 执行抛出未预期异常

参数不完整/非法时打印对应层级的帮助信息（Usage/参数列表/Example），不算异常。

应用场景 / 限制条件：

• 场景：日常巡检（版本、传感器、SEL、日志查询）、配置下发、SOL 会话管理、用户口令管理。
• 限制：写操作需对应权限，部分命令需二次确认或密码鉴权

调试示例（命令底层直调，等价于在受限 Shell 内执行）：

# 查询版本
ipmcget -d version

# 设置 SOL 超时时间
ipmcset -t sol -d timeout -v 15
# 期望输出：Set SOL timeout period successfully.

对于非 Release 构建，ipmcget/ipmcset 命令支持 --verbose=<level> 调整运行日志级别。

调试示例

# 设置日志级别为debug，查看详细调试信息
ipmcget --verbose=debug -d version

<level>	说明
error	仅错误信息
warning	警告及以上
notice	重要通知及以上
info	一般信息（默认）
debug	详细调试信息
mass	大量日志（最高级别）

2.2 受限 Shell 调试命令

命令	作用
help	打印命令帮助
exit	中止CLP会话
ping	测试IPv4网络状态
ping6	测试IPv6网络状态
ifconfig	查看网络设备信息
notimeout	取消登录会话超时
free	检测内存状态
top	检查系统资源使用情况。不接受参数
df	检查磁盘使用情况
netstat	用于检查端口状态
route	用于检查路由信息。不接受参数
reboot [-f] [-r] [-R]	重启 BMC（-f 强制、-r 进入恢复模式、-R 重启并回滚）
rollback	强制重启并回滚
mdbctl	在线调试命令（实现位于 mdbctl 组件）

---

3. 组件扩展案例

3.1 扩展能力概述

本组件支持声明式配置 + 模板扩展命令（主要在rackmount仓的interface_config/cli/目录下），无需改动核心代码。

3.2 扩展点说明

扩展点	位置	作用
接口配置 JSON（rackmount仓）	interface_config/{ipmcget,ipmcset}/*.json	URI → 后端调用映射、参数校验、回显引用
回显模板（rackmount仓）	interface_config/echoes/**	自定义输出格式（Lua 模板引擎）
客户/产品定制（rackmount仓）	interface_config/customer/** interface_config/<platform_board>/	按客户/产品替换配置与模板
自定义路由脚本（cli组件仓）	src/lualib/route/**	复杂命令定制逻辑（如 SOL activate）
命令隐藏过滤（cli组件仓）	interface_config/interface_filter.json	按资源树条件隐藏指定 CLI 命令（见 3.5）

3.3 二次开发指导

openUBMC社区的CLI接口采用接口映射配置方案实现，需要将命令配置到json文件中。CLI命令的接口映射配置文件位于 rackmount 代码仓的 interface_config/cli 路径下。参考社区文档：

• CLI接口映射配置指南
• 北向接口映射器适配指导
• 产品多层级接口定制

3.4 案例：新增一条配置命令（以 sol/timeout 为例，取自单元测试数据）

Step 1：接口配置 interface_config/cli/ipmcset/sol.json，Uri 对应 /cli/v1/sol/timeout：

{
    "Resources": [{
        "Uri": "/cli/v1/sol/timeout",
        "Interfaces": [{
            "Type": "Patch",
            "Usage": "ipmcset -t sol -d timeout -v <value>",
            "ReqBody": {
                "Type": "object",
                "Required": true,
                "Properties": {
                    "Value": { "Required": true, "Type": "integer", "Validator": [{ "Type": "Range", "Formula": [0, 480] }] }
                }
            },
            "ProcessingFlow": [{
                "Type": "Method",
                "Path": "sol/SetTimeout",
                "Interface": "interface",
                "Name": "SetTimeout",
                "Params": ["${ReqBody/Value}"],
                "Destination": { "Result": "Result" }
            }],
            "Echoes": ["ipmcset/sol_timeout", ""]
        }]
    }]
}

Step 2：回显模板 interface_config/cli/echoes/ipmcset/sol_timeout：

Set SOL timeout period {* Result == 0 and 'successfully' or 'failed' *}.

Step 3：验证

ipmcset -t sol -d timeout -v 15
# Set SOL timeout period successfully.

模板标记（src/lualib/template/parser.lua）：{* expr *} 原样输出、{{ expr }} 输出expr的结果(一些特殊符号将会被转义)、{% lua %} 语句、{( view, ctx )} 引入模板、{# comment #} 注释。

参考文档：产品多层级接口定制

3.5 产品定制命令隐藏（interface_filter.json）

产品可通过 interface_config/interface_filter.json按资源树条件隐藏部分 CLI 命令。被隐藏的命令执行时按“命令不存在”处理，且不会出现在 -t/-d/-l 提示列表中。

配置结构：

{
    "Conditions": {
        "ServiceEnabled": {
            "Path": "/bmc/kepler/EventService",
            "Interface": "bmc.kepler.EventService",
            "Property": "ServiceEnabled",
            "Value": true,
            "Description": "资源树匹配示例"
        }
    },
    "CLIFilter": [
        {
            "Conditions": ["ServiceEnabled"],
            "ErrorMessage": "该命令在当前产品下不可用",
            "Get": [
                { "ParentUri": "/cli/v1/sol", "Command": "*" },
                { "ParentUri": "/cli/v1/shelf/_", "Command": "chassisid", "LocationCommand": true }
            ],
            "Set": [
                { "ParentUri": "/cli/v1/shelf/_", "Command": "*", "LocationCommand": true }
            ]
        }
    ]
}

字段	说明
Conditions	资源树条件定义：Path/Interface/Property/Value，条件全部满足时对应过滤条目才生效
CLIFilter[].Conditions	引用的条件名列表，全部满足则该条目的 Get/Set 生效
CLIFilter[].ErrorMessage	可选；命令被隐藏时向用户打印的错误信息
CLIFilter[].Get / .Set	要隐藏的命令列表（Get 对应 ipmcget，Set 对应 ipmcset）

命令条目字段：

字段	说明
ParentUri	命令路径 /cli/v1/<target>，段可用 _ 占位
Command	命令名，或 *（隐藏 ParentUri 下的全部命令，含 ParentUri 本身）
LocationCommand	true 表示当前命令包含-l（location）场景
（条目级）ErrorMessage	命中隐藏时打印的错误信息，无则不打印

参考：示例配置见 example/interface_filter.json；实现位于 src/lualib/interface_filter.lua。

---

4. 问题定界指南

快速定位：提示不完整/Usage 异常 → 参数解析层（ipmc.lua）；Invalid Command/类型未注册 → 命令执行层；输出格式不符/模板缺失 → 回显层；登录提示符/超时/COMMAND NOT SUPPORTED → 受限 Shell 层（src/clp/）。

典型问题：

现象	可能原因	定位
Invalid Command	接口配置缺 URI 或命令类型未注册	运行日志搜 Invalid command type
Request failed.	后端服务返回错误	查后端服务日志
COMMAND NOT SUPPORTED	verb 未注册或功能未使能（如 passwd）	检查 help 输出与 Enabled 开关
任务命令卡在进度	任务对象异常	运行日志搜 get task failed

关键错误码（src/clp/libs/common/inc/clp.h）：241 FUNCTION_NOT_SUPPORTED、245 REQUIRED_OPTION_MISSING、253 COMMAND_NOT_RECOGNIZED、254 COMMAND_NOT_SUPPORTED、255 COMMAND_ERROR_UNSPECIFIED；口令相关 0x83 用户锁定、0x96 初始口令需重置等。

复现方法：

① ipmcget --verbose=debug -d <dataitem> 开日志；

② 底层直调排除 Shell 干扰（见 2.1）；

③ 核对 interface_config 配置；

④ busctl/mdbctl 直接访问后端对象判断问题在 CLI 层还是后端。

---

5. FAQ

Q1：ipmcget/ipmcset 报 Invalid Command？ 命令未命中合法接口配置，或命令执行类型未注册。检查 interface_config 下 URI 配置；app日志搜 Invalid command type。

Q2：配置命令返回 Request failed.？ 命令已下发但后端返回错误，查app日志。

Q3：一键日志包在哪？ 默认 /tmp/dump_info.tar.gz，可用 ipmcget -d diaginfo -v <path> 指定。