1 v1.2

2 v1.2

Model Driven ProgrammabilityNETCONF, RESTCONF and YANG

Trainer Name

3 v1.2

Table of Content

• Device configurations - CLI & SNMP

• Model-driven programmability

• Data Model - YANG

• Protocols - NETCONF & RESTCONF

• Data Encoding - JSON & XML

• API Tools & Resources

4 v1.2

Device Configuration - Command-line Interface

• There are many different ways to connect to and manage a

network

• The most commonly used method for the past 30 years has been

by using the command-line interface (CLI)

• And one of the most glaring and biggest flaws with using CLI to

manage a network is misconfiguration

• A majority of network outages are caused by human errors

5 v1.2

Device Configuration - Command-line Interface

• CLI Pros and Cons

PROs CONs

Well know and documented Difficult to scale

Commonly used method Large number of commands

Command can be scripted Must known IOS command syntax

Syntax help available on each command Executing command can be slow

Can execute only one command at a time

CLI and command can change between

software versions and platforms

Using CLI can pose a security threat if using

Telnet (plaintext)

Vendor-specific commands

Complex in parsing

6 v1.2

Device Configuration - SNMP

• SNMP is widely used for fault handling and monitoring

• In practice, SNMP is rarely used for configuration

• Major problems of the traditional SNMP mode– Insufficient Performance: Data configuration and reading are low, especially in

the development of large-scale networks

– Difficult to deliver configurations: Only a few MIB objects support the write operation

– No support for the transaction mechanism: SNMP operations are stateless. Therefore, the operations cannot be interrupted in the case of a configuration timeout

– Poor programmability: Lack of composite data structures, few RPC interfaces and time-consuming commissioning

7 v1.2

A new API is needed?

• In June, 2002 the IETF Internet Architecture Board (IAB) held a Network Management Workshop to assess the state of network management and develop requirements for next generation network management protocol

• As a result, RFC 3535 was published that identified the need for a new NETwork CONfiguration protocol

• They outline some key requirements for this protocol– Easy to use for the operator

– Provides Clear separation between Configuration state and operational state of the device

– Backup and restore capability

– Human and Machine friendly

– Provides Error checking

An API (Application Programming Interface) in its simplest form

can be considered a Contract or Agreement between two end

points, regarding what to send and what to expect in return.

It is used with Machines to request data and or to change data on

the device

8 v1.2

The Rise of NETCONF

• In 2006 NETCONF was born

– RFC 4741: NETCONF protocol v1.0

– RFC 6241: NETCONF protocol v1.1

• The NETCONF standard define a communication channel

between a Server (network Node) and client (NMS, SDN or

Application)

• The end result has been a programmable device interface ideally

suited for use in SDN and NFV

9 v1.2

Model-driven Programmability

source: https://blogs.cisco.com/getyourbuildon/model-driven-programmability

App1 App2 App3

Model-Driven APIs

YANG Development Kit (YDK)

NETCONF RESTCONF gRPC

XML JSON GPB

SSH HTTP(S)

Data Models

YANG (native, open)

Apps

Bindings

Protocol

Encoding

Transport

Models

Model-driven programmability inherits the power of models, making it easier to

configure routers. It overcomes drawbacks posed by traditional router management

techniques

10 v1.2

Model-driven Programmability - Benefits

• Model based, structured, computer friendly

• Multiple model types (native, OpenConfig, IETF)

• Models decoupled from transport, protocol end encoding

• Choice of transport, protocol and encoding

• Model-driven APIs for abstraction and simplification

• Wide standard support while leveraging open source

11 v1.2

Data Models

• Data models are used to describe – whatever can be configured on a device,

– everything that can be monitored on a device,

– and all the administrative actions that can be executed on a device (example: resetting counters or rebooting the device)

• The list of supported models includes – Native (Vendor)

– OpenConfig and

– IETF models

• YANG (Yet Another Next Generation) provides a modeling language optimized for network devices and with a growing number of tools and utilities

12 v1.2

Protocols

