README

   1 DIRECTORY ORGANIZATION
   2 ======================
   3
   4 - commons
   5   +-- parent : Contains Parent pom.xml for all the ovsdb modules.
   6
   7 - distribution : Builds a working controller distribution based on the controller + ovsdb modules and other
   8                  dependant modules such as openflowplugin
   9   +-- opendaylight : older, OSGi-based distribution
  10   +-- opendaylight-karaf : karaf-based distribution
  11
  12 - features : This folder contains all the Karaf related files.
  13
  14 - library : Contains Schema-independent library that is a reference implementation for RFC 7047.
  15             This module doesn't depend on any of the Opendaylight components.
  16             This library module can also be used independently in a non-OSGi environment.
  17
  18 - openstack
  19   +-- net-virt : Handles the Openstack Neutron ML2 and Network Service calls and performs all the logic required
  20                  for Network Virtualization.
  21   +-- net-virt-providers : Mostly contains data-path programming functionality via OpenFlow or potentially
  22                            other protocols.
  23
  24 - ovs-sfc : SFC implementation using the OVSDB project. Currently it is just a shell.
  25
  26 - plugin : Contains Opendaylight Southbound Plugin APIs and provides a simpler API interface on top of library layer.
  27            Ideally, this module should also be schema independent. But due to legacy reasons this layer contains some
  28            deprecated functionality that assumes openvswitch schema.
  29
  30 - plugin-mdsal-adapter : Adds an MD-SAL Adapter for the OVSDB Plugin. The adapter updates the MD-SAL with nodes
  31                          as they are added and removed from the inventory. The Yang model provides a reference
  32                          between OVSDB nodes and the OpenFlow nodes (bridges) that they manage.
  33
  34 - plugin-shell : Contains a Karaf shell framework for OVSDB plugin and printCache command-line.
  35
  36 - resources : Contains some useful resources such as scripts, testing utilities and tools used for deployment
  37               or testing the binaries generated from the OVSDB project.
  38
  39 - schemas :
  40   +-- openvswitch : Schema wrapper that represents http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf
  41   +-- hardwarevtep: Schema wrapper that represents http://openvswitch.org/docs/vtep.5.pdf
  42
  43 - utils : MD-SAL OpenFlow and OVSDB common utilities.
  44
  45 HOW TO BUILD & RUN
  46 ==================
  47
  48 Pre-requisites : JDK 1.7+, Maven 3+
  49
  50 1. Building a Karaf Feature and deploying it in an Opendaylight Karaf distribution :
  51    1. This is a new method for Opendaylight distribution wherein there is no defined editions such
  52       as Base, Virtualization or SP editions. The end-customer can choose to deploy the required feature
  53       based on his/her deployment needs.
  54
  55    2. From the root ovsdb/ directory, execute "mvn clean install"
  56
  57    3. Next unzip the distribution-karaf-<VERSION_NUMBER>-SNAPSHOT.zip file created from step #2 in
  58       the directory ovsdb/distribution/opendaylight-karaf/target like so:
  59       "unzip distribution-karaf-<VERSION_NUMBER>-SNAPSHOT.zip"
  60
  61    4. Once karaf has started and you see the Opendaylight ascii art in the console, the last step
  62       is to start the OVSDB plugin framework with the following command in the karaf console:
  63       "feature:install odl-ovsdb-openstack" (without quotation marks).
  64
  65    Sample output from Karaf console :
  66
  67    opendaylight-user@root>feature:list | grep -i ovsdb
  68    odl-ovsdb-all                    | 1.0.0-SNAPSHOT      |           | ovsdb-1.0.0-SNAPSHOT                  | OpenDaylight :: OVSDB :: all
  69    odl-ovsdb-library                | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT                  | OVSDB :: Library
  70    odl-ovsdb-schema-openvswitch     | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT                  | OVSDB :: Schema :: Open_vSwitch
  71    odl-ovsdb-schema-hardwarevtep    | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT                  | OVSDB :: Schema :: hardware_vtep
  72    odl-ovsdb-openstack              | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT                  | OpenDaylight :: OVSDB :: OpenStack Network Virtual
  73    odl-ovsdb-ovssfc                 | 0.0.1-SNAPSHOT      |           | ovsdb-0.0.1-SNAPSHOT                  | OpenDaylight :: OVSDB :: OVS Service Function Chai
  74
  75
  76 2. Building a bundle and deploying it in an Opendaylight Karaf distribution :
  77    This method can be used to update and test new code in a bundle. If the bundle of interest is rebuilt as a
  78    snapshot with the same version as what it already defined in a feature repo then that new bundle will be used
  79    when the feature is loaded in karaf. If karaf is already running with the feature loaded then follow the steps
  80    below to load the new bundle:
  81
  82    1. Find the bundle id of the bundle you are going to rebuild:
  83       - bundle:list -s | grep <bundlename>, i.e. bundle:list -s | grep odl-ovsdb-plugin
  84
  85    2. Instruct karaf to watch the new bundle and reload it if it changes:
  86       - bundle:watch <id>
  87       - The id is the value returned in 1 above.
  88       - You can also watch the bundle URL itself:
  89         - bundle:watch mvn:org.opendaylight.ovsdb/plugin/1.0.2-SNAPSHOT
  90
  91    3. Rebuild bundle.
  92       - cd bundle dir, i.e. cd ovsdb/plugin
  93       - mvn clean install. This will install the new bundle into the local mvn repo.
  94
  95    4. karaf will see the changed bundle and reload it.
  96
  97
  98 3. Building an OVSDB based Opendaylight Virtualization edition:
  99    1. This is the legacy way to build and distribute Opendaylight archives. This method was
 100       followed in Hydrogen. It might still work in Helium but it is best effort for support.
 101       The preferred method for Helium and later is to use karaf.
 102
 103    2. From the root folder(that hosts this README), execute "mvn clean install"
 104       That should build a full distribution archive and distribution directory that will contain
 105       Opendaylight Controller + OVSDB bundles + Openflow Plugins under
 106       distribution/opendaylight/target/distribution.ovsdb-X.X.X-osgipackage
 107
 108    3. Upon successful completion of a build, the Controller with OVSDB can be executed by :
 109       cd distribution/opendaylight/target/distribution.ovsdb-X.X.X-osgipackage/opendaylight/
 110       ./run.sh -virt ovsdb
 111
 112 4. Building a Karaf Feature and deploying it in an Opendaylight Karaf distribution :
 113 *** This method is deprecated.
 114    1. This is a new method for Opendaylight distribution wherein there is no defined editions such
 115       as Base, Virtualization or SP editions. Rather each of the projects will generate features in
 116       form of .kar files. The end-customer can choose to deploy the required feature based on his/her
 117       deployment needs.
 118
 119    2. From the features/ directory, execute "mvn clean install"
 120       This will generate a kar file such as "features/target/ovsdb-features-1.2.1-SNAPSHOT.kar"
 121
 122    3. Download (or build from controller project) the Karaf distribution :
 123       http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/controller/distribution.opendaylight-karaf/
 124       Sample zip file :
 125       http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/controller/distribution.opendaylight-karaf/1.4.2-SNAPSHOT/distribution.opendaylight-karaf-1.4.2-20140718.075612-407.zip
 126
 127    4. unzip the downloaded (or built) distribution and copy the ovsdb-features-x.x.x.kar file (from step 2) into
 128       the unzipped distribution.opendaylight-karaf-X.X.X/deploy/ directory.
 129
 130    5. run Karaf from within the distribution.opendaylight-karaf-X.X.X/ directory using "bin/karaf"
 131
 132    Sample output from Karaf console :
 133
 134    opendaylight-user@root>kar:list
 135    KAR Name
 136    -----------------------------
 137    ovsdb-features-1.2.1-SNAPSHOT
 138
 139    opendaylight-user@root>feature:list | grep ovsdb
 140    odl-ovsdb-all | 1.2.1-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OpenDaylight :: OVSDB :: all
 141    odl-ovsdb-library | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OVSDB :: Library
 142    odl-ovsdb-schema-openvswitch | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OVSDB :: Schema :: Open_vSwitch
 143    odl-ovsdb-schema-hardwarevtep | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OVSDB :: Schema :: hardware_vtep
 144    odl-ovsdb-plugin | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OpenDaylight :: OVSDB :: Plugin
 145
 146    opendaylight-user@root>bundle:list | grep OVSDB
 147    186 | Active | 80 | 1.0.0.SNAPSHOT | OVSDB Library
 148    199 | Active | 80 | 1.0.0.SNAPSHOT | OVSDB Open_vSwitch Schema
 149    200 | Active | 80 | 1.0.0.SNAPSHOT | OVSDB hardware_vtep Schema
 150    201 | Active | 80 | 1.0.0.SNAPSHOT | OpenDaylight OVSDB Plugin
 151
 152 Running The Integration Tests
 153 =============================
 154
 155 To run the integration tests locally the following components are required:
 156
 157  - Docker
 158  - Fig or Docker Compose
 159
 160 To install docker, follow the installation guide for your platform:
 161    http://docs.docker.com/installation/
 162
 163 To install fig:
 164    http://www.fig.sh/install.html
 165
 166 To install Docker Compose:
 167    http://docs.docker.com/compose/install/
 168
 169 To run the integration tests:
 170
 171     mvn clean install
 172     # The first time you need to set everything up
 173     fig up -d
 174     # Later runs only need the containers to be started
 175     fig start
 176     # OSX
 177     mvn verify -Pintegrationtest -Dovsdbserver.ipaddress=$(boot2docker ip 2>/dev/null) -Dovsdbserver.port=6640
 178     # Linux
 179     mvn verify -Pintegrationtest -Dovsdbserver.ipaddress=127.0.0.1 -Dovsdbserver.port=6640
 180     fig stop
 181
 182 On Linux you'll generally need to run fig as root (sudo fig ...).
 183
 184 If you're using Docker Compose, replace "fig" above with "docker-compose" and ignore the warnings.
 185
 186 Skipping unit tests and karaf tests
 187 ====================
 188
 189 mvn clean install -Dmaven.test.skip=true -Dskip.karaf=true