Update openvswitch plugin README

https://bugs.launchpad.net/quantum/+bug/850261

Change-Id: Ifb3d46f9743cb2159582d9a39cb704206505dced

quantum/plugins/openvswitch/README

@@ -1,28 +1,50 @@
 # -- Background
 
-The quantum openvswitch plugin is a simple plugin that allows you to manage
+The quantum openvswitch plugin is a simple plugin that allows you to
-connectivity between VMs on hypervisors running openvswitch.
+manage connectivity between VMs on hypervisors running openvswitch.
 
-The quantum openvswitch plugin consists of two components:
+The quantum openvswitch plugin consists of three components:
 
-1) The plugin itself:  The plugin uses a database backend (mysql for now) to
+1) The plugin itself: The plugin uses a database backend (mysql for
-   store configuration and mappings that are used by the agent.
+   now) to store configuration and mappings that are used by the
+   agent.  The mysql server runs on a central server (often the same
+   host as nova itself).
 
-2) An agent which runs on the hypervisor (dom0) and communicates with
+2) The quantum service host which will be running quantum.  This can
-  openvswitch.  The agent gathers the configuration and mappings from the
+   be run on the server running nova.
-  mysql database running on the quantum host.
 
-The sections below describe how to configure and run the quantum service with
+3) An agent which runs on the hypervisor (dom0) and communicates with
-the openvswitch plugin.
+   openvswitch.  The agent gathers the configuration and mappings from
+   the mysql database running on the quantum host.
 
-# -- Nova configuration
+The sections below describe how to configure and run the quantum
+service with the openvswitch plugin.
 