• The separation of models from the choice of protocol provides a

high degree of flexibility

• We can control the network device using

– NETCONF

– RESTCONF or

– Google RPC (gRPC)

• Your protocol choice will ultimately be influenced by your

networking, programming and automation background, plus

tooling available

13 v1.2

Encodings

• The separation of encodings from the choice of model and

protocol provides additional flexibility

• Data can be encoded in

– JSON

– XML or

– Google protocol buffers (GPB) format

• While some transports are currently tied to specific encodings

(e.g. NETCONF and XML), the programmability infrastructure is

designed to support different encodings of the same data model if

the transport protocol supports it

14 v1.2

Module 2: Data ModelsModel Driven Programmability

15 v1.2

YANG

• “Yet Another Next Generation” – A Data Modeling Language for NETCONF

• YANG is a data modeling language used to – model configuration

– state data and

– administrative actions manipulated by the NETCONF protocol

• Key YANG Capabilities– Human readable, easy to learn representation

– Hierarchical configuration data models

– Reusable types and groupings (structured types)

– Extensibility through augmentation mechanisms

– Supports the definition of operations (RPCs)

– Formal constraints for configuration validation

– Data modularity through modules and submodules

– Versioning rules and development support

RFC 6020

RFC 7950

16 v1.2

YANG vs Other Modeling Language

• Other Modeling languages are already existed

– SMI (SNMP)

– UML

– XML Schema

• None of these languages were specifically targeted to the needs

of configuration management

• The Network Modeling (NETMOD) working group is responsible

for the YANG data modeling language

17 v1.2

YANG Structure

• Yang files are called Modules

• Each module is uniquely identified by a namespace URI

• YANG models data using a hierarchical, tree-based structure with nodes

• Main node types:– Container : A grouping of other statements

(which have no value)

– List : Multiple records containing at least one Leaf “Key” and an arbitrary hierarchy of other statements within the Module

– Leaf : A single Key/Value Pair

– Leaf-List : Multiple Key/Value pairs of the same type or commonality

• Each leaf is associated against a data type

18 v1.2

YANG Model Types

• Currently there are three main publishers for the YANG Modules

Vendor (native) IETF OpenConfig

Vendor specific

Example:

“BGP” extensions on IOS-XE

Reference:

https://github.com/YangModels/y

ang/tree/master/vendor/cisco

Standard definition from IETF,

ITU etc)

Example:

ietf-diffserv-policy.yang

ietf-diffserv-target.yang

Reference:

https://github.com/YangModels/y

ang

Vendor-neutral data models

Example:

openconfig-bgp-common-

multiprotocol.yang

openconfig-mpls-rsvp.yang

Reference:

https://www.openconfig.net/

OpenConfig and IETF models are mapped to native models

19 v1.2

YANG Tools - pyang

• pyang is a YANG validator, transformation and code generator,

written in python

• It can be used to validate YANG modules for correctness, to

transform YANG modules into other formats, and to generate code

from the modules

• https://pypi.org/project/pyang/

$ pyang -f tree ietf-interfaces@2018-02-20.yang

module: ietf-interfaces

+--rw interfaces

| +--rw interface* [name]

| +--rw name string

| +--rw description? string

| +--rw type identityref

| +--rw enabled? boolean

| +--rw link-up-down-trap-enable? enumeration {if-mib}?

| +--ro admin-status enumeration {if-mib}?

| +--ro oper-status enumeration

| +--ro last-change? yang:date-and-time

| +--ro if-index int32 {if-mib}?

| +--ro phys-address? yang:phys-address

| +--ro higher-layer-if* interface-ref

| +--ro lower-layer-if* interface-ref

| +--ro speed? yang:gauge64

20 v1.2

YANG Tools - YANG Explorer

• A GUI driven tool to test

NETCONF and RESTCONF

interfaces defined by YANG

models

• Features

– Load YANG models from device

– Browse YANG models

– Execute NETCONF or RESTCONF

Operations

– Generate self-contained Python scripts

– Open Source https://github.com/CiscoDevNet/yang-explorer

