Network Management Interfaces

Simple Network Management Protocol (SNMP), is a network protocol for the management of a network and the monitoring of network devices and their functions. SNMP supports asynchronous event (trap) notifications and queries.MLNX-OS supports:

  • SNMP versions v1, v2c and v3

  • SNMP trap notifications

  • Standard MIBs

  • Private MIBs

Standard MIBs

The following table presents the supported textual conventions and conformance MIBs:

MIB

Standard

INET-ADDRESS-MIB

RFC-4001

SNMPV2-CONF

SNMPV2-TC

RFC 2579

SNMPV2-TM

RFC 3417

SNMP-USM-AES-MIB

RFC 3826

IANA-LANGUAGE-MIB

RFC 2591

IANA-RTPROTO-MIB

RFC 2932

IANAifType-MIB

IANA-ADDRESS-FAMILY-NUMBERS-MIB

IGMP-STD-MIB

RFC2933 (See IGMP-STD-MIB Information section)

The following table presents the supported chassis and switch MIBs:

MIB

Standard

Comments

RFC1213-MIB

RFC 1213

IF-MIB

RFC 2863

ifXTable only supported.

ENTITY-MIB

RFC 4133

ENTITY-STATE-MIB

RFC 4268

Fan and temperature states

ENTITY-SENSOR-MIB

RFC 3433

  • Port module transmit/receiver power sensors (for 1U systems only)

  • Fan and temperature sensors


Private MIBs

MIB

Description

MELLANOX-SMI-MIB

Private MIB main structure (no objects)

MELLANOX-PRODUCTS-MIB

List of OID - per managed system (sysObjID)

MELLANOX-IF-VPI-MIB

IfTable extensions

MELLANOX-EFM-MIB

Partially deprecated MIB (based on Mellanox-MIB)

Traps definitions and test trap set scalar are supported.

MELLANOX-ENTITY-MIB

Enhances the standard ENTITY-MIB (contains GUID and ASIC revision).

MELLANOX-POWER-CYCLE

Allows rebooting the switch system

MELLANOX-SW-UPDATE-MIB

Allows viewing what SW images are installed, uploading and installing new SW images

MELLANOX-CONFIG-DB

Allows loading, uploading, or deleting configuration files

MELLANOX-ENTITY-STATE-MIB

Extension to support state change traps

Note: Currently supported for power supply insertion and extraction only

MELLANOX-XSTP-MIB

Extension to support STP information

MELLANOX-DCB-TRAPS

Extension traps for ETC and PFC

MELLANOX-QOS

Proprietary QoS MIBs

MELLANOX-WJH-MIB

Defines what-just-happened traps

Private MIBs can be downloaded from the support website.

Proprietary Traps

The following private traps are supported by the
MLNX-OS

MELLANOX-EFM-MIB:

Trap

Action Required

asicChipDown

Reboot the system.

asicOverTempReset

Check fans and environmental temperature.

asicOverTemp

Check fans and environmental temperature.

lowPower

Add/connect power supplies.

internalBusError

N/A

procCrash

Generate SysDump and contact support.

cpuUtilHigh

N/A

procUnexpectedExit

Generate SysDump and contact support.

diskSpaceLow

Clean images and sysDump files using the commands “image delete” and “file debug-dump delete”.

systemHealthStatus

Refer to Health Status table.

lowPowerRecover

N/A

insufficientFans

Check Fans and environmental conditions.

insufficientFansRecover

N/A

insufficientPower

Add/connect power supplies, or change power mode using the command “power redundancy mode”.

insufficientPowerRecover

N/A

For additional information refer to MELLANOX-EFM-MIB.

Warning

For event-to-MIB mapping, please refer to “Supported Event Notifications and MIB Mapping”.

The only MELLANOX-POWER-CYCLE trap supported is mellanoxPowerCyclePlannedReload.

Configuring SNMP

Activate the SNMP server on your switch by running:

Copy
Copied!
            

switch (config) # snmp-server enable switch (config) # snmp-server enable notify switch (config) # snmp-server community public ro switch (config) # snmp-server contact "contact name" switch (config) # snmp-server host <host IP address> traps version 2c public switch (config) # snmp-server location "location name" switch (config) # snmp-server user admin v3 enable switch (config) # snmp-server user admin v3 prompt auth md5 priv des

Warning

Community strings are case sensitive.

Warning

Modular switches require SNMP timeout configuration on the agent of 60 seconds.

