The CLI interfaces of the openUBMC community are implemented using mapping solutions that require commands to be configured in the JSON file. The interface mapping configuration file of the CLI command is stored in the CLI path of the rackmount code repository.

This document describes only the configuration rules unique to CLI interfaces. For the common mechanism of interface mapping configuration, see Interface Mapping Configuration.

CLI Command Mapping

The CLI command format is ipmcget/ipmcset [-t <target>] -d <dataitem> [-s <systemid>] [-v <value> ...].

Mapping rules:

ipmcget corresponds to the GET method and ipmcset corresponds to the PATCH method.
The URI format is /cli/v1/<target>/<dataitem>. If the -t parameter is not specified, replace <target> with an underscore _.
The -v parameter and its value (<value>) are not used to form the URI. They are used to construct the request body data.
The -s parameter and its value (<systemid>) are used to construct the request header parameter SystemId.

In the configuration file, the Resources[].Uri field indicates the URI and the Resources[].Interfaces[].Type field indicates the method.

Example:

shell

ipmcget -t service -d list      →   GET /cli/v1/service/list
ipmcset -d upgrade -v /tmp/image.hpm    →   PATCH /cli/v1/_/upgrade

Command Prompt

If the input instruction cannot be matched to a unique command, the system will display the available -t/-d commands along with their corresponding descriptions. For example:

shell

openUBMC:/->ipmcset -t se
    -t <target>
        service                 Operate with service
        sensor                  Operate with sensor
        securitybanner          Operate login security banner information
        securityenhance         Operate security enhance

shell

openUBMC:/->ipmcset -t service
    -d <dataitem>
        state                   Set service enable state
        port                    Set service port

The command description must be configured in Resources[].Interfaces[].Description. For example:

The URI of ipmcset -t service is /cli/v1/service, and the command description is Operate with service. The configuration is as follows:

json

{
    "Uri": "/cli/v1/service",
    "Interfaces": [
        {
            "Type": "PATCH",
            "Description": "Operate with service"
        }
    ]
}

The URI of ipmcset -t service -d port is /cli/v1/service/Port, and the command description is Operate with service. The configuration is as follows:

json

{
    "Uri": "/cli/v1/service/port",
    "Interfaces": [
        {
            "Type": "PATCH",
            "Description": "Set service port"
        }
    ]
}

Parameter Prompt

If the entered instruction can be uniquely matched with a command but the -v parameter is set incorrectly, the system will display the following information:

Command format → Resources[].Interfaces[].Usage
Brief description → Resources[].Interfaces[].Brief
Parameter description → Resources[].Interfaces[].ReqBody[].Name + Description. If the Description field is blank, the parameter description is not output.
Example → Resources[].Interfaces[].Example

NOTE

Each field can be configured as needed. Fields that are not displayed can be left blank, set to null, or set to "". You are advised to include at least the Usage field. The command prompt informs users of the command meaning and usage and can be configured as needed.

The command prompt format is as follows:

shell

Usage: <Command format>
<Brief description>
<Parameter description Name: Description>

Example:
    <Example>

For example, the command prompt of ipmcset -d fanmode is as follows:

shell

openUBMC:/->ipmcset -d fanmode
Usage: ipmcset -d fanmode -v <mode> [timeout]
mode:
    0   auto regulate fan speed, without parameter [timeout]
    1   manual regulate fan speed
        without parameter [timeout], default timeout(30 seconds)
        with parameter [timeout], timeout range <0-100000000>,(0 means max timeout)

Example:
    ipmcset -d fanmode -v 0
    ipmcset -d fanmode -v 1
    ipmcset -d fanmode -v 1 100

The corresponding configuration is as follows:

json

{
    "Uri": "/cli/v1/_/fanmode",
    "Interfaces": [
        {
            "Type": "PATCH",
            "Description": "Set fan mode,you can choose manual or auto",
            "Usage": "ipmcset -d fanmode -v <mode> [timeout]",
            "ReqBody": {
                "Type": "object",
                "Required": false,
                "Properties": {
                    "mode": {
                        "Required": false,
                        "Type": "integer",
                        "Validator": [
                            {
                                "Type": "Enum",
                                "Formula": [0, 1, 2]
                            }
                        ]
                    },
                    "timeout": {
                        "Type": "integer",
                        "Required": false
                    }
                }
            }
        }
    ]
}

`ReqBody` Field Description

Unlike the Redfish interface, the CLI interface does not have a traditional request body. The ReqBody configuration of CLI request body isthe parameters specified after -v in the command. The parameters correspond to the keys in ReqBody.Properties. In the preceding example, <mode> corresponds to ReqBody.Properties.mode.

Field description:

