Hitchhiker’s Guide to

Device APIs
Shelly Cadora, PhD
Principal Engineer, CCIE #16318
Ripped From the Headlines…

3
Apathy Is Not A Good Idea Either

“A feature without
an API is not a
feature. If I can’t
automate it, I
won’t use it.”
Web 2.0 Provider

4
Agenda
• Introduction: What People Want To Automate
• The Network Approach
• Web & App Paradigms
• The Network Approach, Revisited
• Beware of The Leopard

5
Evolving Our Interaction with Network OS
Types of What’s
Why:
Interactions: Evolving:
Bootstrap Manual -> Automated Agility
Configure Static -> Dynamic Scale
Monitoring Generic -> Custom Cost
Distributed ->
Extend Centralized Complexity
6
The Evolution of Device Interaction
Bootstrap Configure Monitor Extend
ONIE
Evolving iPXE Controllers
Push model I2RS
BGP-LS

Plug n Play Openstack onePK

Puppet/Chef
OpenFlow
Netflow
PoAP
REST
Smart JSON RPC SNMP Onbox
Install NETCONF Python
Syslog
Auto Install
CLI EEM
CLI
Traditional CLI
7
How > 70% of Config Management is Done Today
zaphod# conf t Task
Enter configuration commands, one per line. End with CNTL/Z. Oriented

zaphod(config)#
Human
Friendly
“It's the way real men build real networks.”
-- Jayshree Ullal Easy To
Replay

Software Subject To No Common No Error

Unfriendly Change Data Model Reporting No Special
Tools
8
What about SNMP? That’s Software-Friendly…Right?

RFC 3535: SNMP works “reasonably well for device monitoring”

• Typical config: SNMPv2 read-only community strings
• Typical usage: interface statistics queries and traps
• Empirical Observation: SNMP is not used for configuration
Lack of Hard to Requires
Security
Writeable
Concerns Replay / special
MIBs Rollback applications

Google announces intent to disable SNMP for monitoring by 2017

Poor Lack of Proprietary
Scaling Extensibility MIBs
9
The Network Approach:
NETCONF & XML

10
Requirements of Next-Gen Management
Easy to Use

Separates Config and Operational Data

Lots of Tooling

Accessible Format

Error Checking RFC3535

Backup/Restore Capability

Human & Machine Friendly

11
NETCONF is an IETF Config Management Protocol
V 1.0 V 1.1 Extensions Protocol Stack

• RFC 3535 • RFC 6241 – • RFC 5277 Content

Background 1.1 Base Notifications
and NETCONF • RFC 5717
requirements Protocol Partial
• RFC 4741 • RFC 6242 – Locking Operations
1.0 Base NETCONF • RFC 6243
NETCONF over SSH With defaults
Protocol • RFC 6244 Messages
• RFC 4742 NETCONF +
NETCONF YANG
over SSH Architectural Transport
Overview
12
NETCONF Uses a Client-Server Model

• NMS
• Script
• Plugin
• Cut-n-Paste

SSH
Client Connection-Oriented Trustworthy Serve
Authenticated Secure r
Reliable
13
Clients Make Requests Using RPCs

<rpc message-id=“1”>

<rpc-reply message-id=“1”>
Serve
Client r

A simple Remote Procedure Call (RPC) paradigm facilitates communication

between the client and the server (aka the network device).

14
Operations: What Clients Do to Servers
Operation Description
<get-config> Retrieve all or part of specified configuration datastore

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

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

<delete-config> Delete a configuration datastore

<commit> Copy candidate datastore to running datastore

<get> Retrieve running configuration and device state information

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

<close-session> Graceful termination of NETCONF session

<kill-session> Forced termination of NETCONF session 15

NETCONF Data Stores: Target of Operations

<running> <startup> <candidate> <URL>

• Named containers that may hold an entire copy of the configuration

• Not all data stores are supported by all devices
• Running is the only mandatory data store
• Not all data stores are writable
• Check the device’s capabilities
• To make changes to a non-writeable data store, copy from a writable one

• URL is supported by IOS (for config-copy)

16
NETCONF Encodes Everything In XML

eXtensible Markup Language

• XML describes data <?xml version='1.0'
encoding='UTF-8'?>
• <> delimit markup text (tags)
<rpc message-id="1001">
• Machine and human <get-config>
readable <source>
• W3C Recommendation <running/>
• Self-descriptive </source>
</get-config>
</rpc>
17
NETCONF Protocol Stack Summary

Content • Config / Operational Data

Operations • <get>, <get-config>, etc

Messages • <rpc>,<rpc-reply>

