cli ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

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

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 关键术语表 ​

1.5 外部交互边界图 ​

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

2. API 使用说明与示例 ​

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

2.1 ipmcget / ipmcset 命令 ​

功能说明 ​

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

参数说明 ​

命令语法：

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

返回值与异常 ​

可能抛出的异常及触发条件如下。错误通过 pcall 捕获并打印到标准输出，不向调用方抛出堆栈：

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

应用场景 ​

• 日常巡检：查询版本、传感器、SEL、日志等信息。
• 配置下发：通过 ipmcset 修改 BMC 配置。
• 会话管理：管理 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

2.2 受限 Shell 命令 ​

功能说明 ​

列出受限 Shell 中可直接使用的内置命令。

参数说明 ​

各命令参数以 help 输出为准；ping、top、route 等命令只接受受限参数。

返回值与异常 ​

命令成功时输出查询结果或成功提示；未注册、未使能或越权时输出错误信息。

应用场景 ​

用于登录后的现场巡检、网络检查、资源调试和 BMC 重启操作。

限制条件 ​

仅 Release 包默认进入受限 Shell；可用命令受产品配置和 interface_filter.json 控制。

调试示例 ​

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

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

3.2 扩展点说明 ​

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 }
            ]
        }
    ]
}

命令条目字段：

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

4. 日志说明 ​

4.1 一键日志收集 ​

CLI 通过 ipmcget -d diaginfo 触发一键日志收集，默认生成 /tmp/dump_info.tar.gz，也可通过 -v <path> 指定输出路径。收集内容由诊断信息框架和各组件注册项共同决定。

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

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

典型问题：

5.2 最小化复现与证据收集 ​

1. 使用 ipmcget --verbose=debug -d <dataitem> 或 ipmcset --verbose=debug ... 开启调试日志并复现问题。
2. 核对 interface_config 中对应的 URI、参数校验和回显模板。
3. 使用 busctl 或 mdbctl 直接访问后端对象，判断问题位于 CLI 层还是后端资源层。
4. 保留完整命令、标准输出、错误码、/var/log/app.log 和 ipmcget -d diaginfo 收集结果。

5.3 调试方法 ​

• 参数提示或 Usage 异常：检查参数解析和命令帮助配置。
• Invalid Command 或命令类型错误：检查路由映射和命令注册。
• 回显格式错误：检查 echoes 模板和模板变量。
• 受限 Shell 命令缺失：检查 Release/Debug 构建类型、命令注册和 interface_filter.json。

5.4 错误码速查表 ​

6. 常见问题解答 ​

Q1：ipmcget 或 ipmcset 报 Invalid Command，如何处理？ ​

• 问题描述：命令未执行，输出 Invalid Command。
• 一句话答案：命令未命中合法接口配置，或命令执行类型未注册。
• 根因说明：路由映射器响应异常，或 interface_config 中缺少对应 URI/命令类型。
• 解决方案：检查 interface_config 的 URI、-t/-d 参数和命令类型；在运行日志中检索 Invalid command type。
• 规避方案：新增命令后先在测试环境执行 help 和只读命令验证，再纳入产品配置。
• 适用版本：1.130.13。

Q2：配置命令返回 Request failed.，如何定位？ ​

• 问题描述：命令已被 CLI 接收，但后端返回失败。
• 一句话答案：CLI 已完成后端调用，需要结合请求 URI 检查后端组件。
• 根因说明：后端服务返回非空错误列表，或参数未通过后端校验。
• 解决方案：从调试日志获取请求对象和接口，检查对应微组件日志、权限和参数。
• 规避方案：生产变更前在维护窗口验证参数，并保存原值和回显结果。
• 适用版本：1.130.13。

Q3：一键日志包在哪里？ ​

• 问题描述：需要收集 CLI 和系统诊断信息。
• 一句话答案：执行 ipmcget -d diaginfo，默认生成 /tmp/dump_info.tar.gz。
• 根因说明：诊断信息由系统框架统一收集，CLI 通过 diaginfo 数据项触发。
• 解决方案：使用 ipmcget -d diaginfo -v <path> 指定输出路径，生成后确认文件存在。
• 规避方案：不要在空间不足或业务高峰时执行，避免影响现场维护。
• 适用版本：1.130.13。