README fixes

README

@@ -1,25 +1,29 @@
 # -- Welcome!
 
-  You have come across a cloud computing network fabric controller.  It has identified
+  You have come across a cloud computing network fabric controller.  It has
-  itself as "Quantum."  It aims to tame your (cloud) networking!
+  identified itself as "Quantum."  It aims to tame your (cloud) networking!
 
 # -- Basics:
 
-1) Quantum REST API: Quantum supports a REST-ful programmatic interface to manage your
+1) Quantum REST API: Quantum supports a REST-ful programmatic interface to
-   cloud networking fabric.
+   manage your cloud networking fabric.
 
-2) Quantum Plugins: Quantum sports a plug-able architecture that allows Quantum's REST API
+2) Quantum Plugins: Quantum sports a plug-able architecture that allows
-   to be backed by various entities that can create a cloud-class virtual networking fabric.
+   Quantum's REST API to be backed by various entities that can create a
-   The advantages of this plug-able architecture is two-folds:
+   cloud-class virtual networking fabric.  The advantages of this plug-able
+   architecture is two-folds:
 
-   a) Allows for ANY open-source project or commercial vendor to write a Quantum plug-in.
+   a) Allows for ANY open-source project or commercial vendor to write a
+   Quantum plug-in.
 
-   b) Allows Quantum users to not be tied down to a single Quantum implementation and
+   b) Allows Quantum users to not be tied down to a single Quantum
-      enables them to switch out a plug-in by simple editing a config file - plugins.ini
+   implementation and enables them to switch out a plug-in by simple editing a
+   config file - plugins.ini
 
 # -- Dependencies
 
- The following python packages are required to run quantum.  These can be installed using pip:
+ The following python packages are required to run quantum.  These can be
+ installed using pip:
 
  eventlet>=0.9.12
  nose
@@ -32,7 +36,9 @@
  webob
  webtest
 
-1) Install easy_install (there is probably a distribution specific package for this)
+1) Install easy_install (there is probably a distribution specific package for
+this)
+
 2) Install pip:
    $ easy_install pip==dev
 3) Install packages with pip:
@@ -40,14 +46,16 @@
 
 # -- Configuring Quantum plug-in
 
-1) Explore sample and real Quantum plug-ins in the quantum.plugins module.
+1) Identify your desired plug-in.  Choose a plugin from one of he options in
+   the quantum/plugins directory.
 
-2) Or copy another Quantum plug-in into the quantum.plugins module.
+2) Update plug-in configuration by editing the quantum/plugins.ini file and
+   modify "provider" property to point to the location of the Quantum plug-in.
+   It should specify the class path to the plugin and the class name (i.e. for
+   a plugin class MyPlugin in quantum/plugins/myplugin/myplugin.py the
+   provider would be: quantum.plugins.myplugin.myplugin.MyPlugin)
 
-3) Update plug-in configuration by editing plugins.ini file and modify
+3) Read the plugin specific README, this is usually found in the same
-   "provider" property to point to the location of the Quantum plug-in.
-
-4) Read the plugin specific README, this is usually found in the same
    directory as your Quantum plug-in, and follow configuration instructions.
 
 # -- Launching the Quantum Service
@@ -63,8 +71,8 @@ Please refer to sample Web Service client code in:
 
 # -- CLI tools to program the Quantum-managed Cloud networking fabric
 
-Quantum comes with a programmatic CLI that is driven by the Quantum Web Service
+Quantum comes with a programmatic CLI that is driven by the Quantum Web
-You can use the CLI by issuing the following command:
+Service.  You can use the CLI by issuing the following command:
 
 ~/src/quantum$ PYTHONPATH=.:$PYTHONPATH python quantum/cli.py
 
@@ -85,16 +93,16 @@ well as sample plugins available in:
 
 There are a few requirements to writing your own plugin:
 
-1) Your plugin should implement all methods defined in
+1) Your plugin should implement all methods defined in the
-../quantum/quantum/quantum_plugin_base.QuantumPluginBase class
+   quantum/quantum_plugin_base.QuantumPluginBase class
 
-2) Copy your Quantum plug-in over to the ../quantum/quantum/plugins/.. directory
+2) Copy your Quantum plug-in over to the quantum/quantum/plugins/.. directory
 
 3) The next step is to edit the plugins.ini file in the same directory
    as QuantumPluginBase class and specify the location of your custom plugin
    as the "provider"
 
-4) Launch the Quantum Service, and your plug-in is configured and ready to manage
+4) Launch the Quantum Service, and your plug-in is configured and ready to
-   a Cloud Networking Fabric.
+   manage a Cloud Networking Fabric.
 
 

quantum/plugins/openvswitch/README

@@ -43,11 +43,13 @@ To prep mysql, run:
 
 $ 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:
+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
 $ mysql -u root -p
-//grant access to user-remote host combination
+// grant access to user-remote host combination.  Note: if you're going to use
+// a wildcard here it should be a management network with only trusted hosts.
 mysql> GRANT USAGE ON *.* to root@'yourremotehost' IDENTIFIED BY 'newpassword';
 //force update of authorization changes
 mysql> FLUSH PRIVILEGES;
@@ -70,6 +72,7 @@ $ make agent-dist
 - Unpack the tarball and run install.sh.  This will install all of the
   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.
+  Make sure to specify this in your nova flagfile as --flat_network_bridge.
 - Run the agent [on your hypervisor (dom0)]:
 $ /etc/xapi.d/plugins/ovs_quantum_agent.py /etc/xapi.d/plugins/ovs_quantum_plugin.ini
 
@@ -86,21 +89,19 @@ This will show help all of the available commands.
 An example session looks like this:
 
 $ export TENANT=t1
-$ PYTHONPATH=. python quantum/cli.py -v create_net $TENANT network1
+$ PYTHONPATH=. python quantum/cli.py 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 -v create_port $TENANT $NETWORK
+$ PYTHONPATH=. python quantum/cli.py 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 -v plug_iface $TENANT $NETWORK $PORT ubuntu1-eth1
+$ PYTHONPATH=. python quantum/cli.py 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
-$ PYTHONPATH=. python quantum/cli.py -v plug_iface $TENANT $NETWORK $PORT ubuntu2-eth1
-Plugged interface "ubuntu2-eth1" to port:5a1e121b-ccc8-471d-9445-24f15f9f854c on network:e754e7c0-a8eb-40e5-861a-b182d30c3441
 
-Now you should have connectivity between ubuntu1-eth1 and ubuntu2-eth1..
+(.. repeat for more ports and interface combinations..)
 
 # -- Other items
 
-- To get a listing of the vif names that the ovs quantum service will expect
+- To get a listing of the vif names in the format that the ovs quantum service
-  them in, issue the following command on the hypervisor (dom0):
+  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