Model Driven Programmability: YANG, NETCONF and RESTCONF

What it is

Model driven programmability manages a device through a formal data model instead of through CLI text.

A YANG model describes what can be configured and read. NETCONF and RESTCONF are the protocols that carry requests that follow that model.

The result is structured, predictable data that scripts can read and change safely, whatever the device's CLI looks like.

How it works

The model defines the data, and the protocol decides how to send it.

YANG

YANG is a data modelling language. A YANG module defines containers, lists, leaves and their types. It also says which parts are configuration and which are read only status.

Models come from three sources:

A Cisco native model reflects the features of that platform. A standard model works across vendors but may offer fewer features.

NETCONF

NETCONF is a network management protocol defined by the IETF. It uses XML and normally runs over SSH on port 830.

Client and server first exchange a hello message that lists their capabilities. The client then sends remote procedure calls, called RPCs, and the server replies.

NETCONF works on datastores. The running datastore holds the active configuration. Some devices also have a candidate datastore, where you stage changes before a commit, and a startup datastore.

NETCONF is transactional. A change is applied as a whole or not at all, and it can be rolled back.

NETCONF from Python

The ncclient library is the usual Python client.

from ncclient import manager

with manager.connect(
    host=HOST,
    port=830,
    username="admin",
    password=PASSWORD,
    hostkey_verify=False,
) as m:
    for cap in m.server_capabilities:
        print(cap)
    reply = m.get_config(source="running")
    print(reply.xml)

The device replies with an XML document. You usually pass a filter so that you receive only the part that you need.

RESTCONF

RESTCONF gives HTTP access to the same YANG data. It maps the standard HTTP methods onto the model, and it uses HTTPS.

Data lives under /restconf/data/, and operations that run an action live under /restconf/operations/. The path names the module and the node, and a list entry is selected with its key after an equals sign.

GET /restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
Accept: application/yang-data+json

Special characters in a key must be percent encoded, so a slash in an interface name becomes %2F.

The two media types are application/yang-data+json and application/yang-data+xml.

A RESTCONF change

This request changes the description of an interface.

PATCH /restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
Content-Type: application/yang-data+json

{
  "ietf-interfaces:interface": {
    "name": "GigabitEthernet1",
    "description": "Uplink to core"
  }
}

A successful PATCH normally returns 204 with no body. The JSON key carries the module name, a colon, and the node name.

NETCONF compared with RESTCONF

Why use models

• The same data model works with every tool and language.
• Data types are checked, so mistakes are found early.
• Output is structured, so there is no screen scraping.
• Tools such as pyang can read the model and show its tree.