README

/*
*****************************************************
**      CodeChix ONF Driver (LibCCOF)
**      codechix.org - May the code be with you...
**              Sept. 15, 2013
*****************************************************
**
** License:        Apache 2.0 (ONF requirement)
** Version:        0.0
** LibraryName:    LibCCOF
** GLIB License:   GNU LGPL
** Description:    Top level README - individual subdirs
**		   might also have their own README files
** Assumptions:    N/A
** Testing:        N/A
** Authors:        Deepa Karnad Dhurka
**
** Main Contact:   deepa.dhurka@gmail.com
** Alt. Contact:   organizers@codechix.org
*****************************************************
*/


This is LIBCCOF version 0.0
===========================
Copyright: CodeChix 2013


License information
-------------------
LIBCCOF license: Apache 2.0

GLIB license: GNU Library General Public License (GNU LGPL)


What’s new in this release?
---------------------------
Support for Open Flow


Documentation
-------------
* Library header - include/cc_of_lib.h
* Unit test - tests/README
* Java SWIG - include/swig_java/README 
* Python SWIG - include/swig_python/README


Web sites
---------
https://github.com/codechix/OFconnect

Bug report
----------
* Tested only to bring up one switch.
* Tear down of connection hangs the controller
* Ping after installing flows does not work

Supported systems
-----------------
The library has been tested to compile on Ubuntu 12.04 LTS with Intel core.


Dependencies
------------
glib-2.0
libglib2.0-dev
pkg-config
GNU make 3.81
GNU binutils

ToDo
----
* Statistics support
* OF awareness and header file parsing
* OF version negotiation
* Handling of OF hello and OF echo request-reply
* Extensible design for header files of different OF versions 
* Parsing of OF header to extract DPID and AUXID
* TLS transport
* Text log file
* Retry lost connections on switch


Distribution structure
----------------------
The single Makefile in top level directory compiles library and tests.
doc/
include/
include/swig_java
include/swig_python
src/
tests/


These files are generated at run time:

libccof.so.0.0
obj/
  cc_log.o 
  cc_of_lib.o 
  cc_of_util.o 
  cc_pollthr_mgr.o  
  cc_tcp_conn.o
  cc_udp_conn.o
