Open Device Programmability: Hands-on Intro to RESTCONF (and a bit of NETCONF)

Open Device Programmability
A hands-on introduction to RESTCONF
(and a bit of NETCONF)
Ralph Schmieder
Technical Leader, DevNet Evangelist, CCIE #9680
Workbench Session, Las Vegas, July 11th to 14th
DEVNET-2044

Housekeeping
• Lecture Part
• Hands-On Part
• Chrome / Postman
• Python
• Ask questions right away
Agenda and Housekeeping
Agenda
• Overview
• RESTCONF and YANG
• URI Construction
• Configuration Snippets

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Public
Why Network Programmability Matters
0
100%
67%
Source: Forrester
CAPEX OPEX
33%
0 10 100 1000
Computing Networking
Seconds
Source: Open Compute Project
Network Expenses Deployment Speed
DEVNET-2044 3

Network Programmability
Physical and Virtual Network Infrastructure
Business Automation System(s)
Controller
DEVNET-2044 4

Business Automation System(s)
Controller
DEVNET-2044 5

Programmatic
Interfaces
Open
Protocols
Configuration
Management
Traffic
Engineering
Operational
State
DEVNET-2044 6

RESTconf NETCONF gRPC
Implementation
Device Features
Interface BGP QoS ACL …
Data Model
Configuration
Standard
Device
Specific
Operational
Standard
Device
Specific
Other vendors
DEVNET-2044 7

Context: Programmatic Interfaces
RESTCONF
• IETF draft
• Designed for web
applications (REST
“like”, based on
NETCONF)
• Session oriented
• Runs over HTTPS
• IETF standard
• Designed for network
programmability
• Session and connection
oriented
• Runs over SSH
• Open source initiative
• Designed for generic
client / service
communications
• Session oriented
• Runs over HTTPS
NETCONF gRPC
DEVNET-2044 8

RESTCONF: What is it?
• IETF driven
• Extends the idea of NETCONF
• RESTCONF promises a standardized / vendor agnostic management
approach to network device management
• Using REST as a popular access method
• Modular and extensible
• Model definition in YANG
• JSON or XML are used for data representation
DEVNET-2044 9

Current State of Draft / RFC
• Not standardized as of today (July 2016)
• Latest draft revision -15 (expires January 2017)
• https://tools.ietf.org/html/draft-ietf-netconf-restconf-15
DEVNET-2044 10

SDN Controller
Integration
Application
Integration
OSS / BSS
Integration
Open SDN
Controller
Inventory / Topology
Configuration Mgmt
Access Control
Script Automation
DevOps
Custom
Application
Service Provisioning
Fault Mgmt
Configuration Mgmt
Use Cases
DEVNET-2044 11

Data Model Life Cycle Management
• Standard definition (IETF, ITU,
OpenConfig, etc.)
• Compliant with standard, i.e. “Policy”
ietf-diffserv-policy.yang
ietf-diffserv-classifer.yang
ietf-diffserv-target.yang
• Cisco definition
• Common across
Cisco platforms,
i.e. “OTV” on IOS-XE
and NX-OS
• Cisco definition
• Unique to specific
Cisco platform,
i.e. “BGP” extensions
on IOS-XE
Industry
Standard
Cisco
Common
Cisco
Platform
Specific
DEVNET-2044 12

Transport
High Level Manageability Architecture
Network DeviceApplication
RESTCONF
server
NETCONF
server
BGP
QoS
VXLAN
RESTCONF
client
NETCONF
client
YANG-based
XML/JSON
SSH / TLS
HTTPS
ANY (Java, Python,
Perl, PHP)
Manageability
Infra
Config
DB
YANG-based XML
ANY (C, Java,
Python)
DEVNET-2044 13

Reality Check: What’s Available?
• Implementations available in
• IOS XR 6.0
• IOS XE 3.17
• Both are in controlled availability
DEVNET-2044 14

So… where’s the API Reference Guide?
Well, there is none.
RESTCONF
… is about the process, a formalized way to talk to a device
… knows a few ‘verbs’
… uses data models to describe device capabilities and functions
… provides well known entry points to ‘discover’ those
Think ‘SNMP and MIBs’…
DEVNET-2044 16

RESTCONF and SNMP
Definition Language:
YANG
Information Model:
YANG modules
Instantiated / transfer syntax:
XML / JSON
Management Service:
RESTCONF
Definition Language:
SMIv2
Information Model:
MIBs
Instantiated / transfer syntax:
ASN.1 BER
Management Service:
SNMP
“Framework”
“Content”
“Payload”
DEVNET-2044 17

