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 Networks recommends using HTTPS for security reasons. 


The vREST web application that runs on the switch enables the REST API client to access the switch's resources.


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

Modify services on the switch.

if if-string

Specify the administrative service interface. 
The options are mgmt or data.

Specify one or more of the following options:

ssh|no-ssh

Specify if you want to connect to the switch using Secure Shell (SSH).

nfs|no-nfs

Specify if you want to use Network Files System (NFS) for the administrative service.

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.

snmp|no-snmp

Specify if SNMP is allowed as a service.

net-api|no-net-api

Specify if APIs are allowed as a service.

icmp|no-icmp

Specify if Internet Control Message Protocol (ICMP) is allowed as a service.


Verify the 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


To access the log details, enable the web-log parameter by using the command:


CLI (network-admin@switch1) > admin-service-modify if mgmt web-log



Warning: We recommend enabling web-log for debugging purposes and only as advised by Pluribus Networks Technical Support as log files can quickly consume available disk space.



If you wish to confirm web_log is enabled run the following command:


CLI (network-admin@udev-leo1) > admin-service-show format all


To disable the web-log run the following command:


CLI (network-admin@switch1) > admin-service-modify if mgmt no-web-log


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 the 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 API 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.


This command generates the certificate request and saves the files internally.


Enable web-ssl by using the admin-service-modify command.


CLI (network-admin@switch1) admin-service-modify if data web-ssl


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.


In return, the CA provides the server certificate of your switch signed using the intermediate key. 


Upload the signed certificate, the CA root certificate, and the intermediate CA certificate (if an intermediate CA signs the certificate) to /sftp/import directory on the switch using SFTP.


For example:


$ sftp sftp@switch1


Password:pluribus_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 data web-ssl


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 Certs


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


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



Warning: Failure to use the escape character syntax of \n, as highlighted in red in the examples shown, results in the script failing, and the installation of the certificates to fail.




Note: Certificate examples on this page are displayed line-wrapped for purposes of documentation clarity only.



Copy the output into the json payload.


$ curl -u network-admin:pluribus_password 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."}]}}

north
    keyboard_arrow_up
    keyboard_arrow_down
    description
    print
    feedback
    support
    business
    rss_feed
    south