Installation Guide - v1.1.10.4 (October 2018)

Last modified by Kevin Austin on 2018/10/16 18:07

About OpenKilda

OpenKilda was designed to solve the problem of implementing a distributed SDN controller with a data-plane that spans the globe. Unique challenges arrive when you implement a control plane that traverses throughout the globe. OpenKilda solves the problem of control plane latency, scalable SDN control & data-plane and end-to-end flow telemetry for a Global network.

OpenKilda is a project of Telstra Open Source and is available for use under the Apache License 2.0 .

About this guide

This install guide was written using an Ubuntu 18.04.1 install on a 6 core server with 20GB of RAM allocated. For this guide we use the /home/kilda folder that was used to pull the OpenKilda repository, which may differ from your own install. This guide covers the installation of OpenKilda Release v1.1.10.4 (October 2018).

Recommended Hardware Configuration

CPU6 Core Intel® Xeon12 Core Intel® Xeon
Memory16 GB32 GB
Hard Drive256 GB SSD2 TB SSD


This guide walks through how to install the OpenKilda SDN Controller from a stock Ubuntu environment. Before building OpenKilda several packages need to be downloaded and installed for the controller to build successfully. 

Update the system before starting

Get and install the latest updates for your Ubuntu environment, at the command prompt, type:

[user@host:$ sudo apt update
[user@host:$ sudo apt upgrade

When prompted to continue type Y and hit enter.

Install Java8

Install Java version 8 (remember to hit enter after typing the "\").

[user@host:$ sudo add-apt-repository ppa:webupd8team/java
[user@host:$ sudo apt update

[user@host:$ sudo apt install -y --no-install-recommends \ 
oracle-java8-installer \

Now we need to set the path for java in the /etc/environment file:

[user@host:$ sudo nano /etc/environment

Add the following entry to the bottom of the list and hit control+X, hit “Y” to save and press enter:


Reload the /etc/environment file:

[user@host:$ source /etc/environment

Install Python2

Some of the build steps require Python2. To install python-pip we need to add the universe repository.

user@host:$ sudo apt-get install software-properties-common
user@host:$ sudo apt-add-repository universe
user@host:$ sudo apt-get update

Install python via apt and when prompted enter your password and select Y and hit enter

[user@host:$ sudo apt install python2.7 python-pip
 [sudo] password for user:
0 upgraded, 74 newly installed, 0 to remove and 0 not upgraded.
Need to get 72.5 MB of archives.
After this operation, 232 MB of additional disk space will be used.
Do you want to continue? [Y/n] Y

Install virtualenv for Python2

Some build steps require Python2. If Python3 is default in your system please use virtualenv. Install virtualenv, when prompted type your password and hit Y to continue installing:

[user@host:$ sudo apt install virtualenv
 [sudo] password for user:
After this operation, 4144 kB of additional disk space will be used.
Do you want to continue? [Y/n] Y

Now configure virtualenv to use Python2:

[user@host:$ sudo virtualenv --python=python2 .venv
[sudo] password for user:
[user@host:$ cd .venv
[user@host:$ . bin/activate
(.venv) user@host$:

Install tox

Install tox, it’s used during some of the build scripts

[user@host:$ sudo pip install tox
 (.venv) user@host$:

Install Docker

This lets apt use packages over HTTPS: 

[user@host:$ sudo apt install apt-transport-https ca-certificates curl software-properties-common

Add the GPG key for the official Docker repository to your system:

[user@host:$ curl -fsSL | sudo apt-key add -

Add the Docker repository to APT sources:

[user@host:$ sudo add-apt-repository "deb [arch=amd64] bionic stable"

Next, update the package database with the Docker packages from the newly added repo:

[user@host:$ sudo apt update

Make sure you are about to install from the Docker repo instead of the default Ubuntu repo:

[user@host:$ apt-cache policy docker-ce

Finally, install Docker:

[user@host:$ sudo apt install docker-ce

Setup docker command without using sudo, add your username ${USER} to the docker group:

[user@host:$ sudo usermod –aG docker ${USER}

Apply the new group membership, type in the following:

[user@host:$ su - ${USER}

Install Docker Compose

Run this command to download the latest version of Docker Compose:

[user@host:$ sudo curl -L$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

Apply the executable permission to the library:

[user@host:$ sudo chmod +x /usr/local/bin/docker-compose

Test the installation:

[user@host:$ docker-compose -version
docker-compose version 1.22.0, build f46880fe

Install Maven

Install Maven to build Open Kilda.

[user@host:$ sudo apt install maven

Increase Maven RAM limit

Maven needs to have it’s RAM limit raised to at least 1G.

[user@host:$ export MAVEN_OPTS="-Xmx1g -XX:MaxPermSize=128"

Install confd

confd is a tool used for creating config/properties files from templates. To install it, execute the following command:

[user@host:$ sudo wget -O /usr/local/bin/confd

Next set the permissions for confd.

[user@host:$ sudo chmod +x /usr/local/bin/confd

Download the OpenKilda repository from Github

Navigate to the folder that you would like to clone OpenKilda from, I created a folder on the root directory named opt:

[user@host:$ cd home/kilda

Clone OpenKilda with the following command, enter In your system password when prompted:

[user@host:/$ sudo git clone
[sudo] password for user:
Cloning into 'open-kilda'...
remote: Counting objects: 72499, done.
remote: Compressing objects: 100% (313/313), done.
remote: Total 72499 (delta 156), reused 341 (delta 76), pack-reused 71983
Receiving objects: 100% (72499/72499), 201.34 MiB | 13.34 MiB/s, done.
Resolving deltas: 100% (38137/38137), done.

The OpenKilda repository should now be copied to your system, navigate to the folder

user@host:/$ cd open-kilda

Checkout a Tagged Release

For this installation guide we will be building the October 2018 tagged release v1.1.10.4

user@host:~/open-kilda$ sudo git checkout tags/v1.1.10.4

Verify the Tagged Release

Verify that the correct tagged release is set in your build environment.

user@host:~/open-kilda$ git log -1
commit a57a8ea9fa5ff82d903b2057c3377904a7a9ba1b (HEAD, tag: v1.1.10.4, origin/master)
MergeL d849dee38 85e659c61
Author: Sergii Iakovenko <>
Date:    Mon Oct 8 15:52:41 2018 +0300

     Merge branch 'release-'

GUI Startup Fix (Issue#1437)

Note: There is a known issue in OpenKilda v1.1.10.4 where the GUI does not startup, for more details reference Issue #1437 on Github. This step is temporary and a fix has been implemented in later OpenKilda releases. The following steps are a workaround to get the GUI to start in v1.1.10.4.

From the ~/open-kilda directory navigate to the /services/src/openkilda-gui directory.

user@host:~/open-kilda$ cd /services/src/openkilda-gui

Open the Dockerfile in nano to edit

user@host:~open-kilda/services/src/openkilda-gui$ sudo nano Dockerfile

In nano, delete delete the following line (at the end of the file):

CMD ["java","-jar","target/openkilda-gui.jar"]

Add add the following two lines in it's place:

WORKDIR /app/target
CMD ["java","-jar","openkilda-gui.jar"]

Save and close nano by hitting control+x, press "Y" to save and enter to close the file. Navigate back to the base open-kilda directory to continue the installation:

user@host:~open-kilda/services/src/openkilda-gui$ cd ~/open-kilda

The GUI will now start automatically when you startup OpenKilda. To access the GUI, open a browser and go to after completing the installation guide.

Build OpenKilda Controller

From the base of the open-kilda directory, run the make build-latest command (the build process does take some time, so go grab some coffee).

user@host:~/open-kilda$ sudo make build-latest
[sudo] password for user: 

Run OpenKilda

After OpenKilda is built, from the run docker-compose up from the base OpenKilda directory ~/open-kilda . The first time OpenKilda is run, it will download the necessary container images.

user@host:~/open-kilda$ sudo docker-compose up

Verifying services are up

Once you type in the docker-compose up command and OpenKilda starts, OpenKilda will be running in the foregraound, to verify services have started correctly, open another console or ssh session into OpenKilda. Enter in the docker ps command and it will print out all of the containers:

user@host: $ docker ps
CONTAINER ID        IMAGE                               COMMAND                  CREATED             STATUS                   PORTS                                                                                                                                                                                                                            NAMES
5f193d5f3640        kilda/wfm:latest                    "/app/deploy_topos_a…"   4 minutes ago       Up 4 minutes                                                                                                                                                                                                                                              wfm
5aebd7f1350a        kilda/storm:latest                  "/app/…"   4 minutes ago       Up 4 minutes (healthy)>8080/tcp                                                                                                                                                                                                           storm-ui
b2469c7c4f3d        kilda/storm:latest                  "/app/…"   5 minutes ago       Up 5 minutes (healthy)>6700-6714/tcp,>8000/tcp                                                                                                                                                                         storm-supervisor
025029f62a31        kilda/storm:latest                  "/app/…"   5 minutes ago       Up 5 minutes (healthy)>3772-3773/tcp,>6627/tcp,>8000/tcp                                                                                                                                                 storm-nimbus
2a48bc12dd7c        open-kilda_northbound               "java -jar northboun…"   6 minutes ago       Up 5 minutes   >8080/tcp                                                                                                                                                                                                           openkilda-northbound
3716d0b0a4f5        kilda/topology-engine:latest        "./"        6 minutes ago       Up 5 minutes                                                                                                                                                                                                                                              topology-engine
4afff4dcd3b2        kilda/opentsdb:latest               "/app/…"   6 minutes ago       Up 5 minutes   >4242/tcp                                                                                                                                                                                                           opentsdb
0b6d0adba101        kilda/floodlight:latest             "java -Dlogback.conf…"   6 minutes ago       Up 6 minutes   >6642/tcp,>6653/tcp,>6655/tcp,>8080/tcp,>8080/tcp                                                                                                           floodlight
6c6cc6f33f78        kilda/topology-engine-rest:latest   "/bin/sh -c /usr/bin…"   6 minutes ago       Up 6 minutes   >80/tcp                                                                                                                                                                                                               topology-engine-rest
182a5c24ebb0        kilda/kafka:latest                  "/opt/kafka/bin/run_…"   6 minutes ago       Up 6 minutes (healthy)>9092/tcp                                                                                                                                                                                                           kafka
b28abe4c9317        kilda/hbase:latest                  "/opt/hbase/bin/star…"   6 minutes ago       Up 6 minutes (healthy)>8070/tcp,>8090/tcp,>9070/tcp,>9080/tcp,>9090/tcp,>60000/tcp,>60010/tcp,>60020/tcp,>60030/tcp   hbase
63c5e60bdde8        open-kilda_mininet                  "/app/"    7 minutes ago       Up 7 minutes   >17191/tcp,>38080/tcp                                                                                                                                                                               mininet
ad60b0f7a43c        kibana:5.6.5                        "/docker-entrypoint.…"   7 minutes ago       Up 7 minutes   >5601/tcp                                                                                                                                                                                                           kibana
e4fbdc9cf32e        kilda/logstash:latest               "/docker-entrypoint.…"   7 minutes ago       Up 7 minutes             5000-5005/tcp,>9600/tcp                                                                                                                                                                                            logstash
1d3e56b2215f        kilda/neo4j:latest                  "/bin/sh -c /app/ini…"   7 minutes ago       Up 7 minutes (healthy)>7474/tcp,>7687/tcp,>16010-16011/tcp                                                                                                                                             neo4j
0865bb0439b8        elasticsearch:5.6.5                 "/docker-entrypoint.…"   7 minutes ago       Up 7 minutes             9200/tcp, 9300/tcp                                                                                                                                                                                                               elasticsearch
1fcad411a84d        kilda/zookeeper:latest              "/opt/zookeeper/bin/…"   7 minutes ago       Up 7 minutes (healthy)   2888/tcp,>2181/tcp, 3888/tcp                                                                                                                                                                                       zookeeper

Adding the Kibana Dashboards

OpenKilda includes Kibana which visualizes some of the network operations and health of the OpenKilda platform. Once the dashboards are added, you can view them in a browser at: 127:0.0.1:5601

Navigate to the elk-dashboards directory:

user@host:~/open-kilda$ cd ~/open-kilda/tools/elk-dashboards/

Run the following command:

user@host:~/open-kilda$ make all

Stopping OpenKilda

To stop OpenKilda use docker-compose from the /opt/openkilda directory:

user@host:~/open-kilda$ docker-compose down

Setting up a tunnel to access localhost remotely

If you are remotely building Kilda, you will need to create a ssh tunnel and point a browser on your local machine to access the localhost on the environment that Kilda is installed on.  

First create the ssh tunnel using a port that isn’t used, for this tutorial we are using port 8123, open a new terminal session and create the tunnel:

$ ssh –D 8123 –f –C –q –N user@host

Open firefox and select Firefox in the menu bar and select preferences. Scroll down to “Network Proxy” and click “Settings”.

Select “Manual proxy configuration”. In the SOCKS host field enter “localhost” and Port 8123, finally select the SOCKS v5 option, click OK and now firefox has been configured to use the SSH tunnel we just created.


The tunnel will need to be re-established if the connection is lost.

Created by Kevin Austin on 2018/08/20 01:08
©2018 OpenKilda