onePK FAQ


Introduction

 

A FAQ is, by its nature, a living document based on feedback from the community. You ask questions, we create a FAQ entry. So, please ask questions in the onePK community, or by responding to this post, and we will do our best to fill out the FAQ to help you.


Many thanks.


The onePK Team.


Basic Questions


What is Cisco onePK?


One Platform Kit (onePK) is a software development toolkit that enables software developers to access, extend or customize the software functionality provided by Cisco routers and switches, enabled by API Libraries in C, Java and Python,. With onePK users can create advanced applications and services for their networking needs.


The name plays off the acronym “SDK” (Software Development Kit), the Cisco Open Network Environment (ONE), and the key concept that there is one API set for all major platforms: IOS, IOS-XR, IOS-XE, NX-OS platforms.


What does onePK consist of?


The core of onePK is a set of API Libraries that allow for easier access to monitor and control your network. These API libraries are currently available in C, Java, and Python with REST coming soon.  The libraries, tutorials, example applications and network simulation tools in onePK include what you need to get up and running to build, automate, extend and improve applications or services using the features available on Cisco platforms.


  • Current API Libraries include: Policy, Routing Protocols, Data Path, Discovery, Element, and Utility to start.
  • Future extensions offered include: Diagnostics, Identity and more.
  • Developer Support: onePK will be supported via a developer community along with training and tools.

 

When is onePK Available?


The platforms on which onePK is generally available are:


  • ISR G2, from IOS 15.4(2)T
  • ASR1K, ISR4400, CSR1KV from IOS-XE 3.12S
  • ASR9K, from IOS-XR 5.2.0

 

The Software Development Kit (SDK) portion of onePK is available for download on Cisco Developer Network - http://developer.cisco.com/web/onepk.

 

What are the most common use cases for onePK?


Use cases for onePK that we have seen thus far can be categorized into different areas, as shown below. This is not a formal or exhaustive analysis, but rather an indication of what onePK has been used for thus far. 


  • DevOps Integration
  • Custom Routing and Traffic Steering
  • Custom Traffic Analytics
  • Network Automation
  • Network Health Monitoring
  • Policy Control
  • Security
  • Threat Mitigation
  • Data Center Orchestration
  • NMS/OSS Integration.


Who is using onePK today?


There are hundreds of customers, service providers and many ISVs using onePK today.  Examples of specific applications that are being developed include:


  • A configuration and verification tool 
  • A Topology mapping and device location mapping monitor
  • A path trace network monitoring application
  • Programming application routes based on utilization/latency/cost
  • Custom encryption of selected traffic
  • Deployment of Puppet and Chef agents for provisioning and monitoring
  • Traffic Optimisation
  • Ad Hoc wireless mobile network management
  • Traffic pattern anomaly detection
  • Subscriber policy control
  • Deterministic latency measurement
  • Dynamic VoIP configuration
  • Application based routing control


What is the difference between Software Defined Networking (SDN) and onePK.  Is onePK SDN?


SDN is a new approach to designing, building and operating networks. SDN implies a logical control plane that is decoupled from the data plane and is logically centralized in the form of a controller.  Communication between the controller system and the network device is facilitated by a standard protocol such as OpenFlow or any number of possible agents. The controller system can consist of multiple, domain specific, clustered controllers. An SDN architecture usually involves APIs that allow customers and developers control the underlying network. These APIs may be standards-based, or they may be vendor-specific, such as onePK.


The capabilities of onePK may be used to facilitate the construction of an SDN based system.   For example, onePK can be used to implement OpenFlow agents, or used by the Cisco eXtensible Network Controller or the OpenDaylight controller, all of which represent typical elements of the “traditional” SDN architecture.


What is the roadmap for onePK, what sorts of features can we expect in the future?


In addition to proliferating platform support, you will see a growing number of API “Service Sets”.  These new service sets will give developers access to advanced features and components beyond that of today’s base service sets.  In addition to new services the onePK SDK will also add new languages and tools over time.


Most importantly, as third-party developers bring their innovative new applications to market, you will also see a growing set of applications available.


Is there an onePK plugin for OpenDaylight?


An onePK based plugin for the OpenDaylight MD-SAL is under development.


Who would use onePK?


Anyone can use onePK, whether they see themselves as developers, operators, engineers or anyone else who wants to optimize their network infrastructure, and integrate that with other systems. With onePK anyone can customize, extend or automate functionalities of Cisco routers or switches.

What languages does onePK support?


Today, onePK supports C, Java and Python with additional agents for REST coming in the future. Of course, anyone can use onePK to create an agent that exposes their REST interface of choice, or, indeed, any other management interface that they want their network to support, as a "plugin".

How are my applications hosted?