21 v1.2

Module 3: ProtocolsModel Driven Programmability

22 v1.2

Protocols

• Set of rules that determine how data is transmitted between

different devices in the same network

• Common protocols for model-driven programmability

– NETCONF

– RESTCONF

23 v1.2

NETCONF

• NETCONF is an IETF network management protocol designed

specifically for configuration management

• Features:

– Makes a distinction between configuration and state data

– Utilizes multiple configuration data stores (candidate, running, startup)

– Configuration change transactions

– Provides client-side configuration validation

– Uses filtering mechanisms for selective data retrieval

– Uses a client-server model and SSH as transport protocol

24 v1.2

NETCONF Communications

• The NETCONF standard define a communication channel

between a Server (network Node) and client (NMS, SDN or

Application)

25 v1.2

NETCONF Protocol Stack

• The following are the key characteristics of NETCONF

– It uses SSH as Transport protocol

– It is Connection oriented and Session Oriented

– It uses XML for encoding and representing data

– It defines multiple operations to interact with the network device

– It uses RPC methods to invoke these operations on the remote network device

ContentConfiguration /

Operational Data

Operations

Messages

Transport

Actions to Take

Remote Procedure

Call (RPC)

TCP/IP Method

<data>

<get>, <get-config>,

<edit-config>

<rpc>, <rpc-reply>

SSH

XM

L

26 v1.2

NETCONF Operations

Main Operations Cisco Command Description

<get> show ? Retrieve running configuration and device state

information

<get-config> show run Retrieve all or part of specified configuration datastore

<edit-config> con t Loads all or part of a configuration to the specified

configuration datastore

Other Operations Description

<copy-config> Replace an entire configuration datastore with another

<delete-config> Delete a configuration datastore

<commit> Copy candidate datastore to running datastore (ex: XR)

<lock> / <unlock> Lock or unlock the entire configuration datastore

system

<close-session> Graceful termination of NETCONF session

<kill-session> Forced termination of NETCONF session

27 v1.2

NETCONF Data Stores

• The NETCONF standard defines an important concept Called

Data Stores to interact with the network devices, these Data

Stores are:

– Running Data Store: Include the current active configuration on the device

– Candidate Data Store: Holds that configuration changes before

committing/copying to the running configuration

– Startup Data Stores: This is the configuration that the device use during boot up

• Not all data stores are supported by all devices

• Running config is the only required data store

28 v1.2

RESTCONF

• It’s an implementation of a EST API

• Model-driven API

• Functional sub-set of NETCONF

• Exposes YANG models via a REST API (URL)

• Uses HTTP(S) as transport

• Uses XML or JSON for encoding

• Developed to use HTTP tools and programming libraries

29 v1.2

RESTCONF - Background on REST

• Same HTTP Request Methods and Response Codes are used

Client Server

HTTP GET

HTML Response

API ClientWeb Server

On a Network Device

HTTP GET

JSON/XML Response

30 v1.2

REST - HTTP Verbs

GET Retrieve / Read a resource show command

POST Creates a new resource create logical interface

PUT Update/Replace a resource replace full interface config with what’s in

the body of request

PATCH Update/Modify a resource update (append) interface config with

what’s in the body of request

DELETE Removes a resource remove logical interface

• HTTP Verbs in the context of network devices

31 v1.2

REST - HTTP Response Code

• Common HTTP Response Code

Success (2xx) Description

200 Request Succeeded

201 The request has been fulfilled; new resource created

204 The server fulfilled request but does not return a body

Client Error (4xx) Description

400 Bad Request. Malformed syntax

401 Unauthorized

403 Forbidden. Server understood request, but refuses to full fill it.

404 Not found

Server Error (5xx) Description

500 Internal Server Error

501 Not implemented

32 v1.2

REST API message formats - GET

curl -v https://ipwhois.app/json/8.8.8.8\?objects\=country,city,timezone

> GET /json/8.8.8.8?objects=country,city,timezone HTTP/1.1

> Host: ipwhois.app

