Actions REST API
Description – provisioning allows users to perform actions on a specific switch in UFM.
Request URL – /ufmRest/actions
Main Operations
Run Explicit CLI commands
Run a predefined template using the template name
Running Explicit CLI Commands
Description – perform a provisioning job on a switch using explicit CLI commands
Request URL – POST /ufmRest/actions
Request Content Type – Application/json
Request Data
{ "action": "run_cli", "identifier": "identifier", "params": { "commandline": ["<CLI_COMMAND_LINE1>", "<CLI_COMMAND_LINE2>" ], "arguments": { "globals": { "<global_arg1>": "<global_arg_val1>" }, "devices": { "<system_IP>": { "<local_arg1>": "<local_arg_val1>" } } } }, "description": "", "object_ids": ["<object ips/ids>"], "object_type": "object_type" }
WarningThe "identifier" field specifies whether to search for the object using its IP or its ID. Group objects have IDs (name) only. However, for switch provisioning, both identifiers may be used.
Response – the HTTP Response Location Header will contain URI with Job ID created for running the CLI command on the specified switches
Status Codes
202 – successful operation
400 – bad request
Running Predefined Template Using Its Name
Description – perform a Provisioning Job on a switch using the template’s name
Request URL – POST /ufmRest/actions/provisioning/<template_name>
Request Content Type – Application/json
Request Data
{ "identifier": "identifier", "params": { "arguments": { "globals": { "<global_arg1>": "<global_arg_val1>" }, "devices": { "<system_IP>": { "<local_arg1>": "<local_arg_val1>" } } } }, "description": "", "object_ids": ["<objects_ips/ids>"], "object_type": "object_type " }
WarningThe "identifier" field specifies whether to search for the object using its IP or its ID. Group objects have IDs (name) only. However, for switch provisioning, both identifiers may be used.
Response – the HTTP Response Location Header will contain URI with Job ID created for running the CLI command on the specified switches
Status Codes
202 – successful operation
400 – bad request
Description – setting a node description for unmanaged switches
Request URL – POST /ufmRest/actions
Request Content Type – Application/json
Request Data
{ "action": "set_node_description", "identifier": "id", "params": { "arguments": { "devices": { "ec0d9a03000b2640": {"description": "NodeDesc"}} } }, "description": "Set Node Decription", "object_ids": [ "ec0d9a03000b2640" ], "object_type": "System" }
Response – the HTTP Response Location Header will contain URI with Job ID created for running the CLI command on the specified switches
Note – when the node description is set, OpenSM will not be aware of this change, unless the fabric discovery is refreshed using the action detailed in "Fabric Discovery Refresh REST API".
Status Codes
202 – successful operation
400 – bad request
Description – sets hostname of the switch
Request URL – POST ufmRest/actions/provisioning/Set-Hostname
Arguments
Name
Type
Description
switch_hostname
Local (per device)
Hostname to set
Request Data
{ "identifier": "ip", "params": { "arguments": { "globals": {}, "devices": { "10.209.24.39": { "switch_hostname": "r-smg-sw18" } } } }, "object_ids": ["10.209.24.39"], "object_type": "System" }
Description – allows users to run in-band reboot in UFM. In-band reboot supports unmanaged switches only.
Request URL – POST /ufmRest/actions/inband_reboot
Request Content Type – application/json
Request Data
{ "identifier": "id", "object_ids": ["<system1_id>", "<system2_id>"]/["group_id"], "object_type": "System"/"Group" }
WarningThis is a synchronized action (no job will be created).
Response – N/A
WarningThe response will be empty unless an error has taken place. A successful response (one without errors) indicates that the reboot command was successfully sent to the switch, not that the device is rebooted.
Status Codes
202 – accepted. Reboot command was sent successfully.
400 – bad request (bad or missing parameters)
Description – allow users to run sw_upgrade in UFM
Request URL – POST /ufmRest/actions
Request Content Type – application/json
Request Data
{ "action": "sw_upgrade", "identifier": "id", "object_ids": [ "<system1_id>", "<system2_id>" ]/[ "group_id" ], "object_type": "System"/"Group", "params": { "protocol": "scp,ftp", "server": "server_ip", "username": "<username>", "password": "password", "image": "image", "path": "path" }, "description": "<description>" }
Notes
Switches SW images should be .img
Hosts SW images should be .tgz
This action is supported for both switches and hosts that have ufmagent. Job will be successfully completed once the upgrade procedure is done.
For the switch SW upgrade to take effect, make sure to reboot the switch.
Response – the HTTP Response Location Header will contain URI with job ID created for running the action
Status Codes
202 – accepted. Job ID created successfully.
400 – Bad request (bad or missing parameters)
Description – allows users to run fw_upgrade in UFM
Request URL – POST /ufmRest/actions
Request Content Type – application/json
Request Data
{ "action": "fw_upgrade", "identifier": "id", "object_ids": [ "<system1_id>", "<system2_id>" ]/[ "group_id" ], "object_type": "System"/"Group", "params": { "protocol": "ftp", "server": "server_ip", "username": "<username>", "password": "password", "image": "image", "path": "path" }, "description": "<description>" }
Notes
FW images should be placed under /path/<PSID> where the PSID is the PSID of the device, with the name “fw_image”
This action is supported for both switches and hosts that have ufmagent. Job will be successfully completed once the upgrade procedure is done.
Response – the HTTP Response Location Header will contain URI with job ID created for running the action
Status Codes
202 – accepted. Job ID created successfully.
400 – bad request (bad or missing parameters)
Description – allows users to reboot switches/hosts in UFM
Request URL – POST /ufmRest/actions
Request Content Type – application/json
Request Data
{ "action": "reboot", "identifier": "id", "object_ids": [ "<system1_id>", "<system2_id>" ]/[ "group_id" ], "object_type": "System"/"Group", "description": "<description>" }
Note – this action is supported for switches and hosts that have ufmagent. Job will be successfully completed once the upgrade procedure is done.
Response – the HTTP Response Location Header will contain URI with job ID created for running the action
Status Codes
202 – accepted. Job ID created successfully.
400 – bad request (bad or missing parameters)
This feature is supported for cables with the OPN MFS1S00-HxxV only. This feature is supported for MFS1S00-HxxV cables with NVIDIA® ConnectX®-6 HCAs and NVIDIA Quantum devices.
Description – allow user to burn MFS1S00-HxxV cables on NVIDIA Quantum switches using the LinkX tool which is part of Flint.
Request URL – POST /ufmRest/actions
Request Content Type – application/json
{
"params": {"image":"hercules2.bin"},
"action":"burn_cables_transceivers",
"object_ids": ["0002c9030060dc20"],
"object_type":"System",
"description":"",
"identifier":"id"
}
{
"params": {"image":"hercules2.bin"},
"action":" burn_cables_transceivers ",
"object_ids": ["switches"],
"object_type":"Group",
"description":"",
"identifier":"id"
}
Response – the HTTP Response Location Header will contain a URI with a job ID created for running the action
Status Codes
202 – accepted, job ID created successfully
400 – bad request (bad or missing parameters)
404 – host/systems not found
Get List of Available Images
Description – allows users to get all availebe images that could be applied on device.
Request URL – GET /ufmRest/app/images/cables
Request Content Type – Application/json
Request Data:
[
"hercules2.bin",
"hercules3.bin"
]
Status Codes
200 – updated successfully
400 – bad request (bad or missing parameters)
404 – not found.
Upload New Cable Image
Description – allows users to upload a new cable image before applying the burn MFS1S00-HxxV transceiver action.
Request URL – POST /ufmRest/app/images/cables
Request Content Type – Application/json
Request Data:
{ "file": "hercules2.bin" }
Status Codes
200 – updated successfully
400 – bad request (bad or missing parameters)
404 – not found.
Delete Cable Image
Description – allows users to delete an uploaded cable image.
Request URL – DELETE /ufmRest/app/images/cables/<image_name>
Request Content Type – Application/json
Status Codes
200 – updated successfully
400 – bad request (bad or missing parameters)
404 – not found.
Activate Cables Transceivers Firmware Action
Description – Allows users to activate burned image onto list of devices.
Request URL – POST /ufmRest/actions
Request Content Type – Application/json
Request Data:
{ "action":"activate_cables_transceivers_fw", "object_ids": ["0002c9030060dc20"], "object_type":"System", "description":"", "identifier":"id" } { "action":"activate_cables_transceivers_fw", "object_ids": ["switches"], "object_type":"Group", "description":"", "identifier":"id" }
Status Codes:
202 – Accepted
400 – bad request (bad or missing parameters)
404 – not found.
Get Active Firmware Versions
Description – This API will return a dictionary of active FW versions transceivers for the given list of devices, each active FW version transceiver will provide the following:
list of uploaded binary images that are compatible for FW version transceiver.
list of devices that have the above transceiver FW version active on them.
Request URL – POST /ufmRest/app/images/cables/fw_versions
Request Content Type – Application/json
Request Data:
Example one:
{ "object_ids": ["0c42a1030079a66c", "248a0703008a850a"], "object_type":"System" }
Example two:
{ "object_ids": ["Devices"], "object_type":"Group" }
Response -
{ "38.100.057": { "supported_images": [ "hercules2-38_100_059.bin", "hercules2-38_100_057.bin" ], "transceiver_type": "Hercules2", "devices": [ { "system_name": "sw-ufm-qm01", "guid": "0x0c42a1030079a66c", "ip": "10.209.224.32" }, { "system_name": "r-ufm77", "guid": "0x248a0703008a850a", "ip": "11.4.3.175" } ] }, "38.100.059": { "supported_images": [ "hercules2-38_100_059.bin", "hercules2-38_100_057.bin" ], "transceiver_type": " Bagheera ", "devices": [ { "system_name": "sw-ufm-qm01", "guid": "0x0c42a1030079a66c", "ip": "10.209.224.32" }, { "system_name": "r-ufm77", "guid": "0x248a0703008a850a", "ip": "11.4.3.175" } ] }, "46.120.00348": { "supported_images": [ "sec_issu_46_120_00348_dev_signed.bin" ], "transceiver_type": " Louie_did ", "devices": [ { "system_name": "sw-ufm-qm01", "guid": "0x0c42a1030079a66c", "ip": "10.209.224.32" }, { "system_name": "r-ufm77", "guid": "0x248a0703008a850a", "ip": "11.4.3.175" } ] } }
Status Codes:
202 – Accepted
400 – bad request (bad or missing parameters)
404 – not found.
Description – allows users to performs the following actions on ports: enable, disable, and reset
Request URL – POST /ufmRest/actions
Request Content Type – application/json
Request Data
{ "params": { "port_id": "port_name" }, "action": "enable,disable,reset", "object_ids": [ "system_guid" ], "object_type": "System", "description": " description", "identifier": "id" }
Response – the HTTP Response Location Header will contain URI with job ID created for running the action
Status Codes
202 – accepted. Job ID created successfully.
400 – bad request (bad or missing parameters)
Description – allows users to run in-band FW upgrade in UFM.
Request URL – POST /ufmRest/actions
Request Content Type – application/json
Request Data
{ "action": "fw_upgrade", "identifier": "id", "object_ids": ["<system1_id>", "<system2_id>"]/["group_id"], "object_type": "System"/"Group", "params": { "protocol": "inband", }, "description": "<description>" }
Notes
FW images should be placed under /opt/ufm/files/userdata/fw/<PSID> where the PSID is the PSID of the device.
This action is supported for both switches and hosts. Job will be successfully completed after the upgrade procedure on the switch has successfully finished. After the upgrade, the following actions should be performed:
For hosts – restart the openibd driver
For switches – restart the switch
Status Codes
202 – accepted. Job ID created successfully.
400 – bad request (bad or missing parameters)
Description – allows users to collect system dump for switchs/hosts/groups/links in the fabric
Request URL – POST /ufmRest/actions
Request Content Type – Application/json
Request Data Example –
For the hosts, switches, and groups
{ "action": "collect_system_dump", "identifier": "id", "object_ids": ["<system1_id>","<system2_id>"]/["group_id"], "object_type": "System"/"Group", "description": "<description>" }
For the link – POST /ufmRest/resources/links/collect_system_dump
{link_name: "<link_name>"}
Notes
This action used predefine-profile to save the collect system file
This action is supported for switches/hosts/groups/links (it will collect system dump for the endpoints of the link). The job is successfully complete after the generated system dump is saved in the external storage.
The user can configure the external storage using the REST API for the profile
Status Codes
202 – accepted, job ID created successfully
400 – bad request (bad or missing parameters)
404 – host/systems not found
Collect System Dump Profile API
Description – allows users to set remote locatino profile and external storage for System dump operation and IBDiagnet reports.
Request URL – PUT /ufmRest/app/profile/system_dump
Request Content Type – Application/json
Request Data
{protocol: "scp/sftp", server: "<server>", path: “<path>", username: "<username>", password: "<password>"}
Status Codes
200 – updated successfully
400 – bad request (bad or missing parameters)
Description – Mark device as unhealthy.
Request URL –POST /ufmRest/actions
Response - redirect to job id
Payload:
{ "params": { “action”: “isolate” or “no_discover”, “device_policy”: UNHEALTHY” } “action”: “mark_device_unhealthy”, “object_ids”:<Array of devices guid>, “object_type”: “System”, “identifier”:”id” }
Status Codes
200 – OK
404 – NOT FOUND
Description – Mark device as healthy.
Request URL – POST ufmRestV2/actions.
Payload:
{ "params": { “device_policy”: “HEALTHY” } “action”:” mark_device_healthy”, “object_ids”:<Array of devices guid>, “object_type”: “System”, “identifier”:”id” }
Response - redirect to job id
Status Codes
200 – OK
404 – NOT FOUND