Resetting SNMPv3 Engine ID

Warning

Resetting SNMP engine ID is not supported on modular switch systems.

Switch systems shipped with an OS versions older than 3.6.6102 have all had the exact same SNMPv3 engine ID. Going forward, however, all switch systems will ship with a system-specific engine ID.

Upgrading the OS version to 3.6.6102 or higher does not automatically change the current engine ID. That can be done through one of the following methods after performing the software upgrade:

  • Changing a switch system’s profile

  • Running “reset factory”

  • Using the command “snmp-server engineID reset” (for more details, please see the procedure below)

To reset SNMP engine ID using “snmp-server engineID reset”:

Prerequisites:

If any of the following SNMP configurations exist, please delete/disable them and re-enable/reconfigure them only after SNMP engine ID reset is performed:

  1. Make sure SNMP is disabled. Run:

    Copy
    Copied!
                

    switch (config) # no snmp-server enable

  2. Make sure no SNMP trap host is configured. Run:

    Copy
    Copied!
                

    switch (config) # no snmp-server host <ip-address>

  3. Make sure no SNMP users are configured. Run:

    Copy
    Copied!
                

    switch (config) # no snmp-server user <username> v3

Procedure:

  1. Check existing engine ID:

    Copy
    Copied!
                

    switch (config) # show snmp engineID Local SNMP engineID: <current_key>

  2. Reset existing engine ID:

    Copy
    Copied!
                

    switch (config) # snmp-server engineID reset

  3. Verify new engine ID:

    Copy
    Copied!
                

    switch (config) # show snmp engineID Local SNMP engineID: <new_key>

Configuring an SNMPv3 User

To configure an SNMPv3 user:

  1. Configure the user using the command:

    Copy
    Copied!
                

    switch (config) # snmp-server user [role] v3 prompt auth <hash type> priv <privacy type>

    Where:
    • user role—admin
    • auth type—md5 or sha or sha224 or sha256 or sha384 or sha512
    • priv type—des or aes-128 or 3des or aes-192 or aes-256 or aes-192-cfb or aes-256-cfb

  2. Enter authentication password and its confirmation.

  3. Enter privacy password and its confirmation:

    Copy
    Copied!
                

    switch (config) # snmp-server user admin v3 prompt auth md5 priv des Auth password: ******** Confirm: ******** Privacy password: ******** Confirm: ********

    To retrieve the system table, run the following SNMP command:

    Copy
    Copied!
                

    snmpwalk -v3 -l authPriv -a MD5 -u admin -A “<Authentication password>” -x DES -X “<privacy password>” <system ip> SNMPv2-MIB::system

Configuring SNMP Notifications (Traps or Informs)

  1. Make sure SNMP and SNMP notification are enable. Run:

    Copy
    Copied!
                

    switch (config) # snmp-server enable switch (config) # snmp-server enable notify

  2. Configure SNMP host with the desired arguments (IP Address, SNMP version, authentication methods). More than one host can be configured. Each host may have different attributes. Run:

    Copy
    Copied!
                

    switch (config) # snmp-server host 10.134.47.3 traps version 3 user my-username auth sha my-password

  3. Verify the SNMP host configuration. Run:

    Copy
    Copied!
                

    switch (config) # show snmp host Notifications enabled: yes Default notification community: public Default notification port: 162   Notification sinks:   10.134.47.3 Enabled: yes Port: 162 (default) Notification type: SNMP v3 trap Username: my-username Authentication type: sha Privacy type: aes-128 Authentication password: (set) Privacy password: (set)

  4. Configure the desired event to be sent via SNMP. Run:

    Copy
    Copied!
                

    switch (config) # snmp-server notify event interface-up

    Warning

    This particular event is used as an example only.

  5. Verify the list of traps and informs being sent to out of the system. Run:

    Copy
    Copied!
                

    switch (config) # show snmp events Events for which traps will be sent: asic-chip-down: ASIC (Chip) Down cpu-util-high: CPU utilization has risen too high disk-space-low: Filesystem free space has fallen too low health-module-status: Health module Status insufficient-fans: Insufficient amount of fans in system insufficient-fans-recover: Insufficient amount of fans in system recovered insufficient-power: Insufficient power supply interface-down: An interface's link state has changed to down interface-up: An interface's link state has changed to up internal-bus-error: Internal bus (I2C) Error liveness-failure: A process in the system was detected as hung low-power: Low power supply low-power-recover: Low power supply Recover new_root: local bridge became a root bridge paging-high: Paging activity has risen too high power-redundancy-mismatch: Power redundancy mismatch process-crash: A process in the system has crashed process-exit: A process in the system unexpectedly exited snmp-authtrap: An SNMP v3 request has failed authentication topology_change: local bridge triggered a topology change unexpected-shutdown: Unexpected system shutdown