> User-Agent: curl/7.58.0

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: nginx/1.14.0

< Date: Mon, 04 Jan 2021 12:43:10 GMT

< Content-Type: application/json; charset=utf-8

< Transfer-Encoding: chunked

< Connection: keep-alive

< X-Powered-By: PHP/7.4.6

< Access-Control-Allow-Origin: *

< Access-Control-Allow-Headers: *

< X-Robots-Tag: noindex

<

* Connection #0 to host ipwhois.app left intact

{"country":"United

States","city":"Ashburn","timezone":"America\/New_York"}%

Request Headers

Response Headers

Response Body (Payload)

Status Code

Verb

33 v1.2

NETCONF vs RESTCONF

NETCONF RESTCONF

Standard IETF IETF

Resources Paths URLs

Data Modeling Language YANG -

Management Operation NETCONF HTTP Operations

Encoding XML XML, JSON

Transport Stack SSH

TCP

SSL

HTTP

TCP

34 v1.2

Module 4: Data EncodingModel Driven Programmability

35 v1.2

Data Encoding

• There needs to be structure behind what is communicated

between systemscore-router# show run interface GigabitEthernet 1

Building configuration...

Current configuration : 146 bytes

!

interface GigabitEthernet1

vrf forwarding MANAGEMENT

ip address 10.0.0.151 255.255.255.0

negotiation auto

end

• This is formatted text, not structured data

• Standard data formats

• XML

• JSON

36 v1.2

XML

• XML stands for eXtensible MarkupLanguage

• Designed to store and transport data

• In XML we have tags, elements, and attributes

• A tag is the text between <>, such as <ip>

• An element is the starting tag, ending tag, and everything in between. Example from line 7-14

• An attribute is a key/value pair inside the starting tag of an element

<?xml version="1.0" encoding="UTF-8"?>

<GigabitEthernet>

<name>1</name>

<vrf>

<forwarding>MANAGEMENT</forwarding>

</vrf>

<ip>

<address>

<primary>

<address>10.0.0.151</address>

<mask>255.255.255.0</mask>

</primary>

</address>

</ip>

<negotiation xmlns="http://cisco.com/ns/yang/Cisco-

IOS-XE-ethernet" >

<auto>true</auto>

</negotiation>

</GigabitEthernet>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

To start a comment, you use <!-- and

then you end it with --> such as <!--

This is a comment -->

37 v1.2

XML

• Run the following command:

curl -i -k -X "GET" "https://ios-xe-mgmt.cisco.com:9443/restconf/data/Cisco-

IOS-XE-native:native/interface" -H "Accept: application/yang-data+xml" -u

"developer:C1sco12345" -H "Content-Type: application/yang-data+xml"

<interface xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native"

xmlns:ios="http://cisco.com/ns/yang/Cisco-IOS-XE-native">

<GigabitEthernet>

<name>1</name>

<description>MANAGEMENT INTERFACE - DON'T TOUCH ME</description>

<ip>

<address>

<primary>

<address>10.10.20.48</address>

<mask>255.255.255.0</mask>

</primary>

</address>

</ip>

Output:

38 v1.2

JSON

• JSON is based on a subset of the JavaScript programming language, as the name implies

• JSON is a syntax for storing and exchanging data

• JSON has no requirement for indentation or white space. It is ideal to use white space and spaces, most likely either two or four to make it human readable– Strings MUST use double quotes

– Object literal names MUST be lowercase (null, false, true etc)

– Special characters need to be escaped

– { says “begin object”

– } says “end object”

– [ says “begin array”

– ] says “end array”

– : separates key and value in key/value pair

– , separates key/value pair in an object or separates values in an array, think of it as “expect another one”

39 v1.2

JSON

• JSON supports the following data types:– Object

– String

– Number

– Boolean

– Null

– Array

• It’s useful to use JSON formatter and validator– https://jsonformatter.curiousconcept.co

m/

{

"Cisco-IOS-XE-native:GigabitEthernet":{

"name":"1",

"vrf":{

"forwarding":"MANAGEMENT"

},

"ip":{

"address":{

"primary":{

"address":"10.0.0.151",

"mask":"255.255.255.0"

}

}

},

"Cisco-IOS-XE-ethernet:negotiation":{

"auto":true

}

}

}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

40 v1.2

JSON

• Run the following command:

curl -i -k -X "GET" "https://ios-xe-mgmt.cisco.com:9443/restconf/data/Cisco-

IOS-XE-native:native/interface" -H "Accept: application/yang-data+json" -u

"developer:C1sco12345" -H "Content-Type: application/yang-data+json"

{

"Cisco-IOS-XE-native:interface": {

"GigabitEthernet": [

{

"name": "1",

"description": "MANAGEMENT INTERFACE - DON'T TOUCH ME",

"ip": {

"address": {

"primary": {

"address": "10.10.20.48",

"mask": "255.255.255.0"

}

}

},

"mop": {

"enabled": false,

"sysid": false

},

"Cisco-IOS-XE-ethernet:negotiation": {

"auto": true

}

},

Output:

41 v1.2

Module 5: API Tools and ResourcesModel Driven Programmability

42 v1.2

How to consume API

• API documentation : Normally API contains documentation and examples, so the first step is to read the doc to see auth and methods are supported, what format is expected, etc– https://ipwhois.io/documentation

– https://developers.facebook.com/docs/graph-api/overview/

– https://sandbox-sdwan-1.cisco.com/apidocs

– https://developer.cisco.com/meraki/api-v1/#!get-device

• Know API endpoint which consists of:– Server URL : Webserver. For example: NGNIX or Flask

– Resource : Path like /device/interface/id or /client/payments/

• Client– Browser

– CURL

– Postman

– Programming language

43 v1.2

CURL

• Curl is a command-line tool for transferring data specified with URL syntax

• With curl, we can download or upload data using one of the supported protocols including HTTP, HTTPS, SCP, SFTP and FTP

• Install curl

$ sudo apt install curl –y

• CURL CLI arguments

-X --request - Custom request method

-d --data - Sends the specified data

-H --header - Sends headers

-i --include - Display response headers

44 v1.2

CURL - REST API

• CURL verbose mode

curl -v https://ios-xe-mgmt.cisco.com:9443

• CURL GET command

curl -i -k -X "GET" "https://ios-xe-

mgmt.cisco.com:9443/restconf/data/Cisco-IOS-XE-

native:native/interface" -H "Accept: application/yang-data+xml"

-u "developer:C1sco12345" -H "Content-Type: application/yang-

data+xml"

45 v1.2

Postman

• The Collaboration Platform for API Development

• Features

– Create, send and save REST, SOAP or GraphQL requests

– Edit URL

– Select method or create and save custom method

– Edit request headers and

– Save preset headers

– Manage cookies associated with various domains

– Send multipart/form-data, url encoded, binary, or raw data in request body

46 v1.2

Postman

• Download Postman

– https://www.postman.com/downloads/

• Postman Chrome Extension

– https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdd

domop?hl=en

47 v1.2

Module 6: LabsModel Driven Programmability

48 v1.2

NETCONF

• Model Driven Programmability NETCONF Labs

– Exercise 1: NETCONF get-config using SSH

– Exercise 2 : NETCONF get-config using ncclient

49 v1.2

RESTCONF

• Model Driven Programmability RESTCONF Labs

– Exercise 1: RESTCONF using Curl

– Exercise 2 : RESTCONF using Postman

50 v1.2

References

• YANG (https://tools.ietf.org/html/rfc6020)

• NETCONF (https://tools.ietf.org/html/rfc6241)

• RESTCONF (https://tools.ietf.org/html/rfc8040)

• OpenConfig (https://github.com/openconfig/public)

• Postman-for-AlwaysOn-Cisco-SD-WAN

(https://github.com/CiscoDevNet/Postman-for-AlwaysOn-Cisco-

SD-WAN)

• YANG Catalog (https://yangcatalog.org/)

51 v1.2