Transport • SSH
18
Configuring Network Devices For NETCONF
Configuration Notes
XR (config)#ssh server v2 XR 5.2
(config)#netconf agent tty Requires k9sec and
mgbl packages
(config)#ssh server v2 XR 5.3
(config)#ssh server netconf port 830 NETCONF 1.1
(config)#netconf-yang agent ssh
NXOS (config)#feature ssh Enabled by default
IOS / XE (config)#ip ssh version 2

19
NETCONF References
• Tutorials:
• https://www.youtube.com/watch?v=Vr4kB1_6fLQ
• https://www.youtube.com/watch?v=xoPZO1N-x38

• Tools:
• Ncclient: https://github.com/leopoul/ncclient/
• Confd Netconf-console: http://www.tail-f.com/management-agent/

• References
• RFC 6241 https://tools.ietf.org/html/rfc6241
• RFC 6242 https://tools.ietf.org/html/rfc6242

20
Demo: NETCONF

21
Demo Notes: Router Config

22
Demo: SSH with Router Hello
scadora@ubuntu-sc2:~$ ssh cisco@172.30.8.51 -p 830 -s netconf
The authenticity of host '[172.30.8.51]:830 ([172.30.8.51]:830)' can't be established.
RSA key fingerprint is 98:34:30:2d:ac:ee:e7:b0:6f:de:61:a3:79:0a:ee:fe.
Are you sure you want to continue connecting (yes/no)? yes
Failed to add the host to the list of known hosts (/home/scadora/.ssh/known_hosts).
cisco@172.30.8.51's password:
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring</capability>
<capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.1</capability>
<capability>urn:ietf:params:netconf:capability:confirmed-commit:1.1</capability>
<capability>http://cisco.com/ns/yang/Cisco-IOS-XR-common-acl-datatypes?module=Cisco-IOS-XR-common-acl-
datatypes&amp;revision=2015-11-09</capability>
<capability>http://cisco.com/ns/yang/Cisco-IOS-XR-plat-chas-invmgr-oper?module=Cisco-IOS-XR-plat-chas-invmgr-
oper&amp;revision=2015-01-07</capability>
[output omitted for brevity]

23
Demo: Client Hello And Get-Config
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0”>
<capabilities>
<capability>urn:ietf:params:netconf:base:1.1</capability>
</capabilities>
</hello>
]]>]]>

#325
<?xml version='1.0' encoding='UTF-8'?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1001">
<get-config>
<source>
<running/>
</source>
<filter>
<interface-configurations xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg"/>
</filter>
</get-config>
</rpc>
##
24
Demo: Edit-Config
<?xml version="1.0" encoding="utf-8"?>
<rpc message-id="1004" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<candidate/>
</target>
<config>
<interface-configurations xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg">
<interface-configuration>
<active>act</active>
<interface-name>Loopback0</interface-name>
<description>Configured by Shelly via NETCONF</description>
</interface-configuration>
</interface-configurations>
</config>
</edit-config>
</rpc>
##

#130
<?xml version="1.0" encoding="utf-8"?>
<rpc message-id="1005" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit/>
</rpc>
##
25
Netconf-console
scadora@ubuntu-sc2:~/confd-5.4/bin$ ./netconf-console --user=cisco --password=cisco --
host=172.30.8.51 --port 830 -i

* Enter a NETCONF operation, end with an empty line

<get>
<filter xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-infra-statsd-oper">
<infra-statistics><interfaces><interface>
<latest/>
</interface></interfaces></infra-statistics>
</filter>
</get>

https://developer.cisco.com/site/confD/

26
Demo: Ncclient
scadora@ubuntu-sc2:~/ncclient/examples$ python csr1000v_example.py
172.30.8.188 scadora cisco123

https://github.com/ncclient/ncclient.git

27
The Network Approach:
Data Models & YANG

28
“A towel is about the most massively useful thing an
interstellar hitchhiker can have. Partly it has great practical
value …More importantly, a towel has immense
psychological value…What a strag (non-hitchhiker) will think
is that any man that can hitch the length and breadth of the
Galaxy, rough it, slum it, struggle against terrible odds, win
through and still know where his towel is, is clearly a man to
be reckoned with.”
--Hitchhiker’s Guide to the Galaxy

29
Models Are Useful

30
Source: http://www.foodpyrenees.com/2012/02/28/staying-on-the-outside-lane/
Data Model Requirements for NETCONF

Easily Instantiated as XML ✖ ✖

Easy to Read ✖
Domain Specific ✖ ✖
Extensible ✖
Rich Conditions & Constraints ✖ ✖ ✖
31
YANG: Yet Another Next-Gen (IETF RFC 6020)
Life. Loathe
YANG Model NETCONF XML it or ignore
it. You can't
like it.