Warning

To print event notifications to the terminal (SSH or CONSOLE) refer to “Monitor”.

Warning

For the SNMPv1 traps or informs, by default, the "agent address" field is set to the IP address of the "mgmt0" interface. In the case that "source interface" is configured to the same VRF which is used for SNMPv1 traps or informs, the IP address of the source interface is used for "agent address" field. In other cases (e.g., if source interface might be configured in some other VRF), "127.0.0.1" is used for the "agent address".


SNMP SET Operations

The OS allows the user to use SET operations via SNMP interface. This is needed to configure a user/community supporting SET operations.

Enabling SNMP SET

To allow SNMP SET operations using SNMPv1/v2:

  1. Enable SNMP communities. Run:

    Copy
    Copied!
                

    switch (config) # snmp-server enable communities

  2. Configure a read-write community. Run:

    Copy
    Copied!
                

    switch (config) # snmp-server community my-community-name rw

  3. Make sure SNMP communities are enabled (they are enabled by default). Make sure “(DISABLED)” does not appear beside “Read-only communities” / “Read-write communities”. Run:

    Copy
    Copied!
                

    switch (config) # show snmp   SNMP enabled : yes SNMP port : 161 System contact : System location:   Read-only communities: public   Read-write communities: my-community-name   Interface listen enabled: yes   Listen Interfaces: Interface: mgmt0   switch (config) # show snmp No Listen Interfaces.

  4. Configure this RW community in your MIB browser.

To allow SNMP SET operations using SNMPv3:

  1. Create an SNMPv3 user. Run:

    Copy
    Copied!
                

    switch (config) # snmp-server user myuser v3 auth sha <password1> priv aes-128 <password2>

    Warning

    It is possible to use other configuration options not specified in the example above. Please refer to the command “snmp-server user” for more information.

  2. Make sure the username is enabled for SET access and has admin capability level. Run:

    Copy
    Copied!
                

    switch (config) # show snmp user User name: myuser Enabled overall: yes Authentication type: sha Privacy type: aes-128 Authentication password: (set) Privacy password: (set) Require privacy: yes SET access: Enabled: yes Capability level: admin

The OS supports the OIDs for SET operation listed in the following table which are expanded upon in the following subsections.

OID Name

OID

MELLANOX-EFM-MIB

sendTestTrapSet

1.3.6.1.4.1.33049.2.1.1.1.6.0

SNMPv2-MIB

sysName

1.3.6.1.2.1.1.5.0

MELLANOX-CONFIG-DB

mellanoxConfigDBCmdExecute

mellanoxConfigDBCmdFilename

mellanoxConfigDBCmdStatus

mellanoxConfigDBCmdStatusString

mellanoxConfigDBCmdUri

1.3.6.1.4.1.33049.12.1.1.2.3.0

1.3.6.1.4.1.33049.12.1.1.2.2.0

1.3.6.1.4.1.33049.12.1.1.2.4.0

1.3.6.1.4.1.33049.12.1.1.2.5.0

1.3.6.1.4.1.33049.12.1.1.2.1.0

MELLANOX-POWER-CYCLE

mellanoxPowerCycleCmdExecute

mellanoxPowerCycleCmdStatus

mellanoxPowerCycleCmdStatusString

1.3.6.1.4.1.33049.10.1.1.2.1.0

1.3.6.1.4.1.33049.10.1.1.2.2.0

1.3.6.1.4.1.33049.10.1.1.2.3.0

MELLANOX-SW-UPDATE

mellanoxSWUpdateCmdSetNext

mellanoxSWUpdateCmdUri

mellanoxSWUpdateCmdExecute

mellanoxSWUpdateCmdStatus

mellanoxSWUpdateCmdStatusString

mellanoxSWActivePartition

mellanoxSWNextBootPartition

1.3.6.1.4.1.33049.11.1.1.2.1.0

1.3.6.1.4.1.33049.11.1.1.2.2.0

1.3.6.1.4.1.33049.11.1.1.2.3.0