tests/*.o, *.exe, log-*.xml, log-*.html for every .c file
$HOME/.libccof/log-<timestamp> if logging to file is enabled using the API.

Generation of SWIG bindings will create other runtime files in respective SWIG directory.

Contributors 
------------
All contributors are members of:
CodeChix
http://www.codechix.org/
https://github.com/codechix

Sorted by last name:

Kajal Bhargava 
kajal.bhargava1@gmail.com
https://github.com/kajalusc


Ramya Bolla 
bolla.ramya88@gmail.com
https://github.com/bollaramya

Rupa Dachere
rupa@codechix.org
https://github.com/rdachere

Deepa Dhurka 
deepa.dhurka@gmail.com
https://github.com/deepadhurka
https://github.com/edeedhu

Swapna Iyer
swapna.iyer@gmail.com
https://github.com/swapnai


Build Instructions
==================
Compiling the library
---------------------
$ make help
make objects  : build library objects
make all      : compile and link library
make install  : install library
                Needs root permissions
make clean    : cleans all object files of library
make test     : compile all tests
make runtest  : execute all tests
                Creates xml and html log files
make cleantest: cleans all temporary test files
                including log files

If you want to run the compiled test programs multiple times, either 
manually invoke gtester for each program, or, run ‘make cleantest’ 
before every ‘make runtest’.


Compiling an SDN controller or switch using the library
-------------------------------------------------------
1. Install the dependency libraries required by libccof

2. Compile and install the library object
make all
make install

The paths to library directory and header file directory are hard-coded. Please modify Makefile to change each path if necessary.

Default location of libccof.so.0 - /usr/local/lib
Default location of cc_of_lib.h - /usr/local/include


3. Include the header file in your code
#include “cc_of_lib.h”

4. Follow instructions for compilation of glib applications:
https://developer.gnome.org/glib/stable/glib-compiling.html
Set an environment variable with necessary glib flags. For example:

GFLAGS='-I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -lglib-2.0'

Note: the glib flags may vary on each system. Get the exact values from pkg-config output as instructed by Gnome’s manual for glib.

4. Finally, run GCC
gcc your_program.c $GFLAGS -lccof -I/usr/include/lib


Design
======
Terminology:
------------
1. Device:
One instance of the controller or switch defined by:

Controller IP address, Controller L4 port, and if the application
is a switch, also the Switch IP address.

If a Controller is listening on multiple IP addresses or ports,
a device needs to be registered with the library for each 
combination.

For example:
Controller listens on 10.1.1.1/16 and 10.2.1.1/16, with 2 ports
each, the application has to register four devices.

Similarly, a Switch needs to register a unique device for every
combination of Controller IP address, Controller port and Switch IP.


2. Connection:
A connection is uniquely defined by a DP-ID and Aux-ID pair. 
All sockets managed by the library are internal to it. They are not 
exposed to the application. Each socket is uniquely mapped to its 
Aux-ID and DP-ID pair.

'Channel' is another term used interchangeably with Connection.


3. Dummy DP-ID and AUX-ID
Dummy DP-ID and Aux-IDs are generated by the library to identify
a connection until the actual values are derived from the OF Features
Request packet header. At which time, the socket is mapped against
the new values.


4. Net Services Callbacks
This is a feature of the library. An extensible mechanism to introduce 
new layer 4 protocols to the design is by using the net services 
callbacks. Each connection is mapped to its layer 4 protocol type, 
based on which, the processing function for appropriate protocol is 
called. This is a flexible framework to make the introduction of new 
Layer 4 protocols very quick.


5. Polling Threads and Management:


Pollthread:
----------
A thread with a polling loop for pipes and sockets. This
thread is in a while loop polling on fds, and invoking callbacks for
each type of fd. 

Each pollthread has 2 default pipes:
  1. Primary pipe - the library adds or deletes fds to the polling 
     loop by sending a message to the thread on the primary pipe

  2. Data pipe - any message that needs to be sent out on a socket
     is written to this pipe. 

The polling thread has special callbacks for these 2 pipes to handle
the read events.

The library spawns multiple polling threads, as soon as the the existing
ones fill up to capacity in terms of socket FDs and pipes.

Pollthread Manager:
------------------
Utility wrapper for a single pollthread. It creates and deletes the
pollthread, and has interfaces defined to create a pollthread and add 
and delete fds to the pollthread. Each pollthread can be added 
MAX_PER_THREAD_RWSOCKETS and MAX_PER_THREAD PIPES. The availability
of capacity is tracked to dynamically manage the pool of pollthreads.

Each pollthread has its own pollthread manager. The full list of 
pollthread managers for read-write sockets is maintained globally.

Pollthread Pool:
---------------
Elastic pool of pollthreads, sorted by ascending order of available 
number of sockets. The pool has its own utility wrappers on pollthread 
manager to add and delete socket because this impacts the sorting. 
Also, when a thread is freed up of all sockets it is deleted.


Please read doc/README for help on API.

Logging and Debugging:
---------------------
A log file is created with timestamp in $HOME/.libccof each time cc_of_log_toggle() is set to TRUE. All logs are printed in this file which can be cleared and read at any point. Logging will continue until it is toggled off.

Debugging can be enabled to print debug messages on the console or terminal.

Troubleshooting:
================
1. Address in use error:
cc_onf_driver_lib-INFO: cc_of_lib_init(104): CC_OF_Library initilaized successfully
(process:32047): cc_onf_driver_lib-DEBUG: cc_of_dev_register(191): Started Registering Device
(process:32047): cc_onf_driver_lib-DEBUG: tcp_open_listenfd(272): Starting to open listen fd 6633

(process:32047): cc_onf_driver_lib-CRITICAL **: tcp_open_listenfd(293): Address already in use

(process:32047): cc_onf_driver_lib-CRITICAL **: cc_of_dev_register(240): misc error


Solution:
sudo - 
lsof -w -n -i tcp:<port>
fuser -n tcp <port>
netstat -anp|grep :<port>

kill any process that is using the port in question and try again.

*** most important - .libccof log file creation ****