How to create your own NApp: Part 1

Overview

This tutorial covers the basics on how to create your own Network Application (NApp) for Kytos (Kytos).

The average time to go through this is: 15 min

What you will learn

  • How to create a basic NApp;

  • How your NApp communicates with the Kytos Controller;

  • How to install, test, and debug your NApp.

What you will need

Introduction

Most of the Kytos Platform functionalities are delivered by Network Applications, NApps for short. These applications communicate with the controller and with each other through events (KytosEvents), and they can also expose REST endpoints to the world.

If you are developing a basic SDN application, you should be able to do everything inside a NApp, without having to patch the controller core.

Note

If you find something that is limiting your NApp development, don’t shy away from reporting us this issue in our Controller Github page.

The idea of a NApp is to be as atomic as it can be, solving a small and specific problem, in a way that NApps can work together to solve a bigger problem, following the Do one thing, do it well” Unix philosophy.

Moreover, you can use and learn from NApps developed by the Kytos Community that are available at the NApps Server: http://napps.kytos.io.

Caution

Kytos NApps repository is still in beta stage.

Naming your NApp

The first thing that you should do is to create a name for your NApp. We use a namespace based on username and NApp name. Thus, two usernames can use the same NApp name. For instance: john/switchl2 and mary/switchl2 are both valid NApps unique identifiers.

Since your NApp will work as a Python module, its name must follow the same naming rules of Python modules, defined by PEP8, which states that:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability.

Understanding the NApp structure

Here you can see the basic NApp structure. A minimal working NApp must have the files kytos.json and main.py. Don’t worry about creating these folders and files. We provide a tool to generate this structure for you!

<username>
├── __init__.py
└── <napp_name>
    ├── __init__.py
    ├── kytos.json
    ├── main.py
    ├── README.rst
    └── settings.py
  • kytos.json: This file contains your NApp’s metadata. username and name are required. Other attributes are used by the NApps Server to publish and distribute your NApp worldwide.

  • settings.py: Main settings parameters of your NApp (if applicable).

  • main.py: Main source code of your NApp.

  • README.rst: Main description and information about your NApp.

During this tutorial we are going to use only the main.py file (kytos.json content will be automatically created by our tool). If your code is big enough, feel free to split your NApp into multiples files.

Creating your first NApp

Now that we understand the basic structure of a Kytos NApp, let’s start building our own, the hello_world NApp.

You can create the NApp structure manually or use the command line utilities of the kytos-utils project.

Note

Make sure that you had completed your Development Environment setup and the virtual environment is active.

During this first tutorial we are going to create a very dummy application. This application will print a message when loaded and another message when unloaded by the controller.

Let’s create the NApp structure:

$ cd
$ mkdir tutorials
$ cd tutorials
$ kytos napps create

You will be asked a few questions. Answer them according to your needs, they are very basic questions like username and NApp name. For this tutorial purpose, answer tutorial and helloworld, respectively.

The output should be something like this:

--------------------------------------------------------------
Welcome to the bootstrap process of your NApp.
--------------------------------------------------------------
In order to answer both the username and the napp name,
You must follow this naming rules:
 - name starts with a letter
 - name contains only letters, numbers or underscores
 - at least three characters
--------------------------------------------------------------

Please, insert your NApps Server username: tutorial
Please, insert your NApp name: helloworld
Please, insert a brief description for your NApp [optional]: Hello, world!

Congratulations! Your NApp have been bootstrapped!
Now you can go to the directory tutorial/helloworld and begin to code your NApp.
Have fun!

Tip

If you want to change the answers provided in the future, just edit the kytos.json file, and rename the directories if necessary.

Now, we have a bootstrap NApp structure to work with.

During this tutorial, the only file that we need to worry about is the main.py. Open it with your preferred editor and let’s code.

$ cd ~/tutorials
$ gedit tutorial/helloworld/main.py

Note

The code below is a simplified version of yours. You don’t have to delete any other line, just replace the pass statement as described below.

from kytos.core import KytosNApp, log
from napps.tutorial.helloworld import settings


class Main(KytosNApp):

    def setup(self):
        pass

    def execute(self):
        pass

    def shutdown(self):
        pass

In this file, we have an entry point class (Main) to execute our NApp. This class has 3 basic methods: setup, execute and shutdown.

Important

A valid NApp must have the 3 methods above. If you don’t use a method, let the pass statement as its only content.

For this dummy NApp, let’s just print some log messages. To do so, edit the file and replace pass (meaning “do nothing”) by log.info(...) as detailed below:

Attention

In Python, you must be careful about indentation. The log.info(...) lines should start in the same column of pass (4 spaces after the beginning of def ...(self)). Do not use tab to indent.

The setup method is automatically called by the controller when our application is loaded.

Danger

For Python programmers: do not override __init__. A KytosNApp subclass must use the setup method instead.

def setup(self):
    log.info("Hello world! Now, I'm loaded!")

