NVIDIA Docs Hub  Actions REST API
NVIDIA UFM Enterprise REST API Guide v6.10.0

On This Page

Actions REST API

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

    Copy
    Copied!
                
    
            
    {
	"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"
}

    Warning

    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

    Copy
    Copied!
                
    
            
    {
	"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 "
}

    Warning

    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

    Copy
    Copied!
                
    
            
    {
  "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

    Copy
    Copied!
                
    
            
    {
	"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

    Copy
    Copied!
                
    
            
    {
"identifier": "id",
"object_ids": ["<system1_id>", "<system2_id>"]/["group_id"],
"object_type": "System"/"Group"
}

    Warning

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

  • Response – N/A

    Warning

    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

    Copy
    Copied!
                
    
            
    {
  "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

    Copy
    Copied!
                
    
            
    {
  "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

    Copy
    Copied!
                
    
            
    {
  "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

Warning

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

Copy
Copied!
            

            
{
   "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:

Copy
Copied!
            

            
[
  "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:

    Copy
    Copied!
                
    
            
    {
  "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:

    Copy
    Copied!
                
    
            
    	{
   "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:

      Copy
      Copied!
                  
      
            
      {
"object_ids": ["0c42a1030079a66c", "248a0703008a850a"],
 "object_type":"System"
}

    • Example two:

      Copy
      Copied!
                  
      
            
      {
"object_ids": ["Devices"],
"object_type":"Group"
}

  • Response -

    Copy
    Copied!
                
    
            
    {
    "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 – PUT /ufmRest/actions

  • Request Content Type – application/json

  • Request Data

    Copy
    Copied!
                
    
            
    {
  "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

    Copy
    Copied!
                
    
            
    {
       "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

      Copy
      Copied!
                  
      
            
      {
  "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

      Copy
      Copied!
                  
      
            
      {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

    Copy
    Copied!
                
    
            
    {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 ufmRestV2/actions.

    • Response - redirect to job id

    • Payload:

      Copy
      Copied!
                  
      
            
      {
    "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:

    Copy
    Copied!
                
    
            
    {
    "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

© Copyright 2023, NVIDIA. Last updated on Sep 5, 2023.