-- Make sure to set up nova using flat networking.  Also, make sure that the
+# -- Nova configuration (controller node)
-  integration bridge (see below under agent configuration) matches the
+
-  flat_network_bridge specified in your nova flag file.  Here are the relevant
+1) Make sure to set up nova using the quantum network manager in the
-  entries from my nova flag file.
+   nova.conf on the node that will be running nova-network.
---network_manager=nova.network.manager.FlatManager
+
---flat_network_bridge=xapi1
+--network_manager=nova.network.quantum.manager.QuantumManager
+
+# -- Nova configuration (compute node(s))
+
+1a) (If you're using xen) Configure the integration bridge and vif driver
+# Note that the integration bridge could be different on each compute node so
+# be careful to specify the right one in each nova.conf
+--xenapi_ovs_integration_bridge=xapi1
+--linuxnet_interface_driver=nova.network.linux_net.LinuxOVSInterfaceDriver
+
+1b) (If you're using qemu/kvm) Configure the bridge, vif driver, and
+    libvirt/vif type
+
+--libvirt_ovs_integration_bridge=br-int
+--libvirt_type=qemu
+--libvirt_vif_type=ethernet
+--libvirt_vif_driver=nova.virt.libvirt.vif.LibvirtOpenVswitchDriver
+# This last one isn't actually required yet as DHCP isn't integrated
+  with the QuantumManager yet.
+--linuxnet_interface_driver=nova.network.linux_net.LinuxOVSInterfaceDriver
 
 # -- Quantum configuration
 
@@ -31,13 +53,15 @@ Make the openvswitch plugin the current quantum plugin
 - edit ../../plugins.ini and change the provider line to be:
 provider = quantum.plugins.openvswitch.ovs_quantum_plugin.OVSQuantumPlugin
 
-# -- Database config.  The OVS quantum service requires access to a mysql
+# -- Database config.
-# database in order to store configuration and mappings that will be used by
-# the agent.  Here is how to set up the database on the host that you will be
-# running the quantum service on.
 
-MySQL should be installed on the host, and all plugins and clients must be
+The OVS quantum service requires access to a mysql database in order
-configured with access to the database.
+to store configuration and mappings that will be used by the agent.
+Here is how to set up the database on the host that you will be
+running the quantum service on.
+
+MySQL should be installed on the host, and all plugins and clients
+must be configured with access to the database.
 
 To prep mysql, run:
 
@@ -46,67 +70,75 @@ $ mysql -u root -p -e "create database ovs_quantum"
 Make sure any xenserver running the ovs quantum agent will be able to
 communicate with the host running the quantum service:
 
-//log in to mysql service
+# log in to mysql service
 $ mysql -u root -p
-// grant access to user-remote host combination.  Note: if you're going to use
+# The OVS Quantum agent running on each compute node must be able to
-// a wildcard here it should be a management network with only trusted hosts.
+  make a mysql connection back to the main database server.
 mysql> GRANT USAGE ON *.* to root@'yourremotehost' IDENTIFIED BY 'newpassword';
-//force update of authorization changes
+# force update of authorization changes
 mysql> FLUSH PRIVILEGES;
 
-# -- Plugin configuration.
+# -- Plugin configuration
 
-- Edit the configuration file (ovs_quantum_plugin.ini).  Make sure it matches
+- Edit the configuration file (ovs_quantum_plugin.ini).  Make sure it
-  your mysql configuration.  This file must be updated with the addresses and
+  matches your mysql configuration.  This file must be updated with
-  credentials to access the database.  This file will be included in the agent
+  the addresses and credentials to access the database.  This file
-  distribution tarball (see below) and the agent will use the credentials here
+  will be included in the agent distribution tarball (see below) and
-  to access the database.
+  the agent will use the credentials here to access the database.
 
 # -- XenServer Agent configuration
 
 - Create the agent distribution tarball
 
 $ make agent-dist
-- Copy the resulting tarball to your xenserver(s) (copy to dom0, not the nova
+
-  compute node)
+- Copy the resulting tarball to your xenserver(s) (copy to dom0, not
-- Unpack the tarball and run xenserver_install.sh.  This will install all of the
+  the nova compute node)
-  necessary pieces into /etc/xapi.d/plugins.  It will also spit out the name
+
-  of the integration bridge that you'll need for your nova configuration.
+- Unpack the tarball and run xenserver_install.sh.  This will install
-  Make sure to specify this in your nova flagfile as --flat_network_bridge.
+  all of the necessary pieces into /etc/xapi.d/plugins.  It will also
+  output the name of the integration bridge that you'll need for your nova
+  configuration.  Make sure to specify this in your nova flagfile as
+  --xenapi_ovs_integration_bridge.
+
+  NOTE: Make sure the integration bridge that the script emits is the
+  same as the one in your ovs_quantum_plugin.ini file.
+
 - Run the agent [on your hypervisor (dom0)]:
+
 $ /etc/xapi.d/plugins/ovs_quantum_agent.py /etc/xapi.d/plugins/ovs_quantum_plugin.ini
 
 # -- KVM Agent configuration
 
-- Copy ovs_quantum_agent.py and ovs_quantum_plugin.ini to the Linux host and run: 
+- Edit ovs_quantum_plugin.ini and make sure the integration bridge is set to
+  br-int.
+
+- Copy ovs_quantum_agent.py and ovs_quantum_plugin.ini to the compute
+  node and run:
 $ python ovs_quantum_agent.py ovs_quantum_plugin.ini
 
 # -- Getting quantum up and running
 
 - Start quantum [on the quantum service host]:
-~/src/quantum  $ PYTHONPATH=.:$PYTHONPATH python bin/quantum etc/quantum.conf
+~/src/quantum  $ python bin/quantum etc/quantum.conf
 - Run ovs_quantum_plugin.py via the quantum plugin framework cli [on the
   quantum service host]
-~/src/quantum$ PYTHONPATH=.:$PYTHONPATH python quantum/cli.py
+~/src/quantum$ python bin/cli
 
 This will show help all of the available commands.
 
 An example session looks like this:
 
 $ export TENANT=t1
-$ PYTHONPATH=. python quantum/cli.py create_net $TENANT network1
+$ python bin/cli create_net $TENANT network1
 Created a new Virtual Network with ID:e754e7c0-a8eb-40e5-861a-b182d30c3441
 $ export NETWORK=e754e7c0-a8eb-40e5-861a-b182d30c3441
-$ PYTHONPATH=. python quantum/cli.py create_port $TENANT $NETWORK
+$ python bin/cli create_port $TENANT $NETWORK
 Created Virtual Port:5a1e121b-ccc8-471d-9445-24f15f9f854c on Virtual Network:e754e7c0-a8eb-40e5-861a-b182d30c3441
 $ export PORT=5a1e121b-ccc8-471d-9445-24f15f9f854c
-$ PYTHONPATH=. python quantum/cli.py plug_iface $TENANT $NETWORK $PORT ubuntu1-eth1
+$ python bin/cli plug_iface $TENANT $NETWORK $PORT ubuntu1-eth1
 Plugged interface "ubuntu1-eth1" to port:5a1e121b-ccc8-471d-9445-24f15f9f854c on network:e754e7c0-a8eb-40e5-861a-b182d30c3441
 
 (.. repeat for more ports and interface combinations..)
 
-# -- Other items
+See the main quantum documentation for more details on the commands.
-
-- To get a listing of the vif names in the format that the ovs quantum service
-  will expect them in, issue the following command on the hypervisor (dom0):
-$ for vif in `xe vif-list params=uuid --minimal | sed s/,/" "/g`; do echo $(xe vif-list params=vm-name-label uuid=${vif} --minimal)-eth$(xe vif-list params=device uuid=${vif} --minimal); done