32
 YANG Is A Language
module ietf-interfaces { Self-contained top-level hierarchy of nodes
import ietf-yang-types {
prefix yang;
} Import or define data types
container interfaces {
list interface {
Containers group related nodes
key "name";
leaf name {
Edited type string;
for Lists for sequence of entries
Brevity }
leaf enabled {
type boolean;
default "true"; Leaf nodes for simple data
}
… 33
The Interfaces Data Model in Tree Diagram

34

Source: http://www.ietf.org/rfc/rfc7223.txt
The XML Instantiation
<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”
xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type” >
<interface>
<name>eth0</name>
<type>ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
</interface>
</interfaces>
</data>
</rpc-reply> 35
Where Yang Models Come From

Vendors IETF OpenConfig Other

36
YANG References
• Tutorials
• http://www.yang-central.org/twiki/bin/view/Main/YangTutorials
• https://www.youtube.com/watch?v=33VBb6N4yOY

• Tools
• Pyang (python) https://code.google.com/p/pyang/
• Commercial YANG browsers – MG-Soft, Segue Soft
• http://rob.sh/post/209 (pyangbind)

• References
• RFC 6020 (YANG) : http://tools.ietf.org/html/rfc6020
• RFC 7223 (Interface Model) http://www.ietf.org/rfc/rfc7223.txt
• https://github.com/YangModels/yang/tree/master/experimental/openconfig (OpenConfig)
• https://github.com/YangModels/yang/tree/master/vendor/cisco (Cisco)
37
Demo: YANG

38
<get-schema> from router
ssh cisco@172.30.8.51 -p 830 -s netconf

<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capabilities>

<capability>urn:ietf:params:netconf:base:1.1</capability>
</capabilities>
</hello>
]]>]]>

#286
<?xml version="1.0" encoding="utf-8"?>
<rpc message-id="1002" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-schema xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<identifier>Cisco-IOS-XR-ifmgr-cfg</identifier>
<version>2015-07-30</version>
</get-schema>
</rpc>
##
39
Using Pyang: https://github.com/mbj4668/pyang

40
Yang Explorer: https://github.com/CiscoDevNet/yang-explorer

41
Web and IT Paradigms

42
Hitchhiker’s Guide to the Galaxy

43
REST Follows a Familiar Model
Web Browsing REST API
{"ids":[303776224, 19449911, 607032789,
86544242, 2506725913, 17631389],
"next_cursor":0, "next_cursor_str":"0",
"previous_cursor":0, "previous_cursor_str":"0"}

HTTP GET HTTP GET

HTML JSON/XML

Describes how data Describes data in a

should be displayed to format applications
please human viewer can understand
44
REST is An Architectural Style
REST= REpresentational State Transfer

Proposed by Roy Fielding in 2000

Developed by W3C in parallel with HTTP 1.1

Simple CRUD using HTTP

Stateless client-server model

Uses URIs to identify resources of interest

45
This is a RESTful API. Try It Yourself!
https://api.wheretheiss.at/v1/satellites/25544

JavaScript Object Notation (JSON)

• Language independent data format
• Light-weight, open standard, human readable
• Compact alternative to XML
• RFC 4627
46
There Are LOTS of RESTful APIs

47
Why Does This Matter for Networking?

Human Software
Readable Friendly

Large Client Libraries

Developer in Many
Base Languages
48
REST: It’s Not Just for Web Services

https://developer.cisco.com/

49
REST: Coming Soon to a Device Near You?

CSR1kV in XE 3.10, ASR1K in XE

3.14.0S

ASA 5500-X and ASAv in Winter-2014

http://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#62624

Primarily for Configuration

• DNS, NTP, Interface, Routing, ACL, NAT

Some Statistics Available

50
JSON-RPC: Like REST but Different

51
Alike: Both Send/Receive JSON
REST (CSR 1000v) JSON-RPC (N9K NX-API)

52
Different: Resources (URIs)
REST: Many Resources JSON-RPC: Few Resources

• https://172.6.1.118/api/v1… • https://10.10.10.8/ins
…/global/banner
…/global/hostname
…/global/reload
…/interfaces/…
…/routing-svc/…
…/nat-svc/…
…/acl/…
… CSR1kV N9K
53
Different: Methods
REST: Standard HTTP Methods JSON-RPC: POST + body method

• GET: Retrieve/List
• PUT: Replace
• POST: Create New Entry
• DELETE: Delete

54
JSON-RPC Details
• A very simple remote procedure call protocol encoded in JSON
• http://www.jsonrpc.org/specification

