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

Open Device ProgrammabilityA hands-on introduction to RESTCONF(and a bit of NETCONF)

Ralph SchmiederTechnical Leader, DevNet Evangelist, CCIE #9680

Workbench Session, Las Vegas, July 11th to 14th

DEVNET-2044

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Public

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

DEVNET-2044 2

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Public 3

Why Network Programmability Matters

0

100%

67%

Source: ForresterCAPEX OPEX

33%0 10 100 1000

Computing Networking

SecondsSource: Open Compute Project

Network Expenses Deployment Speed

DEVNET-2044


Network Programmability

Physical and Virtual Network Infrastructure

Business Automation System(s)

Controller

DEVNET-2044




Business Automation System(s)

Controller

Open Device Programmability

DEVNET-2044




Open Device Programmability

Programmatic Interfaces

OpenProtocols

Configuration Management

TrafficEngineering

OperationalState

DEVNET-2044


RESTconf NETCONF gRPC

Implementation

Device Features

Interface BGP QoS ACL …

Data Model

Configuration

Standard Device Specific

Operational

Standard Device Specific

Other vendors

DEVNET-2044


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


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


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

https://tools.ietf.org/html/draft-ietf-netconf-restconf-15


SDN ControllerIntegration

ApplicationIntegration

OSS / BSSIntegration

Open SDNController

Inventory / Topology

Configuration Mgmt

Access ControlScript Automation

DevOps

CustomApplication

Service Provisioning

Fault Mgmt

Configuration Mgmt

Use Cases

DEVNET-2044


Data Model Life Cycle Management

• Standard definition (IETF, ITU, OpenConfig, etc.)

• Compliant with standard, i.e. “Policy”

ietf-diffserv-policy.yangietf-diffserv-classifer.yangietf-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


Transport

High Level Manageability Architecture

Network DeviceApplication

RESTCONF server

NETCONF server

BGP

QoS

VXLANRESTCONF

client

NETCONF client

YANG-based XML/JSON

SSH / TLS

HTTPS

ANY (Java, Python, Perl, PHP)

Manageability Infra

Config DB

YANG-based XMLANY (C, Java,

Python)

DEVNET-2044


Reality Check: What’s Available?• Implementations available in

• IOS XR 6.0• IOS XE 3.17

• Both are in controlled availability

DEVNET-2044


RESTCONF and YANG

DEVNET-2044 15


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


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


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


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


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 requiredDEVNET-2044

https://github.com/YangModels/yang

https://github.com/CiscoDevNet/xe-netconf-yang

https://github.com/CiscoDevNet/xe-netconf-yang


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

https://github.com/mbj4668/pyang

https://github.com/CiscoDevNet/yang-explorer


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


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


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

DEVNET-2044 24


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


CRUD Methods in RESTCONFRESTCONF As compared to NETCONFOPTIONS noneHEAD noneGET <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


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


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

Data

Operations (RPC)

DEVNET-2044


Module my-interfaces { namespace ”com.my-interfaces”;

container interfaces { 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>

Data

YANG Model

URI:/restconf/data/my-interfaces:interfaces

URI:/restconf/data/my-interfaces:interfaces/interface/<some name>

DEVNET-2044


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

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; }}

}

POST /restconf/operations/my-interfaces:flap-interface+ JSON/XML Form Data (including name)Response will have JSON/XML result

GET /restconf/data/my-interfaces:interfacesGET /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


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