What is YANG?
• YANG is a modeling language defined in RFC 6020
• Used by RESTCONF to define the objects and data in requests and replies
• Analogous to XML schema and SMI for SNMP (but more powerful)
• Models configuration, operational, and RPC data
• Provides semantics to better define RESTCONF data
• Constraints (i.e., “MUSTs”)
• Reusable structures
• Built-in and derived types
• YANG is extensible and modular
• YANG modules are for RESTCONF what MIBs are for SNMP
DEVNET-2044 18

Working with YANG Models
• RESTCONF defines how a YANG model is mapped to a
RESTful interface
• Specifically
• How to modify the data by applying using REST verbs
(GET / PUT / PATCH / …)
• How to construct URIs to access the model / data
• Tools help to understand YANG models
DEVNET-2044 19

Where to get the Models?
• https://github.com/YangModels/yang
Note: No XE models have been published
so far!
“YANG modules from standard
organizations such as the IETF, open
source such as Open Daylight or vendor
specific modules”
• https://github.com/CiscoDevNet/xe-
netconf-yang **
• During a lab, like here 
** private, add required
DEVNET-2044 20

Tools to work with YANG Models
• PYANG ‘An extensible YANG validator and converter in python’
• https://github.com/mbj4668/pyang
• Via PyPi: pyang - A YANG (RFC 6020) validator and converter
• Mandatory tool 
• YANG Explorer ‘An open-source
YANG Browser and RPC Builder Application’
• https://github.com/CiscoDevNet/yang-explorer
• Web Based GUI
• More difficult to get started with
DEVNET-2044 21

Display a YANG Module
$ pyang -f tree <yang-file>
(restconf)$ pyang -f tree -p yang/standard/ietf/RFC yang/standard/ietf/RFC/ietf-interfaces.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 interfaces-state
+--ro interface* [name]
+--ro name string
+--ro type identityref
+--ro admin-status enumeration {if-mib}?
+--ro oper-status enumeration
[…]
DEVNET-2044 22

pyang Tip
• JavaScript Tree Output really useful
• Use pyang –f jstree –p <path-to-models> <model.yang> >/tmp/ietf.html
• Produces collapsible Tree / HTML
DEVNET-2044 23

URI Construction
(some slides credit: Wojciech Dec’s BRKSDN-1903)

Request URI Structure
<OP> /<api-entry>/<path>?<query>#<fragment>
M=mandatory, O=optional, I=ignored
M
Method
M
Entry
O
Resource
O
Query
I
Fragment
DEVNET-2044 25

CRUD Methods in RESTCONF
RESTCONF As compared to NETCONF
OPTIONS none
HEAD none
GET <get-config>, <get>
POST <edit-config> (operation="create")
PUT <edit-config> (operation="create/replace")
PATCH <edit-config> (operation="merge")
DELETE <edit-config> (operation="delete")
CRUD = Create, Retrieve, Update, Delete
DEVNET-2044 26

Discover API
Entry
List YANG
Modules
Parse
YANG
Model
Apply
RESTCONF
Logic
Construct /
Deconstruct
JSON / XML
Flow: API Discovery and Use
GET /.well-known/host-meta
GET {+restconf}/data/ietf-
yang-library:modules
pyang –f tree <model.yang>
Synthesize URI and
parameters as defined in
(draft) RFC
Map to / from YANG model
(‘GET the JSON data’)
DEVNET-2044 27

RESTCONF API (1/4)
A RESTCONF URI is:
/<api-entry>/<resource-type>/<yang-module:resource>
Module my-interfaces {
namespace ”com.my-interfaces”;
container interfaces {
list interface {
key name;
leaf name {type string;}
leaf admin-status {type enum;}
}
}
rpc flap-interface {
input {
leaf name {type string;}
}
output {
leaf result { type boolean; }
}
}
}
URI:
/restconf/data/my-interfaces:interfaces
URI:
/restconf/operations/my-interfaces:flap-
interface
YANG
Model
DEVNET-2044 28