Name: indicates the parameter name.
Required: The value can be true or false. If not specified, the default value is false. true indicates that the parameter is mandatory, and false indicates that it is optional.
Description: Parameter description. The parameter following -v is used for command prompt printing. The interactive parameter is used to display the prompt.

`ReqBody` Field Data Type Adjustment

By default, the parameter following -v in the CLI interface is a string. For some commands, such as ipmcset -t sol -d timeout -v <value>, the value is an integer within the range of 0–480. Processing the value as a string would increase the configuration complexity.

For the parameter following -v in the CLI interface, that is, the ReqBody configuration, apply the following type conversion rules:

If the Type field exists and the value is an integer or a number, the type conversion is attempted. If the original data can be converted to the corresponding type, the conversion is performed. Otherwise, the original value is retained.

The following uses configuration of value in ipmcset -t sol -d timeout -v <value> as an example:

json

{
    "Name": "Value",
    "Required": true,
    "Type": "integer",
    "Validator": [
        {
            "Type": "Range",
            "Formula": [0, 480]
        }
    ],
    "Description": "\n    0        No limit\n    1-480   SOL timeout period(min)"
}

When <value> is:

xxx: The value cannot be converted to an integer, xxx is retained, and the data type validation fails.
123: The value can be converted to the integer 123, which is within the range of 0–480, so the validation succeeds.
123.0: The value can be converted to the integer 123, so the data type validation succeeds.
1234: The value can be converted to the integer 1234, which is outside the range of 0–480, so the range validation fails.
0x123: The value can be converted to the decimal integer 291, which is within the range of 0–480, so the validation succeeds.

Common Command

After a common command is delivered, it is processed by the service layer. The CLI interface mapping configuration then obtains the response data and prints it directly according to the output template. The following uses ipmcget -d version as an example.

json

{
    "Uri": "/cli/v1/_/version",
    "Interfaces": [
        {
            "Type": "GET",
            "Description": "Get openUBMC version",
            "Usage": "ipmcget -d version",
            "RspBody": {
                "ActiveVersion": "${ProcessingFlow[1]/Destination/ActiveVersion}",
                "ActiveBuildNum": "${ProcessingFlow[1]/Destination/ActiveBuildNum}",
                "ActiveReleaseDate": "${ProcessingFlow[1]/Destination/ActiveReleaseDate}",
                "BackupVersion": "${ProcessingFlow[2]/Destination/BackupVersion}",
                "AvailableVersion": "${ProcessingFlow[3]/Destination/AvailableVersion}",
                "AvailableBuildNum": "${ProcessingFlow[3]/Destination/AvailableBuildNum}"
            },
            "ProcessingFlow": [
                {
                    {
                        "Type": "Property",
                        "Path": "/bmc/kepler/UpdateService/FirmwareInventory/ActiveBMC",
                        "Interface": "bmc.kepler.UpdateService.FirmwareInfo",
                        "Destination": {
                            "Version": "ActiveVersion",
                            "BuildNum": "ActiveBuildNum",
                            "ReleaseDate": "ActiveReleaseDate"
                        }
                    },
                    {
                        "Type": "Property",
                        "Path": "/bmc/kepler/UpdateService/FirmwareInventory/BackupBMC",
                        "Interface": "bmc.kepler.UpdateService.FirmwareInfo",
                        "Destination": {
                            "Version": "BackupVersion"
                        }
                    },
                    {
                        "Type": "Property",
                        "Path": "/bmc/kepler/UpdateService/FirmwareInventory/AvailableBMC",
                        "Interface": "bmc.kepler.UpdateService.FirmwareInfo",
                        "Destination": {
                            "Version": "AvailableVersion",
                            "BuildNum": "AvailableBuildNum"
                        }
                    }
                }
            ],
            "Echoes": [
                "ipmcget/_version",
                ""
            ]
        }
    ]
}

RspBody is the interface mapping response body, which needs to be used together with the Echoes field in the output template.

Pagination Command

A pagination command retrieves a series of text entries in the same format. Since the number of entries can be very large, displaying them all at once would produce too much content, so the output is divided into multiple pages. The fllowing uses ipmcget -d operatelog as an example:

json

{
    "Uri": "/cli/v1/_/operatelog",
    "Interfaces": [
        {
            "Type": "GET",
            "Usage": "ipmcget -d operatelog",
            "Query": {
                "Skip": 0,
                "Top": 20
            },
            "Description": "Print operation log",
            "RspBody": {
                "Count": "${ProcessingFlow[1]/Destination/Count}",
                "Log": "${ProcessingFlow[1]/Destination/Log}"
            },
            "ProcessingFlow": [
                {
                    "Type": "Paging",
                    "Path": "/bmc/kepler/Managers/1/LogServices/OperateLog",
                    "Interface": "bmc.kepler.Managers.LogService",
                    "Name": "GetItems",
                    "Params": [
                        "${Query/Skip}",
                        "${Query/Top}"
                    ],
                    "Destination": {
                        "Count": "Count",
                        "Log": "Log"
                    }
                }
            ],
            "Echoes": [
                "ipmcget/_operatelog",
                ""
            ]
        }
    ]
}