1.3.6.1.4.1.33049.11.1.1.2.4.0

1.3.6.1.4.1.33049.11.1.1.2.5.0

1.3.6.1.4.1.33049.11.1.1.3.0.0

1.3.6.1.4.1.33049.11.1.1.4.0.0


Sending a Test Trap SET Request

The OS allows the user to use test the notification mechanism via SNMP SET. Sending a SET request with the designated OID triggers a test trap.

Prerequisites:

  1. Enable SET operations by following the instructions in “Enabling SNMP SET”.

  2. Configure host to which to send SNMP notifications.

  3. Set a trap receiver in the MIB browser.

Procedure:

  1. Send a SET request to the switch IP with the OID 1.3.6.1.4.1.33049.2.1.1.1.6.0.

  2. Make sure the test trap is received by the aforementioned trap receiver (OID: 1.3.6.1.4.1.33049.2.1.2.13).

Setting Hostname with SNMP

The OS supports setting system hostname using an SNMP SET request as described in SNMPv2-MIB (sysName, OID: 1.3.6.1.2.1.1.5.0).

The restrictions on setting a hostname via CLI also apply to setting a hostname through SNMP. Refer to the command “hostname” for more information.

Power Cycle with SNMP

The OS supports power cycling its systems using an SNMP SET request as described in MELLANOX-POWER-CYCLE MIB.

Power cycle command is issued via the OID mellanoxPowerCycleCmdExecute. The following options are available:

  • Reload—saves any unsaved configuration and reloads the switch

  • Reload discard—reboots the system and discards of any unsaved changes

  • Reload force—forces an expedited reload on the system even if it is busy without saving unsaved configuration (equals the CLI command reload force)

  • Reload slave—reloads the slave management on dual management systems (must be executed from the master management module)

    Warning

    On modular switch systems, it is advised to connect via the BIP to make sure commands are executed from the master management.

Changing Configuration with SNMP

The OS supports making configuration changes on its systems using SNMP SET requests. Configuration requests are performed by setting several values (arguments) and then executing a command by setting the value for the relevant operation.

It is possible to set the parameters and execute the commands on the same SNMP request or separate them to several SET operations. Upon executing a command, the values of its arguments remain and can be read using GET commands.

Once a command is executed there may be two types of errors:

  • Immediate: This error results in a failure of the SNMP request. This means a critical error in the SNMP request has occurred or that a previous SET request is being executed

  • Delayed: The SET request has been accepted by the switch but an error occurred during its execution.

For example, when performing a fetch (download) operation, an immediate error can occur when the given URL is invalid. A delayed error can occur if the download process fails due to network connectivity issues.

The following parameters are arguments are supported:

  • Command URI—URI to fetch the configuration file from or upload the file to (for supported URI format please refer to the CLI command “configuration fetch” for more details)

  • Config file name—filename to save the configuration file to or to upload to remote location

The following commands are supported:

  • BinarySwitchTo—replaces the configuration file with a new binary configuration file. This option fetches the configuration file from the URI provided in the mellanoxConfigDBCmdUri and switches to that configuration file. This command should be preceded by a reload command in order for the new configuration to apply.

  • TextApply—fetches a configuration file in human-readable format and applies its configuration upon the current configuration.

  • BinaryUpload—uploads a binary format configuration file of the current running configuration or an existing configuration file on the switch to the URI in the mellanoxConfigDBCmdUri command. The filename parameter indicates what configuration file on the switch to upload.

  • TextUpload—uploads a human-readable configuration file of the current running configuration of an existing configuration file on the switch to the URI in the mellanoxConfigDBCmdUri command. The filename parameter indicates what configuration file on the switch to upload (same as the CLI command configuration text generate file <filename> upload).

  • ConfigWrite—saves active configuration to a filename on the switch as given in the filename parameter. In case filename is “active”, active configuration is saved to the current saved configuration (same as the CLI command configuration write).

  • BinaryDelete—deletes a binary based configuration file

  • TextDelete—deletes a text based configuration file

Upgrading OS Software with SNMP

The OS supports upgrading its software using an SNMP SET request as described in MELLANOX-SW-UPDATE MIB.

