[[TOC(Documentation/f*, depth=3)]]

== Tutorial: OpenStack Setup==
In this tutorial, we will be using one of the sb9 nodes for setting up OpenStack. Make sure you have Ubuntu 20.04.5 LTS. To get the Ubuntu Version, follow these steps on the sb9 console. The below steps illustrate for node1-2 of sb9. On your sb9 console,

{{{
omf tell -t node1-2 -a offh 
}}}

{{{
omf load -t node1-2 -i baseline20.04.ndz
}}}

{{{
omf tell -t node1-2 -a on
}}}

To verify if you have loaded Ubuntu 20.04 properly, use this command after ssh into the node1-2 

{{{
lsb_release -a
}}} 

this will list the current version of Ubuntu loaded.

=== Set up an OpenStack development environment via DevStack ===
1. Update and Upgrade Packages:
{{{sudo apt-get update && sudo apt-get upgrade}}}
2. Install Git:
{{{sudo apt-get install git}}}
3. Clone the DevStack Repository:
{{{git clone https://github.com/openstack/devstack.git}}}
4. Create a Stack User:
{{{sudo ./devstack/tools/create-stack-user.sh}}}
5. Switch to the Stack User:
{{{sudo su stack}}} 


{{{cd ~}}}
6. Clone the DevStack Repository (as the Stack User):
{{{git clone https://git.openstack.org/openstack-dev/devstack}}}
7. Remove the Existing Python 3 Pip Package (if present) and Download and Install the Latest Python 3 Pip Package:
{{{sudo apt remove python3-pip}}}


{{{wget https://bootstrap.pypa.io/get-pip.py}}} 


{{{sudo python3 get-pip.py}}}

8. Install a Specific Version of the Cryptography Package(there is version conflict with the OpenSSL package automatic installed by dev stack so better install the this below version) :
{{{pip install cryptography==38.0.4}}}
9. Configure and setup local.conf in dev stack folder according to requirement (either the controller or compute node):

{{{cd devstack/samples }}}


{{{cp local.conf ../}}}


{{{cd ../}}}
after copying local.conf to the devstack folder, uncomment and change the HOST_IP to the IP of the current node(so here in this case 10.19.1.2)

10. Start the OpenStack Installation using DevStack:
{{{FORCE=yes ./stack.sh}}}








==== Installing the !OpenFlow Reference System (old) ====
While presented, it is not recommended to install from tarball. 
The detailed instructions may be found here: http://www.openflowswitch.org/wp/getstarted/

1. Download software and required packages. If using git: 
{{{
sudo apt-get install git-core automake m4 pkg-config libtool
git clone http://openflowswitch.org/openflow
cd openflow
./boot.sh
}}}
if installing from tarball:
{{{
mkdir openflow
cd openflow
wget http://openflowswitch.org/downloads/openflow-0.9.0.tar.gz
tar xzf openflow-0.9.0.tar.gz
cd openflow-0.9.0
sudo apt-get install gcc linux-headers-`uname -r`
}}}
2. Make and install.
{{{
./configure --with-l26=/lib/modules/`uname -r`/build
make
make install
}}}

=== Installing NOX  ===
It is not only recommended but also much simpler to use git to install NOX. Therefore the following instructions assume you are using git. The full instructions are found at noxrepo.org:  http://noxrepo.org/manual/installation.html [[BR]]

''' Dependencies ''' [[BR]]
NOX requires the following packages to be installed on the Console:
 * GNU Libtool (libtool)
 * Boost C++ libraries (libboost1.35-dev)
 * Apache HTTP Server (apache2)
 * Xerces C++ parser (libxerces-c28)
 * Xerces development files (libxerces-c2-dev)
 * SSL development libraries (libssl-dev)
 * SQLite 3 development files (libsqlite3-dev)
 * Simple JSON for Python (python-simplejson)
Note, this is with respect to the Console, not the node - you may need to install additional packages before NOX can be installed properly. 

If all dependencies are taken care of, NOX will install with the following steps. 
{{{
git clone git://noxrepo.org/noxcore
cd noxcore/
./boot.sh
mkdir build/
cd build/
../configure --with-python=yes
make
make check 
}}}


=== Controllers on the Console === 

A sub-set of these instructions can be used to install a "custom" controller in userspace on the console. Most of the requisite libraries should already be installed. Use the following commands to install the Reference system in your userspace: 

'''for the !OpenFlow Reference System :'''[[BR]]
{{{
cd
git clone http://openflowswitch.org/openflow
cd openflow
./boot.sh
./configure --with-l26=/lib/modules/`uname -r`/build
make
make install
}}}

'''for NOX :'''[[BR]]
{{{
cd
git clone git://noxrepo.org/noxcore
cd noxcore/
./boot.sh
mkdir build/
cd build/
../configure --with-python=yes
make
make check 
}}}


=== Starting the controller ===
Both commands start the controller and establish a connection with the !OpenFlow switch. The -v is for verbose. -h for both will give you the help files for the controllers. In the reference system, the controller is found under .../openflow/controller/
{{{
./controller -v ptcp:6633 
}}} 
and in NOX, it is found under .../noxcore/build/src/
{{{
./nox-core -v -i ptcp:6633 
}}} 
`ptcp:6633` refers to a passive connection to TCP 6633, the default !OpenFlow port. An active connection method using standard TCP exists, however this does not work on this setup. In the !OpenFlow reference system, a log of the verbose output can be saved by appending `--log-file [filename]`.    

[[BR]]
[[BR]]

----
=== Available Tools ===

Some of these tools require root privileges and will thus require a custom installation on a node. Others can be run from the console directly in an unprivileged mode. 

==== the Wireshark plugin ====
The !OpenFlow Reference system comes with an !OpenFlow wireshark dissector. 

'''Permissions:''' [[BR]]
You must be root in order to use Wireshark; Therefore you must install it on a node. [[BR]]

'''Prerequisites:''' [[BR]]
glib (and of course, wireshark) is required for the plugin to work:
{{{
apt-get install wireshark libgtk2.0-dev
}}}

'''Installation:'''[[BR]]
The patch is located under the utilities directory:
{{{
cd utilities/wireshark_dissectors/openflow
make
sudo make install
}}}  

'''Usage:'''[[BR]]
To use wireshark, you need to do some X11 tunneling. To do this, add the -X option when using SSH to access the Console and the nodes.   

tcpdump pcap files can also be opened using wireshark - once the plugin has been installed, !OpenFlow packets can be interpreted from these files as well.  

==== Iperf ====
For performance testing, you may want to run some bandwidth tests. iperf is a tool that measures maximum network performance using TCP for throughput and UDP for jitter and datagram loss. The standard image used for the Sandbox nodes when booted with command `omf tell on` comes with iperf. To take measurements, you need at least two nodes. One node becomes the server, the other(s), clients.

'''Permissions:''' [[BR]]
Iperf does not require root access. 

'''Usage:'''[[BR]]
Initially, eth0 (the !OpenFlow interface for the nodes) will be disabled. Additionally, there is no DHCP service on that VLAN - you need to enable the interface and statically set the IP address (i.e. using ifconfig). 192.168.x.y is the block associated with the !OpenFlow VLAN.  

To start the server:
{{{
iperf -s 
}}}   
and on the client:
{{{
iperf -c 192.168.x.y 
}}}

Where 192.168.x.y is the IP address of the iperf server. A caveat is that iperf cannot take real-time bandwidth measurements. Real-time bandwidth use can be monitored using BWM-ng.

'''On the Console'''[[BR]]
Iperf is also installed on the Console. The interfaces available on the Console are the following:
 * eth1 - 192.168.100.28
 * eth1.27 / Control - 10.19.0.10
 * eth1.28 / OF virtual switch - 192.168.1.28
 * eth1.100 / OFP interface - 172.16.100.1
 
==== BWM-ng ==== 
BWM-ng is a tool capable of taking real-time throughput measurements of different interfaces of a host.  

'''Permissions:''' [[BR]]
BWM-ng does not require root access, and is installed on the Console.  

'''Usage:'''[[BR]]
By default, the tool will monitor all interfaces on the Console. To monitor just the !OpenFlow interface, you must specify `eth1.100`. To output this to a csv, use the following command: 
{{{
bwm-ng -I eth1.100 -o csv -t 1000 -F <file-name>
}}}  
 * -I : interface
 * -o : output, either in csv or html
 * -t : specifies sampling rate in msec. Here, it is 1000 msec, or 1 sample/sec
 * -F : Filename of output

'''Installation on a node'''[[BR]]
The following command will install BWM-ng:
{{{
apt-get install bwm-ng
}}}

----
==== Development ====
The files defining !OpenFlow Protocol can be found in the following locations:
 * !OpenFlow reference system:  openflow/include/openflow/openflow.h
 * NOX: noxcore/src/include/openflow.hh

In addition, NOX provides a [http://noxrepo.org/manual/app.html Web API] that allows you to do development in C++ or Python.