Exordium

Cisco's One Platform Kit (onePK) is a fantastic toolkit for building custom applications that interact with your Cisco routers and switches. Using onePK, you can build automation directly into the network and extend all sorts of functionality using Cisco devices. The first in a three-part blog series, this article will introduce onePK to the reader, explain what it is, how it can be useful, and will show how to configure onePK on a router. The second and third installments will walk the reader through a simple security-relevant application using the C API. Important to note is that we'll be covering the 0.6.0 version of onePK features and service sets. At the time of this writing, the toolkit is still in Controlled Availability and as such, is still in active development, and the API could change before it is released into General Availability. However, even in the face of API evolutionism, this article will provide you with a solid jumping-off point for your plunge into the wondrous world of onePK.

OK, Just What is onePK?

OnePK is a Cisco IOS Software feature and a set of programming libraries enabling an application programmer to build powerful applications that tightly integrate and interact with Cisco devices. onePK is available to you via a well-documented and unified API, currently offered in C and Java with Python in active development. It is currently in pre-release and is available only on request. Details on how to obtain onePK are provided below.

onePK Lexicon

Before we go any further, let's get on the same page and go through some onePK-specific terminology.

Application
The onePK application is what is developed using the onePK API. This can be built by you, the intrepid programmer, or by a third party such as Cisco. It can live in one of three of places depending on your deployment model (see below).

Network Element
The network element is the platform that hosts the onePK network service provider that provides services to one or more onePK applications. For example, Cisco IOS routers, Cisco IOS-XE Software, Cisco IOS-XR Software, and Cisco NX-OS Software are all onePK-capable platforms.

Session
The communication between a onePK application and the network element(s) is managed using the concept of a session. A session is established from a onePK application to a network element by designating the IP address or hostname of that network element. Also required during session establishment is application authentication, which is done via a valid username and password (or a certificate). Once a session is successfully established, it will be referenced through a special context variable referred to as a session handle.

Service Sets
onePK compartmentalizes different types of functionality into buckets called service sets. For example, the session establishment and authorization functionality is contained within the Element Service Set. Service sets are discussed in more detail below.

Deployment Model
A onePK application can be deployed in one of three ways, as shown below.

• Process Hosting: The application is hosted in a Linux environment on the network element itself. Isolation between the onePK applications and the network processes is provided by Linux Containers or, on some some platforms, full KVM/QEMU.
• Blade Hosting: The application is hosted on a dedicated hardware blade inside the same chassis as the network element.
• End-node Hosting: The application is hosted on end-user commodity hardware ranging from powerful server platforms to compact embedded or mobile devices.

While onePK code is designed to be portable across all three deployment models, the example below assumes the end-node deployment model.

Service Sets

The Base Service Sets provide the base level of functionality for onePK applications, while the optional service set provides additional functionality.

• DataPath Service Set: Provides a capability for the application to hook into the packet flow through a Cisco switch or router and extract packets. These packets may be either copied or punted (diverted) from the data path to the application. The key difference is that when a packet is punted, it does not continue to its destination until the application returns it. On many platforms, packets are sent to and from the network element and application via a specially configured GRE tunnel.
• Policy Service Set: Provides an interface to configure Access Control Lists (ACLs), Access Control Engines (ACEs), Quality of Service (QoS) policies, and interesting traffic to punt/copy to the Data Path Service Set.
• Routing Service Set: Provides an interface for the application to access the Routing Information Base (RIB) of the network element. Insertions, deletions and change notifications are all supported.
• Element Service Set: Provides the core device model for the system. The application connects to the network element and session is managed.
• Discovery Service Set: Provides a mechanism for an application to discover network topology and remote or local network elements providing onePK services.
• Configuration Management Service Set: Provides a capacity to persist API changes to the running configuration, as well as trigger configuration writes to NVRAM.
• Event Service Set: provides a callbacks infrastructure to detect when various system events occur.
• Developer Service Set: Provides debug, logging, and API history auditing capabilities.

Optional Service Sets

At the time of this writing, onePK also contains three additional optional service sets:

• Pathtrace Service Set: Provides essentially the same service as Mediatrace, a sort of beefed up version of Traceroute.
• LISP Service Set: Provides an interface into the Locator/ID Separation Protocol (LISP).
• VTY Service Set: Provides an overlay service to the virtual terminal (teletype) service. Using the VTY SS, literal IOS commands can be sent from the application to be executed on the network element with the output returned.

onePK IOS Commands

The follow section introduces the onePK IOS component and demonstrates some of its available functionality.

Enabling onePK on IOS
Before onePK can be used on Cisco IOS Software (assuming you have an IOS image that supports it), it must be configured and enabled. Your main consideration at this point is to decide if you want your onePK application to talk to the network element in cleartext (over TCP port 15001) or encrypted via TLS (over TCP port 15002). For production applications, Cisco always recommends using TLS, but in the following example, we'll just use the cleartext protocol. To configure onePK, you need to be in IOS's Global Configuration Mode and in the "onep" submode:

router>enable router#configure terminal router(config)#onep router(config-onep)#transport socket router(config-onep)#start

Checking in on onePK
You can verify onePK is running with the following command:

router#show onep statusStatus: enabledVersion: 0.6.0Transport: socket; Status: running; Port: 15001Transport: tls; Status: disabledTransport: tipc; Status disabled

We see the 0.6.0 version of onePK is enabled using cleartext sockets over TCP/15001. We should also note that Transparent Inter-Process Communication (TIPC) is a protocol that facilitates quick and reliable communication amongst applications in a clustered environment. It can be considered a "local" transport and can be used on Cisco IOS-XE Software and Cisco NX-OS Software for container-to-OS communications, but not for regular Cisco IOS Software.

You can get information about connected applications with the following command:

router#show onep session allID        Username State             Timeout Connect Time                 Application Name6778      user1    Connected         0       Thu May 23 11:45:36.435      SCHIFFPK

To get specific information on all currently connected applications:

router#show onep statistics session allSession ID: 9005Application Name: SCHIFFPKAPI In: 1 API Out: 1Bytes In: 134 Bytes Out: 370Vty Count: 0Memory Allocated: 1224 bytes Memory Freed: 0 Memory Held: 18304CPU Utilization for five seconds: 0.0 % one minute: 0.0 % five minutes: 0.0 %

You can also query onePK for overall statistics:

router#show onep statisticsTotal number of sessions 52 Active sessions 1Local session disconnect 2Remote session disconnect 0Total errors 11Authentication errors 11Duplicate application name error 0Memory errors 0Internal errors 0

The Network Admin is still King
Finally, it's good to know that the network admin still has sovereign control and can kill any onePK session (or all of `em):

router#onep stop session all

Cool, I'm Hooked, How Can I Get onePK?

If you're interested in throwing your hat in the ring and acquiring onePK, visit the onePK developer page and sign up. You'll need an ISR G2 router, and because onePK is currently under Controlled Availability, a justifiable use case of why you want to work with it.

Conclusion

In this article you received a shotgun introduction to Cisco's onePK toolkit. We learned about the service sets it provides and how to configure it on a router. In the next installment in this series, you will learn the onePK equivalent of Hello World as we begin to explore the C API.