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.
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.
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.
While onePK code is designed to be portable across all three deployment models, the example below assumes the end-node deployment model.
The Base Service Sets provide the base level of functionality for onePK applications, while the optional service set provides additional functionality.
Optional Service Sets
At the time of this writing, onePK also contains three additional optional service sets:
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
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.
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.