list interface {
key name;
leaf name { type string; }
leaf admin-status { type enum;}
RESTCONF API (2/4)
Containers and Lists
/<api-entry>/<resource-type>/<yang-module:resource>
YANG
Model
URI:
/restconf/data/my-interfaces:interfaces
URI:
/restconf/data/my-interfaces:interfaces/interface/<some name>
DEVNET-2044 29

RESTCONF API (3/4)
Acting on resources
GET : Gets a resource
POST : Creates a resource or invoke operation
PUT : Replaces a resource
DELETE : Removes a resource
{
list interface {
key name;
leaf admin-status { type enum;}
rpc flap-interface {
input {
}
output {
leaf result { type boolean; }
}
}
POST /restconf/operations/my-interfaces:flap-interface
+ JSON/XML Form Data (including name)
Response will have JSON/XML result
GET /restconf/data/my-interfaces:interfaces
GET /restconf/data/my-interfaces:interfaces/interface/<some
name>
PUT /restconf/data/my-interfaces:interfaces/interface/<some
name> + JSON/XML Form Data (name, admin-status)
DELETE /restconf/data/my-interfaces:interfaces/interface
/<some name>
DEVNET-2044 30

RESTCONF API (4/4)
List Data
• RESTCONF requires that data passed includes module name-space
• Creation of List items is done using POST to resource: /restconf/data/my-
interfaces:interfaces/interface with JSON or XML data expressing name
namespace "com.my-interfaces";
list interface {
key name;
leaf name
{ type string; }
leaf admin-status
{ type enum;}
{"my-interfaces:interface": [
{"name": "GigabitEthernet0/0",
"admin-status": up
}
]
}
<interface xmlns="com.my-interfaces">
<name>GigabitEthernet0/0</name>
<admin-status>up</admin-status>
</interface>
DEVNET-2044 31

Conclusion
• RESTCONF defines how a YANG model is mapped to a
RESTful interface
• There is no API guide, but tools to deal with models
• It uses a well understood transport (REST)
Get Ready to RESTCONF!
DEVNET-2044 32

IOS XE (3.17) Configuration Snippet
remote-management
no restful-api
dmi
!
interface VirtualPortGroup0
ip unnumbered GigabitEthernet1
!
virtual-service csr_mgmt
vnic gateway VirtualPortGroup0
guest ip address 172.16.1.32
activate
!
ip route 172.16.1.32 255.255.255.255 VirtualPortGroup0
Ports:
TCP/8008 (HTTP)
In the lab: 9443, port
translated
DEVNET-2044 34

IOS XE (3.17) with VRF Configuration Snippet
remote-management
no restful-api
dmi
!
interface GigabitEthernet1
vrf forwarding <VRF>
ip address <MGMT_IP AND MASK>
!
interface VirtualPortGroup0
vrf forwarding <VRF>
ip unnumbered GigabitEthernet1
!
virtual-service csr_mgmt
vnic gateway VirtualPortGroup0
guest ip address <CONTAINER-IP>
activate
!
ip route VRF <VRF> <CONTAINER-IP> 255.255.255.255 VirtualPortGroup0 <CONTAINER-IP>
DEVNET-2044 35

IOS XR (6.0) Configuration Snippet
interface Loopback1
ipv4 address 128.0.0.1 255.0.0.0
!
web server
service restconf
http-port 80
https-port 443
http-enable
!
!
restconf agent
open-request-limit 10
per-user-request-limit 10
!
DEVNET-2044 36

Resources
Interface Protocols
• RESTCONF- https://tools.ietf.org/html/draft-ietf-netconf-restconf-09
• NETCONF - https://tools.ietf.org/html/rfc6241
• gRPC - http://www.grpc.io
Data Models
• IETF - https://tools.ietf.org/html/rfc6020
• ITU - https://www.itu.int/oth/T1C02000002
• OpenConfig - http://www.openconfig.net/data-models
DEVNET-2044 38

Resources (cont.)
• Wojciech’s CL deck ‘A Model-driven Approach to Software Defined Networks
with Yang, NETCONF/RESTCONF’, BRKSDN-1903
https://www.ciscolive.com/online/connect/sessionDetail.ww?SESSION_ID=8414
9&tclass=popup
• YANG Explorer (open source)
https://github.com/CiscoDevNet/yang-explorer
• SDN Tutorials: What is RESTCONF?
http://sdntutorials.com/what-is-restconf/
• Postman and self-signed Certs
http://blog.getpostman.com/2014/01/28/using-self-signed-certificates-with-
postman/
DEVNET-2044 39

Resources (cont.)
• YANG Module Repository (IETF, Open, Vendors)
https://github.com/YangModels/yang
• Pyang tool
https://github.com/mbj4668/pyang
DEVNET-2044 40

How to Access the Lab and Documentation
• We're using a shared router in a lab on
the DevNet Sandbox
• Use the pod number as assigned
• Detailed Lab Instructions are here
http://virl-dev-innovate.cisco.com:8301/
• Recommend to open the link on your
Windows workstation in Chrome
DEVNET-2044 42

Open Device Programmability: Hands-on Intro to RESTCONF (and a bit of NETCONF)

NETCONF – The Basics
• NETCONF – NETwork CONFiguration Protocol
• Network management protocol – defines management operations
• First version in 2006, RFC 4741
• Latest RFC is RFC 6241 (2011)
• Does not define content in management operations
• Leaves that to YANG
DEVNET-2044 46

NETCONF Overview
Transport
Remote
Operations
Management
Services
Management info
(instantiated/payload)
Management info
(definition)
XML-encoded content
e.g., YANG modules
NETCONF operations
<edit-config>, <get-config>, <get>
Netconf RPC
<rpc>, <rpc-reply>
TLS, SSH
Manager (client)
XML
content
per
YANG
Conceptual
Data
Store
Agent
(server)
Several data stores:
• Running
• Startup
• Candidate
DEVNET-2044 47

NETCONF Sessions
• NETCONF is connection-oriented
• SSH, TLS as underlying transport
• NETCONF client (“manager”) establishes session with
server (“agent”)
• Session establishment: <hello> exchange
• Announce capabilities, modules, features
• Session termination
• <close-session>, <kill-session>
DEVNET-2044 48

NETCONF Operations
• <edit-config>
• target: which data store
• config: the configuration to be applied
• Operations:
• Merge (default)
• Replace
• Create (error in case of already existing
subtree)
• Delete
• Remove
• Additional options (not always
supported, negotiated up-front):
• test-option (validate before applying)
• error-option (stop[default]/ continue/
rollback on error)
• <copy-config>
• copy from a source to a target; target
is overwritten or created
• <delete-config>
• cannot have <running> as target
• <get-schema>
• Retrieve a YANG schema
DEVNET-2044 49

NETCONF Operations (contd.)
• <lock>, <unlock>
• data stores only available as target as a whole, cannot just lock subtree
Partial locks supported in an extension
• locks apply beyond scope of NETCONF itself –
cannot change contents of a data store through other management interfaces either
• <get-config>
• source: which data store
• filter: which portions / subtree (e.g. specified using xpath)
• Containment nodes
• Selection nodes, list element instances, pruning of siblings
• Attribute match expressions
• <get>
• Like <get-config>, but can include operational data
DEVNET-2044 50

Retrieve an interface configuration
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces"
type="xpath"
select="/if:interfaces/if:interface[if:name='eth0']"/>
</get-config>
</rpc>
DEVNET-2044 51

Retrieve an interface configuration
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
<data>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth0</name>
<type>ethernetCsmacd</type>
<location>0</location>
<if-index>2</if-index>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>192.0.2.1</ip>
<prefix-length>24</prefix-length>
</address>
</ipv4>
<address>
<ip>2001:DB8::1</ip>
</address>
<dup-addr-detect-transmits>0</dup-addr-detect-transmits>
</ipv6>
</interface>
</interfaces>
</data>
</rpc-reply>
DEVNET-2044 52

Edit an interface configuration
Change IPv4 address of eth0 to 192.0.2.2
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="102">
<edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0”>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eth0</name>
<address xc:operation=“replace”>
<ip>192.0.2.2</ip>
</address>
</ipv4>
</interface>
</interfaces>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="102“ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
DEVNET-2044 53

Backup: Certificates, Hostnames,
and Ciphers

REST APIs with TLS: Reality Check
HTTPS / TLS should be the default… however...
• Self-signed certificates are an issue (Chrome, Postman, Python, …)
• Systems not in DNS are an issue (CN in certificate does not match the URI / IP)
• Python libraries may not be up-to-date (TLS versions and ciphers proposals)
• Next couple of slides provide some guidance
This is for labs / testing purposes only. Don't do this for
production systems!
DEVNET-2044 55

Newer Versions of OpenSSL and SSH
Newer Distros have disabled unsecure hash ciphers
• OpenSSL disabled RC4 / MD5 by default
• IOS DMI relies on it  for RESTCONF using HTTPS
• SSH disabled various Key Exchange algorithms
• IOS DMI relies on it  for NETCONF using SSH
DEVNET-2044 56

OpenSSH
NETCONF using SSH as a transport
• In ~/.ssh/config add the following lines
Host 198.18.133.* 172.16.33.100
HostKeyAlgorithms +ssh-dss
KexAlgorithms +diffie-hellman-group1-sha1
• These settings can be enabled by host in the Host line
• See man ssh_config
DEVNET-2044 57

"Secure" RESTCONF over TLS
• Really FYI, not to be used in production at all
• Certificate can't be replaced  and is self-signed with weak SHA1 hash**
Signature Algorithm: sha1WithRSAEncryption
Issuer: CN=ios-xe-mgmt
Subject: CN=ios-xe-mgmt
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
[…]
• http://venturebeat.com/2015/12/18/google-will-drop-sha-1-encryption-from-
chrome-by-january-1-2017/
**Will be configurable at FCS
DEVNET-2044 58

"Secure" RESTCONF over TLS (cont'd)
• DMI Web server uses weak ciphers MD5 / SHA1 
• Modern browser will complain badly (Firefox) or not connect at all (Chrome)
• Since Chrome does not like it, there's no way to coerce Postman to use TLS
(just stay away from it)
• Using OpenSSL to retrieve certificate:
openssl s_client -cipher RC4-MD5 -connect
198.18.133.218:8888
DEVNET-2044 59

That said, the following illustrates
the use of self signed certs…
(and uses some screenshots from a different setup)

Prepare System
RESTCONF via HTTPS
• is at 198.18.133.218, port 8888
• Has a self signed cert with
CN=ios-xe-mgmt 
• Needs to be imported / trusted
• Needs '/etc/hosts' entry
DEVNET-2044 61

Postman will not like the Certificate!
You will see this for
various reasons:
• 'ios-xe-mgmt' is
unknown so far
• The certificate that will
be presented is not
trusted
• The used cipher is
deprecated
DEVNET-2044 62

Bad Cipher
HTTPS showstopper
If you see 'unexpectedly closed
the connection':
• This translates to 'Chrome
does not like the webserver'
• No workaround other than not
to use TLS
DEVNET-2044 63

Hosts entry (cont.)
• Open 'cmd.exe' as Administrator
• 'cd WindowsSystem32Drivers'
• 'notepad hosts'
• Add this line at bottom (see next slide)
'198.18.133.218ios-xe-mgmt'
DEVNET-2044 65

Hosts entry (cont.)
DEVNET-2044 66

Hosts File on Mac OS X or Linux
• Edit /etc/hosts
• Use Terminal
sudo vi /etc/hosts
DEVNET-2044 67

Certificate
• It's self signed
• Chrome does not like them
• Here's how to work around
it…
• In Chrome, 'View
certificate'
DEVNET-2044 69

Certificate (cont.)
• Export Certificate to File
• Export as PEM
• Save to desktop as
'ios-xe-mgmt.cer'
DEVNET-2044 70

Certificate (cont.)
• Install Certificate into System
• For 'Current user'
• Place in 'Trusted Root
Certification' Store
• The location IS important!
1
2
3
DEVNET-2044 71

Certificates on Mac OS X
DEVNET-2044 72

Python and SSL
• Python is also picky about certificates
• And TLS versions
DEVNET-2044 74

SSL Warnings
• If you see this
SubjectAltNameWarning: Certificate for apic has no `subjectAltName`, […]
• Then add this to your code
requests.packages.urllib3.disable_warnings()
• This suppresses the warning
• We really should get a proper certificate, shouldn't we?
DEVNET-2044 75

Wrong OpenSSL / TLS version
• If you see this (seen w/ Python 2.7 on my Mac)
requests.exceptions.ConnectionError: ('Connection aborted.', error(54, 'Connection reset
by peer'))
• Then do this
pip install --use-wheel pyopenssl ndg-httpsclient
• This installs a different / newer OpenSSL library
DEVNET-2044 76

Cert Validation in Python
• If you see this
requests.exceptions.SSLError: ("bad handshake: Error([('SSL routines',
'ssl3_get_server_certificate', 'certificate verify failed')],)",)
• Because:
• 'requests' does not look into System Cert storage
• Uses …libsite-packagerequestscacert.pem
• Add ios-xe-mgmt.cer (it's PEM encoded!) to cacert.pem
• Alternatively, add 'verify=False' to your 'get()' call
DEVNET-2044 77

Open Device Programmability: Hands-on Intro to RESTCONF (and a bit of NETCONF)

Recommended

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Open Device Programmability: Hands-on Intro to RESTCONF (and a bit of NETCONF) (20)

More from Cisco DevNet (20)

Recently uploaded (20)

Open Device Programmability: Hands-on Intro to RESTCONF (and a bit of NETCONF)

Editor's Notes