NVUE API
When you upgrade to Cumulus Linux 5.6 or later, the switch overwrites any manual configuration you performed by editing files in Cumulus Linux 5.5 or earlier, such as configuring the listening address, port, TLS, or certificate.
In addition to the CLI, NVUE supports a REST API. Instead of accessing Cumulus Linux using SSH, you can interact with the switch using an HTTP client, such as cURL or a web browser.
The nvued service provides access to the NVUE REST API. Cumulus Linux exposes the HTTP endpoint internally, which makes the NVUE REST API accessible locally within the Cumulus Linux switch. The NVUE CLI also communicates with the nvued service using internal APIs. To provide external access to the NVUE REST API, Cumulus Linux uses an HTTP reverse proxy server, and supports HTTPS and TLS connections from external REST API clients.
The following illustration shows the NVUE REST API architecture and illustrates how Cumulus Linux forwards the requests internally.
Supported HTTP Methods
The NVUE REST API supports the following methods:
- The GET method displays configuration and operational data, and is equivalent to the
nv showcommands. - The POST method creates and submits operations. You typically use this method for
nv actioncommands and for thenv configcommand to create revisions. - The PATCH method replaces or unsets a configuration. You use this method for the
nv setandnv config applycommands. You can either perform:- A targeted configuration patch to make a configuration change, where you run a specific NVUE REST API targeted at a particular OpenAPI end-point URI. Based on the NVUE schema definition, you need to direct the PATCH REST API request at a particular endpoint (for example,
/nvue_v1/vrf/<vrf-id>/router/bgp) and provide the payload that conforms to the schema. With a targeted configuration patch, you can control individual resources. - A root patch, where you run the NVUE PATCH API on the root node of the schema so that a single PATCH operation can change one, some, or the entire configuration in a single payload. The payload of the PATCH method must be aware of the entire NVUE object model schema because you make the configuration changes relative to the root node
/nvue_v1. You typically perform a root patch to push all configurations to the switch in bulk; for example, if you use an SDN controller or a network management system to push the entire switch configuration every time you need to make a change, regardless of how small or large. A root patch can also make configuration changes with fewer round trips to the switch. - The input payload in a PATCH request can have either a
setorunsetjson object for the same resource, but not both. The order in which the API executes thesetandunsetobjects is not deterministic and not supported.
- A targeted configuration patch to make a configuration change, where you run a specific NVUE REST API targeted at a particular OpenAPI end-point URI. Based on the NVUE schema definition, you need to direct the PATCH REST API request at a particular endpoint (for example,
- The DELETE method deletes a configuration and is equivalent to the
nv unsetcommands.
In Cumulus Linux 5.9 and earlier, the REST API PATCH response returns the full state of the NVUE system (your configuration change and all other NVUE configuration on the switch), which can be inefficient with large scale configurations as the system state grows with the configuration. In Cumulus Linux 5.10 and later, the REST API PATCH response returns only the resulting configuration change. The response typically equals the request payload; however, in certain instances the response returns additional changes that the NVUE server patches in automatically. For example, when using well-named interface names like swp1, NVUE configures the type automatically:
PATCH request: {'interface': {'swp1': {}}
PATCH Response: {'interface': {'swp1': {'type': 'swp'}},
...
In Cumulus Linux 5.10 and later, DELETE responses return a 204(No Content) status code. In Cumulus Linux 5.9 and earlier, DELETE responses return 200 with an empty json body ({}).
Secure the API
The NVUE REST API supports HTTP basic authentication, and the same underlying authentication methods for username and password that the NVUE CLI supports. User accounts work the same on both the API and the CLI.
Certificates
Cumulus Linux includes a self-signed certificate and private key to use on the server so that it works out of the box. The switch generates the self-signed certificate and private key when it boots for the first time. The X.509 certificate with the public key is in /etc/ssl/certs/cumulus.pem and the corresponding private key is in /etc/ssl/private/cumulus.key.
NVIDIA recommends you use your own certificates and keys. For the steps to generate self-signed certificates and keys, refer to the Ubuntu Certificates and Security documentation.
Cumulus Linux lets you manage CA certificates (such as DigiCert or Verisign) and entity (end-point) certificates. Both a CA certificate and an entity certificate can contain a chain of certificates.
You can import certificates onto the switch (fetch certificates from an external source), set which certificate you want to use for the NVUE REST API, and show information about a certificate, such as the serial number, and the date and time during which the certificate is valid.
Import a Certificate
- You can import a maximum of 25 entity certificates and a maximum of 25 CA bundles. Each CA bundle file supports up to 100 CA certificates.
- The certificate you import contains sensitive private key information. NVIDIA recommends that you use a secure transport such as SFTP, SCP, or HTTPS.
- To import an entity certificate, run an
nv action import system security certificate <cert-id>command. - To import a CA certificate bundle file, run an
nv action import system security ca-certificate <cert-id>command.
If the certificate is passphrase protected, you need to include the passphrase.
You must provide a certificate ID (<cert-id>) to uniquely identify the certificate you import.
The following example imports a CA certificate bundle with a public key and calls the certificate tls-cert-1. The certificate is passphrase protected with mypassphrase. The public key is a Base64 ASCII encoded PEM string.
- You must enclose the public key in the NVUE command with three double quotes (
"""<public-key>"""). - With the REST API, you must enclose the public key with one double quote (
"<public-key>").
cumulus@switch:~$ nv action import system security ca-certificate tls-cert-1 passphrase mypassphrase data """<public-key>"""
The following example imports an entity certificate and calls the certificate tls-cert-1. The certificate is passphrase protected with mypassphrase.
A certificate bundle must be in .PFX or .P12 format.
cumulus@switch:~$ nv action import system security certificate tls-cert-1 passphrase mypassphrase uri-bundle scp://user@pass:1.2.3.4:/opt/certs/cert.p12
The following example imports an entity certificate with the public key URI scp://user@pass:1.2.3.4 and private key URI scp://user@pass:1.2.3.4, and calls the certificate tls-cert-1. The certificate is not passphrase protected.
A CA certificate must be in .pem, .p7a, or .p7c format.
cumulus@switch:~$ nv action import system security certificate tls-cert-1 uri-public-key scp://user@pass:1.2.3.4 uri-private-key scp://user@pass:1.2.3.4
Set the Certificate to Use
You can configure the NVUE REST API to use a specific certificate.
The following example configures the API to use the certificate or CA bundle named tls-cert-1:
cumulus@switch:~$ nv set system api certificate tls-cert-1
cumulus@switch:~$ nv config apply
The following example configures the API to use the self-signed certificate:
cumulus@switch:~$ nv set system api certificate self-signed
cumulus@switch:~$ nv config apply
To unset the certificate to use with the NVUE REST API:
cumulus@switch:~$ nv unset system api certificate tls-cert-1
To configure a certificate to use for mutual authentication with mTLS:
cumulus@switch:~$ nv set system api mtls ca-certificate tls-cert-1
Delete Certificates
- To delete an entity certificate and the key data stored on the switch, run the
nv action delete system security certificate <cert-id>command. - To delete a CA certificate and the key data stored on the switch, run the
nv action delete system security ca-certificate <cert-id>command.
The following command deletes the certificate tls-cert-1:
cumulus@switch:~$ nv action delete system security certificate tls-cert-1
Show Certificate Information
- To show all the entity certificates on the switch, run the
nv show system security certificatecommand. - To show all the CA certificates on the switch, run the
nv show system security ca-certificatecommand.
The following example shows all the entity certificates on the switch:
cumulus@switch:~$ nv show system security certificate
- To show the applications that are using a specific entity certificate, run the
nv show system security certificate <cert-id> installedcommand. - To show the applications that are using a specific CA certificate, run the
nv show system security ca-certificate <cert-id> installedcommand.
The following example shows the applications that are using a specific entity certificate.
cumulus@switch:~$ nv show system security certificate tls-cert-1 installed
- To show detailed information about a specific entity certificate, run the
nv show system security certificate <cert-id> dumpcommand. - To show detailed information about a specific CA certificate, run the
nv show system security ca-certificate <cert-id> dumpcommand.
The following example shows detailed information about the CA certificate tls-cert-1:
cumulus@switch:~$ nv show system security ca-certificate tls-cert-1 dump
API-only User
To create an API-only user without SSH permissions, use Linux group permissions. You can create the API-only user in the ZTP script.
# Create the dedicated automation user
adduser --disabled-password --gecos "Automation User,,,," --shell /usr/bin/nologin automation
# Set the password
echo 'automation:password!' | chpasswd
# Add the user to nvapply group to make NVUE config changes
adduser automation nvapply
Control Plane ACLs
You can secure the API by configuring:
- A listening address; see API Port and Listening Address below.
- Control plane ACLs; see the following example.
This example shows how to create ACLs to allow users from the management subnet and the local switch to communicate with the switch using REST APIs, and restrict all other access.
cumulus@switch:~$ nv set acl API-PROTECT type ipv4
cumulus@switch:~$ nv set acl API-PROTECT rule 10 action permit
cumulus@switch:~$ nv set acl API-PROTECT rule 10 match ip .protocol tcp .dest-port 8765 .source-ip 192.168.200.0/24
cumulus@switch:~$ nv set acl API-PROTECT rule 10 remark "Allow the Management Subnet to talk to API"
cumulus@switch:~$ nv set acl API-PROTECT rule 20 action permit
cumulus@switch:~$ nv set acl API-PROTECT rule 20 match ip .protocol tcp .dest-port 8765 .source-ip 127.0.0.1
cumulus@switch:~$ nv set acl API-PROTECT rule 20 remark "Allow the local switch to talk to the API"
cumulus@switch:~$ nv set acl API-PROTECT rule 30 action deny
cumulus@switch:~$ nv set acl API-PROTECT rule 30 match ip .protocol tcp .dest-port 8765
cumulus@switch:~$ nv set acl API-PROTECT rule 30 remark "Block everyone else from talking to the API"
cumulus@switch:~$ nv set system control-plane acl API-PROTECT inbound
Supported Objects
The NVUE object model supports most features on the Cumulus Linux switch. The following list shows the supported objects. The NVUE API supports more objects within each of these objects. To see a full listing of the supported API endpoints, refer to NVUE OpenAPI Specification for Cumulus Linux.
| High-level Objects | Description |
|---|---|
| acl | Access control lists. |
| bridge | Bridge domain configuration. |
| evpn | EVPN configuration. |
| interface | Interface configuration. |
| mlag | MLAG configuration. |
| nve | Network virtualization configuration, such as VXLAN-specfic MLAG configuration and VXLAN flooding. |
| platform | Platform configuration, such as hardware and software components. |
| qos | QoS RoCE configuration. |
| router | Router configuration, such as router policies, global BGP and OSPF configuration, PBR, PIM, IGMP, VRR, and VRRP configuration. |
| service | DHCP relays and server, NTP, PTP, LLDP, and syslog configuration. |
| system | Global system settings, such as the reserved routing table range for PBR and the reserved VLAN range for layer 3 VNIs, system login messages and switch reboot history. |
| vrf | VRF configuration. |
Use the API
The NVUE CLI and the REST API are equivalent in functionality; you can run all management operations from the REST API or from the CLI. The NVUE object model drives both the REST API and the CLI management operations. All operations are consistent; for example, the CLI nv show commands reflect any PATCH operation (create and update) you run through the REST API.
NVUE follows a declarative model, removing context-specific commands and settings. The structure of NVUE is like a big tree that represents the entire state of a Cumulus Linux instance. At the base of the tree are high level branches representing objects, such as router and interface. Under each of these branches are more branches. As you navigate through the tree, you gain a more specific context. At the leaves of the tree are actual attributes, represented as key-value pairs. The path through the tree is similar to a filesystem path.
Cumulus Linux enables the NVUE REST API by default. To disable the NVUE REST API, run the nv set system api state disabled command.
To use the NVUE REST API in Cumulus Linux 5.6 and later, you must change the password for the cumulus user; otherwise you see 403 responses when you run commands.
API Port and Listening Address
This section shows how to:
- Set the NVUE REST API port. If you do not set a port, Cumulus Linux uses the default port 8765.
- Specify the NVUE REST API listening address; you can specify an IPv4 address, IPv6 address, or
localhost. If you do not specify a listening address, NGINX listens on all addresses for the target port.
The following example sets the port to 8888:
cumulus@switch:~$ nv set system api port 8888
cumulus@switch:~$ nv config apply
You can listen on multiple interfaces by specifying different listening addresses:
cumulus@switch:~$ nv set system api listening-address 10.10.10.1
cumulus@switch:~$ nv set system api listening-address 10.10.20.1
cumulus@switch:~$ nv config apply
The following example configures the listening address on eth0, which has IP address 172.0.24.0 and uses the management VRF by default:
cumulus@switch:~$ nv set system api listening-address 172.0.24.0
cumulus@switch:~$ nv config apply
The following example configures VRF BLUE on swp1, which has IP address 10.10.20.1, then sets the API listening address to the IP address for swp1 (configured for VRF BLUE).
cumulus@switch:~$ nv set interface swp1 ip address 10.10.10.1/24
cumulus@switch:~$ nv set interface swp1 ip vrf BLUE
cumulus@switch:~$ nv config apply
cumulus@switch:~$ nv set system api listening-address 10.10.10.1
cumulus@switch:~$ nv config apply
The following example sets the port to 8888:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request PATCH https://localhost:8765/nvue_v1/system/api?rev=2 -H 'Content-Type:application/json' -d '{"port": 8888 }'
You can listen on multiple interfaces by specifying different listening addresses. The following example sets localhost, interface address 10.10.10.1, and 10.10.20.1 as listen-addresses.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request PATCH https://localhost:8765/nvue_v1/system/api/listening-address?rev=2 -H 'Content-Type:application/json' -d '{ "localhost": {}, "10.10.10.1": {}, "10.10.20.1": {}}'
The following example configures the listening address on eth0, which has IP address 172.0.24.0 and uses the management VRF by default:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request PATCH https://localhost:8765/nvue_v1/system/api/listening-address?rev=2 -H 'Content-Type:application/json' -d '{"172.0.24.0": {}}'
Show NVUE REST API Information
To show REST API port configuration, state (enabled or disabled), certificate, listening address, and connection information:
Run the nv show system api command:
cumulus@switch:~$ nv show system api
operational applied
-------------- ----------- -------
port 8888 8888
state enabled enabled
certificate self-signed self-signed
[listening-address] localhost localhost
connections
accepted 31
active 1
handled 33
reading 0
requests 28
waiting 0
writing 1
To show connection information only, run the nv show system api connections command:
cumulus@switch:~$ nv show system api connections
operational applied
-------- ----------- -------
accepted 31
active 1
handled 33
reading 0
requests 28
waiting 0
writing 1
To show the configured listening address, run the nv show system api listening-address command:
cumulus@switch:~$ nv show system api listening-address
---------
localhost
To show all the certificates installed on the switch, run the nv show system security certificate command. To show information about a specific certificate, such as the serial number and how long the certificate is valid, run the nv show system security certificate <certificate> command:
cumulus@switch:~$ nv show system security certificate tls-cert-1
operational applied pending
------------- ------------------------- ------- -------
installed
app TLS
serial-number 67:03:3B:B4:6E:35:D3
valid-from 2023-02-14T00:35:18+00:00
valid-to 2033-02-11T00:35:18+00:00
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request GET https://localhost:8765/nvue_v1/system/api?rev=2 -H "accept: application/json"
{
"certificate": "self-signed",
"listening-address": {
"10.10.10.1": {},
"10.10.20.1": {},
"172.0.24.0": {},
"localhost": {}
},
"port": 8888,
"state": "enabled"
}
To show the configured listening address:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request GET https://localhost:8765/nvue_v1/system/api/listening-address?rev=2 -H "accept: application/json"
{
"10.10.10.1": {},
"10.10.20.1": {}
}
To show the certificates on the switch:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request GET https://localhost:8765/nvue_v1/system/api/certificate?rev=2 -H "accept: application/json"
{
"tls-cert-1": {},
"tls-cert-2": {}
}
To show information about a specific certificate, such as the serial number and how long the certificate is valid:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k --request GET https://localhost:8765/nvue_v1/system/api/certificate/tls-cert-1?rev=2 -H "accept: application/json"
{
"serial-number": "67:03:3B:B4:6E:35:D3",
"valid-from": "2023-02-14T00:35:18+00:00",
"valid-to": "2033-02-11T00:35:18+00:00"
}
Run cURL Commands
You can run the cURL commands from the command line. Use the username and password for the switch. For example:
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/interface
{
"eth0": {
"ip": {
"address": {
"192.168.200.12/24": {}
}
},
"link": {
"mtu": 1500,
"state": {
"up": {}
},
"stats": {
"carrier-transitions": 2,
"in-bytes": 184151,
"in-drops": 0,
"in-errors": 0,
"in-pkts": 2371,
"out-bytes": 117506,
"out-drops": 0,
"out-errors": 0,
"out-pkts": 762
}
...
API Use Cases
The following examples show the primary API uses cases.
View a Configuration
Use the following example to obtain the current applied configuration on the switch. Change the rev argument to view any revision. Possible options for the rev argument include startup, pending, operational, and applied.
cumulus@switch:~$ curl -k -u cumulus:cumulus -X GET "https://127.0.0.1:8765/nvue_v1/?rev=applied&filled=false"
"acl": {},
"bridge": {
"domain": {
"br_default": {
"encap": "802.1Q",
"mac-address": "auto",
"multicast": {
"snooping": {
"enable": "off"
}
},
"stp": {
"priority": 32768,
"state": {
"up": {}
}
},
"type": "vlan-aware",
"untagged": 1,
"vlan": {
"10": {
"multicast": {
...
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
if __name__ == "__main__":
r = requests.get(url=nvue_end_point + "/?rev=applied&filled=false",
auth=auth,
verify=False)
print("=======Current Applied Revision=======")
print(json.dumps(r.json(), indent=2))
cumulus@switch:~$ nv config show
- set:
bridge:
domain:
br_default:
type: vlan-aware
vlan:
'10':
vni:
'10': {}
'20':
vni:
'20': {}
'30':
vni:
'30': {}
evpn:
enable: on
mlag:
backup:
10.10.10.2: {}
enable: on
init-delay: 10
mac-address: 44:38:39:BE:EF:AA
...
Replace an Entire Configuration
To replace an entire configuration:
-
Create a new revision ID with a POST:
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure -X POST https://127.0.0.1:8765/nvue_v1/revision { "1": { "state": "pending", "transition": { "issue": {}, "progress": "" } } } -
Record the revision ID. In the above example, the revision ID is
"1". -
Do a root patch to delete the whole configuration.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{}' -H 'Content-Type: application/json' -k -X DELETE https://127.0.0.1:8765/nvue_v1/?rev=1 {} -
Do a root patch to update the switch with the new configuration.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{ "system": { "hostname": "switch01" }, "bridge": { "domain": { "br_default": { "type": "vlan-aware", "vlan": { "10": { "vni": { "10": {} } }, "20": { "vni": { "20": {} } }, "30": { "vni": { "30": {} } } } } } }, "interface": { "eth0": { "ip": { "address": { "192.168.200.6/24": {} }, "vrf": "mgmt" }, "type": "eth" }, "lo": { "ip": { "address": { "10.10.10.1/32": {} } }, "type": "loopback" }, "swp51": { "link": { "state": { "up": {} } }, "type": "swp" }, "swp52": { "link": { "state": { "up": {} } }, "type": "swp" }, "swp53": { "link": { "state": { "up": {} } }, "type": "swp" }, "swp54": { "link": { "state": { "up": {} } }, "type": "swp" } }, "mlag": { "backup": { "10.10.10.2": {} }, "enable": "on", "init-delay": 10, "mac-address": "44:38:39:BE:EF:AA", "peer-ip": "linklocal", "priority": 1000 } "router": { "bgp": { "enable": "on" }, "vrr": { "enable": "on" } }, "service": {}, "vrf": { "mgmt": { "router": { "static": { "0.0.0.0/0": { "address-family": "ipv4-unicast", "via": { "192.168.200.1": { "type": "ipv4-address" } } } } } } } }' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/?rev=1 {} -
Apply the changes with a PATCH to the revision changeset.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -H 'Content-Type:application/json' -d '{"state": "apply", "auto-prompt": {"ays": "ays_yes"}}' -k -X PATCH https://127.0.0.1:8765/nvue_v1/revision/1 { "state": "apply", "transition": { "issue": {}, "progress": "" } }cumulus@switch:~$ nv config apply -
Review the status of the apply and the configuration:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -X GET https://127.0.0.1:8765/nvue_v1/revision/1 { "state": "applied", "transition": { "issue": {}, "progress": "" } }cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/system { "build": "Cumulus Linux 5.4.0", "hostname": "switch01", "timezone": "Etc/UTC", "uptime": 763 } cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/bridge/domain/br_default/vlan/10 { "multicast": { "snooping": { "querier": { "source-ip": "0.0.0.0" } } }, "ptp": { "enable": "off" }, "vni": { "10": { "flooding": { "enable": "auto" }, "mac-learning": "off" } }#!/usr/bin/env python3 import requests from requests.auth import HTTPBasicAuth import json import time auth = HTTPBasicAuth(username="cumulus", password="password") nvue_end_point = "https://127.0.0.1:8765/nvue_v1" mime_header = {"Content-Type": "application/json"} DUMMY_SLEEP = 5 # In seconds POLL_APPLIED = 1 # in seconds RETRIES = 10 def print_request(r: requests.Request): print("=======Request=======") print("URL:", r.url) print("Headers:", r.headers) print("Body:", r.body) def print_response(r: requests.Response): print("=======Response=======") print("Headers:", r.headers) print("Body:", json.dumps(r.json(), indent=2)) def create_nvue_changest(): r = requests.post(url=nvue_end_point + "/revision", auth=auth, verify=False) print_request(r.request) print_response(r) response = r.json() changeset = response.popitem()[0] return changeset def apply_nvue_changeset(changeset): apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}} url = nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe="") r = requests.patch(url=url, auth=auth, verify=False, data=json.dumps(apply_payload), headers=mime_header) print_request(r.request) print_response(r) def is_config_applied(changeset) -> bool: # Check if the configuration was indeed applied global RETRIES global POLL_APPLIED retries = RETRIES while retries > 0: r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""), auth=auth, verify=False) response = r.json() print(response) if response["state"] == "applied": return True retries -= 1 time.sleep(POLL_APPLIED) return False def apply_new_config(path,payload): # Create a new revision ID changeset = create_nvue_changest() print("Using NVUE Changeset: '{}'".format(changeset)) # Delete existing configuration query_string = {"rev": changeset} r = requests.delete(url=nvue_end_point + path, auth=auth, verify=False, params=query_string, headers=mime_header) print_request(r.request) print_response(r) # Patch the new configuration query_string = {"rev": changeset} r = requests.patch(url=nvue_end_point + path, auth=auth, verify=False, data=json.dumps(payload), params=query_string, headers=mime_header) print_request(r.request) print_response(r) # Apply the changes to the new revision changeset apply_nvue_changeset(changeset) # Check if the changeset was applied is_config_applied(changeset) def nvue_get(path): r = requests.get(url=nvue_end_point + path, auth=auth, verify=False) print_request(r.request) print_response(r) if __name__ == "__main__": payload = { "system": { "hostname": "switch01" }, "bridge": { "domain": { "br_default": { "type": "vlan-aware", "vlan": { "10": { "vni": { "10": {} } }, "20": { "vni": { "20": {} } }, "30": { "vni": { "30": {} } } } } } }, "interface": { "eth0": { "ip": { "address": { "192.168.200.6/24": {} }, "vrf": "mgmt" }, "type": "eth" }, "lo": { "ip": { "address": { "10.10.10.1/32": {} } }, "type": "loopback" }, "swp51": { "link": { "state": { "up": {} } }, "type": "swp" }, "swp52": { "link": { "state": { "up": {} } }, "type": "swp" }, "swp53": { "link": { "state": { "up": {} } }, "type": "swp" }, "swp54": { "link": { "state": { "up": {} } }, "type": "swp" } }, "mlag": { "backup": { "10.10.10.2": {} }, "enable": "on", "init-delay": 10, "mac-address": "44:38:39:BE:EF:AA", "peer-ip": "linklocal", "priority": 1000 } "router": { "bgp": { "enable": "on" }, "vrr": { "enable": "on" } }, "service": {}, "vrf": { "mgmt": { "router": { "static": { "0.0.0.0/0": { "address-family": "ipv4-unicast", "via": { "192.168.200.1": { "type": "ipv4-address" } } } } } } } } apply_new_config("/",payload) time.sleep(DUMMY_SLEEP) print("=====Verifying some of the configurations=====") nvue_get("/system") nvue_get("/bridge/domain/br_default/vlan/10")cumulus@switch:~$ nv show system operational applied -------- ------------------- ------- hostname switch01 cumulus build Cumulus Linux 5.4.0 uptime 0:12:59 timezone Etc/UTCcumulus@switch:~$ nv show bridge domain br_default vlan 10 operational applied pending description --------------- ----------- ------- ------- ------------------------------------------------------ [vni] 10 10 10 L2 VNI multicast snooping querier source-ip 0.0.0.0 0.0.0.0 0.0.0.0 Source IP to use when sending IGMP/MLD queries. ptp enable off off off Turn the feature 'on' or 'off'. The default is 'off'.
Make a Configuration Change
To make a configuration change:
-
Create a new revision ID with a POST:
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure -X POST https://127.0.0.1:8765/nvue_v1/revision { "2": { "state": "pending", "transition": { "issue": {}, "progress": "" } } } -
Record the revision ID. In the above example, the revision ID is
"2". -
Make the change with a PATCH and link it to the revision ID:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"99.99.99.99/32": {}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/interface/lo/ip/address?rev=2 { "99.99.99.99/32": {} }cumulus@switch:~$ nv set interface lo ip address 99.99.99.99/32 -
Apply the changes with a PATCH to the revision changeset:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -H 'Content-Type:application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/revision/2 { "state": "apply", "transition": { "issue": {}, "progress": "" } }cumulus@switch:~$ nv config apply -
Review the status of the apply and the configuration:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -X GET https://127.0.0.1:8765/nvue_v1/revision/2 { "state": "applied", "transition": { "issue": {}, "progress": "" } }cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/interface/lo/ip/address { "127.0.0.1/8": {}, "99.99.99.99/32": {}, "::1/128": {} }#!/usr/bin/env python3 import requests from requests.auth import HTTPBasicAuth import json import time auth = HTTPBasicAuth(username="cumulus", password="password") nvue_end_point = "https://127.0.0.1:8765/nvue_v1" mime_header = {"Content-Type": "application/json"} DUMMY_SLEEP = 5 # In seconds POLL_APPLIED = 1 # in seconds RETRIES = 10 def print_request(r: requests.Request): print("=======Request=======") print("URL:", r.url) print("Headers:", r.headers) print("Body:", r.body) def print_response(r: requests.Response): print("=======Response=======") print("Headers:", r.headers) print("Body:", json.dumps(r.json(), indent=2)) def create_nvue_changest(): r = requests.post(url=nvue_end_point + "/revision", auth=auth, verify=False) print_request(r.request) print_response(r) response = r.json() changeset = response.popitem()[0] return changeset def apply_nvue_changeset(changeset): apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}} url = nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe="") r = requests.patch(url=url, auth=auth, verify=False, data=json.dumps(apply_payload), headers=mime_header) print_request(r.request) print_response(r) def is_config_applied(changeset) -> bool: # Check if the configuration was indeed applied global RETRIES global POLL_APPLIED retries = RETRIES while retries > 0: r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""), auth=auth, verify=False) response = r.json() print(response) if response["state"] == "applied": return True retries -= 1 time.sleep(POLL_APPLIED) return False def apply_new_config(path,payload): # Create a new revision ID changeset = create_nvue_changest() print("Using NVUE Changeset: '{}'".format(changeset)) # Delete existing configuration query_string = {"rev": changeset} r = requests.delete(url=nvue_end_point + path, auth=auth, verify=False, params=query_string, headers=mime_header) print_request(r.request) print_response(r) # Patch the new configuration query_string = {"rev": changeset} r = requests.patch(url=nvue_end_point + path, auth=auth, verify=False, data=json.dumps(payload), params=query_string, headers=mime_header) print_request(r.request) print_response(r) # Apply the changes to the new revision changeset apply_nvue_changeset(changeset) # Check if the changeset was applied is_config_applied(changeset) def nvue_get(path): r = requests.get(url=nvue_end_point + path, auth=auth, verify=False) print_request(r.request) print_response(r) if __name__ == "__main__": payload = { "99.99.99.99/32": {} } apply_new_config("/interface/lo/ip/address",payload) time.sleep(DUMMY_SLEEP) nvue_get("/interface/lo/ip/address")cumulus@switch:~$ nv show interface lo ip address ------------- 99.99.99.99/32 127.0.0.1/8 ::1/128
View Differences Between Configurations
To view differences between configurations, run the API GET /nvue_v1/<resource>?rev=<rev-A>&diff=<rev-B> method with the configurations you want to diff. This method is equivalent to the NVUE nv config diff <rev-A> <rev-B> command.
To see the difference between the startup revision and the applied revision:
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure -X GET /nvue_v1/interface?rev=startup&diff=applied
To see the difference between revision 1 and revision 2:
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure -X GET /nvue_v1/<resource>?rev=1&diff=2
You can change the order of the revisions; for example, GET /nvue_v1/<resource>?rev=2&diff=1.
Troubleshoot Configuration Changes
When a configuration change fails, you see an error in the change request.
Configuration Fails Because of a Dependency
If you stage a configuration but it fails because of a dependency, the failure shows the reason. In the following example, the change fails because the BGP router ID is not set.
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/revision/6
{
"state": "invalid",
"transition": {
"issue": {
"0": {
"code": "config_invalid",
"data": {
"location": "router.bgp.enable",
"reason": "BGP requires router-id to be set globally or in the VRF.\n"
},
"message": "Config invalid at router.bgp.enable: BGP requires router-id to be set globally or in the VRF.\n",
"severity": "error"
}
},
"progress": "Invalid config"
}
}
The staged configuration is missing router-id.
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure https://127.0.0.1:8765/nvue_v1/vrf/default/router/bgp?rev=6
{
"autonomous-system": 65999,
"enable": "on"
}
Configuration Apply Fails with Warnings
In some cases, such as the first push with NVUE or if you change a file manually instead of using NVUE, you see a warning prompt and the apply fails.
cumulus@switch:~$ curl -u 'cumulus:cumulus' --insecure -X GET https://127.0.0.1:8765/nvue_v1/revision/6
{
"6": {
"state": "ays_fail",
"transition": {
"issue": {
"0": {
"code": "client_timeout",
"data": {},
"message": "Timeout while waiting for client response",
"severity": "error"
}
},
"progress": "Aborted apply after warnings"
}
}
To resolve this issue, observe the failures or errors, then inspect the configuration that you are trying to apply. After you resolve the errors, retry the API. If you prefer to overlook the errors and force an apply, add "auto-prompt":{"ays": "ays_yes"} to the configuration apply.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"state":"apply","auto-prompt":{"ays": "ays_yes"}}' -H 'Content-Type:application/json' --insecure -X PATCH https://127.0.0.1:8765/nvue_v1/revision/6
Save a Configuration
To save an applied configuration change to the startup configuration file (/etc/nvue.d/startup.yaml) so that the changes persist after a reboot, use a PATCH to the applied revision with the save state.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -X PATCH -d '{"state": "save", "auto-prompt": {"ays": "ays_yes"}}' -H 'Content-Type: application/json' https://127.0.0.1:8765/nvue_v1/revision/applied
{
"state": "save",
"transition": {
"issue": {},
"progress": ""
}
}
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def save_nvue_changeset():
apply_payload = {"state": "save", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/applied"
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
save_nvue_changeset()
cumulus@switch:~$ nv config save
saved
Unset a Configuration Change
To unset a configuration change, use the null value to the key. For example, to delete vlan100 from a switch, use the following syntax:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"vlan100":null}' -H 'Content-Type: application/json' --insecure -X PATCH https://127.0.0.1:8765/nvue_v1/interface/rev=4
When you unset a change, you must still use the PATCH action. The value indicates removal of the entry. The data is {"vlan100":null} with the PATCH action.
Use the API for Active Monitoring
The example below fetches the counters for interface swp1.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -X GET https://127.0.0.1:8765/nvue_v1/interface/swp1/link/stats
{
"carrier-transitions": 6,
"in-bytes": 293771538,
"in-drops": 0,
"in-errors": 0,
"in-pkts": 2321737,
"out-bytes": 366068936,
"out-drops": 0,
"out-errors": 0,
"out-pkts": 3536629
}
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
if __name__ == "__main__":
r = requests.get(url=nvue_end_point + "/interface/swp1/link/stats",
auth=auth,
verify=False)
print("=======Interface swp1 Statistics=======")
print(json.dumps(r.json(), indent=2))
cumulus@switch:~$ nv show interface swp1 link stats
operational applied pending description
------------------- ----------- ------- ------- ----------------------------------------------------------------------
carrier-transitions 6 Number of times the interface state has transitioned between up and...
in-bytes 280.15 MB total number of bytes received on the interface
in-drops 0 number of received packets dropped
in-errors 0 number of received packets with errors
in-pkts 2321659 total number of packets received on the interface
out-bytes 349.10 MB total number of bytes transmitted out of the interface
out-drops 0 The number of outbound packets that were chosen to be discarded eve...
out-errors 0 The number of outbound packets that could not be transmitted becaus...
out-pkts 3536508 total number of packets transmitted out of the interface
Retrieve View Types
NVUE provides views for certain show commands. A view is a subset of information.
To see the views available for a show command, run the command with --view and press TAB:
cumulus@switch:~$ nv show interface --view <<TAB>>
acl-statistics description lldp physical status
bond-members detail lldp-detail pluggables svi
bonds dot1x-counters mac port-security synce-counters
brief dot1x-summary mlag-cc qos-profile up
counters down neighbor small vrf
cumulus@switch:~$ nv show vrf default router rib ipv4 route --view <<TAB>>
brief detail
To retrieve view types through the REST API, you use the curl -u 'cumulus:CumulusLinux!' -k -X GET http://path?view=<brief> syntax. For example, the equivalent REST API method for the NVUE nv show vrf <vrf-id> router rib ipv4 route --view=brief command is:
cumulus@switch:~$ curl -u 'cumulus:CumulusLinux!' -k -X GET https://127.0.0.1:8765/nvue_v1/vrf/BLUE/router/rib/ipv4/route?view=brief
Convert CLI Changes to Use the API
You can take a configuration change from the CLI and use the API to configure the same set of changes.
-
Make your configuration changes on the system with the NVUE CLI.
cumulus@switch:~$ nv set system hostname switch01 cumulus@switch:~$ nv set interface lo ip address 99.99.99.99/32 cumulus@switch:~$ nv set interface eth0 ip address 192.168.200.6/24 cumulus@switch:~$ nv set interface bond0 bond member swp1-4 -
View the changes as a JSON blob.
cumulus@switch:~$ nv config diff -o json [ { "set": { "interface": { "bond0": { "bond": { "member": { "swp1": {}, "swp2": {}, "swp3": {}, "swp4": {} } }, "type": "bond" }, "lo": { "ip": { "address": { "99.99.99.99/32": {} } } } }, "system": { "hostname": "switch01" } } } ] -
Staple the JSON blob to a root patch request as the payload.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{ "interface": { "bond0": { "bond": { "member": { "swp1": {}, "swp2": {}, "swp3": {}, "swp4": {} } }, "type": "bond" }, "lo": { "ip": { "address": { "99.99.99.99/32": {} } } } }, "system": { "hostname": "switch01" } }' -k -X PATCH https://127.0.0.1:8765/nvue_v1/?rev=3 { "bridge": { "domain": { "br_default": { "type": "vlan-aware", "vlan": { "10": { "vni": { "10": {} } }, "20": { "vni": { "20": {} } }, "30": { "vni": { "30": {} } } } } } }, "evpn": { "enable": "on" }, "interface": { "bond1": { "bond": { "lacp-bypass": "on", "member": { "swp1": {} }, ... -
Apply the changes with a PATCH to the revision changeset.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -H 'Content-Type:application/json' -k -d '{"state": "apply", "auto-prompt": {"ays": "ays_yes"}}' -X PATCH https://127.0.0.1:8765/nvue_v1/revision/3 { "state": "apply", "transition": { "issue": {}, "progress": "" } } -
Review the status of the apply and the configuration:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -X GET https://127.0.0.1:8765/nvue_v1/revision/3 { "state": "applied", "transition": { "issue": {}, "progress": "" } }#!/usr/bin/env python3 import requests from requests.auth import HTTPBasicAuth import json import time auth = HTTPBasicAuth(username="cumulus", password="password") nvue_end_point = "https://127.0.0.1:8765/nvue_v1" mime_header = {"Content-Type": "application/json"} DUMMY_SLEEP = 5 # In seconds POLL_APPLIED = 1 # in seconds RETRIES = 10 def print_request(r: requests.Request): print("=======Request=======") print("URL:", r.url) print("Headers:", r.headers) print("Body:", r.body) def print_response(r: requests.Response): print("=======Response=======") print("Headers:", r.headers) print("Body:", json.dumps(r.json(), indent=2)) def create_nvue_changest(): r = requests.post(url=nvue_end_point + "/revision", auth=auth, verify=False) print_request(r.request) print_response(r) response = r.json() changeset = response.popitem()[0] return changeset def apply_nvue_changeset(changeset): # apply_payload = {"state": "apply"} apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}} url = nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe="") r = requests.patch(url=url, auth=auth, verify=False, data=json.dumps(apply_payload), headers=mime_header) print_request(r.request) print_response(r) def is_config_applied(changeset) -> bool: # Check if the configuration was indeed applied global RETRIES global POLL_APPLIED retries = RETRIES while retries > 0: r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""), auth=auth, verify=False) response = r.json() print(response) if response["state"] == "applied": return True retries -= 1 time.sleep(POLL_APPLIED) return False def apply_new_config(path,payload): # Create a new revision ID changeset = create_nvue_changest() print("Using NVUE Changeset: '{}'".format(changeset)) # Delete existing configuration query_string = {"rev": changeset} r = requests.delete(url=nvue_end_point + path, auth=auth, verify=False, params=query_string, headers=mime_header) print_request(r.request) print_response(r) # Patch the new configuration query_string = {"rev": changeset} r = requests.patch(url=nvue_end_point + path, auth=auth, verify=False, data=json.dumps(payload), params=query_string, headers=mime_header) print_request(r.request) print_response(r) # Apply the changes to the new revision changeset apply_nvue_changeset(changeset) # Check if the changeset was applied is_config_applied(changeset) def nvue_get(path): r = requests.get(url=nvue_end_point + path, auth=auth, verify=False) print_request(r.request) print_response(r) if __name__ == "__main__": payload = { "interface": { "bond0": { "bond": { "member": { "swp1": {}, "swp2": {}, "swp3": {}, "swp4": {} } }, "type": "bond" }, "lo": { "ip": { "address": { "99.99.99.99/32": {} } } } }, "system": { "hostname": "switch01" } } apply_new_config("/",payload) time.sleep(DUMMY_SLEEP) nvue_get("/interface/bond0") nvue_get("/interface/lo") nvue_get("/system")
API Examples
The following section provides practical API examples.
Configure the System
To set the system hostname, pre-login or post-login message, and time zone on the switch, send a targeted API request to /nvue_v1/system.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"system": {"hostname":"switch01","timezone":"America/Los_Angeles","message":{"pre-login":"Welcome to NVIDIA Cumulus Linux","post-login":"You have successfully logged in to switch01"}}}' -k -X PATCH https://127.0.0.1:8765/nvue_v1/?rev=4
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
payload = {
"system":
{
"hostname":"switch01",
"timezone":"America/Los_Angeles",
"message":
{
"pre-login":"Welcome to NVIDIA Cumulus Linux",
"post-login:"You have successfully logged in to switch01"
}
}
}
apply_new_config("/",payload) # Root patch
time.sleep(DUMMY_SLEEP)
nvue_get("/system")
cumulus@switch:~$ nv set system hostname switch01
cumulus@switch:~$ nv set system timezone America/Los_Angeles
cumulus@switch:~$ nv set system message pre-login "Welcome to NVIDIA Cumulus Linux"
cumulus@switch:~$ nv set system message post-login "You have successfully logged into switch01"
Configure Services
To set up NTP, DNS, and SNMP on the switch, send a targeted API request to /nvue_v1/service.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"service": { "ntp": {"default":{"server":{"4.cumulusnetworks.pool.ntp.org":{"iburst":"on"}}}}, "dns": {"mgmt":{"server":{"192.168.1.100":{}}}}, "syslog": {"mgmt":{"server":{"192.168.1.120":{"port":8000}}}}}}' -k -X PATCH https://127.0.0.1:8765/nvue_v1/?rev=5
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
payload = {
"service":
{
"ntp":
{
"default":
{
"server:
{
"4.cumulusnetworks.pool.ntp.org":
{
"iburst":"on"
}
}
}
},
"dns":
{
"mgmt":
{
"server:
{
"192.168.1.100":{}
}
}
},
"syslog":
{
"mgmt":
{
"server:
{
"192.168.1.120":
{
"port":8000
}
}
}
}
}
}
apply_new_config("/",payload) # Root patch
time.sleep(DUMMY_SLEEP)
nvue_get("/service/ntp")
nvue_get("/service/dns")
nvue_get("/service/syslog")
cumulus@switch:~$ nv set service ntp default server 4.cumulusnetworks.pool.ntp.org iburst on
cumulus@switch:~$ nv set service dns mgmt server 192.168.1.100
cumulus@switch:~$ nv set service syslog mgmt server 192.168.1.120 port 8000
Configure Users
The following example creates a new user, then deletes the user.
This example creates a new user called test1.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"system": {"aaa": {"user": {"test1": {"hashed-password":"72b28582708d749c6c82f3b3f226041f1bd37090281641eaeba8d44bd915d0042d609a92759d9f6fb96475cb0601cf428cd22613df8a53a09461e0b426cf0a35","role": "nvue-monitor","enable": "on","full-name": "Test User"}}}}}' -k -X PATCH https://127.0.0.1:8765/nvue_v1/?rev=5
This example deletes the test1 user.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -X DELETE https://127.0.0.1:8765/nvue_v1/system/aaa/user/test1?rev=6
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def delete_config(path):
# Create an NVUE changeset
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Equivalent to JSON `null`
payload = None
# Stage the change
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the staged changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
# Need to create a hashed password - The supported password
# hashes are documented here:
# https://docs.nvidia.com/networking-ethernet-software/cumulus-linux-55/System-Configuration/Authentication-Authorization-and-Accounting/User-Accounts/#hashed-passwords # noqa
# Here in this example, we use SHA-512
import crypt
hashed_password = crypt.crypt("hello$world#2023", salt=crypt.METHOD_SHA512)
payload = {
"system": {
"aaa": {
"user": {
"test1": {
"hashed-password": hashed_password,
"role": "nvue-monitor",
"enable": "on",
"full-name": "Test User",
}
}
}
}
}
apply_new_config("/",payload) # Root patch
time.sleep(DUMMY_SLEEP)
nvue_get("/system/user/aaa")
"""Delete an existing user account using the AAA API."""
delete_config("/system/aaa/user/test1")
time.sleep(DUMMY_SLEEP)
nvue_get("/system/user/aaa")
This example creates a new user test1.
cumulus@switch:~$ nv set system aaa user test1
cumulus@switch:~$ nv set system aaa user test1 full-name "Test User"
cumulus@switch:~$ nv set system aaa user test1 password "abcd@test"
cumulus@switch:~$ nv set system aaa user test1 role nvue-monitor
cumulus@switch:~$ nv set system aaa user test1 enable on
This example deletes the user test1.
cumulus@switch:~$ nv unset system aaa user test1
Configure an Interface
The following example configures an interface.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -k -d '{"swp1": {"link":{"state":{"up": {}}}}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/interface?rev=21
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
payload = {
"swp1":
{
"type":"swp",
"link":
{
"state":"up"
}
}
}
apply_new_config("/interface",payload)
time.sleep(DUMMY_SLEEP)
nvue_get("/interface/swp1")
cumulus@switch:~$ nv set interface swp1
Configure a Bond
The following example configures a bond.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"bond0": {"type":"bond","bond":{"member":{"swp1":{},"swp2":{},"swp3":{},"swp4":{}}}}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/interface?rev=7
{
"bond0": {
"bond": {
"member": {
"swp1": {},
"swp2": {},
"swp3": {},
"swp4": {}
}
},
"type": "bond"
}
}
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
payload = {
"bond0":
{
"type":"bond",
"bond":
{
"member":
{
"swp1":{},
"swp2":{},
"swp3":{},
"swp4":{}
}
}
}
}
apply_new_config("/interface",payload)
time.sleep(DUMMY_SLEEP)
nvue_get("/interface/bond0")
cumulus@switch:~$ nv set interface bond0 bond member swp1-4
Configure a Bridge
The following example configures a bridge.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"swp1": {"bridge":{"domain":{"br_default":{}}}},"swp2": {"bridge":{"domain":{"br_default":{}}}}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/interface?rev=21
{
"swp1": {
"bridge": {
"domain": {
"br_default": {}
}
},
"type": "swp"
},
"swp2": {
"bridge": {
"domain": {
"br_default": {}
}
},
"type": "swp"
}
}
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"untagged":1,"vlan":{"10":{},"20":{}}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/bridge/domain/br_default?rev=8
{ “untagged”: 1, “vlan”: { “10”: {}, “20”: {} } }
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
int_payload = {
"swp1":
{
"bridge":
{
"domain":
{
"br_default":{}
}
},
"swp2":
{
"bridge":
{
"domain":
{
"br_default":{}
}
}
}
}
}
apply_new_config("/interface",int_payload)
br_payload = {
"untagged":1,
"vlan":
{
"10":{},
"20":{}
}
}
apply_new_config("/bridge/domain/br_default",br_payload)
time.sleep(DUMMY_SLEEP)
nvue_get("/interface/swp1")
nvue_get("/bridge/domain/br_default")
cumulus@switch:~$ nv set interface swp1-2 bridge domain br_default
cumulus@switch:~$ nv set bridge domain br_default vlan 10,20
cumulus@switch:~$ nv set bridge domain br_default untagged 1
Configure BGP
The following example configures BGP.
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"bgp": {"autonomous-system": 65101,"router-id":"10.10.10.1"}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/router?rev=9
cumulus@switch:~$ curl -u 'cumulus:cumulus' -d '{"bgp":{"neighbor":{"swp51":{"remote-as":"external"}},"address-family":{"ipv4-unicast":{"network":{"10.10.10.1/32":{}}}}}}' -H 'Content-Type: application/json' -k -X PATCH https://127.0.0.1:8765/nvue_v1/vrf/default/router?rev=9
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def create_nvue_changest():
r = requests.post(url=nvue_end_point + "/revision",
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
response = r.json()
changeset = response.popitem()[0]
return changeset
def apply_nvue_changeset(changeset):
# apply_payload = {"state": "apply"}
apply_payload = {"state": "apply", "auto-prompt": {"ays": "ays_yes"}}
url = nvue_end_point + "/revision/" + requests.utils.quote(changeset,
safe="")
r = requests.patch(url=url,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
def is_config_applied(changeset) -> bool:
# Check if the configuration was indeed applied
global RETRIES
global POLL_APPLIED
retries = RETRIES
while retries > 0:
r = requests.get(url=nvue_end_point + "/revision/" + requests.utils.quote(changeset, safe=""),
auth=auth,
verify=False)
response = r.json()
print(response)
if response["state"] == "applied":
return True
retries -= 1
time.sleep(POLL_APPLIED)
return False
def apply_new_config(path,payload):
# Create a new revision ID
changeset = create_nvue_changest()
print("Using NVUE Changeset: '{}'".format(changeset))
# Delete existing configuration
query_string = {"rev": changeset}
r = requests.delete(url=nvue_end_point + path,
auth=auth,
verify=False,
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Patch the new configuration
query_string = {"rev": changeset}
r = requests.patch(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(payload),
params=query_string,
headers=mime_header)
print_request(r.request)
print_response(r)
# Apply the changes to the new revision changeset
apply_nvue_changeset(changeset)
# Check if the changeset was applied
is_config_applied(changeset)
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
rt_payload = {
"bgp":
{
"autonomous-system": 65101,
"router-id":"10.10.10.1"
}
}
apply_new_config("/router",rt_payload)
vrf_payload = {
"bgp":
{
"neighbor":
{
"swp51":
{
"remote-as":"external"
}
},
"address-family":
{
"ipv4-unicast":
{
"network":
{
"10.10.10.1/32":{}
}
}
}
}
}
apply_new_config("/vrf/default/router",vrf_payload)
time.sleep(DUMMY_SLEEP)
nvue_get("/router")
nvue_get("/vrf/default/router")
cumulus@switch:~$ nv set router bgp autonomous-system 65101
cumulus@switch:~$ nv set router bgp router-id 10.10.10.1
cumulus@switch:~$ nv set vrf default router bgp neighbor swp51 remote-as external
cumulus@switch:~$ nv set vrf default router bgp address-family ipv4-unicast network 10.10.10.1/32
Action Operations
The NVUE action operations are ephemeral operations that do not modify the state of the configuration; they reset counters for interfaces, BGP, QoS buffers and pools, and remove conflicts from protodown MLAG bonds.
To clear counters on swp1:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -H 'Content-Type:application/json' -d '{"@clear": {"state": "start", "parameters": {}}}' -k -X POST https://127.0.0.1:8765/nvue_v1/interface/swp1/counters
1
cumulus@switch:~$ curl -u 'cumulus:cumulus' -X GET https://127.0.0.1:8765/nvue_v1/action/1 -k
{"detail":"swp1 counters cleared.","http_status":200,"issue":[],"state":"action_success","status":"swp1 counters cleared.","timeout":60,"type":""}
To clear QoS buffers on swp1:
cumulus@switch:~$ curl -u 'cumulus:cumulus' -H 'Content-Type:application/json' -d '{"@clear": {"state": "start", "parameters": {}}}' -k -X POST https://127.0.0.1:8765/nvue_v1/interface/swp1/qos/buffer
2
cumulus@switch:~$ curl -u 'cumulus:cumulus' -X GET https://127.0.0.1:8765/nvue_v1/action/2 -k
{"detail":"QoS buffers cleared on swp1.","http_status":200,"issue":[],"state":"action_success","status":"QoS buffers cleared on swp1.","timeout":60,"type":""}
#!/usr/bin/env python3
import requests
from requests.auth import HTTPBasicAuth
import json
import time
auth = HTTPBasicAuth(username="cumulus", password="password")
nvue_end_point = "https://127.0.0.1:8765/nvue_v1"
mime_header = {"Content-Type": "application/json"}
DUMMY_SLEEP = 5 # In seconds
POLL_APPLIED = 1 # in seconds
RETRIES = 10
def print_request(r: requests.Request):
print("=======Request=======")
print("URL:", r.url)
print("Headers:", r.headers)
print("Body:", r.body)
def print_response(r: requests.Response):
print("=======Response=======")
print("Headers:", r.headers)
print("Body:", json.dumps(r.json(), indent=2))
def nvue_action():
r = requests.post(url=nvue_end_point + path,
auth=auth,
verify=False,
data=json.dumps(apply_payload),
headers=mime_header)
print_request(r.request)
print_response(r)
return response
def nvue_get(path):
r = requests.get(url=nvue_end_point + path,
auth=auth,
verify=False)
print_request(r.request)
print_response(r)
if __name__ == "__main__":
payload = {
"@clear":
{
"state": "start",
"parameters": {}
}
}
action_id=nvue_action("/interface/swp1/qos/counter",payload)
time.sleep(DUMMY_SLEEP)
nvue_get(f"/action/{action_id}")
cumulus@switch:~$ nv action clear interface swp1 qos counter
Example Python Scripts
Configuration example
In the following python example, the full_config_example() method sets the system pre-login message, enables BGP globally, and changes a few other configuration settings in a single bulk operation. The API end-point goes to the root node /nvue_v1. The bridge_config_example() method performs a targeted API request to /nvue_v1/bridge/domain/<domain-id> to set the vlan-vni-offset attribute.
Link manipulation example
In the following example, get_link_status() fetches the current running state of the switches passed as a parameter. The link_status_down() brings the down the totalLinks links between leafs and spines passed as parameters. It discovers the neighbor switches using LLDP and filters out the interfaces that are not 400G or swp. The link_status_up() brings the previously brought down downLinks up.
Reboot example
In the following example, switch_reboot() reboots the switches passed as a parameter. The issu_reboot() triggers ISSU (In System Service Upgrade) on the switches passed as a parameter, and reboots the switch in the reboot_mode defined.
Try the API
To try out the NVUE REST API, use the NVUE API Lab available on NVIDIA Air. The lab provides a basic example to help you get started. You can also try out the other examples in this document.
Resources
For information about using the NVUE REST API, refer to the NVUE API Swagger documentation. The full object model download is available here.
Considerations
- Unlike the NVUE CLI, the NVUE API does not support configuring a plain text password for a user account; you must configure a hashed password for a user account with the NVUE API.
- If you need to make multiple updates on the switch, NVIDIA recommends you use a root patch, which can make configuration changes with fewer round trips to the switch. Running many specific NVUE PATCH APIs to set or unset objects requires many round trips to the switch to set up the HTTP connection, transfer payload and responses, manage network utilization, and so on.