The software upgrade command is issued via the OID mellanoxSWUpdateCmdExecute. The following options are available:

  • Update—fetches the image from a specified URI (equivalent to the command “image fetch” followed by “image install”)
    The image to update from is defined by the OID mellanoxSWUpdateCmdUri. The restrictions on the URI are identical to what is supported in the CLI command “image fetch”.

  • Set-Next—changes the image for the next boot equivalent to the CLI command “image boot”)
    The partition from which to boot is defined by the OID mellanoxSWUpdateCmdSetNext. The parameters for this OID are as follows:

    • 0—no change

    • 1—partition 1

    • 2—partition 2

    • 3—next partition (default)

Using the OIDs mellanoxSWUpdateCmdStatus and mellanoxSWUpdateCmdStatusString, you may view the status of the latest operation performed from the aforementioned in either integer values, or human-readable forms, respectively. The integer values presented may be as follows:

  • 0—no operation

  • 1-100—progress in percentage

  • 101—success

  • 200—failure

IF-MIB and Interface Information

The OS supports displaying information of switch ports, LAG ports, MLAG ports and VLAN interfaces on all systems via SNMP interface. This feature is enabled by default. The interface information is available in the ifTables, ifXTable and mellanoxIfVPITable.

Additionally, traps for interface up/down, and internal link suboptimal speed are enabled. It is possible to enable one or both of these traps.

Interface up/down traps are sent whenever there is a change in the interface’s operational state. These traps are suppressed for internal links when the internal link’s speed does not match the configured speed of the link (mismatch condition).

Additional Readings and Use Cases

For more information about this feature and its potential applications, please refer to the following community posts:

JavaScript Object Notation (JSON) is a machine-to-machine data-interchange format which is supported in the CLI.

The JSON API allows executing CLI commands and receiving outputs in JSON format which can be easily parsed by the calling software.

Authentication

The JSON API protocol runs over HTTP/HTTPS and uses the existing web authentication mechanism.

In order to access the system via HTTP/HTTPS, an HTTP/HTTPS client is needed to send POST requests to the system.

Warning

HTTPS access to the web-based management console needs to be enabled using the command “web https enable” to allow POST requests.

The HTTPS client must first be authenticated by sending a POST request to the following URL:

Copy
Copied!
            

https://<ip-address>/admin/launch?script=rh&template=json-request&action=json-login

The POST request content should contain the following data (may also be saved as a file) in a JSON format:

Copy
Copied!
            

{  "username": "<user name>",  "password": "<user password>"  }

After a successful login, a session ID (cookie) is returned to be used for other HTTPS requests in the system.

Authentication Example

Before sending JSON HTTPS request, the user must first authenticate.

Create a JSON format file that contains the relevant login credentials. For example, add this content to a file called "post.json":

Copy
Copied!
            

{  "username": "admin",  "password": "admin"  }

Run the following from your server’s shell to create a login session ID in the file: cookiejar.

Copy
Copied!
            

curl -L -X POST -d @post.json -c cookiejar "http://<ip-address>/admin/launch?script=rh&template=json-request&action=json-login"

Upon a successful login, you will receive a reply similar to the following:

Copy
Copied!
            

{  "status": "OK",  "status_message": "Successfully logged-in"  }

The session ID can now be used in all other JSON HTTPS requests to the system.

If authentication fails, the following message is received:

Copy
Copied!
            

{  "status": "ERROR",  "status_message": "<Invalid username or password | Please provide username and password>"  }

You may also log in and execute commands in the same JSON request. In this case, the JSON file must be in the following format:

Copy
Copied!
            

{  "username": "<user name>",  "password": "<user password>",  "commands | cmd": ["<cli command 1>", "<cli command 2>"] | "<cli command>",  "execution_type": "sync | async"  }

For example:

Copy
Copied!
            

{  "username": "admin",  "password": "admin",  "cmd": "show fan"  }

If login is successful, the JSON API response appears. Otherwise, login failure response is presented.

Changing Initial Password Through JSON API

This section provides support for changing the default password through JSON API.

Expected Input

  • To change the initial password, the payload will be as follows:

    Copy
    Copied!
                

    { "username": "admin", "password": "admin", "initial_admin_password": "admin", "initial_monitor_password": "monitor" }

