Installation Guide - v1.1.10.4 (October 2018)
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
| Minimum | Recommended | |
|---|---|---|
| CPU | 6 Core Intel® Xeon | 12 Core Intel® Xeon |
| Memory | 16 GB | 32 GB |
| Hard Drive | 256 GB SSD | 2 TB SSD |
Prerequisites
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 \
oracle-java8-set-default
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:
JAVA_HOME=”/usr/lib/jvm/java-8-oracle”
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 https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
Add the Docker repository to APT sources:
[user@host:$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu 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 https://github.com/docker/compose/releases/download/1.22.0/docker-compose-$(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"
user@host$:
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 https://github.com/kelseyhightower/confd/releases/download/v0.16.0/confd-0.16.0-linux-amd64 -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
[user@host:$
Clone OpenKilda with the following command, enter In your system password when prompted:
[user@host:/$ sudo git clone https://github.com/telstra/open-kilda.git
[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.
user@host:/opt$
The OpenKilda repository should now be copied to your system, navigate to the folder
user@host:/$ cd open-kilda
user@host:~/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 <sergii.iakovenko@gail.com>
Date: Mon Oct 8 15:52:41 2018 +0300
Merge branch 'release-1.1.10.4'
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 
the following line (at the end of the file):
CMD ["java","-jar","target/openkilda-gui.jar"]
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 http://127.0.0.1:8010/openkilda 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/wait-for-it.sh…" 4 minutes ago Up 4 minutes (healthy) 0.0.0.0:8888->8080/tcp storm-ui
b2469c7c4f3d kilda/storm:latest "/app/wait-for-it.sh…" 5 minutes ago Up 5 minutes (healthy) 0.0.0.0:6700-6714->6700-6714/tcp, 0.0.0.0:8001->8000/tcp storm-supervisor
025029f62a31 kilda/storm:latest "/app/wait-for-it.sh…" 5 minutes ago Up 5 minutes (healthy) 0.0.0.0:3772-3773->3772-3773/tcp, 0.0.0.0:6627->6627/tcp, 0.0.0.0:8000->8000/tcp storm-nimbus
2a48bc12dd7c open-kilda_northbound "java -jar northboun…" 6 minutes ago Up 5 minutes 0.0.0.0:8088->8080/tcp openkilda-northbound
3716d0b0a4f5 kilda/topology-engine:latest "./entrypoint.sh" 6 minutes ago Up 5 minutes topology-engine
4afff4dcd3b2 kilda/opentsdb:latest "/app/wait-for-it.sh…" 6 minutes ago Up 5 minutes 0.0.0.0:4242->4242/tcp opentsdb
0b6d0adba101 kilda/floodlight:latest "java -Dlogback.conf…" 6 minutes ago Up 6 minutes 0.0.0.0:6642->6642/tcp, 0.0.0.0:6653->6653/tcp, 0.0.0.0:6655->6655/tcp, 0.0.0.0:8081->8080/tcp, 0.0.0.0:8180->8080/tcp floodlight
6c6cc6f33f78 kilda/topology-engine-rest:latest "/bin/sh -c /usr/bin…" 6 minutes ago Up 6 minutes 0.0.0.0:80->80/tcp topology-engine-rest
182a5c24ebb0 kilda/kafka:latest "/opt/kafka/bin/run_…" 6 minutes ago Up 6 minutes (healthy) 0.0.0.0:9092->9092/tcp kafka
b28abe4c9317 kilda/hbase:latest "/opt/hbase/bin/star…" 6 minutes ago Up 6 minutes (healthy) 0.0.0.0:8070->8070/tcp, 0.0.0.0:8090->8090/tcp, 0.0.0.0:9070->9070/tcp, 0.0.0.0:9080->9080/tcp, 0.0.0.0:9090->9090/tcp, 0.0.0.0:60000->60000/tcp, 0.0.0.0:60010->60010/tcp, 0.0.0.0:60020->60020/tcp, 0.0.0.0:60030->60030/tcp hbase
63c5e60bdde8 open-kilda_mininet "/app/entry-point.sh" 7 minutes ago Up 7 minutes 0.0.0.0:17191->17191/tcp, 0.0.0.0:38080->38080/tcp mininet
ad60b0f7a43c kibana:5.6.5 "/docker-entrypoint.…" 7 minutes ago Up 7 minutes 0.0.0.0:5601->5601/tcp kibana
e4fbdc9cf32e kilda/logstash:latest "/docker-entrypoint.…" 7 minutes ago Up 7 minutes 5000-5005/tcp, 0.0.0.0:9600->9600/tcp logstash
1d3e56b2215f kilda/neo4j:latest "/bin/sh -c /app/ini…" 7 minutes ago Up 7 minutes (healthy) 0.0.0.0:7474->7474/tcp, 0.0.0.0:7687->7687/tcp, 0.0.0.0:16010-16011->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, 0.0.0.0:2181->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.