README

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