JSON RPC Request Properties JSON RPC Response Properties

• method – (string) name of the method to • result - data returned by the invoked
be invoked. method.
• params – (array) objects to be passed • error - specified Error code if there was
as parameters to the defined method. an error invoking the method, otherwise
• Id – (any type) used to match the null.
response with request • id - id of the corresponding request.

55
NX-API: JSON-RPC (and XML-RPC)

Nexus 3000, 5000, 6000,

7000, 9000

Extension of CLI over

HTTPs
• Show, config, Linux Bash

56
Demo: REST

57
REST: Postman with CSR1000v

58
The Network Responds:
RESTCONF

59
RESTCONF: Best of Both Worlds?
“the simplicity of the HTTP protocol with the predictability
NETCONF/YANG and automation potential of a schema-driven API”

– SSH
NETCONF REST
– XML
YANG
+ JSON JSON
+ HTTP(S) HTTP

RESTCONF

60
RESTCONF is Not A Replacement for NETCONF
• Enables Web Applications to
access configuration and
operational data
• A simplified transaction model
• Data can be XML or JSON
NETCONF Operations Not
• Operations include: DELETE, Supported By RESTCONF
PATCH, POST, PUT, GET • Config locking
• Candidate config
• Startup config
• Validate
• Confirmed commit
61
Demo: RESTCONF

62
It’s Still Early Days for RESTCONF
HTTP REQUEST:
GET /restconf/operational/opendaylight-inventory:nodes/node/pe1
HTTP/1.1
RESTCONF Host: norcal-00:8181
Accept: application/xml

NETCONF
http://datatracker.ietf.org/doc/draft-
ietf-netconf-restconf/

63
RESTCONF with Postman

64
65
Beware of the Leopard

66
“But the plans were on display…”
Arthur “On display? I eventually had to go down to the cellar to find
them.”
Mr. Prosser “That’s the display department.”
Arthur “With a flashlight.”
Mr. Prosser “Ah, well, the lights had probably gone.”
Arthur “So had the stairs.”
Mr. Prosser “But look, you found the notice, didn’t you?”
Arthur “Yes, yes I did. It was on display in the bottom of a locked filing
cabinet stuck in a disused lavatory with a sign on the door saying
‘Beware of the Leopard.’”

67
Some Emerging Trends

Monitoring Push Pull

Encoding XML/JSON GPB, …

Transport SSH/HTTP HTTP/2, gRPC

68
Problems With Network Monitoring

Where Data Is Created Where Data Is Useful

SNMP

syslog
sensing &
measurement
storage &
CLI analysis

69
A New Approach

Where Data Is Created Where Data Is Useful

As much data, as fast as

sensing & possible
measurement
storage &
analysis

70
Initial Goal: Streaming Telemetry

SNMP

• Enable a push model

• Make data simple to use
71
 Ultra-high level picture
Instruction on:
• What data to collect
• With what cadence
• And send to where

Receiving
Router
unit

72
 Ultra-high level picture
Instruction on:
• What data to collect
• With what cadence
• And send to where

Table 2 Table 1 Receiving

Router Table 3
unit

73
 Ultra-high level picture
“I am the interface counters table”
Interface ifInErrors ifOutErrors ifHCOutOctets …
Instruction on: HundredGigabitEthernet 0/1/0/2 10 0 123456789 …
• What data to collect
Bundle-Ether 42 3 0 234567890 …
• With what cadence
• And send to where … … … … …

Table 2 Table 1 Receiving

Router Table 3
unit

74
Streaming Telemetry Sample Config
config t
telemetry XR
6.0
encoder json
policy group MyPolicyGroup
policy MyTelemetryPolicy
destination ipv4 172.30.8.7 port 2102
destination ipv6 fd01:23:6::1 port 2104
policy group OtherGroup
policy OtherPolicy
destination ipv6 fd01:2345:6789:0001::1 port 5555

75
 Remote
Management
Data Plane: Encoder Output Station

{
JSON over TCP GPB over UDP
message TelemetryHeader {
”RootOper": { optional uint32 encoding = 1
”Interfaces": {
"GigabitEthernet0/0/0/0": { optional string policy_name = 2;
"InterfaceStatistics": { optional string version = 3;
"PacketsReceived": 0, optional string identifier = 4;
"BytesReceived": 0,
"MulticastPacketsReceived": 0, optional uint64 start_time = 5;
// [similar stats elided ], optional uint64 end_time = 6;
"SecondsSincePacketSent": 0 }
} repeated TelemetryTable tables = 7;
"GigabitEthernet0/0/0/1": { }
"PacketsReceived": 0,
// [ ... ] message TelemetryTable {
} optional string policy_path = 1;
// [ ... more interfaces ] repeated bytes row = 2;
} }
}
}
} 76
 GPB: Google-Style Encoding
