|
|
22 Update Credentials REST API
22.1 Get Device Credentials
•
Description - allows users to get devices credentials in UFM
•
Request - GET /ufmRest/resources/systems/<dev_name>/credentials?
credential_types=<type>
The type parameter may be any of the following:
•
SSH_Server
•
SSH_Switch
•
MLNX-OS
•
IPMI
•
Response Data
[
{
"type": "IPMI",
"user": "admin",
"port": 623,
"timeout": "N\/A",
"name": "IPMI",
"credentials": "admin"
}
]
•
Request Content Type - application/json
•
Notes
•
If connected through HTTP the API will return asterisks (***) instead of actual text
•
If connected through HTTPS the API will return the actual password instead of asterisks
•
Status Codes
•
200 - credentials were updated successfully
•
400 - bad request (bad or missing parameters)
•
404 - system not found
22.2 Get Site Credentials
•
Description - allows users to get siet credentials in UFM
•
Request - GET /ufmRest/resources/sites/<site_name>/credentials?credential_types=<type>
The type parameter may be any of the following:
•
SSH_Server
•
SSH_Switch
•
MLNX-OS
•
IPMI
•
Response Data
[
{
"type": "IPMI",
"user": "admin",
"port": 623,
"timeout": "N\/A",
"name": "IPMI",
"credentials": "admin"
}
]
• Request Content Type - application/json
150
•
Notes
•
If connected through HTTP the API will return asterisks (***) instead of actual text
•
If connected through HTTPS the API will return the actual password instead of asterisks
•
Status Codes
•
200 - credentials were updated successfully
•
400 - bad request (bad or missing parameters)
22.3 Update Devices Credentials
•
Description - allows users to update devices credentials in UFM
•
Request - PUT /ufmRest/resources/systems/<name1>,<name2>,…/credentials
<name1> and <name2> are the system's <name> attribute that should be updated.
•
Request Data
}
"type": "SSH_Server"/"SSH_Switch"/"IPMI"/"SNMP"/"TELNET"/"MLNX_OS",
"user": "<username>",
"password": "<password>",
"port": <port>*,
"timeout": <timeout>*
"use_manual_ip": true/false,
"ip": <ip>
}
The value of this attribute can only be an integer and not a string.
•
Request Content Type - application/json
•
Notes
•
The “type” attribute is mandatory. The rest of the attributes are optional
•
If the “user” and “password” attributes were not updated before, the first update
should contain both attributes
Response
•
Status Codes
•
200 - credentials were updated successfully
•
400 - bad request (bad or missing parameters)
•
404 - system not found
22.4 Update Site Credentials
•
Description - allows users to update site credentials in UFM
•
Request - PUT /ufmRest/resources/sites/<site_name>/credentials
•
Request Data
{
"type": "SSH_Server"/"SSH_Switch"/"IPMI"/"SNMP"/"TELNET"/"MLNX_OS",
"user": "<username>",
"password": "<password>",
"port": <port>,
"timeout": <timeout>
}
• Request Content Type - application/json
151
•
Notes
•
The default site name is “default”
•
The “type” attribute is mandatory. The rest of the attributes are optional.
•
If the “user” and “password” attributes were not updated before, the first update
should contain both attributes
•
Response - N/A
•
Status Codes
•
200 - credentials were updated successfully
•
400 - bad request (bad or missing parameters)
• 404 - system not found
152
23 Groups REST API
•
Description - these interfaces allow users to retrieve information on groups, create, delete,
and update groups
•
Request URL - GET /ufmRest/app/groups
•
Main operations
•
Get all groups
•
Get a group using its name
•
Update a group using its name
•
Delete a group using its name
•
Create a group
•
Add members to a group
•
Remove members from a group
23.1 Get All Groups
•
Description - retrieve information on groups
•
Request URL - GET /ufmRest/resources/groups
•
Request Content Type - Application/json
•
Response
[
{
"description": "grp222",
"type": "Rack",
"severity": "Info",
"name": "grp2"
},
{
"description": "grp111",
"type": "Rack",
"severity": "Info",
"name": "grp1"
}
]
•
Possible Filters
•
Type - filters by type. Example:
/ufmRest/resources/groups?type=Rack
Possible values: “Rack”, “General”, “Port”
•
Members - adds members to the response. Example:
ufmRest/resources/groups?type=Rack&members=true
•
extend_members
/resources/groups?members=true&extend_members=true
•
device_id
/resources/groups?device_id=0008f10001085600
• Response:
153
[
{
"description": "grp222",
"type": "Rack",
"severity":"Info",
"members": [ "0002c90300a7ccf0", "0002c9030060dc20"],
"name": "grp2"
},
{
"description": "grp111",
"type": "Rack",
"severity": "Info",
"members": [ "0002c903007e50a0" ],
"name": "grp1"
}
]
•
Status Codes
•
200 - OK
23.2 Get Group Using Its Name
•
Description - Retrieve information on a group using its name
•
Request URL - GET ufmRest/resources/groups/<group_name>
•
Request Content Type - Application/json
•
Response
[
{
"description": "grp111",
"type": "Rack",
"severity": "Info",
"name": "grp1"
}
]
•
Possible Filters
•
Members - adds members to the response. Example:
/ufmRest/resources/groups/grp1?members=true
•
Status Codes
•
200 - OK
23.3 Update Group Using Name
•
Description - update a group using its name
•
Request URL - PUT ufmRest/resources/groups/<group_name>
•
Request Content Type - Application/json
•
Request Data
{
"description*": "new_desc"
}
*This is the only attribute that can be updated.
•
Status Codes
•
200 - OK
• 400 - BAD REQUEST
154
23.4 Delete Group Using Name
•
Description - delete a group using its name
•
Request URL - DELETE ufmRest/resources/groups/<group_name>
•
Request Content Type - Application/json
•
Request Data - N/A
•
Status Codes
•
202 - accepted
23.5 Create Group
•
Description - create a new group
•
Request URL - POST ufmRest/resources/groups/
•
Request Content Type - Application/json
•
Request Data
{
"description*": "new_desc",
"type**": "group_type",
"name***": "group_name"
}
* Optional attribute.
** Mandatory attribute. Can only be “Rack” or “General”, “Port”.
*** Mandatory attribute.
•
Status Codes
•
201 - created with the link to the group object
•
400 - BAD REQUEST
23.6 Add Members to Group
•
Description - add members to an existing group
•
Request URL - POST /ufmRest/resources/groups/<group_name>/members
•
Request Content Type - Application/json
•
Request Data
{
"object_ids": ["0002c90300a7ccf0", "0002c9030060dc20"]
}
•
Status Codes
•
202 - accepted
•
400 - BAD REQUEST
23.7 Remove Members From Group
• Description - remove members from an existing group
155
•
Request URL - DELETE /ufmRest/resources/groups/<group_name>/members
•
Request Content Type - Application/json
•
Request Data
{
"object_ids": ["0002c90300a7ccf0", "0002c9030060dc20"]
}
•
Note - to remove all members of a group, the object_ids argument in the request data can be
left empty
•
Status Codes
•
202 - accepted
23.8 Apply Software Upgrade or Firmware Upgrade
Action
•
Description - allows user to apply software upgrade action on group of switches or firmware
upgrade action on group of hosts.
•
Request URL - POST /ufmRestV2/actions
•
Request Content Type - Application/json
•
Request Data
{
"params": {
"username": "admin",
"password": "admin",
"path": "/tmp",
"image": "software_upgrade.img",
"protocol": "ftp",
"server": "10.20.30.40"
},
"description": "",
"action": "sw_upgrade",
"object_ids": [
"host"
],
"object_type": "Group",
"identifier": "id"
}
•
Status Codes
•
202 - accepted
•
400 - bad request
• 404 - not found
156
24 Users REST API
•
Description - these interfaces are used for managing UFM users by getting, creating,
updating, and deleting them
•
Request URL - /ufmRest/app/users
•
Main Operations
•
Get all users
•
Get a user by name
•
Create a user
•
Update a user
•
Delete a user
Note that in UFM Appliance, only TENANT users can be managed.
24.1 Get All Users
•
Description - lists all users in UFM
•
Request URL - GET /ufmRest/app/users
•
Request Content Type - Application/json
•
Response
[
{
"name": "admin-3",
"group": "System_Admin",
"id": 3
},
{
"name": "tenant-1",
"group": "Tenant",
"id": 4
}
]
•
Status Codes
•
200 - OK
24.2 Get User by Name
•
Description - fet a specific user using its name
•
Request URL - GET /ufmRest/app/users/<name>
•
Request Content Type - Application/json
•
Response
{
"name": "admin",
"group" "System_Admin",
"id": "1"
}
•
Status Codes
•
200 - OK
• 404 - NOT FOUND
157
24.3 Create User
•
Description - creates a new user
•
Request URL - POST /ufmRest/app/users
•
Request Content Type - Application/json
•
Request Data Parameters
Name
Values
Default
Description
Mandatory/
Optional
name
String.
None
Name of user
Mandatory
Minimum length is 4.
Maximum length is 30,
composed of alphanumeric
characters and "_", "-".
group
String. One of the following:
None
Name of group
Mandatory
•
"System_Admin",
•
"Fabric_Admin",
•
"Fabric_Operator",
•
"Monitoring_Only",
•
"Tenant"
password
String.
None
User’s password
Mandatory
Minimum length is 4.
Maximum length is 30,
composed of alphanumeric and
"_" characters
•
Request Data Example
{
"name": "ufm-tenant",
"group": "Tenant",
"password": "655478"
}
•
Response
{
"name": "ufm-tenant"
}
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
24.4 Update User
•
Description - updates user’s password
•
Request URL - PUT /ufmRest/app/users/<name>
•
Request Content Type - Application/json
• Request Data Parameters
158
Name
Values
Default
Description
Mandatory/
Optional
password
String.
None
User’s password
Mandatory
Minimum length is 4.
Maximum length is 30,
composed of alphanumeric
and "_" characters
•
Request Data Example
{
"password": "45364nnfgd"
}
•
Response - returns the username in the response body. Example:
{
"name": "admin"
}
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
24.5 Delete User
•
Description - deletes an existing user. Note that “admin” user cannot be deleted.
•
Request URL - DELETE /ufmRest/app/users/<name>
•
Request Content Type - Application/json
•
Response - N/A
•
Status Codes
•
204 - NO CONTENT
•
400 - BAD REQUEST
• 404 - NOT FOUND
159
25 Telemetry REST API
•
Description - returns information whether the feature is enabled or not
•
Request URL - GET / ufmRest/app/ufm_config
•
Request Content Type - Application/json
•
Response
{
"ls_auditing": "Disabled",
"monitoring_mode": "Disabled",
"syslog": "Disabled",
"license_state": "valid",
"license_state_info": "N\/A",
"telemetry": "<telemetry_status>"(Enabled/Disabled)
}
25.1 Top X Telemetry Sessions REST API
•
Description - returns information on the Top X telemetry session
•
Request URL - GET /ufmRest/telemetry?
type=topX&membersType=Ports&PickBy=PortTXPackets&limit=15&attributes=[additonal_attrib
utes]
•
Request Content Type - Application/json
•
Response
[
{
"name": "r-dmz-ufm131 mlx5_0",
"guid": "0c42a103008b3bd0_1",
"PortRcvPktsExtended_Rate": 1993291398.4024506,
"phy_received_bits_Rate": 1993291398.4024506,
"PortRcvDataExtended_Rate": 7973165593.609802
},
{
"name": "r-dmz-ufm131 mlx5_1",
"guid": "0c42a103008b3bd1_2",
"PortRcvPktsExtended_Rate": 1993289961.4256535,
"phy_received_bits_Rate": 1993289961.4256535,
"PortRcvDataExtended_Rate": 7973159845.702614
}
]
25.2 History Telemetry Sessions
•
Description - returns information on the history telemetry session
•
Request URL - GET /ufmRest/telemetry?
type=history&membersType=Ports&attributes=[attributes_list]&members=[members_list_guid
s]&function=RAW&start_time=-1h&end_time=-0min
type=history&membersType=Device&attributes=[Infiniband_PckInRate]&function=RA
W&result_format=Port&members=[ec0d9a03007d7f0a]&start_time=-5min&end_time=
-0min
•
Request Content Type - Application/json
• Response
{
160
'data': {
'2021-12-01 19:12:36': {
'Port': {
'ec0d9a03007d7f0a_1': {
'statistics': {'Infiniband_PckInRate': 1.0},
'guid': 'ec0d9a03007d7f0a_1',
'name': 'ufm-host87 mlx5_0'
}
}
}
}, 'members': [{
'description': 'Computer IB Port',
'number': 1,
'external_number': 1,
'physical_state': 'Link Up',
'path': 'default \/ Computer: ufm-host87 \/ HCA-1\/1',
'tier': 1,
'high_ber_severity': 'N\/A',
'lid': 1,
'mirror': 'disable',
'logical_state': 'Active',
'capabilities': ['healthy_operations', 'reset', 'disable'],
'mtu': 4096,
'peer_port_dname': '11',
'severity': 'Info',
'active_speed': 'EDR',
'enabled_speed': ['SDR', 'DDR', 'QDR', 'FDR', 'EDR'],
'supported_speed': ['SDR', 'DDR', 'QDR', 'FDR', 'EDR'],
'active_width': '4x',
'enabled_width': ['1x', '4x'],
'supported_width': ['1x', '4x'],
'dname': 'HCA-1\/1',
'peer_node_name': 'switchib',
'peer': 'ec0d9a030029dba0_11',
'peer_node_guid': 'ec0d9a030029dba0',
'systemID': 'ec0d9a03007d7f0a',
'node_description': 'ufm-host87 mlx5_0',
'name': 'ec0d9a03007d7f0a_1',
'module': 'N\/A',
'peer_lid': 5,
'peer_guid': 'ec0d9a030029dba0',
'peer_node_description': 'switchib:11',
'guid': 'ec0d9a03007d7f0a',
'system_name': 'ufm-host87',
'system_ip': '0.0.0.0',
'peer_ip': '0.0.0.0',
'system_capabilities': ['fw_inband_upgrade', 'mark_device_unhealthy'],
'system_mirroring_template': false
}]
}
161
26 Events Policy REST API
•
Description - these interfaces are used for retrieving information on and updating existing
event policies in UFM
•
Request URL - /ufmRest/app/events_policy
•
Main operations
•
Get all events policies
•
Get an events policy using its ID
•
Update a specific events policy
26.1 Get All Events Policies
•
Description - retrieve information on all events policies in UFM
•
Request URL - GET /ufmRest/app/events_policy/
•
Request Content Type - Application/json
•
Request Data - N/A
•
Response
{
"133": {
"severity": "Minor",
"to_snmp": false,
"use_alarm": true,
"threshold": 10.0,
"to_syslog": false,
"policy_object": "Port",
"duration": 300,
"to_ui": true,
"to_mail": false,
"call_script": false,
"to_log": true,
"description": "Port Normalized Transmit Wait",
"action":"Isolated"
},
"130": {
"severity": "Minor",
"to_snmp": false,
"use_alarm": true,
"threshold": 1.0,
"to_syslog": false,
"policy_object": "Port",
"duration": 0,
"to_ui": true,
"to_mail": false,
"call_script": false,
"to_log": true,
"description": "Non-optimal link width"
}
}
•
Possible Filters - may be used to filter the request:
•
ids - retrieves information on events policies per ID
Example:
GET /ufmRest/app/events_policy?ids=133,135
•
Status Codes
•
200 - OK
26.2 Get Events Policy
•
Description - retrieve information on an events policy using its ID
•
Request URL - GET /ufmRest/app/events_policy/<policy_id>
• Request Content Type - Application/json
162
•
Request Data - N/A
•
Response
{
"severity": "Minor",
"to_snmp": false,
"use_alarm": true,
"threshold": 10.0,
"to_syslog": false,
"policy_object": "Port",
"duration": 300,
"to_ui": true,
"to_mail": false,
"call_script": false,
"to_log": true,
"description": "Port Normalized Transmit Wait",
"action":"Isolated"
}
•
Status Codes
•
200 - OK
26.3 Update Events Policy
•
Description - update an existing events policy using its ID
•
Request URL - PUT /ufmRest/app/events_policy/<policy_id>
•
Request Content Type - Application/json
•
Request Data
{
"duration": 10,
"to_log": true,
"to_syslog": true,
"to_snmp": true,
"to_ui": true,
"to_mail": true,
"use_alarm": true,
"threshold": 10,
"call_script":true,
"severity": "Warning",
"action": "Isolated"
}
•
Response - N/A
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
26.4 Update Events Policies
•
Description - update multiple existing event policies
•
Request URL - PATCH /ufmRest/app/events_policy
•
Request Content Type - Application/json
• Request Data
[
{
"name": "64",
"to_log": true,
"to_mail": false,
"to_snmp": false,
"to_syslog": false,
"to_ui": true,
"use_alarm": false
},
{
"name": "65",
"to_log": true,
"to_mail": false,
163
"to_snmp": false,
"to_syslog": false,
"to_ui": true,
"use_alarm": true
},
{
"name": "66",
"to_log": true,
"to_mail": false,
"to_snmp": false,
"to_syslog": false,
"to_ui": true,
"use_alarm": false
}
]
•
Response - N/A
•
Status Codes
•
200 - OK
• 400 - BAD REQUEST
164
27 Application Object Collection Versioning REST
API
27.1 Get Application Object Collection Versioning
•
Request URL - GET /ufmRest/app/versioning
•
Request Content Type - Application/json
• Response
{
"event_policies_version": 216,
"sites_version": 1457,
"alarms_version": 25296,
"traps_version": 41392,
"templates_version": 4,
"users_version": 3,
"servers_version": 3762,
"switches_version": 225,
"ports_version": 1782,
"links_version": 198,
"modules_version": 198,
"submodules_version": 0,
"mirror_template_version": 0,
"saps_version": 6,
"groups_version": 24,
"objects_groups_version": 6,
"smconfs_version": 1
}
165
28 Reports REST API
•
Description - manages UFM reports by starting, stopping, and retrieving them
•
Request URL - /ufmRest/reports
•
Main operations
•
Start a report
•
Stop a report
•
Get a report
•
Get the last report
28.1 Start Report
•
Description - start a new report
•
Request URL - POST /ufmRest/reports/<report_type>
•
Request Content Type - Application/json
•
Note
•
report_type should be one of the following: Fabric_Health, UFM_Health, or
Topology_Compare
•
Request Data
•
Topology_Compare reports - request data should be the topology file to which UFM will
compare the current topology
•
UFM_Health reports - N/A
• Fabric_Health reports:
{
"duplicate_nodes": true,
"map_guids_desc": true,
"firmware": true
}
At least 1 parameter should be passed to the API.
Name
Values
Defaul
Dependent
Description
t
On*
duplicate_nodes Boolean
False
Lists all nodes with same
node description. Does not
include switches with the
same description.
map_guids_desc Boolean
False
duplicate_node Enables the usage of a
s
mapping file (between node
GUID and node description)
when running duplicate
node description analysis of
the fabric
ufm_alarms
Boolean
False
Lists all open alarms in UFM
166
Name
Values
Defaul
Dependent
Description
t
On*
sm_state
Boolean
False
Verifies that:
•
There is only one
active (master)
Subnet Manager
in the fabric;
•
The master is
selected
according to
highest priority
and lowest port
GUID;
• The report lists
all SMs in the
fabric with their
attributes
firmware
Boolean
False
Checks for firmware
inconsistencies. For each
device model in the fabric,
the test finds the latest
installed version of the
firmware and reports
devices with older versions.
cables
Boolean
False
Reports cable information as
stored in EEPROM on each
port: cable vendor, type,
length and serial number
cables_errors_o
Boolean
False
Cables
errors_only flag for cables
nly
non_opt_links
Boolean
False
Performs a full-fabric
discovery and reports 'non-
responsive' ports with their
path
non_opt_speed_
Boolean
False
Enables link speed and link
width
width checks
link_speed
["ALL", "SDR",
"ALL"
non_opt_speed
Checks if link speed is
"DDR", "QDR",
_width
optimally used
"FDR_10", "FDR",
"EDR"]
Link_width
["ALL", "SDR",
"ALL"
non_opt_speed
Checks if link width is
"DDR", "QDR",
_width
optimally used
"FDR_10", "FDR",
"EDR"]
eye_open
Boolean
False
Lists Eye-Opener
information for each link
min_bound
Integer
22
eye_open
Minimum bound for
eye_open check
max_bound
Integer
65
eye_open
Maximum bound for
eye_open check
167
Name
Values
Defaul
Dependent
Description
t
On*
eye_open_errors
Boolean
False
eye_open
errors_only flag for
_only
eye_open
duplicate_zero_
Boolean
False
Lists all ports with same LID
and_lids
or zero LID value
effective_ber_c
Boolean
True
Lists errors and warnings for
heck
Effective Ber
phy_port_grade Boolean
False
Physical port grade
information
For example: “map_guids_desc” is dependent on “duplicate_nodes” in the
sense that to set “map_guids_desc”, “duplicate_nodes” has to be set to True.
•
Response
{
"report_id": 4
}
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
28.2 Stop Report
•
Description - stops a report using its ID
•
Request URL - DELETE /ufmRest/reports/<report_id>
•
Request Content Type - Application/json
•
Response - N/A
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
28.3 Get Report
•
Description - retrieve report's result using its ID
•
Request URL - GET /ufmRest/reports/<report_id>
•
Request Content Type - Application/json
• Response
{
"date": "2018-04-07 05:38:13",
"sections": [
{
"status": {
"severity": "Info",
"value": ""
},
"elements": [
{
"Warnings": "0",
"Errors": "0",
168
"Fabric Test": "Non-unique Node Descriptions",
"Total": "0"
},
{
"Warnings": "0",
"Errors": "0",
"Fabric Test": "Firmware Versions",
"Total": "0"
},
{
"Warnings": "0",
"Errors": "0",
"Fabric Test": "Total:",
"Total": "0"
}
],
"description": "",
"title": "Report Summary"
},
{
"status": {
"severity": "Info",
"value": ""
},
"elements": [
{
"Count": "1",
"Device Type": "EDR",
"Non Active Ports": "32",
"Active Ports": "4",
"Total Ports": "36"
},
{
"Count": "1",
"Device Type": "SX6036",
"Non Active Ports": "25",
"Active Ports": "11",
"Total Ports": "36"
},
{
"Count": "16",
"Device Type": "Computer",
"Non Active Ports": "0",
"Active Ports": "21",
"Total Ports": "21"
},
{
"Count": "5",
"Device Type": "MSB7700",
"Non Active Ports": "156",
"Active Ports": "24",
"Total Ports": "180"
},
{
"Count": "23",
"Device Type": "Total:",
"Non Active Ports": "213",
"Active Ports": "60",
"Total Ports": "273"
}
],
"description": "",
"title": "Fabric Summary"
},
{
"status": {
"severity": "Info",
"value": "Completed Successfully."
},
"description": "Lists all nodes with same node description. Does not include switches with the
same description. ",
"title": "Non-unique Node Descriptions"
},
{
"status": {
"severity": "Info",
"value": "Completed Successfully."
},
"description": "Checks for firmware inconsistencies. For each device model in the fabric, the
test finds the latest installed version of the firmware and reports devices with older versions. ",
"title": "Firmware Versions"
}
],
"Created by": "admin",
"title": "Fabric Health Report"
}
•
Status Codes
•
200 - OK
•
202 - ACCEPTED (processing report)
• 400 - BAD REQUEST
169
28.4 Get Last Report
•
Description - get the results of the last generated report using its type
•
Request URL - GET /ufmRest/reports/last_report/<report_type>
•
Request Content Type - Application/json
•
Response - See response in the previous chapter
•
Status Codes
•
200 - OK
• 400 - BAD REQUEST
170
29 Periodic Fabric Health REST API
29.1 Get All Periodic Health Tasks
•
URL: GET ufmRestV2/periodic_health
•
Response:
[
{
"report_id": "1451",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:23:10"
},
{
"report_id": "1452",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:24:16"
},
{
"report_id": "1453",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:25:02"
},
{
"report_id": "1454",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:26:08"
},
{
"report_id": "1455",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:27:13"
},
{
"report_id": "1456",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:28:19"
},
{
"report_id": "1457",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:29:05"
},
{
"report_id": "1458",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:30:11"
},
{
"report_id": "1460",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:31:16"
},
{
"report_id": "1461",
"report_scope": "Periodic",
"timestamp": "2022-07-12 14:32:02"
}
]
29.2 Get Periodic Health Task
•
URL: GET ufmRestV2/periodic_health/<report_id>
•
Response: The last complete fabric report.
29.2.1 Enable Feature
•
URL: POST ufmRestV2/periodic_health/start
•
Response: 202
29.2.2 Disable Feature
•
URL: POST ufmRestV2/periodic_health/stop
• Response: 202
171
29.2.3 Set Run Parameters
•
URL: POST ufmRestV2/periodic_health/configure
•
Response:
{ "duplicate_nodes": true, "map_guids_desc": false, "ufm_alarms": true, "sm_state": true, "firmware": false,
"cables": false, "non_opt_links": true, "non_opt_speed_width": true, "link_speed": "ALL", "link_width":
"ALL", "eye_open": false, "duplicate_zero_and_lids": false, "effective_ber_check": false,
"symbol_ber_check": false, "phy_port_grade": false }
29.2.4 Get Run Parameters
•
URL: GET ufmRestV2/periodic_health/configure
•
Response:
{ "duplicate_nodes": true, "map_guids_desc": false, "ufm_alarms": true, "sm_state": true, "firmware": false,
"cables": false, "non_opt_links": true, "non_opt_speed_width": true, "link_speed": "ALL", "link_width":
"ALL", "eye_open": false, "duplicate_zero_and_lids": false, "effective_ber_check": false,
"symbol_ber_check": false, "phy_port_grade": false }
29.2.5 Get Last Report
•
URL: GET ufmRestV2/periodic_health/last_report
• Response: The last complete fabric report.
172
30 SMTP Configuration REST API
•
Description - manages SMTP configurations in UFM
•
Request URL - /ufmRest/app/smtp
•
Main operations
•
Get SMTP configuration
•
Update SMTP configuration
30.1 Get SMTP Configuration
•
Description - get information on SMTP configuration settings in UFM
•
Request URL - GET /ufmRest/app/smtp
•
Request Content Type - application/json
•
Response
{
"sender":"AnasBadaha <ufmvpi@gmail.com>",
"server":"smtp.gmail.com",
"pwd":"123456ufmvpi",
"user":"ufmvpi",
"use_ssl":true,
"use_authentication":true,
"port":465
}
•
Status Codes
•
200 - OK
30.2 Update SMTP Configuration
•
Description - update the settings of the current SMTP configuration in UFM
•
Request URL - PUT /ufmRest/app/smtp
•
Request Content Type - application/json
•
Request Data
{
"sender_name":"AnasBadaha",
"sender_addr":"ufmvpi@gmail.com",
"server":"smtp.gmail.com",
"pwd":"123456ufmvpi",
"user":"ufmvpi",
"use_ssl":true,
"port":465,
"use_authentication":true
}
•
Status Codes
•
200 - OK
• 400 - BAD REQUEST
173
31 Events and Periodic Reports Recipients
Configuration REST API
•
Description - manages recipients of events and periodic reports, including getting, adding,
removing, and deleting existing recipients
•
Request URL - GET /ufmRest/app/smtp/recipients
•
Main operations
•
Get recipients list
•
Add new recipients
•
Delete existing recipients
•
Update existing recipients
31.1 Get Recipients
•
Description - get recipients list of events or periodic reports
•
Request URL - GET /ufmRest/app/smtp/recipients ?recipients_type=("events",
"periodic_report")
Note: recipients_type should either be “events” or “periodic_report”
•
Request Content Type - application/json
•
Response
{
"recipients":[
"anasb@mellanox.com"
],
"recipients_type":"events"
}
•
Status Codes
•
200 - OK
•
404 - bad request
31.2 Add Recipients
•
Description - adds new recipients of the events or periodic reports
•
Request URL - POST /ufmRest/app/smtp/recipients
•
Request Content Type - application/json
•
Request Data
{
"recipients":[
"anasb@mellanox.com"
],
"recipients_type":"events"
}
•
Status Codes
•
201 - created
• 404 - bad request
174
31.3 Delete Recipients
•
Description - deletes existing recipients from the events or periodic reports
•
Request URL - POST /ufmRest/app/smtp/recipients
•
Request Content Type - application/json
•
Request Data
{
"recipients":[
"anasb@mellanox.com"
],
"recipients_type":"events"
}
•
Status Codes
•
204 - NO CONTENT
•
404 - bad request
31.4 Update Recipients
•
Description - updates the recipients of the events or periodic reports
•
Request URL - PUT /ufmRest/app/smtp/recipients
•
Request Content Type - application/json
•
Request Data
{
"old_recipients":[
"anasb@mellanox.com"
],
"new_recipients":[
"new@mellanox.com"
],
"recipients_type":"events"
}
•
Status Codes
•
200 - OK
• 404 - bad request
175
32 SM Configuration REST API
•
Description - these interfaces are used for configuring SM properties
•
Request URL - /ufmRest/app/smconf
•
Main operations:
•
GET configuration
•
Update configuration
32.1 Get SM Configuration
•
Description - get any value for OpenSM configurations by sending the key_name
•
Request URL - GET /ufmRest/app/smconf?param_name=<sm_configuration_key_name>
•
Request Content Type - application/json
•
Response - Sent key value
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
•
Request URL example - /ufmRest/app/smconf?param_name
•
Response -
{
"m_key": "0x0",
"sm_key": "0x1",
"sa_key": "0x1",
"m_key_lease_period": 60,
"no_partition_enforcement": false,
"vl_stall_count": "0x7",
"leaf_vl_stall_count": "0x7",
"sm_priority": 15,
"ignore_other_sm": false,
"sminfo_polling_timeout": 5000,
"polling_retry_number": 4,
"honor_guid2lid_file": false,
"max_wire_smps": 8,
"transaction_timeout": 200,
"max_msg_fifo_timeout": 10000,
"single_thread": false,
"log_file": "\/opt\/ufm\/files\/log\/opensm.log",
"dump_files_dir": "\/opt\/ufm\/files\/log\/",
"sa_db_file": "(null)",
"no_clients_rereg": false,
"disable_multicast": false,
"exit_on_fatal": true,
"routing_engine_active": "minhop",
"lid_matrix_dump_file": "\/opt\/ufm\/files\/conf\/opensm\/lid_matrix.conf",
"lfts_file": "\/opt\/ufm\/files\/conf\/opensm\/lfts.conf",
"root_guid_file": "\/opt\/ufm\/files\/conf\/opensm\/root_guid.conf",
"cn_guid_file": "(null)",
"ids_guid_file": "(null)",
"guid_routing_order_file": "(null)",
"node_name_map_file": "(null)",
"qos": 0,
"qos_options": {
"default": {
"sl2vl": {
"0": 0,
"1": 1,
"2": 2,
"3": 3,
"4": 0,
"5": 1,
"6": 2,
"7": 3
}
},
"hca": {
"sl2vl": {
"0": 0,
"1": 1,
"2": 2,
"3": 3,
"4": 0,
"5": 1,
"6": 2,
"7": 3
}
},
"switchPort0": {
176
"sl2vl": {
"0": 0,
"1": 1,
"2": 2,
"3": 3,
"4": 0,
"5": 1,
"6": 2,
"7": 3
}
},
"switchExternalPorts": {
"sl2vl": {
"0": 0,
"1": 1,
"2": 2,
"3": 3,
"4": 0,
"5": 1,
"6": 2,
"7": 3
}
},
"router": {
"sl2vl": {
"0": 0,
"1": 1,
"2": 2,
"3": 3,
"4": 0,
"5": 1,
"6": 2,
"7": 3
}
}
},
"subnet_prefix": "0xfe80000000000000",
"lmc": 0,
"packet_lifetime": "0x12",
"force_link_speed": "Max_Supported",
"head_of_queue_lifetime": "0x12",
"leaf_head_of_queue_lifetime": "0x10",
"sl_confs": {
},
"max_op_vls": 3,
"subnet_timeout": 18,
"local_phy_errors_threshold": "0x8",
"overrun_errors_threshold": "0x8",
"sweep_interval": 10,
"reassign_lids": false,
"force_heavy_sweep": false,
"sweep_on_trap": true,
"force_log_flush": false,
"log_flags": [
"Error",
"Info"
],
"log_max_size": 4096,
"accum_log_file": true,
"routing_engine_names": [
"minhop"
],
"connect_roots": false,
"use_ucast_cache": true,
"m_key_per_port": false,
"m_key_lookup": false,
"sa_enhanced_trust_model": false,
"sa_etm_allow_untrusted_guidinfo_rec": false,
"sa_etm_allow_guidinfo_rec_by_vf": false,
"sa_etm_allow_untrusted_proxy_requests": false,
"sa_check_sgid_spoofing": true,
"sa_etm_max_num_mcgs": 128,
"sa_etm_max_num_srvcs": 32,
"sa_etm_max_num_event_subs": 32,
"mlnx_congestion_control": 0,
"congestion_control_policy_file": "\/opt\/ufm\/files\/conf\/opensm\/cc-policy.conf",
"ar_sl_mask": "0xffff",
"dfp_max_cas_on_spine": 2,
"dfp_down_up_turns_mode": 0,
"name": "default"
}
32.2 Set SM Configuration
•
Description - update the OpenSM configurations by REST API
•
Request URL - PUT /ufmRest/app/smconf
•
Request Content Type - application/json
• Request Data -
{
177
“sm_configuration_key_name”: “sm_configuration_key_value”,
“sm_configuration_key_name2”: “sm_configuration_key_value2”,
}
•
Response - sent key value
•
Status codes
•
200 - OK
• 400 - BAD REQUEST
178
33 Enhanced QoS REST API
•
Description - configures QoS settings for physical and virtual ports. Through this feature,
users can set specific values for guaranteed bandwidth, and assign a specific rate limit per
SL.
•
Request URL - /ufmRest/resources/sl_qos/
•
Main operations
•
Bandwidth Names
•
Get bandwidth names
•
Get a specific bandwidth name
•
Delete a specific bandwidth name
•
Update a specific bandwidth name
•
Add a new bandwidth name
•
Ports Rules
•
Get all ports rules
•
Get specific ports rules
•
Delete specific ports rules
•
Update specific ports rules
•
Add new ports rules
33.1 Bandwidth Names REST API
33.1.1 Get Bandwidth Names
•
Description - get all saved bandwidth names (bandwidths values are in Mb/s)
•
Request URL - GET /ufmRest/resources/sl_qos/names
•
Request Content Type - application/json
•
Response
{
"bw1": 50,
"bw2": 100,
"bw4": 90,
"bw5": 80
}
•
Status Codes
•
200 - OK
33.2 Get Specific Bandwidth Name
•
Description - get a specific bandwidth name
•
Request URL - GET ufmRest/resources/sl_qos/names? name=bw1
•
Request Content Type - application/json
•
Response
50
•
Status Codes
•
200 - OK
• 404 - NOT FOUND
179
33.3 Delete Specific Bandwidth Name
•
Description - deletes a specific bandwidth name
•
Request URL - DELETE ufmRest/resources/sl_qos/names? name=bw1
•
Request Content Type - application/json
•
Status Codes
•
202 - NO CONTENT
•
400 - BAD REQUEST
•
404 - NOT FOUND
33.4 Update Specific Bandwidth Name
•
Description - updates a specific bandwidth name (bandwidth values are in Mb/s)
•
Request URL - PUT ufmRest/resources/sl_qos/names /<bw_name>
•
Request Content Type - application/json
•
Request Data - rate limit integer value:
70
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
•
404 - NOT FOUND
33.5 Add New Bandwidth Name
•
Description - adds a new bandwidth name
•
Request URL - POST ufmRest/resources/sl_qos/names
•
Request Content Type - application/json
•
Request Data
{
"bw1": 50,
"bw2": 60,
"bw3": 200,
"bw4": 50
}
•
Status Codes
•
201 - created
•
400 - BAD REQUEST
33.6 Ports Rules REST API
33.6.1 Get All Ports Rules
•
Description - get all configured physical and virtual ports rules
•
Request URL -
•
GET ufmRest/resources/sl_qos/rules - to get all physical ports rules
•
GET ufmRest/resources/sl_qos/vport_rules - to get all virtual ports rules
• Request Content Type - application/json
180
•
Response
{
"rules": {
"default": {
"sl_list": {
"1": "bw1",
"3": "bw2",
"all": "bw1"
}
},
"2c90000000000025": {
"sl_list": {
"1": "bw2"
}
}
}
}
•
Status Codes
•
200 - OK
33.7 Get Specific Ports Rules
•
Description - get Rules for specific physical or virtual ports
•
Request URL -
•
GET ufmRest/resources/sl_qos/rules?guid_list= default, 2c90000000025 - to get
specific physical ports rules
•
GET ufmRest/resources/sl_qos/vport_rules?guid_list= default, 2c90000000025 - to get
specific virtual ports rules
•
Request Content Type - application/json
•
Response
{
"rules": {
"default": {
"sl_list": {
"1": "bw1",
"3": "bw2",
"all": "bw1"
}
},
"2c90000000000025": {
"sl_list": {
"1": "bw2"
}
}
}
}
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
•
404 - NOT FOUND
33.8 Delete Specific Ports Rules
•
Description - delete rules for specific physical or virtual ports
•
Request URL -
•
DELETE ufmRest/resources/sl_qos/rules?guid_list= default, 2c90000000025 - to delete
physical ports rules
•
DELETE ufmRest/resources/sl_qos/vport_rules?guid_list= default, 2c90000000025 - to
delete virtual ports rules
• Request Content Type - application/json
181
•
Status Codes
•
204 - NO CONTENT
•
400 - BAD REQUEST
•
404 - NOT FOUND
33.9 Update Specific Ports Rules
•
Description - update rules for specific physical or virtual ports
•
Request URL -
•
PUT ufmRest/resources/sl_qos/rules/<guid> - to update specific physical port rules
•
PUT ufmRest/resources/sl_qos/vport_rules/<guid> - to update specific virtual port
rules
•
Request Content Type - application/json
•
Request Data
{
"sl_list": {
"3": "bw1",
"3": "bw2",
"all": "bw1"
}
}
•
Status Codes
•
200 - OK
•
400 - BAD REQUEST
•
404 - NOT FOUND
33.10 Add New Ports Rules
•
Description - add new rules for specific physical or virtual ports
•
Request URL -
•
POST ufmRest/resources/sl_qos/rules - to add new physical ports rules
•
POST ufmRest/resources/sl_qos/vport_rules - to add new virtual ports rules
•
Request Content Type - application/json
•
Request Data
{
"rules": {
"default": {
"sl_list": {
"1": "bw1",
"3": "bw2",
"all": "bw1"
}
},
"2c90000000000025": {
"sl_list": {
"1": "bw2"
}
}
}
}
•
Status Codes
•
201 - created
• 400 - BAD REQUEST
182
34 NVIDIA SHARP REST API
34.1 SHARP Reservations APIs
SHARPv2 must be running (enable_SHARP = true) and the NVIDIA Scalable Hierarchical
Aggregation and Reduction Protocol (SHARP)™ allocation parameter must be enabled
(enable_SHARP_alloction = true) for this API to trigger resource (GUID) allocations and
deallocations within SHARP.
NVIDIA SHARP reservation REST APIs support the following operations:
•
Get Specific SHARP Reservation
•
Create a New SHARP Reservation
•
Delete SHARP Reservation
•
Update SHARP Reservation
34.1.1 Get All Reservations
•
Description - Retrieves all SHARP reservations
•
Request URL - GET /ufmRest/app/sharp/allocate_resources
•
Request Content-Type - Application/json
•
Response
{
"anas1":{
"pkey":"0x12",
"guids":["0x248a0703008a850a", "0x248a0703008a850b"]
},
"anas2":{
"pkey":"0x12",
"guids": ["0xf452140300383a01", "0xf452140300383a02"]
}
}
•
Status Codes
•
200 - OK
•
400 - BAD_REQUEST
34.1.2 Get Specific SHARP Reservation
•
Description - Gets specific SHARP reservation by app_id
•
Request URL - GET /ufmRest/app/sharp/allocate_resources/<app_id>
•
Request Content Type - Application/json
•
Status Codes
•
200 - OK
•
400 - BAD_REQUEST
• 404 - NOT_FOUND
{
"anas1":{
"pkey": "0x12",
"guids": ["0x248a0703008a850a", "0x248a0703008a850b"]
}
}
183
34.1.3 Create a New SHARP Reservation
The following API is replacing the deprecated SHARP API presented in earlier versions of this
•
Description - Creates a new SHARP reservation. By default, the SHARP blocking API is called,
which entails sending the reservation request to SHARP and awaiting the response (success or
fail). To revert to the previous behavior of using the non-blocking API, set the "blocking"
parameter in the API to false. If the partial allocation parameter is set to false, the SHARP
allocation request will not succeed in the event that even a single node is absent in the
fabric. By default, this parameter is set to true.
•
Example of a false partial allocation: Request URL - POST /ufmRest/app/sharp/resources?
partially_alloc=false
•
Example of calling a non-blocking API: Request URL - POST /ufmRest/app/sharp/resources?
blocking=false
•
Request Content-Type - Application/json
•
Status Codes
•
202 - ACCEPTED (All nodes were added successfully to created allocation)
•
206 - PARTIAL (Not all nodes were added to created allocation because they are not
found in the fabric)
•
200 - OK (All nodes were added successfully to the created allocation and the SHARP
blocking API is called)
•
400 - BAD_REQUEST
•
Request Data
Name
Value
Default
Description
Mandatory/
Optional
App_id
String
None
"0x7fff" (This is the
Mandatory
default management
pkey) Application id.
It is also the identifier
of this nodes allocation
App_resources_ Integer
-1
Application resources Optional
limit
limitation
Hosts_names
String
None
A string of hosts names
Optional
separated by a
comma, to be added
to sharp allocation.
Example:
"r-ufm77,r-ufm51"
Port_guids
list
None
List of ports guids
Optional
Example:
["f452140300383a01",
"f452140300383a02"]
184
Name
Value
Default
Description
Mandatory/
Optional
pkey
Hexadecimal string
"0x7fff" (This is the
Created network PKey Optional
between
default
to be used by Sharp
"0x0001"-"0x7ffe"
management pkey)
exclusive
Examples:
•
Create SHARP allocation by sending hosts_names:
{
"app_id":"99",
"hosts_names":"r-ufm51,r-ufm55",
"pkey":"0x12",
"app_resources_limit": -1
}
•
Create SHARP allocation by sending port_guids:
{
"app_id":"99",
"port_guids": ["f452140300383a01", "f452140300383a02"],
"pkey":"0x12",
"app_resources_limit": -1
}
34.1.4 Delete SHARP Reservation
The following API is replacing the deprecated SHARP API presented in earlier versions of the
•
Description - Deletes SHARP Allocation. By default, the SHARP blocking API is called to delete
SHARP reservation.
•
Example of calling delete allocation using SHARP blocking API: Request URL - DELETE /
ufmRest/app/sharp/resources/<app_id>
•
Example of calling delete allocation using SHARP non-blocking API: Request URL - DELETE /
ufmRest/app/sharp/resources/<app_id>?blocking=false
•
Request Content-Type - Application/json
•
Status Codes
•
204 - NO CONTENT
•
400 - BAD_REQUEST
34.1.5 Update SHARP Reservation
The following API is replacing the deprecated SHARP API presented in earlier versions of this
• Description - Updates SHARP Allocation. If the partial allocation parameter is set to false, the
SHARP allocation request will not succeed in the event that even a single node is absent in
the fabric. By default, this parameter is set to true.
185
•
Request URL: PUT /ufmRest/app/sharp/resources/<app_id>
•
Request Content-Type - Application/json
•
Status Codes
•
202 - ACCEPTED
•
206 - PARTIAL
•
400 - BAD_REQUEST
•
Body Examples:
•
Update SHARP allocation by sending hosts_names:
{
"hosts_names":"r-ufm51,r-ufm77"
}
•
Update SHARP allocation by sending port_guids:
{
"port_guids":["f452140300383a01", "f452140300383a02"]
}
34.2 SHARP Jobs APIs
The SHARP jobs REST API provides methods on obtaining information on SHARP jobs and support the
following operations:
•
Get All SHARP Jobs
•
Get a Specific SHARP Job
•
Get All SHARP Non-Blocking Jobs
•
Get Specific SHARP Non-Blocking Job
34.2.1 Get All SHARP Jobs
•
Description - Retrieves all active SHARP jobs.
•
Request URL - GET /ufmRest/app/sharp/resources/jobs
•
Request Content Type - Application/json
•
Status Codes
•
200 - OK
• Response
{
"99:58":{
"job_id":58,
"num_guids":1,
"num_rails":1,
"trees":{
"0":{
"tree_id":0,
"type":"LLT",
"ANs":{
"0x33333":{
"description":"sw3",
"lid":23,
"rank":1,
"guid":"0x33333",
"parent_guid":null,
"child_guids":null,
"hca_guids":[
"0x78395179",
"0x78395178"
]
}
}
}
186
},
"reservation_key":"99"
},
"99:74":{
"job_id":74,
"num_guids":1,
"num_rails":1,
"trees":{
"0":{
"tree_id":0,
"type":"LLT",
"ANs":{
"0x33333":{
"description":"sw3",
"lid":23,
"rank":1,
"guid":"0x33333",
"parent_guid":null,
"child_guids":null,
"hca_guids":[
"0x78395179",
"0x78395178"
]
}
},
"reservation_key":"99"
}
}
}
}
34.2.2 Get a Specific SHARP Job
•
Description - Retrieves specific active SHARP jobs with specific a reservation_id
•
Request URL - GET /ufmRest/app/sharp/resources/jobs/<job_id>?
reservation_id=<reservation_id>
•
Request Content Type - Application/json
•
Status Codes
•
200 - OK
•
404 - NOT_FOUND
•
Response
{
"99:58":{
"job_id":58,
"num_guids":1,
"num_rails":1,
"trees":{
"0":{
"tree_id":0,
"type":"LLT",
"ANs":{
"0x33333":{
"description":"sw3",
"lid":23,
"rank":1,
"guid":"0x33333",
"parent_guid":null,
"child_guids":null,
"hca_guids":[
"0x78395179",
"0x78395178"
]
}
}
}
},
"reservation_key":"99"
}
}
34.2.3 Get All SHARP Non-Blocking Jobs
•
Description - Retrieves all active SHARP jobs using non blocking SHARP API
•
Request URL - GET /ufmRest/app/sharp/resources/jobs_nb
•
Request Content Type - Application/json
• Status Codes
187
•
200 - OK
•
Response - the HTTP response location header contains a URL with job ID created for running
the action.
Example:
{
"ID":"1",
"Status":"Completed",
"Progress":100,
"Description":"Get sharp jobs",
"Created":"2023-05-03 09:48:35",
"LastUpdated":"2023-05-03 09:48:35",
"Summary": {
"99:58":{
"job_id":58,
"num_guids":1,
"num_rails":1,
"trees":{
"0":{
"tree_id":0,
"type":"LLT",
"ANs":{
"0x33333":{
"description":"sw3",
"lid":23,
"rank":1,
"guid":"0x33333",
"parent_guid":null,
"child_guids":null,
"hca_guids":["0x78395179", "0x78395178"]
}
}
}
},
"reservation_key":"99"
},
"99:74":{
"job_id":74,
"num_guids":1,
"num_rails":1,
"trees":{
"0":{
"tree_id":0,
"type":"LLT",
"ANs":{
"0x33333":{
"description":"sw3",
"lid":23,
"rank":1,
"guid":"0x33333",
"parent_guid":null,
"child_guids":null,
"hca_guids":["0x78395179", "0x78395178"]
}
},
"reservation_key":"99"
}
}
}
},
"RelatedObjects":[],
"CreatedBy":"admin",
"Operation":"Get sharp jobs",
"Foreground":true,
"SiteName":""
}
34.2.4 Get Specific SHARP Non-Blocking Job
•
Description - Retrieves specific active SHARP jobs with specific reservation_id using non
blocking SHARP API
•
Request URL - GET /ufmRest/app/sharp/resources/jobs_nb/<job_id>?
reservation_id=<reservation_id>
•
Request Content Type - Application/json
•
Status Codes
•
200 - OK
•
404 - NOT_FOUND
• Response - the HTTP Response location header contains a URL with job ID created for running
the action. Example:
188
{
"ID":"1",
"Status":"Completed",
"Progress":100,
"Description":"Get sharp jobs",
"Created":"2023-05-03 09:48:35",
"LastUpdated":"2023-05-03 09:48:35",
"Summary": {
"99:58":{
"job_id":58,
"num_guids":1,
"num_rails":1,
"trees":{
"0":{
"tree_id":0,
"type":"LLT",
"ANs":{
"0x33333":{
"description":"sw3",
"lid":23,
"rank":1,
"guid":"0x33333",
"parent_guid":null,
"child_guids":null,
"hca_guids":["0x78395179", "0x78395178"]
}
}
}
},
"reservation_key":"99"
},
"RelatedObjects":[],
"CreatedBy":"admin",
"Operation":"Get sharp jobs",
"Foreground":true,
"SiteName":""
}
189
35 Topology Compare REST API
35.1 Compare Current Topology with External .topo File
This API is asynchronous, therefore will create a hidden job and return its ID in the response.
•
URL: POST ufmRestV2/reports/Topology_Compare
•
Payload: .topo file (the payload is optional and if you do not send it, then the topology is
compared against the master typology).
•
Response: redirect to job ID
35.2 Get Compare Result
•
URL: GET ufmRestV2/reports/last_report/Topology_Compare
• Response:
"{
{
"added": {
"nodes": [
{
"guid": "0002c9000002026c",
"system_name": "L0_R03_B15_I04",
"ip": "0.0.0.0",
"type": "switch"
},
{
"guid": "0002c90000012721",
"system_name": "H_5",
"ip": "0.0.0.0",
"type": "host"
}
],
"links": [
{
"source_guid": "0002c9000002026c",
"destination_guid": "0002c90000021b7c",
"name": "0002c9000002026c_28:0002c90000021b7c_4"
},
{
"source_guid": "0002c9000002026c",
"destination_guid": "0002c90000021b88",
"name": "0002c9000002026c_31:0002c90000021b88_4"
},
{
"source_guid": "0002c9000002026c",
"destination_guid": "0002c90000021b8c",
"name": "0002c9000002026c_32:0002c90000021b8c_4"
}
]
},
"removed": {
"nodes": [
{
"guid": "0002c9000002026c",
"system_name": "L0_R03_B15_I04",
"ip": "0.0.0.0",
"type": "switch"
},
{
"guid": "0002c90000012721",
"system_name": "H_5",
"ip": "0.0.0.0",
"type": "host"
}
],
"links": [
{
"source_guid": "0002c9000002026c",
"destination_guid": "0002c90000021b7c",
"name": "0002c9000002026c_28:0002c90000021b7c_4"
},
{
"source_guid": "0002c9000002026c",
"destination_guid": "0002c90000021b88",
"name": "0002c9000002026c_31:0002c90000021b88_4"
},
{
"source_guid": "0002c9000002026c",
"destination_guid": "0002c90000021b8c",
"name": "0002c9000002026c_32:0002c90000021b8c_4"
}
190
]
}
}
35.3 Get List of Created Topodiff Results
•
URL: GET /ufmRestV2/Topology_Compare
•
Response:
[
{
"report_id": "4",
"report_scope": "Periodic",
"timestamp": "2021-06-22 11:00:00"
},
{
"report_id": "5",
"report_scope": "Periodic",
"timestamp": "2021-06-22 11:05:00"
},
{
"report_id": "6",
"report_scope": "Periodic",
"timestamp": "2021-06-22 11:10:00"
},
]
35.4 Get Topodiff Report Information
•
URL: GET /ufmRest/reports/Topology_Compare/<report_id>
•
Response:
{
"title": "Topology Compare Report",
"date": "2021-01-21 12:02:00",
"sections": [
{
"title": "Topology Compare",
"description": "Compares planned topology to an actual one ",
"status": {
"severity": "Critical",
"value": "Completed Successfully. 3 Errors Found, 1 Warnings Found"
},
"elements": [
{
"status": {
"severity": "Critical",
"value": "Completed Successfully. 3 Errors Found, 1 Warnings Found"
},
"elements": [
{
"Detected Differences": " Found mismatches between the topology defined in /opt/ufm/data/fabric.topo
and the discovered fabric.",
"Severity": "Warning"
},
{
"Detected Differences": " Total: 3 Additional nodes detected",
"Severity": "Critical"
},
{
"Detected Differences": " Unplanned node detected: r-hyp-sw01/U1",
"Severity": "Critical"
},
{
"Detected Differences": " Unplanned node detected: r-ufm254-hyp-03/mlx5_0",
"Severity": "Critical"
},
{
"Detected Differences": " Unplanned node detected: r-ufm254-hyp-04/U1",
"Severity": "Critical"
} ] } ] } ],
"Created by": "admin"
}
35.4.1 Update Master Topology File with Current Topology or
External File
• URL: POST ufmRestV2/Topology_Compare/master_topology
191
•
External file optional (if not sent, the API aligns the master topology with the current
topology).
35.5 Export Topology File
•
Description: generates the .topo file for the current topology. Could be synchronous or
asynchronous call.
•
URL: POST ufmRestV2/Topology_Compare/topology_file
•
Request Data: N/A
•
Response:
{
"file_name": "mytop.topo"
}
35.6 Retrieve Topology File
•
Description: requests the file from the server side in order to download it on the local
machine.
•
URL: GET /ufmRest/topology_file/<file_name>
•
Response: .topo file
35.7 Get Notification
•
URL: GET /ufmRest/notifications
•
Response:
[
{
"instanceID": 4,
"subject": "Topology Diff",
"severity": "Info",
"timestamp": "2021-01-29 15:16:18",
"read": true,
"body": {"is_stable":true} }]
35.8 Acknowledge Notification
•
Description: Acknowledge the notification once the user gets the message.
•
URL: PUT/ufmRest/notifications/>instanceID>
• Response: 202 successful operation
192
36 Periodic IBDiagnet REST API
36.1 Start New IBDiagnet Task
•
Description - start new task
•
Request URL - POST /ufmRest/reports/ibdiagnetPeriodic
•
Request Content Type - Application/json
•
Request Data
•
general - general parameters of the task including the name , running mode
(scheduled/once), and the location of the IBDiagnet results which are:
•
Remote: save reports and data to remote location configured in UFM remote
location settings
•
Local: save reports and data to default local path on UFM server
•
command_flags - dictionary of "key":"value" with desired ibdiagnet flags
•
conf_file_parms - advanced parameters to run as configuration file
•
run - parameters regarding scheduling
•
Example
{
"general": {
"name": "example1",
"running_mode": "scheduled",
"location": "remote"
},
"command_flags": {
"--mads_timeout": 500
},
"run": {
"startTime": "2020-10-01 16:40:59",
"endTime": "2020-10-01 18:45:59",
"interval": 3600
},
"conf_file_params": "max_hops=64"
}
36.2 Deactivate IBDiagnet Task
•
Description - stop running task
•
Request URL - POST /ufmRest/reports/ibdiagnetPeriodic/stop/<task_name>
•
Request Content Type - Application/json
36.3 Start Deactivated Task
•
Description - start deactivated task
•
Request URL - POST /ufmRest/reports/ibdiagnetPeriodic/start/<task_name>
•
Request Content Type - Application/json
36.4 Delete IBDiagnet Task
•
Description - delete task
•
Request URL - DELETE /ufmRest/reports/ibdiagnetPeriodic/<task_name>
• Request Content Type - Application/json
193
36.5 Edit Running Task
•
Description - edit running task
•
Request URL - PUT /ufmRest/reports/ibdiagnetPeriodic/<task_name>
•
Request Content Type - Application/json
•
Request Data
•
general - general parameters of the task including the name and running mode (scheduled/
once)
•
run - parameters regarding scheduling
•
Example
{
"general": {
"name": "example1",
"running_mode": "scheduled"
},
"run": {
"startTime": "2020-10-01 16:40:59",
"endTime": "2020-10-01 18:45:59",
"interval": 3600
}
}
36.6 Get All IBDiagnet Tasks
•
Description - get all system tasks
•
Request URL - GET /ufmRest/reports/ibdiagnetPeriodic
•
Request Content Type - Application/json
• Response example:
[
{
"id": "351915390845",
"name": "example",
"last_run_result": "Successful",
"next_scheduled_run": "01\/10\/2020 16:53:00",
"last_result_location": "\/opt\/ufm\/files\/periodicIbdiagnet\/example-01-10-2020-16.03.21",
"running_mode": "scheduled",
"last_run_time": "01\/10\/2020 16:03:21",
"task_state": "Enabled",
"ibdiagnet_params": null,
"command_flags": {
},
"scheduling_object": {
"endTime": "2020-10-01 18:58:00",
"interval": 3600,
"startTime": "2020-10-01 16:53:00"
}
},
{
"id": "256750526107",
"name": "example1",
"last_run_result": "Successful",
"next_scheduled_run": "01\/10\/2020 17:41:01",
"last_result_location": "\/opt\/ufm\/files\/periodicIbdiagnet\/example1-01-10-2020-16.41.01",
"running_mode": "scheduled",
"last_run_time": "01\/10\/2020 16:41:01",
"task_state": "Disabled",
"ibdiagnet_params": "max_hops=64",
"command_flags": {
"--mads_timeout": 500
},
"scheduling_object": {
"endTime": "2020-10-01 18:45:59",
"interval": 3600,
"startTime": "2020-10-01 16:40:59"
}
}
]
194
36.7 Get IBDiagnet Task
•
Description - task parameter
•
Request URL - GET /ufmRest/reports/ibdiagnetPeriodic/<task_name>
• Request Content Type - Application/json
195
37 Logging REST API
37.1 Logging REST API
•
Description - Retrieves different types of logs.
•
Request URL - /ufmRest/app/logs/<type>
•
Types:
•
Event
•
SM
•
UFM
37.2 Get Log
•
Description - Retrieves a log file of a specific type.
•
Request URL - GET /ufmRest/app/logs/<type>[&length=<number>]
•
Length is an optional limit on the number of returned lines and defaults to 500. It
cannot be set to more than 10000
•
Request Content Type - Application/json
•
Response - content attribute will contain the logs text
•
Status Codes
•
200 - OK
•
400 - bad request (bad or missing parameters)
37.3 Get Events Logs in JSON Format
•
Description - Retrieves event logs with support for server pagination.
•
Request URL - GET ufmRest/app/logs/history_events?
page_number=<page_namer>&rpp=<page size>
•
Request Content Type - Application/json
•
Response - Content attribute contains JSON list
•
Status Codes
•
200 - OK
•
400 - bad request (bad or missing parameters)
37.4 Create History
•
Description - Create a file with log entries from a specific time range (including archived
logs)
•
Request URL - POST /ufmRest/app/logs/<type>/history?
start=<timestamp>&end=<timestamp>[&length=<number>][&tz=<timezone>][&
event_src=<events src>]
•
Start and end are the time range in milliseconds
•
Length is an optional limit on the number of returned lines and defaults to
configuration option max_history_lines (100000)
• Tz is an optional timezone and defaults to utc. Must be one of these values.
196
•
Event Source is an optional parameter that is only valid if the log type is 'Event'. It must be
specified as either 'device' or 'link'.Request Content Type - Application/json
•
Response - the HTTP Response Location Header will contain URI with job ID created for
generating the file. Once the job is successfully finished, its summary field will have the
following format:
{"result_exceeds_limit":false,"file_name":"event_history_admin","limit":10000}
Where limit is the given/default length, result_exceeds_limit indicates whether
increasing the limit will return more data, and file_name points to the result file. The file
can be obtained by using:
GET /ufm_web/<file_name>
•
Status Codes
•
202 - accepted. Job ID created successfully
•
400 - bad request (bad or missing parameters)
37.5 Usage Statistics REST API
•
Description - This REST API stores statistics into the usage statistics file which is stored in the
file system.
•
Request URL - POST /ufmRest/app/usage_statistics
•
Request Content Type - Application/json
•
Request data example:
{ “events”: [
"2023-11-01 10:38:36\tadmin\tufm\tUFM application has been started",
"2023-11-01 10:38:36\tadmin\tufm\tTimepicker has been set: Last 5 Minutes",
"2023-11-01 10:39:13\tadmin\tufm\tUFM window has been hidden"
]] }
•
Response:
{
"file_path":"/opt/ufm/files/log/usage_statistics/usage_statistics"
}
•
Status Code:
• 202 - Accepted
197
38 Access Tokens API
38.1 Get All Tokens
•
Description - returns information on all created tokens by the user
•
Request URL - GET /ufmRest/app/tokens
•
Response:
[
{
"access_token": "czQYeCfKIeXqlwSqtorunOPysaSp2r",
"revoked": false,
"issued_at": 1637067961,
"expires_in": 315360000,
"username": "admin"
}
]
•
Status Codes:
•
200 - Ok
38.2 Create New Token
•
Description - Create a new token
•
Request URL - POST /ufmRest/app/tokens
•
Response:
{
"access_token": "czQYeCfKIeXqlwSqtorunOPysaSp2r",
"revoked": false,
"issued_at": 1637067961,
"expires_in": 315360000,
"username": "admin"
}
•
Status Codes:
•
200 - Ok
38.3 Revoke a Token
•
Description - Revoke a specific token
•
Request URL - POST /ufmRest/app/tokens/revoke
•
Request Content Type - Multipart/form-data
token: oiR3v37KxscBKfemvMnXzgazqZD15Z
•
Status Codes:
•
200 - Ok
• 404 - Not Found
38.4 How to Use the Access Token
The access token should be attached in the header of the API request as the following example:
To get all fabric events using the token based authentication:
198
• URL /ufmRestV3/app/events
• Headers: {… Authorization: Basic <access_token> …}
199
39 Roles Access Control
39.1 Get Rest APIs
•
Description - Returns all Rest APIs in UFM.
•
Request URL - GET /ufmRest/app/roles_access_control/rest_apis
•
Response:
[
{
"route": "/monitoring/start",
"method": "POST"
}
]
•
Status Codes:
•
200 - Ok
39.2 Get All Roles
•
Description - Returns all roles.
•
Request URL - GET /ufmRest/app/roles_access_control/roles
•
Response:
] [
{
"name": "Read_only",
"allowed_urls": {
"/monitoring/start": [
"POST"
],
"/monitoring/session/<session_id>": [
"PUT",
"DELETE",
"GET"
]}
}
}
•
Status Codes:
•
200 - Ok
39.3 Get Role by Name
•
Description - Returns a specific role.
•
Request URL - GET /ufmRest/app/roles_access_control/roles/<role_name>
•
Response:
] {
"name": "Read_only",
"allowed_urls": {
"/monitoring/start": [
"POST"
],
"/monitoring/session/<session_id>": [
"PUT",
"DELETE",
"GET"
]}
}
}
•
Status Codes:
• 200 - Ok
200
39.4 Create New Role
•
Description - Creates a new role.
•
Request URL - POST /ufmRest/app/roles_access_control/roles
•
Request Data:
{
"name":"Role_Name",
"allowed_urls":{"/monitoring/attribute_values":["GET"]}
}
•
Status Codes:
•
200 - Ok
39.5 Update Role
•
Description - Updates a role.
•
Request URL - PUT /ufmRest/app/roles_access_control/roles/<role-name>
•
Request Data:
{
"allowed_urls":{"/monitoring/attribute_values":["GET"]}
}
•
Status Codes:
•
200 - Ok
39.6 Delete Role
•
Description - Deletes a role.
•
Request URL -DELETE /ufmRest/app/roles_access_control/roles/<role-name>
•
Status Codes:
• 200 - Ok
201
40 CloudX APIs
40.1 Create Network
•
Description - Create a new network
•
Request URL - POST /ufmRest/cloudx/Network
•
Request Payload:
{
"id": "43a0f1c4-8bf5-4d69-8775-fe7c35549b91",
"name": "privateCX4",
"tenant_id": "6a51b867d9c149b5af70a66240a35353",
"admin_state_up": true,
"mtu": 1500,
"status": "ACTIVE",
"subnets": [],
"standard_attr_id": 36,
"shared": false,
"project_id": "6a51b867d9c149b5af70a66240a35353",
"port_security_enabled": true,
"router:external": false,
"provider:network_type": "vlan",
"provider:physical_network": "ConnectX5",
"provider:segmentation_id": 10,
"availability_zone_hints": [],
"is_default": false,
"availability_zones": [],
"ipv4_address_scope": null,
"ipv6_address_scope": null,
"vlan_transparent": null,
"description": "",
"tags": [],
"created_at": "2021-09-21T08:33:27Z",
"updated_at": "2021-09-21T08:33:28Z",
"revision_number": 1,
"network_qos_policy": null
}
•
Response - the HTTP Response Location Header will contain URI with Job ID created for this
action.
•
Status Codes
•
202 - successful operation
•
400 - bad request
40.2 Delete Network
•
Description - Delete existing network
•
Request URL - DELETE /ufmRest/cloudx/Network
•
Request Payload:
{
"id":"<network_id>"
}
•
Response - the HTTP Response Location Header will contain URI with Job ID created for this
action.
•
Status Codes
•
202 - successful operation
•
400 - bad request
• 404 - not found
202
40.3 Add Port to Network
•
Description - Add port to existing network
•
Request URL - POST /ufmRest/cloudx/Port
•
Request Payload:
{
"id": "85379c18-1b09-4f19-b471-b3496b145993",
"name": "",
"network_id": "43a0f1c4-8bf5-4d69-8775-fe7c35549b91",
"tenant_id": "29b7850797be4f0b9a2f888d07fce349",
"mac_address": "fa:16:3e:b9:be:c4",
"admin_state_up": true,
"status": "DOWN",
"device_id": "dhcp9c934189-944b-53e6-9103-75806a1e8e87-a029821a-ca6a-4ddf-9d85-801ea318a25e",
"device_owner": "network:dhcp",
"standard_attr_id": 247,
"fixed_ips": [
{
"subnet_id": "acff29ee-3ddc-47b7-a4bd-3f61cc2bc953",
"ip_address": "11.11.11.2"
}
],
"project_id": "29b7850797be4f0b9a2f888d07fce349",
"qos_policy_id": null,
"port_security_enabled": false,
"security_groups": [],
"binding:vnic_type": "normal",
"binding:profile": {},
"binding:host_id": "r-ufm254-hyp-04",
"binding:vif_type": "unbound",
"binding:vif_details": {},
"allowed_address_pairs": [],
"network_qos_policy": null,
"extra_dhcp_opts": [],
"description": "",
"qos_network_policy_id": null,
"resource_request": null,
"ip_allocation": "immediate",
"tags": [],
"created_at": "2021-10-18T08:52:02Z",
"updated_at": "2021-10-18T08:52:02Z",
"revision_number": 1,
"network": {
"id": "a029821a-ca6a-4ddf-9d85-801ea318a25e",
"name": "ib_tenant_net",
"tenant_id": "29b7850797be4f0b9a2f888d07fce349",
"admin_state_up": true,
"mtu": 1500,
"status": "ACTIVE",
"subnets": [
"acff29ee-3ddc-47b7-a4bd-3f61cc2bc953"
],
"standard_attr_id": 244,
"shared": true,
"availability_zone_hints": [],
"availability_zones": [
"nova",
"nova"
],
"ipv4_address_scope": null,
"ipv6_address_scope": null,
"router:external": false,
"vlan_transparent": null,
"description": "",
"qos_policy_id": null,
"port_security_enabled": true,
"l2_adjacency": true,
"tags": [],
"created_at": "2021-10-18T08:51:57Z",
"updated_at": "2021-10-18T08:52:01Z",
"revision_number": 2,
"project_id": "29b7850797be4f0b9a2f888d07fce349",
"provider:network_type": "vlan",
"provider:physical_network": "ibnet",
"provider:segmentation_id": 97
}
}
•
Response - the HTTP Response Location Header will contain URI with Job ID created for this
action.
•
Status Codes
•
202 - successful operation
• 400 - bad request
203
40.4 Delete Port From Network
•
Description - Delete existing port from a network
•
Request URL - DELETE /ufmRest/cloudx/Port
•
Request Payload:
{
"id": "85379c18-1b09-4f19-b471-b3496b145993",
"name": "",
"network_id": "43a0f1c4-8bf5-4d69-8775-fe7c35549b91",
"tenant_id": "29b7850797be4f0b9a2f888d07fce349",
"mac_address": "fa:16:3e:b9:be:c4",
"admin_state_up": true,
"status": "ACTIVE",
"device_id": "dhcp9c934189-944b-53e6-9103-75806a1e8e87-a029821a-ca6a-4ddf-9d85-801ea318a25e",
"device_owner": "network:dhcp",
"standard_attr_id": 247,
"fixed_ips": [
{
"subnet_id": "acff29ee-3ddc-47b7-a4bd-3f61cc2bc953",
"ip_address": "11.11.11.2"
}
],
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"security_groups": [],
"description": "",
"binding:vnic_type": "normal",
"binding:profile": {},
"binding:host_id": "r-ufm254-hyp-04",
"binding:vif_type": "other",
"binding:vif_details": {},
"qos_policy_id": null,
"qos_network_policy_id": null,
"port_security_enabled": false,
"resource_request": null,
"ip_allocation": "immediate",
"tags": [],
"created_at": "2021-10-18T08:52:02Z",
"updated_at": "2021-10-18T08:52:02Z",
"revision_number": 2,
"project_id": "29b7850797be4f0b9a2f888d07fce349",
"network_qos_policy": null
}
•
Response - the HTTP Response Location Header will contain URI with Job ID created for this
action.
•
Status Codes
•
202 - successful operation
•
400 - bad request
• 404 - not found
204
41 Client Authentication REST API
41.1 Get Client Authentication Settings
•
Description: Get client authentication settings
•
URL: GET /ufmRest/app/client_authentication/settings
•
Request Content Type - Application/json
•
Request Data: N/A
•
Response:
{
"enable": true,
"client_cert_sans": [
{
"san": "ufm-test.net",
"user": "ufmsysadmin"
}
],
"ssl_cert_hostnames": [
"ufm-test.net"
],
"ssl_cert_file": "Present",
"ca_intermediate_cert_file": "Present",
"cert_auto_refresh": {
"enabled": true,
"root_intermediate_certs_url": https://test.net,
"ssl_cert_url": https://rest.net,
"ssl_cert_thumbprint": "41EBA872F116E720E494A0AE1ED357EF8A0C60C9",
"last_checked": "2022-03-15 11:35:40",
"last_updated": "2022-03-15 11:35:40",
"bootstrap_cert_file": "Present"
}
}
•
Status Codes:
•
200 - Ok
41.2 Configure Certificate "Auto-Refresh"
•
Description: Configure settings
•
URL: PUT /ufmRest/app/client_authentication/settings
•
Request Content Type - Application/json
•
Request Data format:
{
"enable": true,
"client_cert_sans": [
{
"san": "ufm-test.net",
"user": "ufmsysadmin"
}
],
"ssl_cert_hostnames": [
"ufm-test.net"
],
"cert_auto_refresh": {
"enable": true,
"root_intermediate_certs_url": https://test.net2,
"ssl_cert_url": passwordhttps://test.net,
"ssl_cert_thumbprint": "2268BDD79DF7FD9C818EB97F315AE0F35D223A16",
"bootstrap_pfx_password": "password",
"bootstrap_cert_file": base64 test format
"bootstrap_pfx_password_file":
}
• Response: N/A
• Only switches to "auto-refresh after refresh.
• The bootstrap_cert_file file should be made up of base64 strings
205
•
Status Codes:
•
200 - Ok
•
400 - Bad Request (bad or missing parameters)
•
404 - Resource does not exist
Bootstrap certificate bootstrap_pfx_password_file and bootstrap_pfx_password
options are mutually exclusive, only one should be provided.
41.3 Update Certificates
•
Description: Update certificates
•
URL: POST /ufmRest/app/client_authentication/auto_refresh_certificates
•
Request Content Type - Application/json
•
Request Data: N/A
•
Response: N/A
After the certificates are updated, the system switches to client certificates.
•
Status Codes:
•
200 - Ok
•
400 - Bad Request (bad or missing parameters)
41.4 Delete All Client Certificates
•
Description: Delete client certificates return to user/password
•
URL: DELETE /ufmRest/app/client_authentication/settings
•
Request Content Type - Application/json
•
Request Data: N/A
•
Response: "Success"
•
Status Codes:
•
200 - Ok
•
400 - Bad Request (bad or missing parameters)
• 404 - Resource does not exist
206
42 Uploading New UFM Appliance Version REST API
42.1 Infrastructure Usage
•
Using upgrade_ufm_appliance.py package which is part of the UFM software.
•
Using UFM REST API infrastructure to control the upgrade.
42.2 Upgrade Flow
•
Prerequisite:
a.
The upgrade is performed only on UFM APL.
b.
The system's initial version is HA master/slave.
c.
UFM runs on the master system.
•
Via REST API, download the UFM appliance image.
•
Via REST API, start upgrade using upgrade_ufm_appliance.py tool. The tool performs the
following steps:
a.
Validates cluster.
b.
Retrieves HA status.
c.
Verifies installed version.
d.
Uploads the image to both systems.
e.
Installs the image on both systems.
f.
Changes boot location on slave.
g.
Reloads slave.
h.
Changes boot location on master.
•
Via REST API reload master.
42.3 REST API
42.3.1 Upload New UFM APL Image
•
Description - Allows users to upload a new UFM APL image before applying the upgrade.
•
Request URL - POST /ufmRest/app//images/appliance
•
Request Content Type - Application/json
•
Request Data:
{
"file": " image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.7-20220502-060753.img"
}
•
Status Codes
•
202 - ACCEPTED
•
400 - bad request (bad or missing parameters, allowed only 10 images).
42.3.2 Delete UFM APL Image
•
Description - Allows users to delete an uploaded UFM APL.
• Request URL - DELETE /ufmRest/app/images/appliance/<image_name>
207
•
Request Content Type - Application/json
•
Status Codes
•
202 - ACCEPTED
•
404 - NOT_FOUND
42.3.3 Activate UFM APL Upgrade Image
•
Description - Allows users to activate UFM APL upgrade.
•
Request URL - POST /ufmRest/ actions/appliance/upgrade
•
Request Content Type - Application/json
•
Request Data:
{
"name": " image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.7-20220502-060753.img"
}
•
Status Codes
•
202 - ACCEPTED
•
400 - BAD REQUEST- Bad or missing parameter
•
404 - NOT_FOUND
42.3.4 Activate UFM APL Master reload
•
Description - Allows users to reload master system.
•
Request URL - POST /ufmRest/ actions/appliance/master_reboot
•
Request Content Type - Application/json
•
Request Data:
•
Status Codes
•
202 - ACCEPTED
42.3.5 Get the List of Available Images
•
Description - Allows users to get all the available images applied on a device.
•
Request URL - GET /ufmRest/app/ images/appliance
•
Request Content Type - Application/json
•
Response Data:
{
image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.7-20220502-060753.img,
image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.9-20220502-060753.img
}
•
Status Codes
•
200 - OK
42.3.6 Get Upgrade Status
•
Description - Allows users to get upgrade status.
• Request URL - GET /ufmRest/ actions/appliance/upgrade_status
208
•
Request Content Type - Application/json
•
Response Data:
{
2022-05-17 07:44:49.374 INFO
Going to install image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.7-2022
0502-060753.img: image version UFMAPL_4.8.0.6_UFM_6.9.0.7
2022-05-17 07:44:49.381 INFO
Validating cluster: 10.209.36.38, 10.209.36.35
2022-05-17 07:44:49.382 INFO
Validating cluster: 10.209.36.38, 10.209.36.35
2022-05-17 07:44:49.382 INFO
Retrieving ha status info from: 10.209.36.38
2022-05-17 07:44:49.382 INFO
Retrieving version info from: 10.209.36.38
2022-05-17 07:45:25.069 INFO
Image version for 10.209.36.38 is: UFMAPL_4.8.0.4_UFM_6.9.0.4
2022-05-17 07:45:25.069 INFO
Retrieving ufm status info from: 10.209.36.38
2022-05-17 07:45:41.007 INFO
Show installed images on: 10.209.36.38
2022-05-17 07:45:47.015 INFO
Retrieving ha status info from: 10.209.36.35
2022-05-17 07:45:47.016 INFO
Retrieving version info from: 10.209.36.35
2022-05-17 07:45:52.491 INFO
Image version for 10.209.36.35 is: UFMAPL_4.8.0.4_UFM_6.9.0.4
2022-05-17 07:45:52.491 INFO
Retrieving ufm status info from: 10.209.36.35
2022-05-17 07:46:07.550 INFO
Show installed images on: 10.209.36.35
2022-05-17 07:46:13.212 INFO
Upgrading cluster: 10.209.36.38, 10.209.36.35
2022-05-17 07:46:13.212 INFO
Uploading image /tmp/image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.7-2
0220502-060753.img on: 10.209.36.38
2022-05-17 07:46:13.213 INFO
Uploading image /tmp/image-ufm_appliance-x86_64-UFMAPL_4.8.0.6_UFM_6.9.0.7-2
0220502-060753.img on: 10.209.36.35
2022-05-17 07:47:59.972 INFO
Installing image on: 10.209.36.38
2022-05-17 07:48:00.964 INFO
Installing image on: 10.209.36.35
2022-05-17 07:49:28.473 INFO
Changing boot location on: 10.209.36.38
2022-05-17 07:49:33.882 INFO
Rebooting device: 10.209.36.38
2022-05-17 07:49:38.744 INFO
Reload command 'reload noconfirm' initiated on '10.209.36.38'
2022-05-17 07:53:47.738 INFO
Reload command on '10.209.36.38' ended, status: True
2022-05-17 07:53:47.739 INFO
Retrieving version info from: 10.209.36.38
2022-05-17 07:53:52.999 INFO
Changing boot location on: 10.209.36.35
}
•
Status Codes
•
200 - OK
•
404 - NOT_FOUND (log file not found)
42.4 UFM System Dump API
42.4.1 Create New System Dump
•
Description - Allows users to execute UFM system dump according to the mode of operation (if
mode is not specified, the Default mode is set, see below). The system triggers the job, and
once created, it signals the start of the backup process. Upon process completion, the job
returns the location of the backup (system dump) on the machine.
•
Request URL - POST /ufmRest/app/backup?mode=Default
•
Mode
•
Default - For basic collection
•
Snapshot - For more extended collection (including UFM logs)
•
Request Content Type - Application/json
•
Response type - hyperlink
• Response Data
!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to target URL: <a href="/ufmRestV2/jobs/10">/ufmRestV2/jobs/10</
a>. If not click the link.
Status Codes
202 - ACCEPTED
400 - bad request.
209
43 UFM Dynamic Telemetry Instances REST API
The management of dynamic telemetry instances involves the facilitation of user requests for the
creation of multiple telemetry instances. As part of this process, the UFM enables users to establish
new UFM Telemetry instances according to their preferred counters and configurations. These
instances are not initiated by the UFM but rather are monitored for their operational status through
the use of the UFM Telemetry bring-up tool.
43.1 Instantiate a New Instance
•
Description: Instantiates a new telemetry instance per the requested configuration in the
request parameters
•
•
Request Data:
Parameter
Description
requested_guids
An array of objects, where each object specifies the node GUID
and ports of the requested GUID
guid
A string specifying the unique identifier (node GUID) of the
requested metrics
ports
An array of integers specifying the ports of the requested GUID.
counters
An array of strings specifying the names of the metrics counters
to be retrieved - only supported counters can be sent (can be
retrieved via the supported counters API).
configuration
An optional object specifying additional configuration
parameters.
sample_rate
An integer specifying the rate at which the metrics are
sampled.
base_config
An optional string specifying the base configuration to be used.
ttl
An optional string specifying the time-to-live (TTL) for the
metrics data.
is_registered_discovery
An optional boolean value indicating whether the metrics are
registered with the discovery service.
is_async
An optional boolean value. If this parameter is sent, the
creation will become asynchronous, and a job_id will be
returned. To get the status of this job, please refer to the Jobs
API. We recommend using this parameter.
•
Response: Port number to communicate with the instantiated new instance.
•
Request Example:
Content-Type: application/json
{
"requested_guids": [
{
"guid": "xyz123",
"ports": [8080, 8081, 8082]
},
{
"guid": "abc456",
"ports": [9090]
}
210
],
"counters": ["cpu", "memory"],
"configuration": {
"setting1": "value1",
"setting2": "value2"
},
"sample_rate": 5,
"base_config": "config1",
"ttl": "24h",
"is_registered_discovery": true
}
The API will return a port that will be exposed by the UFM Telemetry.
Get All Instances
GET https://10.209.36.126/ufmRestV2/app/telemetry/instances
Return list of all instances + configuration + ports
{
"<cset_name>": {
"name": " <cset_name> ",
"requested_guids": [
{
"guid": "248a0703008dae46",
"ports": [
1
]
}
],
"counters": [
"PortXmitDataExtended",
"PortRcvDataExtended"
],
"sample_rate": 20,
"ttl": "1h",
"base_config": "",
"endpoint_port": 9007,
"status": "",
"is_registered_discovery": true,
"root_dir": "/opt/ufm/files/dynamic_telemetry/ <cset_name> ",
"configuration": {
"num_iterations": "20000",
"plugin_env_CLX_EXPORT_API_SHOW_STATISTICS": 1,
"plugin_env_UFM_TELEMETRY_MANAGED_MODE": 1
},
"conf_file": "",
"hca": "mlx5_0",
"pid": 7837
}
}
Get Specific Instance Configuration
•
Description: Gets a specific instance configuration.
•
•
Request Data: N/A
• Response Example:
{
"pdr_dynamic": {
"name": "pdr_dynamic",
"requested_guids": [
{
"guid": "248a0703008fa280",
"ports": [
1,
1,
1,
1
]
},
{
"guid": "ec0d9a0300bf551c",
"ports": [
1
]
},
{
"guid": "e8ebd3030064b7c6",
"ports": [
1,
1
]
},
{
"guid": "043f720300b818a0",
"ports": [
39
]
},
{
"guid": "7cfe900300d5ba54",
"ports": [
1,
1,
211
1
]
},
{
"guid": "98039b03009fce76",
"ports": [
1
]
}
],
"counters": [
"phy_raw_errors_lane0",
"phy_raw_errors_lane1",
"phy_raw_errors_lane2",
"phy_raw_errors_lane3",
"phy_effective_errors",
"phy_symbol_errors",
],
"sample_rate": 300,
"ttl": "10000d",
"base_config": "",
"endpoint_port": 9007,
"status": {
"managed_mode": true,
"start_time": 1683039674.951503,
"num_ports": 29,
"status": "running",
"iteration_time_sec": 0.274126,
"export_time_sec": 0.000279,
"port_counters_time_sec": 0.010115,
"ports_per_sec": 2867.029164607019,
"timestamp": 1683093341.727322
},
"is_registered_discovery": true,
"root_dir": "/opt/ufm/files/dynamic_telemetry/pdr_dynamic",
"configuration": {
"plugin_env_UFM_TELEMETRY_MANAGED_MODE": 1,
"plugin_env_CLX_EXPORT_API_SHOW_STATISTICS": 1
},
"conf_file": "",
"hca": "mlx5_0",
"pid": 3662593
}
}
43.2 Change Running Instance
•
Description: Modifies the run configuration of an active telemetry instance. Specifically, the
user is permitted to alter a specific set of GUIDs and the sample rate in their request.
•
•
Request Data:
Content-Type: application/json
{
"requested_guids": [
{
"guid": "1234",
"ports": [5, 1]
},
{
"guid": "5678",
"ports": [8]
}
],
"sample_rate": 5
}
43.3 Get All Instances Status
•
Description: Returns the running status and statistics of the started instances
•
URL: GET https://10.209.36.126/ufmRestV2/app/telemetry/instances/status
•
Request Data: N/A
• Response Example:
{
"dror": {
"managed_mode": true,
"start_time": 1681422289.418903,
"num_ports": 1,
212
"status": "running",
"iteration_time_sec": 0.026844,
"export_time_sec": 9.4e-5,
"port_counters_time_sec": 0.00068,
"ports_per_sec": 1470.5882352941176,
"timestamp": 1681422417.825401
}
}
43.4 Pause Running Instance
•
Description: Pauses a running instance (with an option to rerun it with the same
configuration).
•
•
Request Data: N/A
•
Response Example: N/A
43.5 Continue Running a Stopped Instance
•
Description: Continues running a stopped instance
•
{
"requested_guids": [
{
"guid": "1234",
"ports": [5, 1]
},
{
"guid": "5678",
"ports": [8]
}
],
"sample_rate": 5,
"ttl": “300d”,
}
•
Request Data: N/A
•
Response Example: N/A
43.6 Get Supported Counters
•
Description: Returns a list of all the supported counters.
•
•
Request Data: N/A
•
Response Example:
[
"ob_amp_lane3",
"link_width_active",
...,
"alev_plus_bfm2_lane0",
"pre_tap_lane0" ]
43.7 Delete a Running Instance
•
Description: Deletes a running telemetry instance and returns a job_id to track the deletion
process.
•
• Request Data: N/A
213
• Response Example:
job_id to track the deletion process
214
44 REST API Complementary Information
The section provides complementary information with regard to all UFM REST APIs.
44.1 Exposing site_name field in REST API
In addition to the existing REST API, users can configure the UFM to expose the site_name
(configurable) field in all the supported REST APIs. The site_name field can be used to identify
the current InfiniBand fabric that is managed by the UFM Enterprise.
To expose the site_name field, perform the following:
•
In gv.cfg and in the [Server] section, set a value for " site_name "
•
In gv.cfg and in the [Server] section, set " expose_site_name " to " true "
•
Restart UFM for the changes to take effect
44.2 Examples of REST APIs Using Various Authentication
Types
44.3 Basic Authentication
For basic authentication, run:
curl -k https://<ufm-ip>/ufmRest/resources/systems -u <username>:<password>
44.4 Session-Based Authentication
For session-based Authentication, follow the below instructions:
1.
Run the below command to log in and store the session in a cookie file.
curl -k -f -X POST -c cookies.txt -d "httpd_username=<user>" -d "httpd_password=<password>" https://<ufm-
ip>/dologin
2.
Use the session saved earlier to make as many ufmRestV2 requests as needed, for instance:
curl -k -cookie cookies.txt https://<ufm-ip>/ufmRestV2/reources/systems
44.5 Token-Based Authentication
For token-based authentication, follow the below instructions
1.
Create an access token using either the user's credentials or session:
curl -k -X POST https://<ufm-ip>/ufmRest/app/tokens -u username:password
2. Access ufmRestV3 using the access token generated earlier:
215
curl -k https://<ufm-ip>/ufmRest/resources/systems -H "Authorization:Basic <access_token>"
216
45 Plugin Management API
45.1 Get All Plugins
•
Description - Returns information about all loaded plugins
•
Request URL - GET /ufmRest/plugin
•
Response:
[
{
"name":"tfs",
"is_added":false,
"enabled":"No",
"tag":"NA",
"shared_volumes":"NA",
"port":"NA",
"status":"stopped",
"ui_config":{},
"httpd_conf_file":"Not present",
"capabilities":["add"],
"tags":["latest"]
}
]
•
Status Codes:
•
200 - Ok
45.2 Add Plugin
•
Description - Adds a plugin
•
Request URL - POST /ufmRest/plugin/<plugin-name>/run/add
•
Request Data:
{
" plugin-tag ":"<tag-version>"
}
•
Response: Redirect to job id
•
Status Codes:
•
200 - Ok
45.3 Remove Plugin
•
Description - Removes a plugin
•
Request URL - POST /ufmRest/plugin/<plugin-name>/run/remove
•
Response: Redirect to job id
•
Status Codes:
•
200 - Ok
45.4 Disable Plugin
•
Description - Disables a plugin
• Request URL - POST /ufmRest/plugin/<plugin-name>/run/disable
217
•
Response: Redirect to job id
•
Status Codes:
•
200 - Ok
45.5 Enable Plugin
•
Description - Enables a plugin
•
Request URL - POST /ufmRest/plugin/<plugin-name>/run/enable
•
Response: Redirect to job id
•
Status Codes:
•
200 - Ok
45.6 Pull Plugin Image
•
Description - Pulls plugin image. The request data may include an optional parameter called
"ha_standby," which is necessary only when the setup operates in high availability (HA) mode.
Furthermore, the fields "username" and "password" are also optional, particularly when there
is no trusted communication required between the master and standby nodes.
•
Request URL - POST /ufmRest/plugin/pull
•
Request Data:
{
{
"repository_name": <Image path in docker hup>,
“ha_standby":
{
"load_to_ha_standby": Boolean,
"username": string,
"password": string
}
}
•
Response: Redirects to job ID
•
Status Code:
•
200 - OK
45.7 Load Plugin Image
•
Description - Loads plugin image. The request data may include an optional parameter called
"ha_standby," which is necessary only when the setup operates in high availability (HA) mode.
Furthermore, the fields "username" and "password" are also optional, particularly when there
is no trusted communication required between the master and standby nodes.
•
Request URL - POST /ufmRest/plugin/load
•
Request Data:
{
"file": <file>,
“ha_standby":
{
"load_to_ha_standby": Boolean,
"username": string,
"password": string
}
}
•
Response: Redirects to job ID
• Status Code:
218
• 200 - Ok
219
46 System Monitoring REST API
46.1 Get System Monitoring Prometheus Metrics
•
Description - Retrieves Prometheus-formatted metrics for system monitoring, including CPU
Utilization Percentage, Memory Usage Percentage, IO Operations Statistics, and additional
metrics associated with UFM REST API calls and UFM Events.
•
Request URL - GET ufmRest/system_monitoring/metrics
•
Response - Text in Prometheus format
•
Status Code:
•
200 - Ok
46.2 Get Topology Changes Events History Counters
•
Description - This API grants access to event history counters associated with topology
changes, including events such as node status changes (up/down), switch status changes (up/
down), director switch status changes (up/down), and link status changes (up/down). These
events are collected through the Prometheus endpoint.
•
Request URL - GET ufmRest/system_monitoring/events_counters
•
Request Content Type - Application/json
•
Response
{
"12h": {
"Director Switch is Down": 0,
"Director Switch is Up": 0,
"Link is Down": 0,
"Link is Up": 0,
"Node is Down": 0,
"Node is Up": 6,
"Switch is Down": 0,
"Switch is Up": 0
},
"1h": {
"Director Switch is Down": 0,
"Director Switch is Up": 0,
"Link is Down": 0,
"Link is Up": 0,
"Node is Down": 0,
"Node is Up": 0,
"Switch is Down": 0,
"Switch is Up": 0
},
……
……
}
•
Status Code:
• 200 - Ok
220
47 UFM Configuration REST API
47.1 Get UFM Configuration
•
Description - Returns UFM configuration details, such as whether the feature is activated or
not, and more.
•
Request URL - GET / ufmRest/app/ufm_config
•
Request Content Type - Application/json
•
Response
default_session_interval: 30
disabled_features: ["UsageStatistics"]
ha_mode: "Disabled"
ha_standby_node: []
is_local_user: true
•
Status Code:
•
200 - Ok
47.2 Update UFM Configuration
•
Description - Updates sections within the gv.cfg file. Please note that not all sections and
properties can to be modified.
•
Request URL - PUT / ufmRest/app/ufm_config
•
Request Content Type - Application/json
•
Response: Text
•
Request Data
<section name>:{
<property>:<value>
}
•
Status Code:
• 200 - Ok
221
48 Plugin REST APIs
•
NDT Plugin REST API
•
Telemetry to FluentD Streaming (TFS) Plugin REST API
•
Events to FluentD Streaming (EFS) Plugin REST API
•
UFM Bright Cluster Integration Plugin REST APIs
•
Autonomous Link Maintenance (ALM) Plugin REST API
•
gRPC-Streamer Plugin REST API
•
Sysinfo Plugin REST API
•
SNMP REST API
48.1 NDT Plugin REST API
48.1.1 Topodiff REST APIs
48.1.1.1 Authentication
Following authentication types are supported:
•
basic (/ufmRest)
•
client (/ufmRestV2)
•
token (/ufmRestV3)
48.1.1.2 Upload NDT File
•
Description: Uploads NDT file to UFM
•
URL: POST ufmRestV2/plugin/ndt/upload_metadata
•
Request Data:
[
{
"file_name": "topo1.ndt",
"file": base64 string,
"file_type": "switch_to_host",
"sha-1": "xxx"
},
{
"file_name": "topo2.ndt",
"file": base64 string,
"file_type": "switch_to_switch",
"sha-1": "xxx"
}
]
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
•
500 - insufficient resources (disk space)
48.1.1.3 Delete NDT File
•
Description: Deletes NDT files from UFM
•
URL: POST ufmRestV2/plugin/ndt/delete
• Request Content Type - Application/json
222
•
Request Data:
[
{
"file_name": "topo1.ndt"
},
{
"file_name": "topo2.ndt"
}
]
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
•
404 - not found.
48.1.1.4 Get List of Uploaded NDT Files
•
Description: Get list of uploaded NDT files
•
URL: GET ufmRestV2/plugin/ndt/list
•
Request Data: N/A
•
Response:
[
{
"file_name": "topo1.ndt",
"last_uploaded": "2020-09-13 10:57:09.253",
"sha-1”: "c3499c2729730a7f807efb8676a92dcb6f8a3f8f",
"file_type": "switch_to_host"
},
{
"file_name": "topo2.ndt",
"last_uploaded": "2020-08-15 11:55:19.203",
"sha-1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"file_type": "switch_to_switch"
}
]
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.1.5 Run NDT Topo Diff
•
Description: Run NDT topo compare and save last X reports
•
URL: POST ufmRestV2/plugin/ndt/compare
•
Request Data (Optional):
{
"run": {
"startTime": "2020-10-01 16:40:59",
"endTime": "2020-10-01 18:45:59",
"interval": 3600
}
}
•
request data is needed only to define periodic execution
•
startTime - when to start the first run
•
endTime - the time of the last run
• interval - interval between the runs in minutes
• Response: N/A
223
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters).
48.1.1.6 Cancel NDT Topo Diff
•
Description: Cancels periodic NDT comparison
•
URL: GET ufmRestV2/plugin/ndt/cancel
•
Request: N/A
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.1.7 Get NDT Topo Diff Reports
•
Description: Get reports list
•
URL: GET ufmRestV2/plugin/ndt/reports
•
Request: N/A
•
Response Content Type - Application/json
•
Response:
[
{
"report_id": "1",
"report_scope": "Periodic",
"timestamp": "2021-06-22 11:00:00"
},
{
"report_id": "2",
"report_scope": "Periodic",
"timestamp": "2021-06-22 11:05:00"
},
{
"report_id": "3",
"report_scope": "Periodic",
"timestamp": "2021-06-22 11:10:00"
},
]
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.1.8 Get NDT Topo Diff Report
•
Description: Get a specific report
•
URL: GET ufmRestV2/plugin/ndt/reports/
•
Request: N/A
•
Response Content Type - Application/json
• Response:
{
"error”: "",
"timestamp": "2020-09-13 10:57:09.253",
"report":
{
"miss-wired":
[
{
"expected": "DSM09-0101-0617-001IB2/P2 - DSM09-0101-0721-001IB4/P2"
224
|
||
|
|
|