Expected Outputs

  • Admin and Monitor passwords cannot be changed because they have already been changed:

    Copy
    Copied!
                

    { "status": "ERROR", "status_message": " ‘admin’ password was already set & ‘monitor’ password was already set" }

  • Admin and Monitor passwords were changed successfully:

    Copy
    Copied!
                

    { "status_message": " <‘admin’ password was updated successfully> & <‘monitor’ password was updated successfully> " }

  • Admin and Monitor passwords were not updated:

    Copy
    Copied!
                

    { "status": "OK", "status_message": "’admin’ password was updated successfully & ‘monitor’ password was updated successfully" }

  • One of the passwords of either Admin or Monitor was changed, while the other remained the same:

    Copy
    Copied!
                

    { "status": "<ERROR|OK>", "status_message": " < Initial password for the ‘admin’ password was already set | ‘admin’ password was updated successfully> " }

  • When the payload does not have initial passwords, check change-password nodes to see if there is no updated password return in this JSON payload:

    Copy
    Copied!
                

    { "status": "ERROR", "status_message": “Please set the default password for ‘admin’ account by using initial password parameters” }

When there is no issue with the login, flow will proceed without needing this step.

JSON API Logout

To logout, do the following:

  1. Performs a POST operation on URL (the request should contain the session cookie):

    Copy
    Copied!
                

    [switch_ip]/script=rh&template=json-request&action=json-logout

  2. The switch will remove the session and return the following JSON in the response text (in case of error, content will be relevant to the error):

    Copy
    Copied!
                

    { "status": "OK", "status_message": "Successfully logged-out" }

  3. Make sure there is no cookie. A request with an invalid cookie will respond that the cookie is invalid.

Logout Example

To logout, use the “curl” tool.

Copy
Copied!
            

curl -b cookiejar "http://[switch-ip]/admin/launch?script=rh&template=json-request&action=json-logout

Sending the Request

After successful authentication, the HTTPS client can start sending JSON requests. All requests (POST and GET) should be sent to the following URL:

After the request is handled in the system the HTTPS client receives a JSON response with an indication of the request execution result. If there is data resulting from the request, it is returned as part of the response.

See “JSON Request Format” for the CLI request format.

See “JSON Response Format” for the reply format.JSON requests may also be sent using the WebUI. For more information on using the WebUI with JSON, please refer to “JSON Request Using WebUI”.

JSON Request Format

JSON Execution Requests

JSON execution requests are HTTPS POST requests that contain CLI commands to be executed in the system.

Execution request can contain a single command or multiple commands to be executed.

Single command execution request format:

Copy
Copied!
            

{ "cmd": "<CLI command to execute>" }

Example:

Copy
Copied!
            

{ "cmd": "show interfaces ethernet 1/1" }

Multiple command execution request format:

Copy
Copied!
            

{ "commands":["<CLI cmd 1>", "<CLI cmd 2>", … , <CLI cmd n>] }

Example:

Copy
Copied!
            

{ "commands": [ "show interfaces ethernet 1/1", "show interfaces ethernet 1/2" ] }

In case of a multiple command request, the execution of the commands is done in the order they appear in the execution list. Note that the execution of a multiple command request will be stopped upon first failure. That is, in case the execution of one of the commands fails, none of the remaining commands will be executed.

Execution Types

Execution requests can be either synchronous (default) or asynchronous.

Synchronous requests will wait for a JSON response from the system. The synchronous request has a defined wait time after which the user will receive a timeout response. The timeout for a synchronous request is configurable by the user and is 30 seconds by default (see the CLI command “json-gw synchronous-request-timeout”).

Asynchronous requests will return immediately after sending the request with a reply containing a “job_id” key. The user can use the given job ID to later query for request status and execution results. Queries for asynchronous request results are guaranteed to be accessible up to 60 seconds after the request has been completed. After the result has been successfully queried it will be deleted and will no longer be accessible (even if the result is not 60 seconds old).

To specify the execution type, the user needs to add the following key to the JSON execution request:

Copy
Copied!
            

"execution_type":"<async|sync>"

Example:

Copy
Copied!
            

{ "execution_type":"async", "cmd": "show interfaces ethernet 1/1" }

JSON Query Requests

JSON Query requests are HTTPS GET requests that contain a job ID parameter. Using a query request, the user can get information on the current execution state of an ongoing request or the execution results of a completed request. To send a query request, the user should add the following parameters to the JSON URL:

Copy
Copied!
            

job_id=<job number>

Example:

Copy
Copied!
            

https://<switch-ip-address>/admin/launch?script=json&job_id=<job number>

See “JSON Examples” for more examples.

JSON Response Format

Warning

Set commands normally do not return any data or output. If a set command does return an output, it will be displayed in the “status_message” field.

Single Command Response Format

The HTTPS POST response format structure is a JSON object consisting of 4 name-value pairs as follows:

Copy
Copied!
            

{ "executed_command": "<CLI command that was executed>", "status" = "<OK|ERROR>", "status_message" = "<information on the status received>", "data" = {the information that was asked for in the request} }

  • executed_command—the CLI command that was executed in the request

  • status—the result of the request execution:

    • “OK” if the execution is successful

    • “ERROR” in case of a problem with the execution

  • The value type of this key is “string”.

  • data—a JSON object containing the information requested. Returns an empty string if there is no data.

  • status message—additional information on the received status. May be empty. The value type of this key is “string”.

Example:

Copy
Copied!
            

{ “executed_command”: “show interfaces ethernet 1/1 "status": "OK", "status_message": "", "data": { "speed": "40GbE", "admin_state": "up" } }

See “JSON Examples” for more examples.

Multiple Command Response Format

The HTTPS response format structure is a JSON object consisting of a list of JSON results. Each JSON structure in the list is structured the same as in the single command execution response (see the previous section).

However, the status field can contain in this case an additional value, “ABORTED”, in case a previous command failed. This status value indicates that the command has not been executed at all in the system.

Copy
Copied!
            

{ "results": [ { "executed_command": "<…>", "status": "<OK|ERROR|ABORTED>", "status_message": "<…>", "data": {…} }, { "executed_command": "<…>", "status": "<OK|ERROR|ABORTED>", "status_message": "<…>", "data": {…} }, … { "executed_command": "<…>", "status": "<OK|ERROR|ABORTED>", "status_message": "<…>", "data": {…} } ] }

Example:

Copy
Copied!
            

{ "results": [ { "executed_command": "show interfaces ethernet 1/1", "status": "OK", "status_message": ""  "data": {"speed":"40GbE", "admin_state":"up"} }, { "executed_command": "show interfaces ethernet 1/100", "status": "ERROR", "status_message": "wrong interfaces name", "data": "" }, { "executed_command": "show interfaces ethernet 1/2", "status": "ABORTED", "status_message": "", "data": "" } ] }

See “JSON Examples” for more examples.

Query Response Format

Response to a query request can be of two types. In case the request completes its execution, the response will be similar to the single/multiple command response format, depending on the format of the request, and will display the execution results.
In case the execution is not complete yet, the response format will be similar to the single command response format. However, the status field will contain in this case the value “PENDING” to indicate that the request is still in progress. In addition, the “executed_command” field will contain the current request command being handled by the system.

Example:

Copy
Copied!
            

{ "executed_command": "show interfaces ethernet 1/1", "status": "PENDING", "status_message": "", "data":"" }


Asynchronous Response Format

Response to an asynchronous request is similar to the HTTPS response format of the single command response. However, an additional unique field will be added, “job_id”, containing the job id number for querying the request later. The value of the job_id key is of type string.

Another difference is that the “executed_command” field will be empty.

Example:

Copy
Copied!
            

{ "executed_command": "" "status": "OK" "status_message": "" "data": "" "job_id": "2754930426" }

Supported Commands

  • Show commands

  • Set commands— a ll non-interactive CLI set commands are supported

    Warning

    Interactive commands are commands which require user interaction to complete (e.g. type “yes” to confirm). These commands are not supported by the JSON API.

JSON Examples

The following examples use curl (a common tool in Linux systems) to send HTTPS POST requests to the system.

Synchronous Execution Request Example

Single Command

This example sends a request to query the system profile.

Request (save it to a file named req.json):

Copy
Copied!
            

{"cmd": "show system profile"}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

When the system finishes processing the request, the user will receive a response similar to the following:

Copy
Copied!
            

{ "status": "OK", "executed_command": "show system profile", "status_message": "", "data": { "Profile": "ib", "Adaptive Routing": "yes", "Number of SWIDs": "1" } }


Multiple Commands

This example sends a request to change an interface description and then queries for its status.

Request (save it to a file named req.json):

Copy
Copied!
            

{"commands": ["interfaces ib 1/1 description test description", "show interfaces ib 1/1 status"]}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

When the system finishes processing the request, the user will receive a response similar to the following:

Copy
Copied!
            

{ "results": [ { "status": "OK", "executed_command": "interfaces ib 1/1 description test description", "status_message": "", "data": "" }, { "status": "OK", "executed_command": "show interfaces ib 1/1 status", "status_message": "", "data": { "IB1/1": [ { "Description": "test description", "Speed": "56.0 Gbps", "Logical port state": "Initialize", "Physical port state": "LinkUp", "Current line rate": "56.0 Gbps", "IB Subnet": "infiniband-default" } ] } } ] }