Google Protocol Buffers (GPB)
Design Goals Non-Goals

• Simplicity • Human-Readable
• Performance • Self-Describing
Call them • Forward/Backward • Text-based
“protobufs” Compatibility
for short
“Protocol buffers are Google's language-neutral, platform-neutral,
extensible mechanism for serializing structured data – think XML,
but smaller, faster, and simpler.”
77
Some Consumption Models
Impala

Kibana Hadoop

ODL ElasticSearch Kafka

BYO Proprietary
Black Output Codec or OS-
Box Logstash based
S ST Input Codec S
S S
T T

Custom Open Source, Customizable Commercial Stack 78

Transport: Beyond SSH & HTTPS

HTTP/2
• Replacement for HTTP
• Optimized for high performance.
• Supports bidirectional streaming, flow control, header compression, multiplexing.
• http://www.ietf.org/id/draft-voit-restconf-yang-push-00.txt
gRPC
• an open source RPC framework on top of HTTP/2
• adds application-layer flow-control, load-balancing, call-cancelation.
• Encodes requests and responses in binary (GPB)
RP/0/RP0/CPU0 (config)#grpc
• http://www.grpc.io/
RP/0/RP0/CPU0 (config-grpc)#
79
The Vision: Any-Any-Any for Monitoring and Config

80
Demo: Streaming
Telemetry

81
 Topology Collectors
.py

10.5.0.1 10.2.0.1
.17 .18 .22
.5 CVG BOS
.13 .29
10.0.0.6 .21 10.7.0.1

10.1.0.1 SFO
RSVP TE TUNNEL WITH AUTO-BW NYC
.26
10.0.0.2
.14 .30

.1 ATL .9 .10 MIA .25

10.3.0.1 .38
10.6.0.1
82
CLIENT 10.0.0.X = Loopback SERVER
Demo: Auto-Bandwidth In Action

83
Resources
• HTTP/2: https://http2.github.io/
• gRPC: http://www.grpc.io/
• Tech Field Days (Cisco, Google, SignalFx on Telemetry)
• http://techfieldday.com/event/dfdr1/
• Telemetry Receivers and Sample Code on Github
• https://github.com/cisco/bigmuddy-network-telemetry-stacks

84
Conclusion

85
 Do Device APIs Matter?

DevOps Controllers

86
The Network Isn’t Isolated Anymore

Cloud Openstack

Chef
Web JSON-RPC
JSONDevOps
Apps REST Ruby Puppet
Python Ansible
Mashups
RESTCONF

Network
XML YANG
NETCONF

87
Configuration Automation Summary
Protocol / Tool Platform Availability Feature Pros Cons
Coverage
XR NX XE IOS ASA

All All Features, All Not Automation Friendly

CLI Platforms
All Industry Standard Evolving Data Models
NETCONF
Growing Tooling Early days
YANG
Task-specific Popular format Limited Platforms
REST (conf)
All Popular format Limited Platforms
JSON-RPC
Task-specific Devops-ready Server optimized
Puppet/Chef
Task-specific Cloud-ready Limited use cases
Openstack 88
For Everything Else, The Answer Is…
• YANG Data Modeling and NETFCONF: Cisco and Industry Developments [BRKNMS-
2032]
• Introduction to YANG Data Models and Their Use in OpenDaylight [DevNet-1083]
• Network programming using Yang service models with Cisco Network Services
Orchestrator [DevNet-1177]
• Introduction to Data Models and Cisco's NextGen Device Level APIs [DevNet-1082]
• Introduction to RESTCONF [DevNet-1081]
• Automating with NX-OS - Let's Get Started! [DevNet-1077]
• Coding 101 : How to Call REST APIs from a REST Client and Python [DevNet-1001]
• Coding 201 : Parsing JSON [DevNet-1004]
• Maximizing Network Programmability and Automation with Open NX-OS [BRKDCT-2025]
• Bringing DevOps to Routing with Evolved XR [DevNet-1089]
• …
89
Call to Action
• Visit the World of Solutions for
• Cisco Campus
• Walk in Labs
• Technical Solution Clinics

• Meet the Engineer

• Lunch and Learn Topics
• DevNet zone related sessions
Complete Your Online Session Evaluation
• Please complete your online session
evaluations after each session.
Complete 4 session evaluations
& the Overall Conference Evaluation
(available from Thursday)
to receive your Cisco Live T-shirt.

• All surveys can be completed via

the Cisco Live Mobile App or the
Communication Stations
Thank you

92
93