X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README;h=a3a45ae871640ac0a3ec207b374edf3efdb146dd;hb=3cd392cee99b9cf9c97ae36399b3b97f14244fac;hp=1401a994b5daf1740cd8717719f864b630a3023a;hpb=fb5f6a394d26ab3ef3c9943a6d975d60c70ae949;p=netvirt.git diff --git a/README b/README index 1401a994b5..a3a45ae871 100644 --- a/README +++ b/README @@ -1,38 +1,189 @@ DIRECTORY ORGANIZATION ====================== -- commons: contains the parent pom.xml for all ovsdb projects. -- ovsdb: contains the ovsdb SB plugin -- distribution/opendaylight: will build a working controller distribution - based on the controller + ovsdb modules +- commons + +-- parent : Contains Parent pom.xml for all the ovsdb modules. -HOW TO BUILD -============ +- distribution : Builds a working controller distribution based on the controller + ovsdb modules and other + dependant modules such as openflowplugin + +-- opendaylight : older, OSGi-based distribution + +-- opendaylight-karaf : karaf-based distribution -In order to build it's required to have JDK 1.7+ and Maven 3+, to get -a build going it's needed to: +- features : This folder contains all the Karaf related files. -cd commons/ -mvn clean install +- library : Contains Schema-independent library that is a reference implementation for RFC 7047. + This module doesn't depend on any of the Opendaylight components. + This library module can also be used independently in a non-OSGi environment. -or if you want to avoid SNAPSHOT checking +- openstack + +-- net-virt : Handles the Openstack Neutron ML2 and Network Service calls and performs all the logic required + for Network Virtualization. + +-- net-virt-providers : Mostly contains data-path programming functionality via OpenFlow or potentially + other protocols. -cd commons/ -mvn clean install -nsu +- ovs-sfc : SFC implementation using the OVSDB project. Currently it is just a shell. -HOW TO RUN -============ +- plugin : Contains Opendaylight Southbound Plugin APIs and provides a simpler API interface on top of library layer. + Ideally, this module should also be schema independent. But due to legacy reasons this layer contains some + deprecated functionality that assumes openvswitch schema. -Upon successful completion of a build +- plugin-mdsal-adapter : Adds an MD-SAL Adapter for the OVSDB Plugin. The adapter updates the MD-SAL with nodes + as they are added and removed from the inventory. The Yang model provides a reference + between OVSDB nodes and the OpenFlow nodes (bridges) that they manage. -cd distribution/opendaylight/target/distribution.ovsdb-1.0.0-SNAPSHOT-osgipackage/opendaylight/ -./run.sh +- plugin-shell : Contains a Karaf shell framework for OVSDB plugin and printCache command-line. -Wait for the osgi console to startup and then point a browser at +- resources : Contains some useful resources such as scripts, testing utilities and tools used for deployment + or testing the binaries generated from the OVSDB project. -http:localhost:8080/ +- schemas : + +-- openvswitch : Schema wrapper that represents http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf + +-- hardwarevtep: Schema wrapper that represents http://openvswitch.org/docs/vtep.5.pdf +- utils : MD-SAL OpenFlow and OVSDB common utilities. +HOW TO BUILD & RUN +================== +Pre-requisites : JDK 1.7+, Maven 3+ +1. Building a Karaf Feature and deploying it in an Opendaylight Karaf distribution : + 1. This is a new method for Opendaylight distribution wherein there is no defined editions such + as Base, Virtualization or SP editions. The end-customer can choose to deploy the required feature + based on his/her deployment needs. + 2. From the root ovsdb/ directory, execute "mvn clean install" + + 3. Next unzip the distribution-karaf--SNAPSHOT.zip file created from step #2 in + the directory ovsdb/distribution/opendaylight-karaf/target like so: + "unzip distribution-karaf--SNAPSHOT.zip" + + 4. Once karaf has started and you see the Opendaylight ascii art in the console, the last step + is to start the OVSDB plugin framework with the following command in the karaf console: + "feature:install odl-ovsdb-openstack" (without quotation marks). + + Sample output from Karaf console : + + opendaylight-user@root>feature:list | grep -i ovsdb + odl-ovsdb-all | 1.0.0-SNAPSHOT | | ovsdb-1.0.0-SNAPSHOT | OpenDaylight :: OVSDB :: all + odl-ovsdb-library | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT | OVSDB :: Library + odl-ovsdb-schema-openvswitch | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT | OVSDB :: Schema :: Open_vSwitch + odl-ovsdb-schema-hardwarevtep | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT | OVSDB :: Schema :: hardware_vtep + odl-ovsdb-openstack | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT | OpenDaylight :: OVSDB :: OpenStack Network Virtual + odl-ovsdb-ovssfc | 0.0.1-SNAPSHOT | | ovsdb-0.0.1-SNAPSHOT | OpenDaylight :: OVSDB :: OVS Service Function Chai + + +2. Building a bundle and deploying it in an Opendaylight Karaf distribution : + This method can be used to update and test new code in a bundle. If the bundle of interest is rebuilt as a + snapshot with the same version as what it already defined in a feature repo then that new bundle will be used + when the feature is loaded in karaf. If karaf is already running with the feature loaded then follow the steps + below to load the new bundle: + + 1. Find the bundle id of the bundle you are going to rebuild: + - bundle:list -s | grep , i.e. bundle:list -s | grep odl-ovsdb-plugin + + 2. Instruct karaf to watch the new bundle and reload it if it changes: + - bundle:watch + - The id is the value returned in 1 above. + - You can also watch the bundle URL itself: + - bundle:watch mvn:org.opendaylight.ovsdb/plugin/1.0.2-SNAPSHOT + + 3. Rebuild bundle. + - cd bundle dir, i.e. cd ovsdb/plugin + - mvn clean install. This will install the new bundle into the local mvn repo. + + 4. karaf will see the changed bundle and reload it. + + +3. Building an OVSDB based Opendaylight Virtualization edition: + 1. This is the legacy way to build and distribute Opendaylight archives. This method was + followed in Hydrogen. It might still work in Helium but it is best effort for support. + The preferred method for Helium and later is to use karaf. + + 2. From the root folder(that hosts this README), execute "mvn clean install" + That should build a full distribution archive and distribution directory that will contain + Opendaylight Controller + OVSDB bundles + Openflow Plugins under + distribution/opendaylight/target/distribution.ovsdb-X.X.X-osgipackage + + 3. Upon successful completion of a build, the Controller with OVSDB can be executed by : + cd distribution/opendaylight/target/distribution.ovsdb-X.X.X-osgipackage/opendaylight/ + ./run.sh -virt ovsdb + +4. Building a Karaf Feature and deploying it in an Opendaylight Karaf distribution : +*** This method is deprecated. + 1. This is a new method for Opendaylight distribution wherein there is no defined editions such + as Base, Virtualization or SP editions. Rather each of the projects will generate features in + form of .kar files. The end-customer can choose to deploy the required feature based on his/her + deployment needs. + + 2. From the features/ directory, execute "mvn clean install" + This will generate a kar file such as "features/target/ovsdb-features-1.2.1-SNAPSHOT.kar" + + 3. Download (or build from controller project) the Karaf distribution : + http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/controller/distribution.opendaylight-karaf/ + Sample zip file : + 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 + + 4. unzip the downloaded (or built) distribution and copy the ovsdb-features-x.x.x.kar file (from step 2) into + the unzipped distribution.opendaylight-karaf-X.X.X/deploy/ directory. + + 5. run Karaf from within the distribution.opendaylight-karaf-X.X.X/ directory using "bin/karaf" + + Sample output from Karaf console : + + opendaylight-user@root>kar:list + KAR Name + ----------------------------- + ovsdb-features-1.2.1-SNAPSHOT + + opendaylight-user@root>feature:list | grep ovsdb + odl-ovsdb-all | 1.2.1-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OpenDaylight :: OVSDB :: all + odl-ovsdb-library | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OVSDB :: Library + odl-ovsdb-schema-openvswitch | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OVSDB :: Schema :: Open_vSwitch + odl-ovsdb-schema-hardwarevtep | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OVSDB :: Schema :: hardware_vtep + odl-ovsdb-plugin | 1.0.0-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OpenDaylight :: OVSDB :: Plugin + + opendaylight-user@root>bundle:list | grep OVSDB + 186 | Active | 80 | 1.0.0.SNAPSHOT | OVSDB Library + 199 | Active | 80 | 1.0.0.SNAPSHOT | OVSDB Open_vSwitch Schema + 200 | Active | 80 | 1.0.0.SNAPSHOT | OVSDB hardware_vtep Schema + 201 | Active | 80 | 1.0.0.SNAPSHOT | OpenDaylight OVSDB Plugin + +Running The Integration Tests +============================= + +To run the integration tests locally the following components are required: + + - Docker + - Fig or Docker Compose + +To install docker, follow the installation guide for your platform: + http://docs.docker.com/installation/ + +To install fig: + http://www.fig.sh/install.html + +To install Docker Compose: + http://docs.docker.com/compose/install/ + +To run the integration tests: + + mvn clean install + # The first time you need to set everything up + fig up -d + # Later runs only need the containers to be started + fig start + # OSX + mvn verify -Pintegrationtest -Dovsdbserver.ipaddress=$(boot2docker ip 2>/dev/null) -Dovsdbserver.port=6640 + # Linux + mvn verify -Pintegrationtest -Dovsdbserver.ipaddress=127.0.0.1 -Dovsdbserver.port=6640 + fig stop + +On Linux you'll generally need to run fig as root (sudo fig ...). + +If you're using Docker Compose, replace "fig" above with "docker-compose" and ignore the warnings. + +Skipping unit tests and karaf tests +==================== + +mvn clean install -Dmaven.test.skip=true -Dskip.karaf=true