Show last authors
1 = About OpenKilda =
2
3
4 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.
5
6 OpenKilda is a project of Telstra Open Source and is available for use under the Apache License 2.0 .
7
8 = About this guide =
9
10 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.11.27 (//November 2018//). Please refer to the [[Release Notes Page>>doc:Release Notes.WebHome]] for code changes between this version and the v.1.1.10.23 October build.
11
12 = Recommended Hardware Configuration =
13
14
15 (% class="responsive-table" style="margin-left:auto; margin-right:auto" %)
16 (% class="active" %)|=(% scope="row" %) |=(% style="text-align: center;" %)Minimum|=(% style="text-align: center;" %)Recommended
17 |=CPU|(% style="text-align:center" %)6 Core Intel^^®^^ Xeon|(% style="text-align:center" %)12 Core Intel^^®^^ Xeon
18 |=Memory|(% style="text-align:center" %)16 GB|(% style="text-align:center" %)32 GB
19 |=Hard Drive|(% style="text-align:center" %)256 GB SSD|(% style="text-align:center" %)2 TB SSD
20
21 = Prerequisites =
22
23 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.
24
25 == Update the system before starting ==
26
27 Get and install the latest updates for your Ubuntu environment, at the command prompt, type:
28
29 (% class="box" %)
30 (((
31 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ (% style="color:null; font-family:Courier New,Courier,monospace" %)**sudo apt update**(%%)
32 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt upgrade**
33 )))
34
35 When prompted to continue type Y and hit enter.
36
37
38 == Install Java8 ==
39
40 Install Java version 8 (remember to hit enter after typing the "\").
41
42 (% class="box" %)
43 (((
44 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo add-apt-repository ppa:webupd8team/java**
45 [user@host:$ **sudo apt update**(%%)
46 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$** sudo apt install -y ~-~-no-install-recommends \ **(%%)
47 (% style="font-family:Courier New,Courier,monospace" %)**oracle-java8-installer \
48 oracle-java8-set-default **
49 )))
50
51 Now we need to set the path for java in the /etc/environment file:
52
53 (% class="box" %)
54 (((
55 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo nano /etc/environment**
56 )))
57
58 Add the following entry to the bottom of the list and hit control+X, hit “Y” to save and press enter:
59
60 (% class="box" %)
61 (((
62 (% style="font-family:Courier New,Courier,monospace" %)**JAVA_HOME=”/usr/lib/jvm/java-8-oracle”**(%%)
63 )))
64
65 Reload the /etc/environment file:
66
67 (% class="box" %)
68 (((
69 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **source /etc/environment**
70 )))
71
72 == Install Python2 ==
73
74 Some of the build steps require Python2. To install python-pip we need to add the universe repository.
75
76 (% class="box" %)
77 (((
78 (% style="font-family:Courier New,Courier,monospace" %)user@host:$ **sudo apt-get install software-properties-common**
79 user@host:$ **sudo apt-add-repository universe**
80 user@host:$ **sudo apt-get update**
81 )))
82
83 Install python via apt and when prompted enter your password and select Y and hit enter
84
85 (% class="box" %)
86 (((
87 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt install python2.7 python-pip**
88 [sudo] password for user:
89 0 upgraded, 74 newly installed, 0 to remove and 0 not upgraded.
90 Need to get 72.5 MB of archives.
91 After this operation, 232 MB of additional disk space will be used.
92 Do you want to continue? [Y/n] **Y**
93 )))
94
95 == Install virtualenv for Python2 ==
96
97 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:
98
99 (% class="box" %)
100 (((
101 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt install virtualenv**
102 [sudo] password for user:
103 After this operation, 4144 kB of additional disk space will be used.
104 Do you want to continue? [Y/n] **Y**
105 )))
106
107 Now configure virtualenv to use Python2:
108
109 (% class="box" %)
110 (((
111 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo virtualenv ~-~-python=python2 .venv**
112 [sudo] password for user:
113 [user@host:$ **cd .venv**
114 [user@host:$ **. bin/activate**
115 (.venv) user@host$:
116 )))
117
118 == Install tox ==
119
120 Install tox, it’s used during some of the build scripts
121
122 (% class="box" %)
123 (((
124 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo pip install tox**
125 (.venv) user@host$:
126 )))
127
128 == Install Docker ==
129
130 This lets apt use packages over HTTPS:
131
132 (% class="box" %)
133 (((
134 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt install apt-transport-https ca-certificates curl software-properties-common**
135 )))
136
137 Add the GPG key for the official Docker repository to your system:
138
139 (% class="box" %)
140 (((
141 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **curl -fsSL https:~/~/download.docker.com/linux/ubuntu/gpg | sudo apt-key add -**
142 )))
143
144 Add the Docker repository to APT sources:
145
146 (% class="box" %)
147 (((
148 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo add-apt-repository "deb [arch=amd64] https:~/~/download.docker.com/linux/ubuntu bionic stable"**
149 )))
150
151 Next, update the package database with the Docker packages from the newly added repo:
152
153 (% class="box" %)
154 (((
155 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt update**
156 )))
157
158 Make sure you are about to install from the Docker repo instead of the default Ubuntu repo:
159
160 (% class="box" %)
161 (((
162 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **apt-cache policy docker-ce**
163 )))
164
165 Finally, install Docker:
166
167 (% class="box" %)
168 (((
169 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt install docker-ce**
170 )))
171
172 Setup docker command without using sudo, add your username ${USER} to the docker group:
173
174 (% class="box" %)
175 (((
176 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo usermod –aG docker ${USER}**
177 )))
178
179 Apply the new group membership, type in the following:
180
181 (% class="box" %)
182 (((
183 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **su - ${USER}**
184 )))
185
186 == Install Docker Compose ==
187
188 Run this command to download the latest version of Docker Compose:
189
190 (% class="box" %)
191 (((
192 (% style="font-family:Courier New,Courier,monospace" %)[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**
193 )))
194
195 Apply the executable permission to the library:
196
197 (% class="box" %)
198 (((
199 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo chmod +x /usr/local/bin/docker-compose**
200 )))
201
202 Test the installation:
203
204 (% class="box" %)
205 (((
206 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **docker-compose -version**
207 docker-compose version 1.22.0, build f46880fe
208 )))
209
210 == Install Maven ==
211
212 Install Maven to build Open Kilda.
213
214 (% class="box" %)
215 (((
216 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo apt install maven**
217 )))
218
219 == Increase Maven RAM limit ==
220
221 Maven needs to have it’s RAM limit raised to at least 1G.
222
223 (% class="box" %)
224 (((
225 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **export MAVEN_OPTS="-Xmx1g -XX:MaxPermSize=128"**
226 user@host$:
227 )))
228
229 == Install confd ==
230
231 confd is a tool used for creating config/properties files from templates. To install it, execute the following command:
232
233 (% class="box" %)
234 (((
235 (% style="font-family:Courier New,Courier,monospace" %)[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**
236 )))
237
238 (% class="wikigeneratedid" %)
239 Next set the permissions for confd.
240
241 (% class="box" %)
242 (((
243 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **sudo chmod +x /usr/local/bin/confd**
244 )))
245
246 = Download the OpenKilda repository from Github =
247
248 Navigate to the folder that you would like to clone OpenKilda to. For this guide, we use the home directory.
249
250 (% class="box" %)
251 (((
252 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$ **cd home/kilda**(%%)
253 (% style="font-family:Courier New,Courier,monospace" %)[user@host:$
254 )))
255
256 Clone OpenKilda with the following command, enter In your system password when prompted:
257
258 (% class="box" %)
259 (((
260 (% style="font-family:Courier New,Courier,monospace" %)[user@host:/$ **sudo git clone https:~/~/github.com/telstra/open-kilda.git**
261 [sudo] password for user:
262 Cloning into 'open-kilda'...(%%)
263 (% style="font-family:Courier New,Courier,monospace" %)remote: Enumerating objects: 362, done.(%%)
264 (% style="font-family:Courier New,Courier,monospace" %)remote: Counting objects: 100% (362/362), done.
265 remote: Compressing objects: 100% (231/231), done.
266 remote: Total 90380 (delta 134), reused 248 (delta 80), pack-reused 90018
267 Receiving objects: 100% (90380/90380), 207.16 MiB | 28.44 MiB/s, done.
268 Resolving deltas: 100% (48040/48040), done.
269 user@host:/open-kilda$
270 )))
271
272 The OpenKilda repository should now be copied to your system, navigate to the folder
273
274 (% class="box" %)
275 (((
276 (% style="font-family:Courier New,Courier,monospace" %)user@host:/$ **cd open-kilda**
277 user@host:~~/open-kilda$
278 )))
279
280 == Checkout a Tagged Release ==
281
282 For this installation guide we will be building the November 2018 tagged release v1.1.11.27
283
284 (% class="box" %)
285 (((
286 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **sudo git checkout tags/v1.1.11.27**
287 )))
288
289 == Verify the Tagged Release ==
290
291 (% class="wikigeneratedid" %)
292 Verify that the correct tagged release is set in your build environment.
293
294 (% class="box" %)
295 (((
296 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **git log -1**
297 commit 2579a82e4943b63d7b4cf68ccd70d18c5b958be0 (HEAD, tag: v1.1.11.27, origin/master)
298 MergeL bca3b8f4c 8ad242c2c
299 Author: Dmitry Bogun <nyaka@nyaka.org>
300 Date: Wed Nov 28 10:09:55 2018 +0200
301 \\ Merge branch 'release-1.1.11.27'
302 )))
303
304 = Build OpenKilda Controller =
305
306 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).
307
308 (% class="box" %)
309 (((
310 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **sudo make build-latest**
311 [sudo] password for user:
312 )))
313
314 = Run OpenKilda =
315
316 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.
317
318 (% class="box" %)
319 (((
320 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **sudo docker-compose up**
321 )))
322
323 == Verifying services are up ==
324
325 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:
326
327 (% class="box" %)
328 (((
329 (% style="font-family:Courier New,Courier,monospace" %)user@host: $ **docker ps**(%%)
330 (% style="font-family:Courier New,Courier,monospace; font-size:8px" %)CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
331 5f193d5f3640 kilda/wfm:latest "/app/deploy_topos_a…" 4 minutes ago Up 4 minutes wfm
332 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
333 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
334 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
335 2a48bc12dd7c open-kilda_northbound "java -jar northboun…" 6 minutes ago Up 5 minutes 0.0.0.0:8088->8080/tcp openkilda-northbound
336 3716d0b0a4f5 kilda/topology-engine:latest "./entrypoint.sh" 6 minutes ago Up 5 minutes topology-engine
337 4afff4dcd3b2 kilda/opentsdb:latest "/app/wait-for-it.sh…" 6 minutes ago Up 5 minutes 0.0.0.0:4242->4242/tcp opentsdb
338 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
339 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
340 182a5c24ebb0 kilda/kafka:latest "/opt/kafka/bin/run_…" 6 minutes ago Up 6 minutes (healthy) 0.0.0.0:9092->9092/tcp kafka
341 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
342 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
343 ad60b0f7a43c kibana:5.6.5 "/docker-entrypoint.…" 7 minutes ago Up 7 minutes 0.0.0.0:5601->5601/tcp kibana
344 e4fbdc9cf32e kilda/logstash:latest "/docker-entrypoint.…" 7 minutes ago Up 7 minutes 5000-5005/tcp, 0.0.0.0:9600->9600/tcp logstash
345 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
346 0865bb0439b8 elasticsearch:5.6.5 "/docker-entrypoint.…" 7 minutes ago Up 7 minutes 9200/tcp, 9300/tcp elasticsearch
347 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
348 )))
349
350 = Adding the Kibana Dashboards =
351
352 (% class="wikigeneratedid" %)
353 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
354
355 Navigate to the elk-dashboards directory:
356
357 (% class="box" %)
358 (((
359 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **cd ~~/open-kilda/tools/elk-dashboards/**
360 )))
361
362 Run the following command:
363
364 (% class="box" %)
365 (((
366 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **make all**
367 )))
368
369 = Stopping OpenKilda =
370
371 To stop OpenKilda use docker-compose from the /opt/openkilda directory:
372
373 (% class="box" %)
374 (((
375 (% style="font-family:Courier New,Courier,monospace" %)user@host:~~/open-kilda$ **docker-compose down**
376 )))
377
378 = Setting up a tunnel to access localhost remotely =
379
380 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. 
381
382 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:
383
384 (% class="box" %)
385 (((
386 (% style="font-family:Courier New,Courier,monospace" %)$ **ssh –D 8123 –f –C –q –N user@host**
387 )))
388
389 Open firefox and select Firefox in the menu bar and select preferences. Scroll down to “Network Proxy” and click “Settings”.
390
391 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.
392
393 (% style="text-align:center" %)
394 [[image:firefox_settings.jpeg||height="308" width="400"]]
395
396
397 The tunnel will need to be re-established if the connection is lost.
©2018 OpenKilda