If you have come across Installing and Running ONOS, you'll notice that there are several ways to install and run ONOS. This tutorial takes the aforementioned page, and focuses on showing you one useful deployment method - ONOS packaged from source, and deployed in an Ubuntu VM or on OS X.
By completing this tutorial, you will understand how to:
- Use cell definitions to configure the ONOS build environment to customize the ONOS package
- Configure which modules the ONOS binary loads by default
- Install ONOS on a VM using the
- Access the CLI and monitor ONOS remotely
Commands at the shell of the VM begin with
And commands at the build machine shell begin with
You need a build machine for packaging ONOS and for running your VM. The build machine should be running a UNIX-like OS. This tutorial assumes that your build machine is running Ubuntu 14.04, 64-bit.
You should have some kind of VM hosting software, such as VirtualBox, installed on your build machine. This tutorial assumes you are using VirtualBox.
Finally, you should generate a SSH public key on your build machine if you hadn't done so in the past:
The default options and no password are fine for this tutorial.
1. Prepare the VM.
Download Ubuntu Server 14.04 LTS 64-bit. Create a VM using this image, with the following settings:
- 2GB RAM
- 2 processors
- At least 5GB disk space
- Two network interfaces, Adapter 1 attached to NAT, and Adapter 2 attached to host-only Adapter set to vboxnet0. Configure both to use DHCP.
During the Ubuntu installation:
- create a user named sdn, with password rocks, and confirm that you want to use this password. This will be the primary account used for this tutorial.
- when prompted to encrypt the disk, select No
- For partitioning the disk, select Guided - use entire disk and follow with the defaults provided.
- For configuring proxy information, follow what best suits your environment.
- when prompted to install additional software (Software Install) choose OpenSSH server.
This tutorial calls the VM onos-scratch.
Once the VM starts up:
Log into your new VM as sdn and give the user passwordless sudo privileges. Run
sudo visudo, and add the following line to the end of the file:
Then, update the package repository:
You should also be able to verify that it has two network interfaces, eth0 and eth1:
From the build machine you should be able to SSH to the VM using the IP address assigned to eth1:
If the ssh connection failed make sure that the openssh-server is installed by running:
2. Install required software
On the Build machine
Create two directories called ~/Downloads and ~/Applications. Download the Karaf 3.0.3 and Maven 3.3.1 binaries (the tar.gz versions of both) into ~/Downloads and extract it to ~/Applications. Keep the tar archives in ~/Downloads; we'll need that later.
Next, install Oracle Java 8:
It will ask you to acknowledge the license; do so when prompted.
Finally, clone the ONOS source to sdn's home directory:
This will create a directory called onos, with the source code in it.
On the Ubuntu VM
The VM only requires Java 8 - follow the instructions for Java 8 above.
3. Set up your build environment
First off, you will need to export several environment variables. The ONOS source comes with a sample
bash_profile that can set these variables for you.
This file can be sourced from the interactive portion of
bash) of user
sdn, by adding the following line to it at the end:
Warning: technically any
bash-specific code should not go in
.profile. If you have a Debian-based system (e.g. Raspbian) where
.profile may be executed by a shell that is not
dash or some other POSIX-like shell), make sure you put the above line in .bash_aliases or the interactive portion of .bashrc rather than
.profile to avoid problems (such as
startx not working on Raspbian.)
Once the line is added, source the user's .profile (or just log out and log back in):
Once you run the above command, you will see in the output of
env that several new variables, such as ONOS_ROOT, OCI, and KARAF_ROOT, have been set.
Use different user name or group
Make sure you also setup ONOS_USER If you used a user name other than "sdn" during the Ubuntu installation. You can also customize the ONOS_GROUP (typically, the user name and group name will be identical.)
~/Applications/apache-karaf-3.0.3/etc/org.apache.karaf.features.cfg by appending the following line to featuresRepositories:
Now we are ready to build ONOS with Maven:
Now we are ready to start customizing, creating, and installing ONOS packages.
If previous version of ONOS is running, the service should be stopped (sudo service onos stop) before building with mvn. Otherwise, the test on onlab.nio package would fail with "address already in use" error.
4. Create a custom cell definition
A quick intro to cells
Under ONOS terminology, a cell is a collection of environment variables that are used:
- by the utility scripts included with ONOS, including the ones that we are about to talk about
- for telling the packaging process how we want to customize our ONOS package
Cells make it easy to use the utility scripts to package, configure, install, and run ONOS.
Here we will create an ONOS package that, when installed and launched, starts up a single-instance (non-clustering) ONOS instance that uses the intent-based forwarding application.
Create a cell definition file
A cell is defined in a cell definition file. We will create the following cell definition file called tutorial in ~/onos/tools/test/cells/ :
- OC1 and OCI are set to the address of eth1 in our VM
- ONOS_APPS indicates the ONOS applications we want to activate, including OpenFlow protocol, reactive forwarding (fwd), proxy ARP, and mobility.
Applying a cell
This cell can be applied to your build environment with the cell command:
Now any ONOS package you will build will take up the ONOS_APPS setting. Additionally, if you need to create packages with other configurations (i.e. different applications or install targets), all you need to do is to apply a different cell definition to your environment before package creation and deployment. Which brings us to:
5. Package and deploy ONOS
Passwordless VM access
For convenience, before we can deploy anything to our VM, we will configure paswordless login to the VM from our build machine with
This tutorial deals with only 1 VM, but if you want to create a cluster of ONOS, cloning the 1st VM, onos-patch-vm script can be used to set the hostname, etc. to the cloned VM.
Creating the package
To create a ONOS binary, run
op, for short):
This creates a tar archive in /tmp .
Deploying the package
We can now deploy it to our VM:
onos-install returns with the last message in the code block above, we can try logging on from our build machine:
We are now actually logged into the ONOS CLI of the instance that we have deployed on the VM.
apps to list all installed applications. The one with asterisk sign indicates that it is activated (running).
Note that there will be many more modules than you have configured - these are part of the ONOS OpenFlow and core components. Refer to Appendix C : Source Tree Organization to see descriptions of the modules.
You can log out (detach) from the CLI with
logout, or Ctrl-D.
The argument $OC1 can be replaced with $OCI, or even omitted; when omitted, the scripts will fall back to using the value stored in OCI.
Deploy on Mac OS X
onos-install uses the
initctl system to start and stop onos semi-automatically.
OS X manages daemons using
onos-install doesn't currently support, so we need to specify "nostart" (
and start ONOS manually using
- Now that you've got the basics of a development environment, try a hand at creating an application in the Template Application Tutorial.
- Learn more about the installation process in Installing and Running ONOS.
- Learn more about cells in Test Environment Setup.