Module my-interfaces { namespace "com.my-interfaces"; container 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


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


Configuration Snippets

DEVNET-2044 33


IOS XE (3.17) Configuration Snippetremote-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


IOS XE (3.17) with VRF Configuration Snippetremote-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


IOS XR (6.0) Configuration Snippetinterface 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


Resources

DEVNET-2044 37


ResourcesInterface 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



https://tools.ietf.org/html/rfc6241


http://www.grpc.io/

http://www.grpc.io/

http://www.grpc.io/


https://www.itu.int/oth/T1C02000002

http://www.openconfig.net/data-models


Resources (cont.)• Wojciech’s CL deck ‘A Model-driven Approach to Software Defined Networks

with Yang, NETCONF/RESTCONF’, BRKSDN-1903https://www.ciscolive.com/online/connect/sessionDetail.ww?SESSION_ID=84149&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 Certshttp://blog.getpostman.com/2014/01/28/using-self-signed-certificates-with-postman/

DEVNET-2044

https://www.ciscolive.com/online/connect/sessionDetail.ww?SESSION_ID=84149&tclass=popup

https://www.ciscolive.com/online/connect/sessionDetail.ww?SESSION_ID=84149&tclass=popup

https://github.com/CiscoDevNet/yang-explorer

http://sdntutorials.com/what-is-restconf/

http://blog.getpostman.com/2014/01/28/using-self-signed-certificates-with-postman/

http://blog.getpostman.com/2014/01/28/using-self-signed-certificates-with-postman/


Resources (cont.)• YANG Module Repository (IETF, Open, Vendors)


• Pyang toolhttps://github.com/mbj4668/pyang

DEVNET-2044


https://github.com/mbj4668/pyang


RESTCONF / NETCONFHands On

DEVNET-2044 41


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 herehttp://virl-dev-innovate.cisco.com:8301/

• Recommend to open the link on your Windows workstation in Chrome

DEVNET-2044

http://virl-dev-innovate.cisco.com:8301/

Thank you

© 2016 Cisco and/or its affiliates. All rights reserved. Cisco PublicDEVNET-2044 43


Backup:NETCONF Basics

DEVNET-2044 45


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


NETCONF Overview

Transport

RemoteOperations

ManagementServices

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

ConceptualData Store

Agent(server)

Several data stores:• Running• Startup• Candidate

DEVNET-2044


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


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


NETCONF Operations (contd.)• <lock>, <unlock>

• data stores only available as target as a whole, cannot just lock subtreePartial 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


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


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> <ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"> <address> <ip>2001:DB8::1</ip> <prefix-length>32</prefix-length> </address> <dup-addr-detect-transmits>0</dup-addr-detect-transmits> </ipv6> </interface> </interfaces> </data></rpc-reply>

DEVNET-2044


Edit an interface configurationChange 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> <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"> <address xc:operation=“replace”> <ip>192.0.2.2</ip> <prefix-length>24</prefix-length> </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


Backup: Certificates, Hostnames, and Ciphers

DEVNET-2044 54


REST APIs with TLS: Reality CheckHTTPS / 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


Newer Versions of OpenSSL and SSHNewer 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


OpenSSHNETCONF using SSH as a transport

• In ~/.ssh/config add the following linesHost 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


"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

http://venturebeat.com/2015/12/18/google-will-drop-sha-1-encryption-from-chrome-by-january-1-2017/





"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


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

DEVNET-2044 60


Prepare SystemRESTCONF 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


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


Bad CipherHTTPS showstopperIf 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


Hosts File

DEVNET-2044 64


Hosts entry (cont.)• Open 'cmd.exe' as Administrator

• 'cd \Windows\System32\Drivers'• 'notepad hosts'

• Add this line at bottom (see next slide) '198.18.133.218 ios-xe-mgmt'

DEVNET-2044


Hosts entry (cont.)

This!

DEVNET-2044


Hosts File on Mac OS X or Linux• Edit /etc/hosts• Use Terminal

sudo vi /etc/hosts

DEVNET-2044


Certificate

DEVNET-2044 68


Certificate• It's self signed

• Chrome does not like them

• Here's how to work around it…

• In Chrome, 'View certificate'

clic

k

DEVNET-2044


Certificate (cont.)• Export Certificate to

File• Export as PEM• Save to desktop as

'ios-xe-mgmt.cer'

clic

k

clic

k

DEVNET-2044


Certificate (cont.)• Install Certificate into System

• For 'Current user'

• Place in 'Trusted Root Certification' Store

• The location IS important!

click

1

2

3

DEVNET-2044


Certificates on Mac OS X

Trust

DEVNET-2044


Python and SSL

DEVNET-2044 73


Python and SSL• Python is also picky about certificates

• And TLS versions

DEVNET-2044


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


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 thispip install --use-wheel pyopenssl ndg-httpsclient

• This installs a different / newer OpenSSL library

DEVNET-2044


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 …\lib\site-package\requests\cacert.pem

• Add ios-xe-mgmt.cer (it's PEM encoded!) to cacert.pem• Alternatively, add 'verify=False' to your 'get()' call

DEVNET-2044

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

Technology

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