Right after the setup there is the execute method, which we will cover in a deeper way on part 2 of the tutorial.

def execute(self):
    log.info("Hello world! I'm being executed!")

Finally we have the shutdown method. This method is executed when the NApp is unloaded.

def shutdown(self):
    log.info("Bye world!")

After making the suggested modifications, the Main file should look like this (simplified, without comments):

from kytos.core import KytosNApp, log
from napps.tutorial.helloworld import settings


class Main(KytosNApp):

    def setup(self):
        log.info("Hello world! Now, I'm loaded!")

    def execute(self):
        log.info("Hello world! I'm being executed!")

    def shutdown(self):
        log.info("Bye world!")

Running your NApp

In order to install and enable your NApp, you have to first run the Kytos controller. Kytos will then be able to recognize and manage installed/enabled NApps.

Let’s start our controller. When it is executed, it loads all of the previously enabled NApps. At this point, only the kytos/of_core NApp shall be loaded. The Kytos controller runs by default as a daemon. The -f option runs it in foreground. Open another terminal window, make sure to activate your virtual environment and execute:

$ kytosd -f
2017-07-04 14:47:57,429 - INFO [kytos.core.logs] (MainThread) Logging config file "/home/user/test42/etc/kytos/logging.ini" loaded successfully.
2017-07-04 14:47:57,430 - INFO [kytos.core.controller] (MainThread) /home/user/test42/var/run/kytos
2017-07-04 14:47:57,431 - INFO [kytos.core.controller] (MainThread) Starting Kytos - Kytos Controller
2017-07-04 14:47:57,432 - INFO [kytos.core.tcp_server] (TCP server) Kytos listening at 0.0.0.0:6653
2017-07-04 14:47:57,435 - INFO [kytos.core.controller] (RawEvent Handler) Raw Event Handler started
2017-07-04 14:47:57,436 - INFO [kytos.core.controller] (MsgInEvent Handler) Message In Event Handler started
2017-07-04 14:47:57,439 - INFO [kytos.core.controller] (MsgOutEvent Handler) Message Out Event Handler started
2017-07-04 14:47:57,440 - INFO [kytos.core.controller] (AppEvent Handler) App Event Handler started
2017-07-04 14:47:57,441 - INFO [kytos.core.controller] (MainThread) Loading Kytos NApps...
2017-07-04 14:47:57,450 - INFO [kytos.core.napps.napp_dir_listener] (MainThread) NAppDirListener Started...

(...)

kytos $>

You can list all installed and enabled NApps by switching back to the previous terminal and running the command:

$ kytos napps list

Status |          NApp ID          |                      Description
=======+===========================+=======================================================
 [i-]  | kytos/of_core             | OpenFlow Core of Kytos Controller, responsible for ...
 [i-]  | kytos/flow_manager        | Manage switches' flows through a REST API.
 [i-]  | kytos/of_l2ls             | An L2 learning switch application for OpenFlow swit...
 [i-]  | kytos/of_lldp             | Discovers switches and hosts in the network using t...
 [i-]  | kytos/topology            | Keeps track of links between hosts and switches. Re...

Status: (i)nstalled, (e)nabled

For this demo, we don’t need to have any other NApp loaded except the one we just created. So, if your setup has multiple enabled NApps, you can disable them with the command:

$ kytos napps disable <NApp ID>

Yes, we are not running any other NApp for now. We are disabling everything including OpenFlow NApps.

In order to run your NApp, you have to install it first. Again, we are going to use the kytos command line from the kytos-utils project.

$ cd ~/tutorials
$ kytos napps install tutorial/helloworld
INFO  NApp tutorial/helloworld:
INFO    Searching local NApp...
INFO    Found and installed.
INFO    Enabling...
INFO    Enabled.

Note

This will look for the helloworld NApp inside the tutorial/helloworld directory (and also the current one), then install it into your system. This NApp will also be enabled and immediately executed by Kytos.

Testing your NApp

You can check the logs in the Kytos console to verify your NApp working! The log messages are presented as follows:

2017-07-04 14:51:59,931 - INFO [tutorial/helloworld] (Thread-1) Hello world! Now, I'm loaded!
2017-07-04 14:51:59,935 - INFO [root] (helloworld) Running NApp: <Main(helloworld, started 139884979275520)>
2017-07-04 14:51:59,938 - INFO [tutorial/helloworld] (helloworld) Hello world! I'm being executed!

Congratulations! You have created your first Kytos NApp! To see the shutdown message, type quit in the Kytos console:

kytos $> quit
Stopping Kytos daemon... Bye, see you!
(...)
2017-07-04 14:54:28,511 - INFO [kytos.core.controller] (MainThread) Shutting down NApp tutorial/helloworld...
2017-07-04 14:54:28,515 - INFO [tutorial/helloworld] (MainThread) Bye, world!

Well done! What’s Next?

Congratulations for finishing this Kytos Tutorial.

If you want to see other tutorials, click here to go to our Tutorials page.