Provisioning

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

The "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 "
}

The "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

Set Node Description

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

Set Hostname Provisioning Example

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

In-Band Reboot

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

This is a synchronized action (no job will be created).

Response – N/A

The 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)

Software Upgrade

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)

Firmware Upgrade

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)

Reboot

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)

Burn HDR Active Fiber Cable Transceivers

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.

Disable/Enable/Reset Ports

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)

In-Band FW Upgrade

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)

Collect System Dump

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)

Mark Device as Unhealthy

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

Mark Device as Healthy

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

Content

Space Tools

On This Page

Provisioning

Running Explicit CLI Commands

Running Predefined Template Using Its Name

Set Node Description

Set Hostname Provisioning Example

In-Band Reboot

Software Upgrade

Firmware Upgrade

Reboot

Burn HDR Active Fiber Cable Transceivers

Get List of Available Images

Upload New Cable Image

Delete Cable Image

Activate Cables Transceivers Firmware Action

Get Active Firmware Versions

Disable/Enable/Reset Ports

In-Band FW Upgrade

Collect System Dump

Collect System Dump Profile API

Mark Device as Unhealthy

Mark Device as Healthy

Content

Space Tools

Actions REST API

On This Page

Provisioning

Running Explicit CLI Commands

Running Predefined Template Using Its Name

Set Node Description

Set Hostname Provisioning Example

In-Band Reboot

Software Upgrade

Firmware Upgrade

Reboot

Burn HDR Active Fiber Cable Transceivers

Get List of Available Images

Upload New Cable Image

Delete Cable Image

Activate Cables Transceivers Firmware Action

Get Active Firmware Versions

Disable/Enable/Reset Ports

In-Band FW Upgrade

Collect System Dump

Collect System Dump Profile API

Mark Device as Unhealthy

Mark Device as Healthy