Cisco Nexus 9000 Series NX-OS Programmability Guide, Release 10.2(x)

About the RESTCONF Agent

Cisco NX-OS RESTCONF is an HTTP -based protocol for configuring data that are defined in YANG version 1, using datastores defined in NETCONF.

NETCONF defines configuration datastores and a set of Create, Retrieve, Update, and Delete (CRUD) operations that can be used to access these datastores. The YANG language defines the syntax and semantics of datastore content, operational data, protocol operations, and event notifications.

Cisco NX-OS RESTCONF uses HTTP operations to provide CRUD operations on a conceptual datastore containing YANG-defined data. This data is compatible with a server which implements NETCONF datastores.

The RESTCONF protocol supports both XML and JSON payload encodings. User authentication is done through the HTTP Basic Authentication.

The following table shows the Protocol operations that the Cisco NX-OS RESTCONF Agent supports:


RESTCONF	NETCONF Equivalent
OPTIONS	NETCONF: none
HEAD	NETCONF: none
GET	NETCONF: <get-config>, <get>
POST	NETCONF: <edit-config> (operation="create")
PUT	NETCONF: <edit-config> (operation="create/replace")
PATCH	NETCONF: <edit-config> (operation="merge")
DELETE	NETCONF: <edit-config> (operation="delete")

Guidelines and Limitations

The RESTCONF Agent has the following guideline and limitation:

Cisco NX-OS RESTCONF is based on an RFC draft entitled RESTCONF Protocol draft-ietf-netconf-restconf-10. See https://tools.ietf.org/html/draft-ietf-netconf-restconf-10.
RESTCONF does not support enhanced Role-Based Access Control (RBAC) as specified in RFC 6536. Only users with a "network-admin" role are granted access to the RESTCONF agent.
Beginning with 10.2(1)F release, the operations checkpoint, rollback, install, import ca certificate, switch reload, individual module reload, and copy file are supported.

Using the RESTCONF Agent

General Commands

Configure the following commands to enable HTTP or HTTPS access:
- feature nxapi
- nxapi http port 80
- nxapi https port 443

General Control Commands

You can enable or disable the RESTCONF Agent [no] feature restconf command.

Viewing the Agent Status

To view the status of the RESTCONF agent, use the show feature command and include the expression restconf.

switch-1# show feature | grep restconf
restconf               1          enabled 
switch-1#

Sending a POST Request to the Server Using Curl


client-host % curl -X POST -H "Authorization: Basic YWRtaW46Y2lzY28=" -H "Content-Type: application/yang.data+xml" -d '<always>enabled</always><rtrId>2.2.2.2</rtrId>' "http://192.0.20.123/restconf/data/Cisco-NX-OS-device:System/bgp-items/inst-items/dom-items/Dom-list=default" -i

HTTP/1.1 201 Created
Server: nginx/1.7.10
Date: Tue, 27 Sep 2016 20:25:31 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: nxapi_auth=admin:147500853169574134
Status: 201 Created
Location: /System/bgp-items/inst-items/dom-items/Dom-list=default/always/rtrId/

Sending a GET Request to the Server Using Curl


client-host % curl -X GET -H "Authorization: Basic YWRtaW46Y2lzY28=" -H "Accept: application/yang.data+xml" "http://192.0.20.123/restconf/data/Cisco-NX-OS-device:System/bgp-items/inst-items/dom-items/Dom-list?content=config" -i

HTTP/1.1 200 OK
Server: nginx/1.7.10
Date: Tue, 27 Sep 2016 20:26:03 GMT
Content-Type: application/yang.data+xml
Content-Length: 395
Connection: keep-alive
Set-Cookie: nxapi_auth=admin:147500856185650327
Status: 200 OK

    <Dom-list>
        <name>default</name>
        <always>enabled</always>
        <bestPathIntvl>300</bestPathIntvl>
        <holdIntvl>180</holdIntvl>
        <kaIntvl>60</kaIntvl>
        <maxAsLimit>0</maxAsLimit>
        <pfxPeerTimeout>30</pfxPeerTimeout>
        <pfxPeerWaitTime>90</pfxPeerWaitTime>
        <reConnIntvl>60</reConnIntvl>
        <rtrId>2.2.2.2</rtrId>
    </Dom-list>
client-host %

Troubleshooting the RESTCONF Agent

Troubleshooting Connectivity

Enable the web server by issuing the feature nxapi command.
Ensure that the nxapi http port 80 command is configured to open up the port for HTTP
Ensure that the nxapi https port 443 command is configured to open up the port for HTTPS.
Ping the management port of the switch to verify that the switch is reachable.

About Ephemeral Data in RESTCONF

This feature provides access to ephemeral data. Ephemeral data is high volume data. DME provides a batching mechanism to retrieve the data so that each batch is of a manageable size in terms of memory usage. The size of the batch is the number of MOs to be retrieved.

You can find information about which data is ephemeral by the comment "Ephemeral data" in the published Cisco-NX-OS-device.yang file.

The output from ephemeral data is returned, if and only if the URI in the request points to:

A leaf from ephemeral data
A container or list with ephemeral data children
An empty container that is used to wrap a list that has direct ephemeral data children

System level GET queries do not return ephemeral data.

RESTCONF Ephemeral Data Example

This is an example for retrieving ephemeral data.

The client might send the following GET request message:

GET /restconf/data/Cisco-NX-OS-device:System//urib-items/table4-items/Table4-list=management/route4-items HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json
 
   The server might respond:
 
      HTTP/1.1 200 OK
      Date: Fri, 06 Mar 2020 11:10:30 GMT
      Server: nginx/1.7.10
      Content-Type: application/yang.data+json
 
      {
          "route4-items": {
               "Route4-list": [{
                   "prefix": "172.23.167.255/32",
                   "flags": "0",
                   ...

Execution Operations

About Operational Commands in RESTCONF

This feature provides ways to perform model driven operation commands execution on the switch.

The following is the list of supported execution RPCs. Information about the RPCs can be found in the published Cisco-NX-OS-device.yang file.

Table 1. About Model Driven Operations in RESTCONF
Operation	RESTCONF RPC	CLI
Checkpoint	checkpoint	checkpoint <name> checkpoint <file>
Rollback	rollback	rollback running-config checkpoint <name> rollback running-config checkpoint <file>
Install	install_all_nxos install_add install_activate install_deactivate install_commit install_remove	install all nxos <image> install {add \| activate \| deactivate \| commit \| remove} <rpm>
Import Crypto Certificate	import_ca_certificate	crypto ca import <trustpoint> pkcs12 <file> <passphrase>
Switch Reload or Module Reload	reload	reload [timer <seconds>] reload module <module number>
Copy File	copy	copy <source> <destination>