Asynchronous Execution Request Example

This example sends an asynchronous request to change an interface description and then queries for its status.

Request (save it to a file named req.json):

Copy
Copied!
            

{"execution_type":"async", "commands": ["interfaces ib 1/1 description test description", "show interfaces ib 1/1 status"]}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

The system immediately returns a response similar to the following:

Copy
Copied!
            

{ "executed_command": "", "status": "OK", "status_message": "", "data": "", "job_id": "91329386" }


Query Request Example

This example sends a request to query for a job ID received from a previous execution request.

The request is a an HTTPS GET operation to the JSON URL with the “job_id” parameter.

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X GET "https://10.10.10.10/admin/launch?script=json&job_id=91329386" 

If the system is still processing the request, the user receives a response similar to the following:

Copy
Copied!
            

{ "executed_command": " interfaces ib 1/1 description test description ", "status": "PENDING", "status_message": "", "data": "" }

If the system is done processing the request, the user receives a response similar to the following:

Copy
Copied!
            

{ "results": [ { "status": "OK", "executed_command": "interfaces ib 1/1 description test description", "status_message": "", "data": "" }, { "status": "OK", "executed_command": "show interfaces ib 1/1 status", "status_message": "", "data": { "IB1/1": [ { "Description": "test description", "Speed": "fdr", "Logical port state": "Initialize", "Physical port state": "LinkUp", "Current line rate": "56.0 Gbps", "IB Subnet": "infiniband-default" } ] } } ] }


Error Response Example

General Error

This example sends a request with an illegal JSON structure.

Request—without closing bracket “]” (save it to a file named req.json):

Copy
Copied!
            

{"commands": ["interface ib 1/1 description test description", "show interfaces ib 1/1 status"}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

Error response:

Copy
Copied!
            

{ "status": "ERROR", "executed_command": "", "status_message": "Handle request failed. Reason:\nIllegal JSON structure found in given JSON data.\nExpecting , delimiter: line 1 column 95 (char 94)", "data": "" }


Multiple Command Request Failure

This example sends a multiple command request where one command fails.

Request—with a non-existing interface (1/200) (save it to a file named req.json):

Copy
Copied!
            

{ "execution_type": "sync", "commands": [ "interfaces ib 1/1 speed sdr", "interfaces ib 1/200 speed sdr", "interfaces ib 1/3 speed sdr"] }

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

Error response:

Copy
Copied!
            

{ "results": [ { "status": "OK", "executed_command": "interfaces ib 1/1 speed sdr", "status_message": "", "data": "" }, { "status": "ERROR", "executed_command": "interfaces ib 1/200 speed sdr", "status_message": "% 1st interface does not exist", "data": "" }, { "status": "ABORTED", "executed_command": "interfacesib 1/3 speed sdr", "status_message": "", "data": "" } ] }

JSON Request Using WebUI

The
MLNX-OS

WebUI also allows users to send JSON HTTPS POST and GET requests.

Log into the WebUI, go to the “Setup” tab, and select “JSON API” from the left side menu.

Warning

This section is displayed only if JSON API is enabled using the command “json-gw enable”.

To Execute a JSON Request

  1. Choose “Execute JSON command”.

  2. Choose the “execution_type” from the drop down list.

  3. In the “commands” field, type the CLI command(s) to execute.
    Use the “+” and “-” buttons to add or remove additional commands to the request.

  4. Click “Submit”.

The JSON response is then shown in the “JSON Response” box below.

The HTTPS method (HTTPS POST in this instance) and the URL used to send the request will be displayed next to the “HTTPS Method” and “URL” field respectively.

JSON_API_WebUI_Example.png


To Query an Asynchronous JSON Request

  1. Choose “Query asynchronous job status”.

  2. Type the job ID in the “Job ID” text box.

  3. Press “Query Status”.

The JSON response is then shown in the “JSON Response” box below.
The HTTPS method (HTTPS GET in this instance) and the URL used to send the request will be displayed next to the “HTTPS Method” and “URL” field respectively.

JSON_API_Asynchronous_Job_WebUI_Example.png

Additional Reading and Use Cases

For more information about this feature and its potential applications, please refer to the following community post:

© Copyright 2023, NVIDIA. Last updated on Nov 21, 2023.