In the preceding example, when ProcessingFlow contains a valid configuration with Type set to Paging, the command is recognized as a pagination command and is typically configured with the keywords Query.Skip and Query.Top. In most cases, Skip=0, Top=20 are configured, indicating that each page contains 20 entries. Pressing q exits the command, while pressing any other key displays the next page, continuing until all entries have been shown and the command exits. ProcessingFlow only requires defining the rules for fetching a single page. The mapping framework and backend components handle the pagination automatically, sending a request each time a page is fetched and updating the Skip and Top values passed to the resource for the next page.

Format Requirements for the Resource Collaboration Interface `Method`

The ipmcget -d operatelog interface is used as an example. To correctly obtain the specified text content and respond appropriately, the following format requirements must be met:

Input parameters
The input parameters contain two fields (the field names transferred in the interface mapping configuration can be different, but the fields must be included and the types and values must be correct).
- Skip: indicates the number of entries to skip, with the same meaning as the $skip query parameter in the Redfish interface.
- Top: indicates the number of entries to retrieve, with the same meaning as the $Top query parameter in the Redfish interface.
Method response
The input parameters contain two fields (the field names transferred in the interface mapping configuration can be different, but the fields must be included).
- Count: indicates the total number of entries.
- Log: indicates an array which consists of Top pieces of information requested.
Result sequence
The results obtained by the method are sorted in ascending order, while those displayed by page are printed in descending order. When the method is called to retrieve data, the data at that moment is saved. During pagination, data retrieval is based on this saved data.

Task Command

A resource collaboration method may take a long time to execute. In such cases, it is generally processed asynchronously, for example, in one-click log collection. The CLI command delivers the task and polls its progress until the task is completed or terminates abnormally. For details about the general task mechanism, see section Task in the Resource Collaboration Interface Mapping Configuration chapter in rackmount Component Interface Description.

The ipmcget -d diaginfo interface is used as an example:

shell

openUBMC:/->ipmcget -d diaginfo
Downloading...
100%
Download diagnose info to /tmp/ successfully.

An example of the corresponding interface mapping configuration is as follows:

json

{
    "Uri": "/cli/v1/_/diaginfo",
    "Interfaces": [
        {
            "Type": "GET",
            "Description": "Get diagnostic info of management subsystem",
            "Usage": "ipmcget -d diaginfo",
            "RspBody": {
                "TaskId": "${ProcessingFlow[1]/Destination/TaskId}"
            },
            "ProcessingFlow": [
                {
                    "Type": "Task",
                    "Path": "/bmc/kepler/Managers/1/LogServices",
                    "Interface": "bmc.kepler.Managers.LogServices",
                    "Name": "Dump",
                    "Params": [
                        0,
                        "${Statements/GetDestination()}"
                    ],
                    "Destination": {
                        "TaskId": "TaskId"
                    }
                }
            ],
            "Echoes": [
                "ipmcget/_diaginfo"
            ]
        }
    ]
}

Interactive Command

An interactive command is executed only after the user enters the required input. The interactive commands involved in the CLI commands can be classified into the following types:

`Y/N` Confirmation

For certain commands, you must enter Y or N to confirm whether to proceed with the next action before executing the resource collaboration interface mapping. For example, ipmcset -d reset will reboot the BMC, which is a high-risk operation and requires confirmation before proceeding.

shell

openUBMC:/->ipmcset -d reset
This operation will reboot openUBMC system.
Continue? [Y/N]:

The corresponding configuration is as follows:

json

{
    "Uri": "/cli/v1/_/reset",
    "Interfaces": [
        {
            "Type": "PATCH",
            "Usage": "ipmcset -d reset",
            "Description": "Reboot openUBMC system",
            "Confirm": {
                "Condition": true,
                "Description": "This operation will reboot openUBMC system.\nContinue? [Y/N]:"
            },
            "ProcessingFlow": [xxx],
            "Echoes": [xxx]
        }
    ]
}

Confirm.Condition: indicates whether Y/N confirmation is required. The value can be true or false. Condition can also be configured as a data reference and the reference source must be ReqBody. As shown in the following interface mapping configuration, if ReqBody.option is set to disabled, confirmation is required.
Confirm.Description: is a prompted message for Y/N confirmation. It can also be configured as a data reference and the reference source must be ReqBody.

json