With onePK your application can be hosted on a Cisco switch or router, called “process” hosting, on services blades, e.g. UCS-E on an ISRG2, within the switch or router, called “blade hosting”, or on a separate server, known as “end-point” hosting. Applications use a secure communications channel to communicate with the onePK infrastructure in the Network Operating Systems (NOS).

Will all hosting models be supported on all platforms?


Support for hosting models will vary based on the hardware configuration, operating system, application type (Cisco, customer, 3rd party), software release and program phase.

Can I program data plane operations?


Yes. The onePK service sets offer functions to divert, copy and inject packets, and set policies. See more on that below.

How does building applications or adding new services to your network with onePK compare with scripting using the CLI or other interfaces?


Scripting, using the CLI or other management interfaces, is most often used for simple network automation tasks oriented toward one specific device. The same developers can also use onePK to address the same uses cases, but with much greater ease and, crucially, without being subject to CLI changes that break scripts. 


Security


How do I prevent unauthorized applications from accessing onePK?


There are many layers of security that prevent unauthorized access:


  1. An administrator must explicitly enable and configure onePK connectivity in the network element configuration before applications can access the API infrastructure in the NOS.
  2. Applications must authenticate whenever they connect to a router or switch, and the user identity must have the appropriate authorization level. 
  3. Communication between the application and the device NOS is encrypted.
  4. Only signed applications can be deployed in process hosting models. Application signing will be provided through different mechanisms depending upon where and how the authorized application is hosted.


How can I be sure that my application will not disrupt router or switch functionality?


While providing a rich set of functionality, the API has been designed using best practices to reduce the likelihood of an error that would disrupt system operation. This does not remove the need for appropriate quality assurance of application code and a risk assessment of any new operational models. Additionally:


  1. The network administrator can configure the allowable resource consumption for applications in the process-hosted model.
  2. The network administrator can terminate any application via CLI.
  3. For applications deployed in the process-hosted mode or on blades, a container infrastructure is used to constrain application operation, enhance security and protect system resources.
  4. Code isolation and strong typing of the client libraries ensure the integrity of the NOS.


Authentication


All onePK applications must authenticate to connect to a network element. A simple way to do that, suitable for development and test purposes, is this configuration:


username cisco privilege 15 password 0 cisco


For production purposes, it is recommended that an external authentication source be configured.


How do I Configure TLS Connections?


The basic configuration for configuring a TLS connection for onePK is:


onep

transport type tls disable-remotecert-validation

  start


Note that "tls" is the only option here. All connections must be encrypted as the authentication credentials are passed over that connection. By default, this configuration creates a "self-signed" certificate used for encryption, which can be used in conjunction with the "pinning" features of the presentation layer (see below).


What is "Pinning"?


Pinning is a mechanism used by onePK when establishing a TLS connection to bind a host to a hash generated from a certificate provided by the host when the TLS connection is being negotiated. It is logically the same mechanism as used by SSH when populating the know_hosts file.


When establishing a connection in onePK, a "pinning handler" can be provided as illustrated in the Python code below.

 

class PinningHandler(tlspinning.TLSUnverifiedElementHandler):

    def handle_verify(self, host, hash_type, fingerprint, changed):

        return tlspinning.DecisionType.ACCEPT_ONCE

...

 

self.handler                         = PinningHandler()            

self.config.set_tls_pinning(None, self.handler)

  self.networkApplication              = NetworkApplication.get_instance()

  self.network_element = NetworkElement(ip_address, self.application_name)    

try:

   self.network_element.connect(username, password, self.config)

except:

...


The certificate used for pinning can be automatically generated by using this form of configuration for TLS:

 

transport type tls disable-remotecert-validation

 

OpenFlow and onePK


What is OpenFlow?


The OpenFlow specification is an open standard that enables researchers to run experimental protocols in the campus networks we use every day. OpenFlow is developed, specified and sponsored by the Open Networking Forum (ONF). OpenFlow is added as a feature to Ethernet switches, routers and wireless access points and provides a standardized line protocol between the controller and data networking equipment of a software defined network.


Will Cisco Support OpenFlow?


Yes.  Cisco has OpenFlow 1.0 agents in limited availability for various Catalyst, ASR9K and Nexus Platforms. Cisco will introduce production ready versions of OpenFlow 1.3 for a variety platforms, expanding into general availability. This support will based on “plugins”, which are onePK applications running on a device that use APIs to control the NOS and expose the OpenFlow protocol to controllers. 

 

How does OpenFlow differ from onePK? Do they do basically the same thing?


OpenFlow is an emerging protocol that focuses on forwarding plane operation. whereas onePK is a development kit that allows users to access and optimize the function of Cisco devices. The scope of onePK allows access to information on routing, policy, manageability, provisioning, discovery and a wide variety of device and network functions, in addition to data plane access and programmability.


