cli

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

---

1. 组件概述

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

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

• 受限 Shell：登录提示符、命令历史、会话超时（默认 900 秒，notimeout 可取消）、敏感信息遮蔽；命令集含 help、ipmcget、ipmcset、mdbctl、ping、reboot、rollback、passwd、ssh 等。
• ipmcget / ipmcset：参数化命令 [-l <location>] [-t <target>] -d <dataitem> [-s <systemid>] [-v <value>]，支持普通/分页/任务三类执行模式、敏感命令二次确认与鉴权、SOL 会话管理、一键日志收集入口（ipmcget -d diaginfo）。
• 交互边界：本组件不持有数据，所有查询/配置最终通过 D-Bus 用户会话总线（sd_bus）访问资源协作接口对象（path + interface）与后端服务（账号、重启、SOL、任务服务等）。mdbctl 在线调试命令由独立的 mdbctl 组件实现，不属于本组件。

---

2. API 使用说明和示例

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 会话管理、用户口令管理。
• 限制：ipmcget 只读；写操作需对应权限，部分命令需二次确认或密码鉴权；passwd 命令仅在 bmc.kepler.Cli.Command 的 Enabled 为真时可用。

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

# 查询版本
/opt/bmc/skynet/lua /opt/bmc/apps/cli/service/ipmcget.lua -d version

# 设置 SOL 超时时间
/opt/bmc/skynet/lua /opt/bmc/apps/cli/service/ipmcset.lua -t sol -d timeout -v 15
# 期望输出：Set SOL timeout period successfully.

非 Release 构建支持 --verbose=<level> 调整运行日志级别（error/warning/notice/info/debug/mass）。

2.2 受限 Shell 调试命令

命令	作用
help	打印命令帮助
notimeout	取消会话超时
reboot [-f] [-r] [-R]	重启 BMC（-f 强制、-r 进入恢复模式、-R 重启并回滚）
rollback	强制重启并回滚
passwd [options] [LOGIN]	修改/锁定/解锁账号口令
mdbctl	在线调试命令（实现位于 mdbctl 组件）

2.3 通过 busctl / mdbctl 调试后端对象

命令本质是转成对资源树对象的 D-Bus 调用，可绕过 CLI 直接访问后端对象定位问题。

# 通用流程
busctl --user --no-pager list                              # 列出服务
busctl --user --no-pager tree <service>                    # 对象树
busctl --user --no-pager introspect <service> <path>       # 接口/属性/方法
busctl --user --no-pager get-property <service> <path> <interface> <property>
busctl --user --no-pager call <service> <path> <interface> <method> <signature> <args...>
busctl --user --no-pager monitor                           # 监听属性变化

结合本组件代码中实际引用的对象：

# 查询单机/多机形态
busctl --user --no-pager get-property bmc.kepler.fructrl \
  /bmc/kepler/Managers/1/Multihost \
  bmc.kepler.Managers.Multihost HostType

# 查询 SOL 模式/超时
busctl --user --no-pager get-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/SOL \
  bmc.kepler.Managers.SOL Mode

<service> 用 busctl --user list 查询；具体签名以目标环境 introspect 为准。debug shell 中若 busctl --user 失败，先导出：

export XDG_RUNTIME_DIR=/run/user/0
export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus

mdbctl 常用子命令（实现见 mdbctl 组件）：attach / lsobj / lsprop / call / setprop modify，完整语法与响应样例以 mdbctl 组件文档为准。

---

3. 组件扩展案例

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

扩展点	位置	作用
接口配置 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）

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

Step 1：接口配置 interface_config/cli/ipmcset/sol.json，Uri 对应 /cli/v1/<target>/<dataitem>：

{
    "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：验证

/opt/bmc/skynet/lua /opt/bmc/apps/cli/service/ipmcset.lua -t sol -d timeout -v 15
# Set SOL timeout period successfully.

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

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

---

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日志，或 --verbose=debug 提升日志级别。

Q3：受限 Shell 里 passwd 显示 COMMAND NOT SUPPORTED？ CLI 的 passwd 未使能（bmc.kepler.Cli.Command 的 Enabled 为false）。确认功能开关已打开。

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

---

参考文档

• CLI接口映射配置指南
• 北向接口映射器适配指导