Cisco Logo


Security

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 routersCisco IOS-XE SoftwareCisco 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.

onepk1

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.

onepk2

Optional Service Sets

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

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 status
Status: enabled
Version: 0.6.0
Transport: socket; Status: running; Port: 15001
Transport: tls; Status: disabled
Transport: 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 all
ID        Username State             Timeout Connect Time                 Application Name
6778      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 all
Session ID: 9005
Application Name: SCHIFFPK
API In: 1 API Out: 1
Bytes In: 134 Bytes Out: 370
Vty Count: 0
Memory Allocated: 1224 bytes Memory Freed: 0 Memory Held: 18304
CPU 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 statistics
Total number of sessions 52 
Active sessions 1
Local session disconnect 2
Remote session disconnect 0
Total errors 11
Authentication errors 11
Duplicate application name error 0
Memory errors 0
Internal 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.

In an effort to keep conversations fresh, Cisco Blogs closes comments after 90 days. Please visit the Cisco Blogs hub page for the latest content.

3 Comments.


  1. “You’ll need an ISR G2 router”

    so in this Controlled Availability phase it support only ISR G2 series routers? No Catalysts for example?

    thanks

       0 likes

    • Mike Schiffman
      Mike Schiffman

      Today, onePK is only available on the ISR G2 only but we’ll have more platforms in the next year, so stay tuned!

         0 likes

  2. good stuff Mike, looking forward to posts 2 & 3.

       0 likes

  1. Return to Countries/Regions
  2. Return to Home
  1. All Security
  2. Return to Home