Configuring REST API Access
Netvisor ONE enables you to use REST API over HTTP and HTTPS to manage the switches in a fabric, in addition to using the CLI. Though REST API access over HTTP is simpler to configure, Pluribus recommends using HTTPS for security reasons. The vREST web application that runs on the switch enables the REST API client to access the resources on the switch.
Follow the steps below to configure REST API access over HTTP:
- Enable the web service using the command admin-service-modify.
CLI (network-admin@switch1) admin-service-modify if mgmt web
admin-service-modify |
Modifies services on the switch. |
if if-string |
Specify the administrative service interface. |
web|no-web |
Specify if you want to enable web management. Use this option to enable REST API access over HTTP. |
web-ssl|no-web-ssl |
Specify if you want to use SSL and certificates for web services. Use this option to enable REST API access over HTTPS. |
web-ssl-port web-ssl-port-number |
Specify the web SSL port. |
web-port web-port-number |
Specify the port for web management. |
web-log|no-web-log |
Specify if you want to turn on or off web logging. |
- Verify configuration using the command admin-service-show:
CLI (network-admin@switch1) admin-service-show
switch if ssh nfs web web-ssl web-ssl-port web-port snmp net-api icmp
----------- ---- --- --- --- ------- ------------ -------- ---- ------- ----
switch1 mgmt on off on on 443 80 on off on
switch1 data on off on off 443 80 on off on
- Download Swagger tool onto the desktop and open index.html file.
- Paste the URL http://<ip-address>/vRest/api-docs into the URL field.
<ip-address> should be the hostname or management IP address of your switch.
- Click 'Explore'. Commands are populated as below:
Figure 2- 1: Swagger UI for Pluribus REST API
- Right click to enable Chrome Inspect, and view the network tab to ensure that all the commands are loaded.
- Expand one of the CLI commands to see the corresponding GET/POST/DELETE/PUT options.
- Click on the model schema to view the list of configurable options supported under that model (vRest API) which are populated as key-value pairs. Make the required modifications to the values and click 'Try it out!'.
Using cURL with REST API
To create a VLAN, use the vREST API:
$ curl -u network-admin:pluribus!23 -H "Content-Type:application/json" -X POST http://switch1/vRest/vlans -d
'{
"scope": "local",
"id": 1111,
"description": "hello world"
}'
By default, all the vRest APIs provide fabric level information. To specifically access the resources of the switch (scope : local ), the switch ID needs to be specified in the URL.
For switch ID specific information, use the command:
$ curl -u network-admin:pluribus!23 http://switch1/vRest/vlans?api.switch={hostid} | python -m json.tool
as in the following example:
$ curl -u network-admin:pluribus!23 http://10.10.10.10/vRest/vlans?api.switch=201327131 | python -m json.tool
For switch information listing a local scope:
$ curl -u network-admin:pluribus!23 http://switch1/vRest/vlans?api.switch=fabric | python -m json.tool
or
$ curl -u network-admin:pluribus!23 http://switch1/vRest/vlans | python -m json.tool
as in the following example:
$ curl -u network-admin:pluribus!23 http://10.110.0.48/vRest/vlans | python -m json.tool
Configuring REST API Access over HTTPS
To enable HTTPS communication between a REST API client and Netvisor vREST web service, you have two options:
1. You can generate a self-signed certificate using Netvisor CLI and use this certificate for REST web service.
2. After creating a self-signed certificate using Netvisor CLI, create a certificate request, get the certificate request signed by a trusted Certificate Authority (CA), import the signed certificate and CA certificate into Netvisor ONE and use the certificates for REST web service.
Follow the steps below to create the certificates and deploy them:
- Generate self-signed certificate (the private key and the certificate file, in PEM format) using the web-cert-self-signed-create command.
CLI (network-admin@switch1) > web-cert-self-signed-create
web-cert-self-signed-create |
This command creates a self-signed certificate and deletes any existing certificates. |
country country-string |
Specify the contact address of the organization, starting with the country code. |
state state-string |
Specify the state or province. |
city city-string |
Specify the city. |
organization organization-string |
Specify the name of the organization. |
organizational-unit organizational-unit-string |
Specify the organizational unit. |
common-name common-name-string |
Specify the common name. The common name must precisely match the hostname where the certificate is installed. |
For example:
CLI (network-admin@switch1) > web-cert-self-signed-create country US state California city "Santa Clara" organization "Pluribus Networks Inc" organizational-unit Engineering common-name switch1.pluribusnetworks.com
Successfully generated self-signed certificate.
- ·If you want to get the certificate signed by a trusted Certificate Authority(CA), generate a CSR from the self-signed certificate by using the command web-cert-request-create.
CLI (network-admin@switch1) > web-cert-request-create
Certificate signing request successfully generated at /sftp/export/switch1.pluribusnetworks.com.csr.
- To view the CSR, use the command web-cert-request-show.
CLI (network-admin@switch1) > web-cert-request-show
web-cert-request-show |
Displays the certificate signing request. |
cert-request cert-request-string |
Specify the name of the CSR. |
For example:
CLI (network-switch1) > web-cert-request-show
cert-request
----------------------------------------------------------------
-----BEGIN CERTIFICATE REQUEST-----
MIICnDCCAYQCAQEwVzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQswCQYDVQQH
DAJTSjELMAkGA1UECgwCUE4xDTALBgNVBAsMBEVuZ2cxEjAQBgNVBAMMCWVxLWNv
bG8tMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALMmrZ8hvZ5J+FRs
Lo1sfVtwmmLEaxyhaxD/HNVdXSRhzbQDT20+qySfOudxtWGKyCsuCFFbgMUz7rgu
H1Xle8uwPSoxgTjLGq20sgBQIfNBT5UwDLDuzUUPzMEEjFb3/9Cg1VWju2t1KPim
Gqg3rcA3PCsMeCr/q+9Gz6gfLe6Rfx91yxTA44ZWsOWnvgDdXAPfHOLZ5zBWG8a3
ohgOwMLjy21ytDTA6aR1M9I12MkJwev3t0y6n/CLp6Zigp5wXiArPPnR9sZ+E7so
MqpEzz0rjFDfrNwNAGMzT3WPcmlYRjYrUJ0QsOEQ+O1uHJaNbw1pJEmK2jm97kbk
/HvEFmMCAwEAAaAAMA0GCSqGSIb3DQEBBQUAA4IBAQCnlgEwzoesbuiCYG7HZJN/
Rxm/NcznpvJXxdlTAdzSbTWWLswrZMyX6bQqUTWEb3qvVccD4tIZShyIGiR0CpCD
22m8LD4+e6/FA6NijjanHkKsRW9Z7ka97TFpsUaH27sUTtfFDDkDImwRIGfns+nu
kTRNMuNiyC/+uHovsvCxS8is3OasQtS1lkG28sZgxisvP17qmfjlb9fQC3pcvR4t
K8GciPMUfgcIA5qLDmCZAg1A6JBMb/UHtUuEnztLrLz4qjWqJJK3pWvdLWZcKDEz
C0t5Dre9ByJ2RT75GdUq2c16xYBGAwZNCzjdhParyBnvn00Mwb6PpPmLGcBQiRNn
-----END CERTIFICATE REQUEST-----
- Send the CSR to your trusted CA. You can copy the web-cert-request-show output and send it to the CA for signing the certificate.
You can also connect to the switch by using SFTP and copy the certificate file from /sftp/export location and send it to the CA.
If disabled, use the command admin-sftp-modify enable to enable SFTP.
- Upload the signed certificate, the CA root certificate, and the intermediate CA certificate (if the certificate is signed by an intermediate CA) to /sftp/import directory on the switch using SFTP.
For example, to upload the file server-cert.pem to the /sftp/import directory, follow the steps below:
$ sftp sftp@switch1
Password:
sftp> cd /sftp/import
sftp> put server-cert.pem
- Import the signed server certificate, CA root certificate, and the intermediate certificate (if available) onto the switch using the web-cert-import command:
CLI (network-admin@switch1) > web-cert-import
web-cert-import |
This command imports certificates from /sftp/import directory. |
file-ca file-ca-string |
Specify the name of the CA certificate file. |
file-server file-server-string |
Specify the name of server certificate file (signed by CA). |
file-inter file-inter-string |
Specify the name of intermediate CA certificate file. |
CLI (network-admin@switch1) > web-cert-import file-ca ca.pem file-server server-cert.pem file-inter intermediate.pem
Successfully imported certificates.
- After the import is successful, enable web-ssl using the admin-service-modify command.
CLI (network-admin@switch) > admin-service-modify if mgmt web-ssl
- Download the Swagger tool and follow the general steps above to complete the configuration of REST API access.
Related Commands
- web-cert-clear
Use this command to delete previously generated certificates.
For example:
CLI (network-admin@switch1) > web-cert-clear
Successfully deleted all certificate files.
- web-cert-info-show
Use this command to display web certificate information.
CLI (network-admin@switch1) web-cert-info-show
web-cert-info-show |
Displays the web certificate information. |
Specify any of the following options: |
|
cert-type ca|intermediate|server |
Specify the one among the options as the certificate type. |
subject subject-string |
Specify the the subject of the certificate. |
issuer issuer-string |
Specify the issuer of the certificate. |
serial-number serial-number |
Specify the serial number of the certificate. |
valid-from valid-from-string |
Specify the time from which the certificate is valid. |
valid-to valid-to-string |
Specify the time at which the certificate expires and is no longer valid. |
For example:
CLI (network-admin@switch1) web-cert-info-show
switch: switch1
cert-type: ca
subject: /C=US/ST=CA/L=SJ/O=PN/OU=Engg/CN=switch1
issuer: /C=US/ST=CA/L=SJ/O=PN/OU=Engg/CN=switch1
serial-number: 1
valid-from: May 7 18:16:10 2019 GMT
valid-to: May 6 18:16:10 2020 GMT
----------------------------------------
switch: switch1
cert-type: server
subject: /C=US/ST=CA/L=SJ/O=PN/OU=Engg/CN=switch1
issuer: /C=US/ST=CA/L=SJ/O=PN/OU=Engg/CN=switch1
Using cURL to Implement SSL Certificates
Use cURL to automate the upload of the CA root, CA intermediate, and signed switch certificates.
Run the following command for each of the PEM formatted certificates:
awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <file-name>.pem
For example:
$ awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' /tmp/server-cert.pem.bkp
-----BEGIN CERTIFICATE-----\nMIIDHDCCAgQCAQEwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCSU4xCzAJBgNV\nBAgMAktBMQwwCgYDVQQHDANCTFIxCzAJBgNVBAoMAlBOMQwwCgYDVQQLDANFTkcx\nDzANBgNVBAMMBlNQSU5FMTAeFw0yMDA1MDQxODM4NTZaFw0yMTA1MDQxODM4NTZa\nMFQxCzAJBgNVBAYTAklOMQswCQYDVQQIDAJLQTEMMAoGA1UEBwwDQkxSMQswCQYD\nVQQKDAJQTjEMMAoGA1UECwwDRU5HMQ8wDQYDVQQDDAZTUElORTEwggEiMA0GCSqG\nSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCot16ddH0LNHOrWZt63FHYiArVXYIYbCDh\nWCY6MX3suoXYvKstvRgJkUe/6G5As+vYtwRi2bDqdDsgTC5+Qo4SnjrdTcTM98F+\n0Qzqv02c+dbzk5GclUkljqq0PHGXRPGOMhou8B/6LI9Hg5XkG+FSfaDGQTM39uj2\nzzvrMOFn96gzpTBoh40sMoIpnKQLrWeGjlNxaBxhM342c1jn1CVmXss/uHMQeang\nsVhPTynikyxIrDwl9gh/2X1EwzVzpAnUBTUZvJ9rgrceC9GcuGmiPZgxxSruNb0w\nK8xsyH8/hLwhK4Axgu3a+lfmmKFmSWjywmcxlmQl+jwiMPA/Ty55AgMBAAEwDQYJ\nKoZIhvcNAQELBQADggEBAEG0D/2FcNU6Z6w/6eKbyH855kHSrJyqeU8eoCW9rnOb\nqdnAsFX3aYwiUCjzSFXpWA3bRr3L7X0Y01x7VSvwITuDvwO43llK29rQfrSvoPiw\nf7fhU7bszlUc2GAumU9OEdYBnSI1DzfBawUcPmbDmm+ci27k0po53KDWTbxkBIZR\n2Oh25LXkmq8ZBzE4vgS+mAw436nToazB1/vDTMWoBuLVzOUlU8cdcjJUnJBevTbX\nThP691sHVMED8B8Fhl08BzIJmQQ9qp1tjplFq1Ea9oEFnT5U5gKvJYy48qEPlW+r\nhRIHysvZXF/dghtrLXDMSBWLlLofUsDQsh+qLxpo1+k=\n-----END CERTIFICATE-----\n
Copy the output into the JSON payload.
Note: The escape character syntax of \n" must be used as highlighted in red in the example below. Otherwise, the script will fail, and the certificates will not install.
$ curl -u network-admin:test123 http://10.100.64.5/vRest/web-certs/upload -H "content-type:application/json" -v -X POST -d '{"cert-ca":"-----BEGIN CERTIFICATE-----\nMIIDHDCCAgQCAQEwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCSU4xCzAJBgNV\nBAgMAktBMQwwCgYDVQQHDANCTFIxCzAJBgNVBAoMAlBOMQwwCgYDVQQLDANFTkcx\nDzANBgNVBAMMBlNQSU5FMTAeFw0yMDA1MDQxODM4NTZaFw0yMTA1MDQxODM4NTZa\nMFQxCzAJBgNVBAYTAklOMQswCQYDVQQIDAJLQTEMMAoGA1UEBwwDQkxSMQswCQYD\nVQQKDAJQTjEMMAoGA1UECwwDRU5HMQ8wDQYDVQQDDAZTUElORTEwggEiMA0GCSqG\nSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCot16ddH0LNHOrWZt63FHYiArVXYIYbCDh\nWCY6MX3suoXYvKstvRgJkUe/6G5As+vYtwRi2bDqdDsgTC5+Qo4SnjrdTcTM98F+\n0Qzqv02c+dbzk5GclUkljqq0PHGXRPGOMhou8B/6LI9Hg5XkG+FSfaDGQTM39uj2\nzzvrMOFn96gzpTBoh40sMoIpnKQLrWeGjlNxaBxhM342c1jn1CVmXss/uHMQeang\nsVhPTynikyxIrDwl9gh/2X1EwzVzpAnUBTUZvJ9rgrceC9GcuGmiPZgxxSruNb0w\nK8xsyH8/hLwhK4Axgu3a+lfmmKFmSWjywmcxlmQl+jwiMPA/Ty55AgMBAAEwDQYJ\nKoZIhvcNAQELBQADggEBAEG0D/2FcNU6Z6w/6eKbyH855kHSrJyqeU8eoCW9rnOb\nqdnAsFX3aYwiUCjzSFXpWA3bRr3L7X0Y01x7VSvwITuDvwO43llK29rQfrSvoPiw\nf7fhU7bszlUc2GAumU9OEdYBnSI1DzfBawUcPmbDmm+ci27k0po53KDWTbxkBIZR\n2Oh25LXkmq8ZBzE4vgS+mAw436nToazB1/vDTMWoBuLVzOUlU8cdcjJUnJBevTbX\nThP691sHVMED8B8Fhl08BzIJmQQ9qp1tjplFq1Ea9oEFnT5U5gKvJYy48qEPlW+r\nhRIHysvZXF/dghtrLXDMSBWLlLofUsDQsh+qLxpo1+k=\n-----END CERTIFICATE-----\n", "cert-server":"-----BEGIN CERTIFICATE-----\nMIIDHDCCAgQCAQEwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCSU4xCzAJBgNV\nBAgMAktBMQwwCgYDVQQHDANCTFIxCzAJBgNVBAoMAlBOMQwwCgYDVQQLDANFTkcx\nDzANBgNVBAMMBlNQSU5FMTAeFw0yMDA1MDQxODM4NTZaFw0yMTA1MDQxODM4NTZa\nMFQxCzAJBgNVBAYTAklOMQswCQYDVQQIDAJLQTEMMAoGA1UEBwwDQkxSMQswCQYD\nVQQKDAJQTjEMMAoGA1UECwwDRU5HMQ8wDQYDVQQDDAZTUElORTEwggEiMA0GCSqG\nSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCot16ddH0LNHOrWZt63FHYiArVXYIYbCDh\nWCY6MX3suoXYvKstvRgJkUe/6G5As+vYtwRi2bDqdDsgTC5+Qo4SnjrdTcTM98F+\n0Qzqv02c+dbzk5GclUkljqq0PHGXRPGOMhou8B/6LI9Hg5XkG+FSfaDGQTM39uj2\nzzvrMOFn96gzpTBoh40sMoIpnKQLrWeGjlNxaBxhM342c1jn1CVmXss/uHMQeang\nsVhPTynikyxIrDwl9gh/2X1EwzVzpAnUBTUZvJ9rgrceC9GcuGmiPZgxxSruNb0w\nK8xsyH8/hLwhK4Axgu3a+lfmmKFmSWjywmcxlmQl+jwiMPA/Ty55AgMBAAEwDQYJ\nKoZIhvcNAQELBQADggEBAEG0D/2FcNU6Z6w/6eKbyH855kHSrJyqeU8eoCW9rnOb\nqdnAsFX3aYwiUCjzSFXpWA3bRr3L7X0Y01x7VSvwITuDvwO43llK29rQfrSvoPiw\nf7fhU7bszlUc2GAumU9OEdYBnSI1DzfBawUcPmbDmm+ci27k0po53KDWTbxkBIZR\n2Oh25LXkmq8ZBzE4vgS+mAw436nToazB1/vDTMWoBuLVzOUlU8cdcjJUnJBevTbX\nThP691sHVMED8B8Fhl08BzIJmQQ9qp1tjplFq1Ea9oEFnT5U5gKvJYy48qEPlW+r\nhRIHysvZXF/dghtrLXDMSBWLlLofUsDQsh+qLxpo1+k=\n-----END CERTIFICATE-----\n"}'
Note: Unnecessary use of -X or --request, POST is already inferred.
* Trying 10.100.64.5...
* TCP_NODELAY set
* Connected to 10.100.64.5 (10.100.64.5) port 80 (#0)
* Server auth using Basic with user 'network-admin'
> POST /vRest/web-certs/upload HTTP/1.1
> Host: 10.100.64.5
> Authorization: Basic bmV0d29yay1hZG1pbjp0ZXN0MTIz
> User-Agent: curl/7.54.0
> Accept: */*
> content-type:application/json
> Content-Length: 2348
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< Set-Cookie: JSESSIONID=C52C3170DEEAC8E4996FF428D152BF25; Path=/vRest/; HttpOnly
< Date: Tue, 05 May 2020 19:34:05 GMT
< Content-Type: application/json
< Content-Length: 162
<
* Connection #0 to host 10.100.64.5 left intact
{"result":{"status":"Success","result":[{"api.switch-name":"local","scope":"local","status":"Success","code":0,"message":"Successfully uploaded certificates."}]}}