OpenFlow and onePK as complementary, indeed Cisco’s OpenFlow support is provided via a onePK plugin. Developers working with OpenFlow may be able to benefit from the functionality provided by onePK beyond the scope of the OpenFlow specification.


Technical Questions


Is onePK a replacement for CLI?


The purpose of onePK is to provide capabilities for controlling and managing a Cisco devices that are far easier to use than CLI for automation. Many of the use cases for onePK can also be addressed via CLI, albeit less efficiently, and with exposure to necessary CLI changes. Above and beyond that, onePK also offers capabilities, such as the Data Path service set, that are not available via CLI.


Is onePK a replacement for the Embedded Event Manager (EEM)?


No. Indeed, EEM is a major infrastructure element of the onePK NOS implementation, and the two programming models can be very successfully combined. While both can be used for network automation, EEM and onePK typically enable different sets of users and use cases. Existing EEM scripts can be extended and integrated with onePK applications using the same event model that EEM supports today.

How is the SDK organized?


Functionality is broken down into "Service Sets" which group API calls into similar functions. The following graphic shows how the service sets can be used.

srervice_sets.png

  

What are the "abstraction" and "presentation" layers in onePK?


The onePK system is a "client-server" system where the server side is the network element operating system (NOS), and the client side is your application code using the onePK client libraries. The onePK API is defined in an IDL that is used in conjunction with an "idl compiler" to generate code for the client and server parts of the system. The server side "skeleton" code is the abstraction layer that is implemented on a per NOS basis. The client side "stubs" are the APIs that your application calls, somewhat wrapped in other client side code that makes auto-generated code easier to use.


Installing onePK

 

Where do I get the SDK from?

 

Go to onepkdeveloper.com, and use the "Downloads" link. You will need to select your desired language, and 32/64 bit platform in the case of C, and agree to the End User Licence Agreement (EULA). The download is a zip file that needs to be unzipped and untarred (typically by double clicking in a file browser). Inside the directory that will be created you will find the installer scripts.

 

How do I install the SDK?

 

The SDK installers for C and Java are install.sh shell scripts designed to work on Linux. You can also use the scripts to install the Java SDK on OSX (the C SDK will also install on OSX, but only works on Linux). The Python SDK install is based on a setup.py Python script that will run anywhere where a 2.7 version of Python is already installed. The install location is /opt/cisco/onep.

 

Java, Maven and libthrift


The sample projects in the SDK are based on a Maven project structure. When you install the Java SDK there is a README.maven_jars in SDK install directory. The essence of what that README contains is that you need to run these commands, where <version> is the version number of the SDK you have installed:


mvn install:install-file -Dfile=/opt/cisco/onep/java/sdk-java-<version>/java/lib/libonep-core-rel.jar -DgroupId=com.cisco.onep -DartifactId=libonep-core-rel -Dversion=<version> -Dpackaging=jar

 

mvn install:install-file -Dfile=/opt/cisco/onep/java/sdk-java-<version>java/lib/libthrift-0.6.1.jar -DgroupId=org.apache.thrift -DartifactId=libthrift -Dversion=libthrift-0.6.1-Cisco-1.1.jar -Dpackaging=jar

 

Note that the installed version of the libthrift artefact is a Cisco specific version, as this is a Cisco specific version of the Thrift code with bug fixes. The real libthrift 0.6.1, i.e. the one found in a public Maven repository, will not work

 

Developing onePK Applications

 

(could include where to get SDK, using the development environhttps://developer.cisco.com/site/networking/one/onepk/sdk-and-docs/all-in-one-vm/ment in AiO, using your own development environment, language support and limitations, etc)

 

AiO, Fusion and Developing in OSX

Using the Datapath Service set


How do I enable DPSS on the device?


The Datapath Service Set is not enabled by default on any network element, even when onePK is enabled.  The specific DPSS configuration varies slightly depending on the platform.


IOS:


onep
datapath transport gre sender-id 10 interface GigabitEthernet0/1



IOS-XE:


onep
datapath transport vpathgre sender-id 10 interface GigabitEthernet0/0/1



IOS-XR:


onep
datapath transport vpathudp sender-id 10



In these examples, the sender-id value must be unique across all devices that will be using the Datapath Service Set as well as the ID of the DPSS Main Process.  Typically, the DPSS Main Process will have an ID of 2.  The interface in the above examples should reflect the interface closest to the host running the DPSS applications.


Versioning

Testing  your application

 

(vIOS in the AiO, testing against real hardware)

See https://developer.cisco.com/site/networking/one/sdlc/overview/

Deploying your application