"Confirm": {
    "Condition": "${Statements/condition()}",
    "Description": "WARNING: Disabling the complexity checking function may reduce the system security.\nDo you want to continue?[Y/N]:",
},
"Statements": {
    "condition": {
        "Steps": [
            {
                "Type": "Script",
                "Formula": "return ReqBody.option == 'disabled'"
            }
        ]
    }
}

Password Authentication

For security reasons, you must re-enter your login password to verify your identity when running certain commands. For example, ipmcset -t user -d state -v <username> <state>:

shell

openUBMC:/->ipmcset -t user -d state -v Test enabled
Input your password:
Enable user:Test successfully.

The corresponding configuration is as follows:

json

{
    "Uri": "/cli/v1/user/state",
    "Interfaces": [
        {
            "Type": "PATCH",
            "Usage": "ipmcset -t user -d state -v <username> [enabled|disabled]",
            "Description": "Enabled/Disabled user",
            "Authentication": {
                "Description": "Input your password:",
                "Condition": true
            },
            "ReqBody": {xxx},
            "RspBody": {xxx},
            "ProcessingFlow": [xxx],
            "Echoes": [xxx]
        }
    ]
}

Authentication.Condition: indicates whether password authentication is required. The value can be true or false. Condition can also be configured as a data reference and the reference source must be ReqBody.
Authentication.Description: is a prompted message for password authentication. Description can also be configured as a data reference and the reference source must be ReqBody.

Entering a New Password

Some commands, such as -d adduser for adding a new user, require not only entering the current user's password but also entering the new user's password twice. These password inputs produce no output.

shell

openUBMC:/->ipmcset -d adduser -v Test1
Input your password:
Password:
Confirm password:
Add user successfully.

The interface mapping configuration allows for password input without producing any output. The backend component encapsulates the plugin for entering the password twice.

json

"Statements": {
    "GetPwd": {
        "Steps": [
            {
                "Type": "Plugin",
                "Formula": "orchestrator.account.get_pwd()"
            }
        ]
    }
},
"ProcessingFlow": [
    {
        "Type": "Method",
        "Path": "/bmc/kepler/AccountService/Accounts",
        "Interface": "bmc.kepler.AccountService.ManagerAccounts",
        "Name": "New",
        "Params": [
            0,
            "${ReqBody/username}",
            "${Statements/GetPwd()[2]}",
            0,
            [1, 2, 4, 8, 16, 64, 128],
            2
        ],
        "CallIf": {
            "${Statements/GetPwd()[1]}": 0
        },
        "Destination": {
            "AccountId": "AccountId"
        }
    }
]

Output Template

Resources[].Interfaces[].Echoes is a string array. Currently, only Echoes[1] is used, indicating the built-in output template configuration. For example, if the value of Echoes[1] of ipmcget -d version is ipmcget/_version, the ipmcget/_version file must exist in the CLI interface output template path in the rackmount code repository. The file content is as follows:

shell

------------------- openUBMC INFO -------------------
Active openUBMC    Version:         {* ActiveVersion *}
Active openUBMC      Build:         {* ActiveBuildNum *}
Active openUBMC      Built:         {* ActiveReleaseDate *}
Backup openUBMC    Version:         {* BackupVersion *}
Available openUBMC Version:         {* AvailableVersion *}
Available openUBMC   Build:         {* AvailableBuildNum *}
------------------- Product INFO --------------------
Product               Name:         {* ProductName *}

Template engine rules:

{{var}}
Outputs the result of var and some special characters are escaped, so it is not recommended to use this rule.
{* var *}
Outputs the result of var and no special characters are escaped.
{% code %}
Executes a piece of Lua code, for example, {% for i = x, y do... end %}.
{# comments #}
comments is for annotation only and is not included in the output string.
{{template}}
Imports other template files. Parameters can be transferred, for example, { (file.html, { message = "Hello, World" })}.

Note

If the return value of RspBody is of the bool type, the output template can only recognize true. A value of false will be treated as nil.
If the following expression appears in the output template, the content inside echo cannot be printed. Use io.write('xxx') instead.
shell
```
if xx then
    echo('xxx')
    return
end
```

CLI Command Mapping ​

Command Prompt ​

Parameter Prompt ​

ReqBody Field Description ​

ReqBody Field Data Type Adjustment ​

Common Command ​

Pagination Command ​

Format Requirements for the Resource Collaboration Interface Method ​

Task Command ​

Interactive Command ​

Y/N Confirmation ​

Password Authentication ​

Entering a New Password ​

Output Template ​

Note ​

CLI Command Mapping

Command Prompt

Parameter Prompt

`ReqBody` Field Description

`ReqBody` Field Data Type Adjustment

Common Command

Pagination Command

Format Requirements for the Resource Collaboration Interface `Method`

Task Command

Interactive Command

`Y/N` Confirmation

Password Authentication

Entering a New Password

Output Template

Note