|
|
"actual": “DSM09-0101-0617-001IB2/P2 - DSM09-0101-0721-001IB4/P3"
},
{
"expected": "DSM09-0101-0721-001IB4/P3 - DSM09-0101-0617-001IB2/P2"
"actual": "DSM09-0101-0721-001IB4/P3 - DSM09-0101-0617-001IB2/P4"
}
],
"missing_in_ufm":
[
"DSM09-0101-0617-001IB2/P2-DSM09-0101 - 0721-001IB4/P2",
"DSM09-0101-0617-001IB2/P3-DSM09-0101 - 0721-001IB4/P3"
],
"missing_in_ndt":
[
"DSM09-0101-0617-001IB2/P6-DSM09-0101 - 0721-001IB4/P6",
"DSM09-0101-0617-001IB2/P5-DSM09-0101 - 0721-001IB4/P5"
]
}
}
In case the report can’t be generated, the error would be raised:
{
"errors": "Can’t parse file topo1.ndt",
"timestamp": "2020-09-13 10:57:09.253"
}
•
Status Codes:
The report can have three types of link and should be limited to the first 10K error
events:
•
miss-wired links - links that are connected differently than specified in the
NDTs
•
missing_in_ufm - links that are specified in the NDT files, but missing in the
UFM
• missing_in_ndt - links that aren’t specified in the NDT, but found by the UFM
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2 Subnet Merger REST APIs
48.1.2.1 Upload Merger NDT File
•
Description: Uploads Merger NDT file to the NDT plugin
•
URL: POST ufmRestV2/plugin/merger_upload_ndt
•
Request Data:
file: (binary)
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - Bad request (bad or missing parameters).
48.1.2.2 Get List of Uploaded Merger NDT Files
• Description: Gets a list of uploaded merger NDT files
225
•
URL: GET ufmRestV2/plugin/ndt/merger_ndts_list
•
Request Data: N/A
•
Response Content Type - Application/json
•
Response:
[
{
"file": "ndt_small_fabric_new.csv",
"timestamp": "2023-08-09 11:34:59",
"sha-1": "",
"file_type": "",
"file_status": "Verified",
"file_capabilities": "Verify,Deploy,Update"
},
{
"file": "ndt_full_fabric_new.csv",
"timestamp": "2023-08-13 10:49:29",
"sha-1": "",
"file_type": "",
"file_status": "Verified",
"file_capabilities": "Verify,Deploy,Update"
}
]
•
Status Codes:
•
200 - Ok.
•
400 - Bad request (bad or missing parameters).
48.1.2.3 Get Info about Uploaded Merger NDT File
•
Description: Gets information about the single uploaded merger NDT file
•
URL: GET ufmRestV2/plugin/ndt/merger_ndts_list/NDT_FILE_NAME
•
Request Data: N/A
•
Response:
{
"file": "ndt_small_fabric_new.csv",
"timestamp": "2023-08-09 11:34:59",
"sha-1": "",
"file_type": "",
"file_status": "Verified",
"file_capabilities": "Verify,Deploy,Update"
}
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.4 Verify Merger NDT File
•
Description: Verifies merger NDT file with current IB fabric. The response is the number of
created reports.
•
URL: POST ufmRestV2/plugin/ndt/merger_verify_ndt
•
Request Data:
{
"ndt_file_name": "NDT_FILE_NAME",
"NDT_status": "Active"
}
Response Content Type - Application/json
Response:
{
"ndt_file_name": "NDT_FILE_NAME",
"report_id": 47
}
• Status Codes:
226
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.5 Get List of Merger Verification Reports
•
Description: Gets a list of verification reports.
•
URL: GET ufmRestV2/plugin/ndt/merger_verify_ndt_reports
•
Request Data: N/A
•
Response Content Type - Application/json
•
Response:
[
{
"report_id": 1,
"report_scope": "Single",
"timestamp": "2023-08-06 15:54:07"
},
{
"report_id": 2,
"report_scope": "Single",
"timestamp": "2023-08-06 17:03:17"
},
{
"report_id": 3,
"report_scope": "Single",
"timestamp": "2023-08-06 17:04:21"
},
{
"report_id": 4,
"report_scope": "Single",
"timestamp": "2023-08-06 17:12:59"
},
{
"report_id": 5,
"report_scope": "Single",
"timestamp": "2023-08-06 17:14:00"
}
]
Status Codes:
00 - Ok.
400 - bad request (bad or missing parameters).
48.1.2.6 Get Merger Verification Report
•
Description: Gets report by report number with all the issues found during verification.
•
URL: GET ufmRestV2/plugin/ndt/merger_verify_ndt_reports/REPORT_ID
•
Request Data: N/A
•
Response Content Type - Application/json
•
Response:
{
"status": "Completed with errors",
"error": "",
"timestamp": "2023-08-07 10:12:21",
"report": [
{
"category": "missing in wire",
"description": "expected: MF0;r-ufm-sw13:MQM8700/U1/1 - NEMO-LEAF-2/11.
actual: MF0;r-ufm-sw13:MQM8700/U1/1 - NEMO-LEAF-2/1"
}
],
"NDT_file": "miswired_in_ndt_file.csv"
}
Status Codes:
200 - Ok.
400 - bad request (bad or missing parameters).
48.1.2.7 Merger Create Topoconfig File Based on NDT file
• Description: Creates a topoconfig file based on the NDT file with specified boundary port
state.
227
•
URL: POST ufmRestV2/plugin/ndt/merger_create_topoconfig
•
Request Data:
{
"ndt_file_name": "ndt_small_fabric_new.csv",
"boundary_port_state": "Disabled"
}
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.8 Merger Deploy Topoconfig File Based on NDT file
•
Description: Deploy opoconfig file to UFM server and signal OpenSM to reload configuration.
•
URL: POST ufmRestV2/plugin/ndt/merger_deploy_ndt_config
•
Request Data:
{
"ndt_file_name": "ndt_small_fabric_new.csv”
}
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.9 Merger Update and Deploy topoconfig File Based on NDT file
•
Description: Merger update boundary port state in topoconfig file and deploy topoconfig file
based on NDT file to OpenSM.
•
URL: POST ufmRestV2/plugin/ndt/merger_update_deploy_ndt_config
•
Request Data:
{
"ndt_file_name": "ndt_small_fabric_new.csv",
"boundary_port_state": "No-discover"
}
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.10 Merger Update Topoconfig File Based on NDT file
•
Description: Merger update boundary port state in topoconfig file.
•
URL: POST ufmRestV2/plugin/ndt/merger_update_topoconfig
• Request Data:
{
"ndt_file_name": "ndt_small_fabric_new.csv",
228
"boundary_port_state": "No-discover"
}
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.11 Merger Delete NDT File
•
Description: Deletes an NDT file.
•
URL: POST ufmRestV2/plugin/ndt/merger_delete_ndt
•
Request Data:
{
"ndt_file_name": "ndt_small_fabric_new.csv”
}
•
Response: N/A
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.12 Get Last Deployed NDT File
•
Description: Gets name of last deployed NDT file.
•
URL: GET ufmRestV2/plugin/ndt/merger_deployed_ndt
•
Request Data: N/A
•
Response Content Type - Application/json
•
Response:
{
"last_deployed_file": "miswired_in_ndt_file.csv"
}
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.1.2.13 Configure Cable Validation Plugin Connection
•
Description: Retrieves the connection definition status from the Cable Validation Plugin.
•
URL: POST ufmRestV2/plugin/ndt/cable_validation_connection_configuration
•
Request Data:
For local host connection
{
"address": "localhost"
}
For remote host connection
{
"address": "remote_host_name_or_ip_address",
"port": 443,
"username": "admin",
"password": "123456"
}
• Response: N/A
229
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
48.1.2.14 Get Cable Validation Plugin Connectivity Status
•
Description: Retrieves the connection definition status for the Cable Validation Plugin.
•
URL: GET ufmRestV2/plugin/ndt/cable_validation_connection_configuration
•
Request Data: N/A
•
Response Content Type - Application/json
•
Response:
For remote host connection
{
"mode": "remote",
"is_enabled": true,
"address": ""remote_host_name_or_ip_address",
"port": 443,
"username": "admin"
}
For local connection
{
"mode": "local",
"is_enabled": true
}
For disabled connection
{
"is_enabled": false
}
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
48.1.2.15 Get Cable Validation Report
•
Description: Retrieves Cable Validation Report
•
URL: GET ufmRestV2/plugin/ndt/cable_validation_report
•
Request Data: N/A
•
Response Content Type - Application/json
• Response:
{
"report": "ValidationReport",
"stats": {
"in_progress": 1,
"no_issues": 0,
"not_started": 0
},
"issues": [
{
"timestamp": 1698670939.5339258,
"node_desc": "MQM8700 r-ufm-sw13",
"rack": null,
"unit": null,
"issues": [
[
"Wrong-neighbor",
"r-ufm-sw13:P1",
"S98039b0300867bba N98039b0300867bba:P1",
"NEMO-LEAF-2:P1",
"NA",
"Switch-Switch"
],
[
"Wrong-neighbor",
"r-ufm-sw13:P3",
"S98039b0300867bba N98039b0300867bba:P3",
"NEMO-LEAF-2:P3",
230
"NA",
"Switch-Switch"
]
]
}
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters
48.2 Telemetry to FluentD Streaming (TFS) Plugin REST
API
The following authentication types are supported:
•
basic (/ufmRest)
•
client (/ufmRestV2)
•
token (/ufmRestV3)
For complete instructions on how to deploy the TFS plugin and the detailed plugin’s APIs, refer
to UFM Telemetry Endpoint Stream to Fluent Endpoint (TFS).
48.2.1 Get Streaming Configurations
•
Description: Gets the current streaming configurations
•
URL: GET ufmRest/plugin/tfs/conf
• Request Data: N/A
Response:
{
"ufm-telemetry-endpoint": [{
"host": "127.0.0.1",
"url": "csv/metrics",
"port": 9001,
"interval": 10,
"message_tag_name": "high_freq_endpoint"
}],
"fluentd-endpoint": {
"host": "10.209.36.68",
"port": 24226
},
"streaming": {
"compressed_streaming": true,
"bulk_streaming": true,
"enabled": true,
"stream_only_new_samples": true
},
"logs-config": {
"log_file_backup_count": 5,
"log_file_max_size": 10485760,
"logs_file_name": "/log/tfs.log",
"logs_level": "INFO"
},
"meta-fields":{
"alias_node_description": "node_name",
"alias_node_guid": "AID",
"add_type":"csv"
}
}
48.2.2 Update Streaming Configurations
• Description: Sets/updates streaming configurations
• URL: POST ufmRest/plugin/tfs/conf
• Request Data:
231
{
"ufm-telemetry-endpoint": [{
"host": "127.0.0.1",
"url": "csv/metrics",
"port": 9001,
"interval": 10,
"message_tag_name": "high_freq_endpoint"
}],
"fluentd-endpoint": {
"host": "10.209.36.68",
"port": 24226
},
"streaming": {
"compressed_streaming": true,
"bulk_streaming": true,
"enabled": true,
"stream_only_new_samples": true
},
"logs-config": {
"log_file_backup_count": 5,
"log_file_max_size": 10485760,
"logs_file_name": "/log/tfs.log",
"logs_level": "INFO"
},
"meta-fields":{
"alias_node_description": "node_name",
"alias_node_guid": "AID",
"add_type":"csv"
}
}
•
Response: string “set configurations has been done successfully”
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.2.3 Multiple UFM Telemetry Endpoints
To retrieve metrics from several endpoints, you can configure the TFS plugin to retrieve them. This
can be done by adding the telemetry endpoint configurations through the configuration API. Each
endpoint that you add has a separate retrieving process or streaming interval. The below is an
example payload that includes configurations for multiple UFM telemetry endpoints:
{
"ufm-telemetry-endpoint": [{
"host": "127.0.0.1",
"url": "csv/metrics",
"port": 9001,
"interval": 10,
"message_tag_name": "high_freq_endpoint"
},{
"host": "127.0.0.1",
"url": "csv/metrics",
"port": 9002,
"interval": 60,
"message_tag_name": "low_freq_endpoint"
}],
"fluentd-endpoint": {
"host": "10.209.36.68",
"port": 24226
}
}
48.2.4 Get Streaming Attributes Configurations
•
Description: Gets the current streaming attributes configurations (the enabled/disabled
attributes and also their streamed names)
•
URL: GET ufmRest/plugin/tfs/attributes
• Request Data: N/A
Response:
232
{ ...
"ExcessiveBufferOverrunErrorsExtended": {
"enabled": true,
"name": "ExcessiveBufferOverrunErrorsExtended"
},
"LinkDownedCounterExtended": {
"enabled": true,
"name": "LinkDownedCounterExtended"
},
"LinkErrorRecoveryCounterExtended": {
"enabled": true,
"name": "LinkErrorRecoveryCounterExtended"
},
"LocalLinkIntegrityErrorsExtended": {
"enabled": true,
"name": "LocalLinkIntegrityErrorsExtended"
}
}
48.2.5 Update Streaming Attributes Configurations
•
Description: Sets/updates streaming attributes configurations
•
URL: POST ufmRest/plugin/tfs/attributes
•
Request Data:
{ ...
"ExcessiveBufferOverrunErrorsExtended": {
"enabled": true,
"name": "ExcBuffOverrunErrExt"
},
"LinkDownedCounterExtended": {
"enabled": false
},
"LinkErrorRecoveryCounterExtended": {
"enabled": true,
"name": "linkErrRecCountExt"
},
"LocalLinkIntegrityErrorsExtended": {
"enabled": true,
"name": "localLinkIntErrExt"
}
}
•
Response: “Set attributes configurations has been done successfully”
•
Status Codes:
•
200 - Ok
•
400 - Bad request (bad or missing parameters)
48.3 Events to FluentD Streaming (EFS) Plugin REST API
The following authentication types are supported:
•
basic (/ufmRest)
•
client (/ufmRestV2)
•
token (/ufmRestV3)
48.3.1 Get Streaming Configurations
•
Description: Get the current streaming configurations
•
URL: GET ufmRest/plugin/efs/conf
•
Request Data: N/A
• Response:
{
233
"UFM-syslog-endpoint": {
"host": "127.0.0.1",
"port": 5140
},
"fluent-bit-endpoint": {
"destination_host": "127.0.0.1",
"destination_port": 24226,
"enabled": true,
"message_tag_name": "ufm_syslog",
"source_port": 24227
},
"logs-config": {
"log_file_backup_count": 5,
"log_file_max_size": 10485760,
"logs_file_name": "/log/efs.log",
"logs_level": "INFO"
},
"streaming": {
"enabled": false
},
"syslog-destination-endpoint": {
"enabled": false,
"host": "127.0.0.1",
"port": 514
}
}
48.3.2 Update Streaming Configurations
•
Description: Update the current streaming configurations
•
URL: PUT ufmRest/plugin/efs/conf
•
Request Data:
{
"UFM-syslog-endpoint": {
"host": "127.0.0.1",
"port": 5140
},
"fluent-bit-endpoint": {
"destination_host": "127.0.0.1",
"destination_port": 24226,
"enabled": true,
"message_tag_name": "ufm_syslog",
"source_port": 24227
},
"logs-config": {
"log_file_backup_count": 5,
"log_file_max_size": 10485760,
"logs_file_name": "/log/efs.log",
"logs_level": "INFO"
},
"streaming": {
"enabled": false
},
"syslog-destination-endpoint": {
"enabled": false,
"host": "127.0.0.1",
"port": 514
}
}
•
Response: string “set configurations has been done successfully”
•
Status Codes:
•
200 - Ok.
•
400 - bad request (bad or missing parameters).
48.4 UFM Bright Cluster Integration Plugin REST APIs
The following authentication types are supported:
•
basic (/ufmRest)
•
client (/ufmRestV2)
• token (/ufmRestV3)
234
48.4.1 Get Plugin Configurations
•
Description: Gets the current streaming configurations
•
URL: GET ufmRest/plugin/bright/conf
•
Request Data: N/A
•
Response:
{
"bright-config": {
"certificate": "-----BEGIN CERTIFICATE-----\nXXXXXXX\n-----END CERTIFICATE-----\n",
"certificate_key": "-----BEGIN PRIVATE KEY-----\nXXXXXXX\n-----END PRIVATE KEY-----\n",
"data_retention_period": "30d",
"enabled": true,
"host": "10.209.36.79",
"port": 8081,
"status": {
"err_message": "",
"status": "Healthy"
},
"timezone": "Europe/Amsterdam"
},
"logs-config": {
"log_file_backup_count": 5,
"log_file_max_size": 10485760,
"logs_file_name": "/log/bright_plugin.log",
"logs_level": "INFO"
}
}
48.4.2 Update Plugin Configurations
•
Description: Updates the current bright configurations
•
URL: PUT ufmRest/plugin/bright/conf
•
Request Data:
{
"bright-config": {
"certificate": "-----BEGIN CERTIFICATE-----\nXXXXXXX\n-----END CERTIFICATE-----\n",
"certificate_key": "-----BEGIN PRIVATE KEY-----\nXXXXXXX\n-----END PRIVATE KEY-----\n",
"data_retention_period": "30d",
"enabled": true,
"host": "10.209.36.79",
"port": 8081,
"status": {
"err_message": "",
"status": "Healthy"
},
"timezone": "Europe/Amsterdam"
},
"logs-config": {
"log_file_backup_count": 5,
"log_file_max_size": 10485760,
"logs_file_name": "/log/bright_plugin.log",
"logs_level": "INFO"
}
}
•
Response: string “Set configurations has been done successfully”
•
Status Codes:
•
200 - Ok.
• 400 - bad request (bad or missing parameters).
Configurations parameter details:
Parameter
Description
Host
Hostname or IP of the BCM server
Port
Port of the BCM server, normally will be 8081
235
Parameter
Description
Certificate
BMC client certificate content that could be located in the BMC
server machine under .cm/XXX.pem
Certificate key
BMC client certificate key that could be located in the BMC server
machine under .cm/XXX.key
Data retention period
UFM erases the data gathered in the database after the configured
retention period. By default, after 30 days.
48.4.3 Get Bright Nodes
•
Description: Gets the cached nodes from the Bright Cluster Manager
•
URL: GET ufmRest/plugin/bright/data/nodes
•
Request Data: N/A
•
Response:
[
"node001",
"swx-tor01"
]
48.4.4 Get Bright Jobs
•
Description: Gets the cached jobs from the Bright Cluster Manager nodes
•
URL: GET ufmRest/plugin/bright/data/jobs[?nodes=<node1,node2,…
>]&from=timestamp1&to=timestamp2&tz=”requested_client_timezone”
•
Request Data: N/A
• Response:
[
{
"account": "root",
"arguments": "",
"arrayID": "",
"baseType": "Job",
"cgroup": "",
"childType": "SlurmJob",
"commandLineInterpreter": "",
"comment": "",
"debug": false,
"dependencies": [],
"endtime": "2023-04-13T14:08:59",
"environmentVariables": [],
"executable": "",
"exitCode": 0,
"inqueue": "",
"jobID": "166",
"jobname": "interactive",
"mailList": "",
"mailNotify": false,
"mailOptions": "",
"maxWallClock": "UNLIMITED",
"memoryUse": 0,
"minMemPerNode": 0,
"modified": false,
"modules": [],
"nodes": [
"node001"
],
"numberOfNodes": 1,
"numberOfProcesses": 8,
"oldLocalUniqueKey": 0,
"parallelEnvironment": "",
"parentID": "",
"pendingReasons": [
"NonZeroExitCode"
236
],
"placement": "",
"priority": "4294901759",
"project": "",
"refJobQueueUniqueKey": 77309411329,
"refWlmClusterUniqueKey": 163208757249,
"requestedCPUCores": 0,
"requestedCPUs": 8,
"requestedGPUs": 0,
"requestedMemory": 0,
"requestedSlots": 0,
"resourceList": [],
"revision": "",
"runWallClock": 3,
"rundirectory": "/root",
"scriptFile": "",
"starttime": "2023-04-13T14:08:56",
"status": "FAILED",
"stderrfile": "",
"stdinfile": "",
"stdoutfile": "",
"submittime": "2023-04-13T14:08:56",
"taskID": "",
"toBeRemoved": false,
"uniqueKey": 70368744177830,
"userdefined": [],
"usergroup": "root",
"username": "root"
}
]
Please be aware that the following filters are available as options (as indicated in the URL):
•
To filter jobs by node(s) name, use the parameter "nodes" followed by a comma-separated list
of nodes (e.g. nodes=node1,node2,etc...).
•
To filter jobs by their creation timestamp, specify a start and end time in integer timestamp
format (in milliseconds).
48.5 Autonomous Link Maintenance (ALM) Plugin REST
API
48.5.1 Generate System Dump
•
Description: Triggers system dump to collect data from ALM
•
URL: POST ufmRestV2/plugin/alm/alm/sys_dump
•
Request Data: N/A
•
Status Code:
•
200 - System_dump ID located at the location field in the header
48.5.2 Get System Dump
•
Description: Gets system dump for ALM
•
URL: GET ufmRestV2/plugin/alm/alm/sys_dump/<system_dup_id>
•
Request Data: N/A
•
Status Code:
•
200 - Ok - Once the system dump procedure is completed, a compressed file containing
the system dump is provided
•
404 - "Not Found" - The system dump is not found
• 409 - "Conflict - The system dump procedure is in progress
237
48.6 gRPC-Streamer Plugin REST API
48.6.1 Authentication
The following authentication types are supported:
•
basic (/ufmRest)
•
token (/ufmRestV3)
48.6.2 Create a Session to UFM from gRPC
Description: Creates a session to receive REST API results from the gRPC server. After a stream or
submitting a call once, the session is deleted so that the authorizations are not saved by the server.
•
Call: CreateSession in the gRPC
•
Request Content Type: message SessionAuth
•
Request Data:
message SessionAuth{
string job_id=1;
string username = 2;
string password = 3;
optional string token = 4;
}
•
Job_id - A unique identifier for the client
•
Username - Basic authentication username
•
Password - Basic authentication password
•
Token - The authentication token
•
Response content type:
message SessionRespond{
string respond=1;
}
•
Respond types:
•
Success - Ok.
•
ConnectionError - UFM connection error (bad parameters or UFM is down).
•
Other exceptions - Details sent in the response.
•
Console command:
client session --server_ip=server_ip --id=client_id --auth=username,password --token=token
48.6.3 Create a New Subscription
•
Description: Only after the server has an established session for this gRPC client, the server
adds all the requested REST APIs with intervals and delta requests.
•
Call: AddSubscriber
•
Request Content Type - Message SubscriberParams
• Request Data:
238
message SubscriberParams{
message APIParams {
string ufm_api_name = 1;
int32 interval = 2;
optional bool only_delta = 3;
}
string job_id = 1;
repeated APIParams apiParams = 2;
}
•
Job_id - A unique identifier of this subscriber
•
apiParams - A list of apiParams from the message above
•
ufm_api_name - A name from the supported REST API list of names
•
interval - The interval (in seconds) between messages that the server sends in a stream
run
•
only_delta - Receive the difference between the previous messages in a stream run
•
Response content type:
message SessionRespond{
string respond=1;
}
•
Response types:
•
Created user with session and added a new IP address - Ok.
•
Cannot add subscriber without an established session - need to create a session before
creating a subscriber.
•
The server already has the ID - need to create a new session and a new subscriber with
a unique ID.
•
Console command:
client create --server_ip=localhost --id=client_id --apis=events;40;True,links,alarms;10
•
The list of APIs is separated by commas, and the modifiers of each REST API is
separated by a semi comma.
•
If the modifiers are not provided, the server uses default ones (where only_delta is
False and interval is based on the API).
48.6.4 Edit a Known Subscription
•
Description: Changes a known IP address, even if the IP address exists on the server or not.
•
Call: AddSubscriber
•
Request Content Type: Message SubscriberParams
•
Request Data:
message SubscriberParams{
message APIParams {
string ufm_api_name = 1;
int32 interval = 2;
optional bool only_delta = 3;
}
string job_id = 1; //unique identifier for this job
repeated APIParams apiParams = 2;
}
• Job_id - A unique identifier of this subscriber.
239
•
apiParams - The list of apiParams from the above message
•
ufm_api_name - A name from the supported REST API list of names
•
interval - The interval in seconds between messages that the server sends in a stream
run
•
only_delta - Receives only the difference between the previous messages in a stream
run
•
Response content type:
message SessionRespond{
string respond=1;
}
•
Response Types:
•
Created a user with a session and added a new IP address - Ok.
•
Cannot add subscriber that does not have a session - need to create a session before
creating a subscriber.
•
Cannot add subscriber illegal APIs - cannot create subscriber with empty API list, call
again with correct API list.
48.6.5 Get a List of Known Subscribers
•
Description: Gets a list of subscribers including the requested API lists.
•
Call: ListSubscribers
•
Request Content Type: google.protobuf.Empty
•
Response:
message ListSubscriberParams{
repeated SubscriberParams subscribers = 1;
}
•
Console command: server subscribes --server_ip=server_ip
48.6.6 Delete a Known Subscriber
•
Description: Deletes the subscriber and session (if existing).
•
Call: DeleteSubscriber
•
Request Content Type: Message gRPCStreamerID
•
Request Data:
message gRPCStreamerID{
string job_id = 1;
}
•
Response: google.protobuf.Empty
48.6.7 Run a Known Subscriber Once
•
Description: Runs the Rest API list once for a known subscriber and returns the result in
message runOnceRespond, and then deletes the subscriber session.
• Call: RunOnceJob
240
•
Request Content Type: Message gRPCStreamerID
•
Request Data:
message gRPCStreamerID{
string job_id = 1;
}
•
Response content type:
message runOnceRespond{
string job_id=1;
repeated gRPCStreamerParams results = 2;
}
•
Job_id- A unique identifier of the first message.
•
Results - A list of gRPCStreamerParams contains the results from each REST API list.
•
Respond:
•
Job id - Cannot run a client without an established session. Empty results - no session
for this client, and the client is not known to the server.
•
Job id - Cannot run a client without creating a subscriber. Empty results - a session was
created for this client, but not a subscription.
•
Job_id - Could not connect to the UFM. Empty results - the gRPC server cannot connect
to the UFM machine and receive empty results, because it cannot create a subscriber
with an empty API list. This means that the UFM machine has a problem or is shut
down.
•
Job_id - The first unique identifier of the messages, and not empty results - Ok.
•
Console command:
client once_id --server_ip=server_ip --id=client_id
48.6.8 Run Streamed Data of a Known Subscriber
•
Description: Runs a stream of results from the Rest API list for a known subscriber and returns
the result as an iterator, where each item type is a message gRPCStreamerParams. At the
end, the server deletes the session.
•
Call: RunStreamJob.
•
Request Content Type: Message gRPCStreamerID.
•
Request Data:
message gRPCStreamerID{
string job_id = 1;
}
•
Response content type: iterator of messages gRPCStreamerParams:
message gRPCStreamerParams{
string message_id = 1; // unique identifier for messages
string ufm_api_name = 2; // what rest api receive the data from
google.protobuf.Timestamp timestamp = 3; //what time we created the message, can be converted to Datetime
string data = 4; // data of rest api call
}
•
Response:
• Only one message with data - no session.
241
•
No message - no session and/or no subscriber with this ID.
•
Messages with interval between with the modifiers - Ok.
•
Console command:
client stream_id --server_ip=server_ip --id=client_id
48.6.9 Run New Subscriber Once
•
Description: After the server checks it has a session for this job ID, it runs the Rest API list for
a new subscriber once and returns the result in message runOnceRespond. It does not save
the subscriber ID or the session in the server.
•
Call: RunOnce
•
Request Content Type: Message SubscriberParams
•
Request Data:
message SubscriberParams{
message APIParams {
string ufm_api_name = 1;
int32 interval = 2;
optional bool only_delta = 3;
}
string job_id = 1; //unique identifier for this job
repeated APIParams apiParams = 2;
}
•
Response content type:
message runOnceRespond{
string job_id=1;
repeated gRPCStreamerParams results = 2;
}
•
Response:
•
Job id - Cannot run a client without an established session. Empty results - no session
for this client.
•
Job_id - 0 - The gRPC server cannot connect to the UFM machine and receive empty
results, or it cannot create a subscriber with an empty API list.
•
Job_id - The first unique identifier of the messages. Not empty results - Ok.
•
Console command:
client once --server_ip=server_ip --id=client_id --auth=username,password --token=token --apis=events;40;Tr
ue,links;20;False,alarms;10
•
The console command also creates a session for this client.
•
Either a token or basic authorization is needed.
48.6.10 Run Streamed Data of a New Subscriber
•
Description: After the server checks it has a session for this job ID, it runs a stream of results
from the Rest API list for a new subscriber and returns the result as an iterator, where each
item is a message gRPCStreamerParams. At the end, it deletes the session.
•
Call: RunPeriodically
• Request Content Type: Message SubscriberParams
242
•
Request Data:
message SubscriberParams{
message APIParams {
string ufm_api_name = 1;
int32 interval = 2;
optional bool only_delta = 3;
}
string job_id = 1; //unique identifier for this job
repeated APIParams apiParams = 2;
}
•
Response content type: iterator of messages gRPCStreamerParams
•
Response:
•
Only one message with data - Cannot run client without an established session - No
session
•
Messages with intervals between with the modifiers - Ok
•
Console command:
client stream --server_ip=server_ip --id=client_id --auth=username,password --token=token --apis=events;40;
True,links;20;False,alarms;10
•
The console command also creates a session for the client.
•
Either a token or a basic authorization is needed.
48.6.11 Run a Serialization on all Running Streams
•
Description: Runs a serialization for each running stream. The serialization returns results
from the REST API list to each of the machines.
•
Call: Serialization
•
Request Content Type: protobuf.Empty
•
Response: google.protobuf.Empty
48.6.12 Stop a Running Stream
•
Description: Cancels running streams using the client's stream ID and stops it from outside.
•
Call: StopStream
•
Request Content Type: Message gRPCStreamerID
•
Request Data:
message gRPCStreamerID{
string job_id = 1;
}
•
Response: google.protobuf.Empty
48.6.13 Run a Subscribe Stream
•
Description: Creates a subscription to a client identifier. All new messages that go to that
client, will be copied and also sent to this stream.
•
Call: Serialization SubscribeToStream
• Request Content Type: message gRPCStreamerID
243
•
Response: iterator of messages gRPCStreamerParams
message gRPCStreamerParams{
string message_id = 1; // unique identifier for messages
string ufm_api_name = 2; // what rest api receive the data from
google.protobuf.Timestamp timestamp = 3; //what time we created the message, can be converted to Datetime
string data = 4; // data of rest api call
}
•
The identifier may or may not be in the gRPC server.
•
Streams cannot be stopped using StopStream.
•
Console command:
client subscribe --server_ip=server_ip --id=client_id
48.6.14 Get Variables from a Known Subscriber
•
Description: Get the variables of known subscriber (if found), else return empty variables.
•
Call: GetJobParams
•
Request Content Type: message gRPCStreamerID
•
Response:
message SubscriberParams{
message APIParams {
string ufm_api_name = 1; //currently the list of api from ufm that are supported are [Jobs, Events,
Links, Alarms]
int32 interval = 2;
optional bool only_delta = 3;
}
string job_id = 1; //unique identifier for this job
repeated APIParams apiParams = 2;
}
48.6.15 Get Help / Version
•
Description: Get help, plugin version, and information on how to interact with the server.
What stages need to be done to extract the REST APIs (Session>run once/stream or
Session>AddSubscriber>once_id/stream_id)
•
Call: Help or Version
•
Request Content Type: google.protobuf.Empty
•
Response:
message SessionRespond{
string respond=1;
}
48.7 Sysinfo Plugin REST API
48.7.1 Authentication
Following authentication types are supported:
• basic (/ufmRest)
244
•
client (/ufmRestV2)
•
token (/ufmRestV3)
48.7.2 Create Request Query
•
Description: Starts a new query to retrieve system information for each specified switch. The
plugin will initiate new queries for the switches that are specified in the UFM. If no switches
are specified, the plugin startS queries for all switches.
•
URL: POST ufmRestV2/plugin/sysinfo/query
• Request Data:
{
“switches”:[]
“commands”:[“show inventory”,”show power”]
“callback”:” http://localhost:8999/dummy”
“one_by_one”: false
“periodic_run”:{
“interval”:10
“duration”:”00:02:00”
}
}
Field Name
Description
Example
Default
switches
List of switches IPs
["11.222.33.44","11 All managed switches on
the fabric discover by
.333.444.55"]
UFM
commands
List of commands to run
["show guid","show None
fan"]
callback
Endpoint to send switch responses "http://
None
to
localhost:5566/
management/
key_value"
one_by_one
True - Sends results for the switch
False
True
running on it
False - Waits for all the switches
to end and send all switch results
at once
ignore_ufm
When presenting a list of
True
False
switches, UFM validates that
these switches are included in its
database. If a switch is not
recognized by UFM, it will be
disregarded. To override this
behavior, use the " ignore_ufm "
flag
245
Field Name
Description
Example
Default
periodic_run Executes the request repeatedly
{ "interval": 5, #
None
for a set duration, the interval at
seconds
which it runs should be specified
"duration":
in seconds using the "interval"
field. The period over which the
"00:30:00", #
request should be executed can
HH:MM:SS
be defined by utilizing either the
"startTime":
" startTime " and " endTime "
"2023-02-15
fields or the " duration " field.
9:26:30",
"endTime":
"2023-02-15
18:40:30"
}
•
Response:
{ ”request_id”:” 114730344”}
•
Status Codes:
•
200 - Ok
•
400 - Bad request (bad or missing parameters)
48.7.3 Delete Schedule Request
•
Description: Deletes and cancels future requests from the plugin.
•
URL: POST ufmRestV2/plugin/sysinfo/delete/<request_id>
•
Request Data: N/A
•
Response: N/A
•
Status Codes:
•
200 - Ok
•
400 - Request ID not found
48.7.4 Cancel Sysinfo Scheduler Run
•
Description: This plugin allows you to cancel and delete future requests to the plugin, but the
request ID is stored for later reactivation. To reactivate the sysinfo request, you need to call
the Update API using the same request ID and specify the new duration for the request. You
can refer to the Update Schedule Request
•
API for more information.
•
URL: GET ufmRestV2/plugin/sysinfo/cancel/<request_id>
•
Request: N/A
•
Response: N/A
•
Status Codes:
•
200 - Ok
• 400 - Request ID not found
246
48.7.5 Update Schedule Request
•
Description: This plugin allows you to update an existing schedule request with a new
duration. A duration flag can be used instead of the endTime flag (which is identical to the
schedule_run Request API flags). Instead of using the endTime flag, you can use a duration
flag which calculates the required end time by adding the API duration to the current time.
The plugin then extends the requests for the calculated duration time. If the calculated
duration is shorter than the existing duration, the plugin cancels future requests to match the
new duration. If a request is cancelled, the plugin restarts and initiates future calls for it.
•
URL: POST ufmRestV2/plugin/sysinfo/update/<request_id>
•
Request Content Type - Application/json
•
Request:
{
“duration”:”00:20:00”
}
•
Response: N/A
•
Status Codes:
•
200 - Ok
•
400 - Bad request (bad or missing parameters) or not found
48.7.6 Help
•
Description: Returns a help message that includes the available commands and flags, as well
as instructions on how to use them.
•
URL: GET ufmRestV2/plugin/sysinfo/help
•
Request Content Type - Application/json
•
Request: N/A
•
Response:
{
"API": ["GET /version", "POST /query", "POST /cancel", "POST /update", "POST /delete","POST /dummy"],
"POST /query":
{
"Description": "Post a query of commands to the switches and return the information as callback",
"URL": "POST ufmRestV2/plugin/sysinfo/query",
}
"POST /cancel":{
}
"POST /update":{
}...
}
•
Status Codes:
•
200 - Ok
48.7.7 Version
•
Description: Returns plugin version
•
URL: GET ufmRestV2/plugin/sysinfo/Version
•
Request Content Type - Application/json
• Request: N/A
247
•
Response:
{"version": "1.0.5-0"}
•
Status Codes:
•
200 - Ok
48.8 SNMP REST API
48.8.1 Register Switches
•
Description: Registers switches to receive traps to the specified hosts
•
URL: POST ufmRestV2/plugin/snmp/register
•
Request Content Type - Application/json
•
Request Data:
{
“switches”: [“0.0.0.0”, “1.1.1.1”],
“hosts”: [“1.2.3.4”]
}
Notes:
•
Request data is needed only to define specific switches and hosts, by default, all switches are
registered to send traps to the plugin
•
Hosts are optional, specified switches are registered to send traps to the plugin by default
•
Response: N/A
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
•
500 - internal error
48.8.2 Unregister Switches
•
Description: Unregisters switches to stop sending traps to the specified hosts
•
URL: POST ufmRestV2/plugin/snmp/unregister
•
Request Content Type - Application/json
•
Request Data:
{
“switches”: [“0.0.0.0”, “1.1.1.1”],
“hosts”: [“1.2.3.4”]
}
Notes:
•
Request data is needed only to define specific switches and hosts, by default, all switches are
unregistered
•
Hosts are optional, specified switches are unregistered to stop sending traps to the plugin by
default
• Response: N/A
248
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
•
500 - internal error
48.8.3 Enable Trap
•
Description: Enables sending the specified traps from all switches
•
URL: POST ufmRestV2/plugin/snmp/enable_trap
•
Request Content Type - Application/json
•
Request Data:
{
“traps”: [“trap1”, “trap2”]
}
•
Response: N/A
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
•
500 - internal error
48.8.4 Disable Trap
•
Description: Disable the sending of specified traps from all switches
•
URL: POST ufmRestV2/plugin/snmp/disable_trap
•
Request Content Type - Application/json
•
Request Data:
{
“traps”: [“trap1”, “trap2”]
}
•
Response: N/A
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
•
500 - internal error
48.8.5 Get a List of Registered Switches
•
Description: Gets a list of registered switches
•
URL: GET ufmRestV2/plugin/snmp/switch_list
•
Request Data: N/A
•
Response Content Type - Application/json
•
Response:
[“0.0.0.0”, “1.1.1.1”]
• Status Codes:
249
•
200 - Ok
•
400- bad request (bad or missing parameters)
•
500 - internal error
48.8.6 Get a List of Monitored Traps
•
Description: Gets a list of monitored traps
•
URL: GET ufmRestV2/plugin/snmp/trap_list
•
Request: N/A
•
Response:
[“trap1”, “trap2”, “trap3”]
•
Status Codes:
•
200 - Ok
•
400 - bad request (bad or missing parameters)
•
500 - internal error
48.8.7 SNMP Plugin Version
•
Description: Returns a release version
•
URL: POST ufmRestV2/plugin/snmp/version
•
Request: N/A
•
Response Content Type - Application/json
•
Status Codes:
•
200 - Ok
• 400 - bad request (bad or missing parameters)
250
49 Document Revision History
Revision
Nate
Description
6.15.2
Jan 5, 2024
No changes
6.15.1
Dec 12, 2023
Added the following sections under NDT Plugin
REST API:
•
Configure Cable Validation Plugin Connection
•
Get Cable Validation Plugin Connectivity
Status
•
Get Cable Validation Report
6.15.0
Nov 5, 2023
Updated:
•
Get Managed Switches Power Consumption
•
Create History
•
Continue Running a Stopped Instance -
Updated URL
•
REST API Complementary Information -
Introduced new authentication methods
•
Mark Healthy Ports as Unhealthy
•
Instantiate a New Instance
•
Delete a Running Instance
Added:
•
Create an Empty PKey
•
Forge InfiniBand Anti-Spoofing REST API
•
Get Events Logs in JSON Format
•
Usage Statistics REST API
•
UFM Configuration REST API
•
System Monitoring REST API
•
REST API Complementary Information
6.14.1
Aug 29, 2023
Updated:
•
Modules REST API - Added "hw_revision" field
in module REST API
•
Systems REST API - Added "hw_revision" field
in module REST API
Added:
Subnet Merger REST APIs
6.14.0
Aug 10, 2023
Updated:
•
Mark Unhealthy Ports as Healthy
•
Create a New SHARP Reservation
•
Delete SHARP Reservation
Added:
•
Delete Policies
•
Get Healthy Policy Ports
•
Get Healthy Policy Devices
•
Load Plugin Image
•
Pull Plugin Image
• Roles Access Control
6.13.1
May 18, 2023
No change
251
Revision
Nate
Description
6.13.0
May 5, 2023
Updated:
•
Create a New SHARP Reservation - Added
partial aloc parameter to the API
•
Update SHARP Reservation - Added partial
aloc parameter to the API
•
Get Virtual Ports for Specific Physical Port
•
Telemetry to FluentD Streaming (TFS) Plugin
REST API
•
PKey GUIDs Rest API
Added:
•
UFM Dynamic Telemetry Instances REST API
•
SNMP REST API
•
Sysinfo Plugin REST API
•
Added the following REST APIs under NVIDIA
SHARP REST API
•
Get All SHARP Jobs
•
Get a Specific SHARP Job
•
Get All SHARP Non-Blocking Jobs
•
Get Specific SHARP Non-Blocking Job
•
Added the following REST APIs under
Telemetry to FluentD Streaming (TFS) Plugin
REST API
•
Multiple UFM Telemetry Endpoints
•
Get Streaming Attributes
Configurations
•
Update Streaming Configurations
•
Autonomous Link Maintenance (ALM) Plugin
REST API
6.12.1
Feb 19, 2023
No changes
6.12.0
Feb 6, 2023
Updated:
•
Create a New SHARP Reservation
•
Delete SHARP Reservation
•
Update SHARP Reservation
Added:
•
Remove Hosts from PKey
•
Delete PKey
•
UFM System Dump API
•
Plugin Management API
6.11.1
Dec, 2022
Removed Logical Server (LS) Auditing REST API
6.11.0
Nov, 2022
Added:
•
Get Default Monitoring Session Data by PKey
Filtering
•
Monitoring Sessions REST API - Added
filtering by group name
•
Mark All Unhealthy Ports as Healthy at Once
•
Systems REST API
•
Events to FluentD Streaming (EFS) Plugin
REST API
Updated:
•
Disable/Enable/Reset Ports
•
Mark Device as Unhealthy
• Telemetry to FluentD Streaming (TFS) Plugin
REST API
252
Revision
Nate
Description
6.10.0
Jul, 2022
Added:
•
Periodic Fabric Health REST API
•
Uploading New UFM Appliance Version REST
API
Aug, 2022
Updated:
•
NVIDIA SHARP REST API
6.9.0
Apr, 2022
Added:
•
Page Client Authentication REST API
•
Page Telemetry to FluentD Streaming (TFS)
Plugin REST API
•
Section Activate Cables Transceivers
Firmware Action
• Section Get Active Firmware Versions
253
Notice
This document is provided for information purposes only and shall not be regarded as a warranty of a certain
functionality, condition, or quality of a product. Neither NVIDIA Corporation nor any of its direct or indirect subsidiaries
and affiliates (collectively: “NVIDIA”) make any representations or warranties, expressed or implied, as to the accuracy
or completeness of the information contained in this document and assumes no responsibility for any errors contained
herein. NVIDIA shall have no liability for the consequences or use of such information or for any infringement of patents
or other rights of third parties that may result from its use. This document is not a commitment to develop, release, or
deliver any Material (defined below), code, or functionality.
NVIDIA reserves the right to make corrections, modifications, enhancements, improvements, and any other changes to
this document, at any time without notice. Customer should obtain the latest relevant information before placing orders
and should verify that such information is current and complete.
NVIDIA products are sold subject to the NVIDIA standard terms and conditions of sale supplied at the time of order
acknowledgement, unless otherwise agreed in an individual sales agreement signed by authorized representatives of
NVIDIA and customer (“Terms of Sale”). NVIDIA hereby expressly objects to applying any customer general terms and
conditions with regards to the purchase of the NVIDIA product referenced in this document. No contractual obligations
are formed either directly or indirectly by this document.
NVIDIA products are not designed, authorized, or warranted to be suitable for use in medical, military, aircraft, space, or
life support equipment, nor in applications where failure or malfunction of the NVIDIA product can reasonably be
expected to result in personal injury, death, or property or environmental damage. NVIDIA accepts no liability for
inclusion and/or use of NVIDIA products in such equipment or applications and therefore such inclusion and/or use is at
customer’s own risk.
NVIDIA makes no representation or warranty that products based on this document will be suitable for any specified use.
Testing of all parameters of each product is not necessarily performed by NVIDIA. It is customer’s sole responsibility to
evaluate and determine the applicability of any information contained in this document, ensure the product is suitable
and fit for the application planned by customer, and perform the necessary testing for the application in order to avoid a
default of the application or the product. Weaknesses in customer’s product designs may affect the quality and reliability
of the NVIDIA product and may result in additional or different conditions and/or requirements beyond those contained in
this document. NVIDIA accepts no liability related to any default, damage, costs, or problem which may be based on or
attributable to: (i) the use of the NVIDIA product in any manner that is contrary to this document or (ii) customer product
designs.
No license, either expressed or implied, is granted under any NVIDIA patent right, copyright, or other NVIDIA intellectual
property right under this document. Information published by NVIDIA regarding third-party products or services does not
constitute a license from NVIDIA to use such products or services or a warranty or endorsement thereof. Use of such
information may require a license from a third party under the patents or other intellectual property rights of the third
party, or a license from NVIDIA under the patents or other intellectual property rights of NVIDIA.
Reproduction of information in this document is permissible only if approved in advance by NVIDIA in writing, reproduced
without alteration and in full compliance with all applicable export laws and regulations, and accompanied by all
associated conditions, limitations, and notices.
THIS DOCUMENT AND ALL NVIDIA DESIGN SPECIFICATIONS, REFERENCE BOARDS, FILES, DRAWINGS, DIAGNOSTICS, LISTS,
AND OTHER DOCUMENTS (TOGETHER AND SEPARATELY, “MATERIALS”) ARE BEING PROVIDED “AS IS.” NVIDIA MAKES NO
WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE MATERIALS, AND EXPRESSLY
DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL NVIDIA BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT
LIMITATION ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF ANY USE OF THIS DOCUMENT, EVEN IF NVIDIA HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Notwithstanding any damages that customer might incur for any reason
whatsoever, NVIDIA’s aggregate and cumulative liability towards customer for the products described herein shall be
limited in accordance with the Terms of Sale for the product.
Trademarks
NVIDIA, the NVIDIA logo, and Mellanox are trademarks and/or registered trademarks of NVIDIA Corporation and/or
|