diff --git a/README.rst b/README.rst
index c8e1a23..222c680 100644
--- a/README.rst
+++ b/README.rst
@@ -88,346 +88,3 @@ VMTP will display the results to stdout with the following data:
     |   |   |  average, min, max and stddev round trip time in ms
 
 Detailed results can also be stored in a file in JSON format using the *--json* command line argument.
-
-
-Installation
-============
-
-For people who wants to do development for VMTP, it is recommended to set up the develop environments as below. However, for people who just wants to run the tool, or without root access, please refer to the "How to Run VMTP Tool" section and use VMTP Docker Image instead.
-
-Here is an example for Ubuntu developers, and similar packages can be found and installed on RPM-based distro as well.
-
-.. code::
-
-    $ sudo apt-get install python-dev python-virtualenv git git-review
-    $ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev
-    $ virtualenv vmtpenv
-    $ source vmtpenv/bin/activate
-    $ git clone git://git.openstack.org/stackforge/vmtp
-    $ cd vmtp
-    $ pip install -r requirements-dev.txt
-    $ python vmtp.py -h
-
-
-How to Run VMTP Tool
-====================
-
-
-VMTP Docker Image
------------------
-
-In its Docker image form, VMTP is located under the /vmtp directory in the container and can either take arguments from the host shell, or can be executed from inside the Docker image shell.
-
-To run VMTP directly from the host shell (may require "sudo" up front if not root)
-
-.. code::
-
-    docker run <vmtp-docker-image-name> python /vmtp/vmtp.py <args>
-
-To run VMTP from the Docker image shell:
-
-.. code::
-
-    docker run <vmtp-docker-image-name> /bin/bash
-    cd /vmtp.py
-    python vmtp.py <args>
-
-(then type exit to exit and terminate the container instance)
-
-
-Docker Shared Volume to Share Files with the Container
-------------------------------------------------------
-
-VMTP can accept files as input (e.g. configuration and openrc file) and can generate json results into a file.
-
-It is possible to use the VMTP Docker image with files persisted on the host by using Docker shared volumes.
-
-For example, one can decide to mount the current host directory as /vmtp/shared in the container in read-write mode.
-
-To get a copy of the VMTP default configuration file from the container:
-
-.. code::
-
-    docker run -v $PWD:/vmtp/shared:rw <docker-vmtp-image-name>  cp /vmtp/cfg.default.yaml /vmtp/shared/mycfg.yaml
-
-Assume you have edited the configuration file "mycfg.yaml" and retrieved an openrc file "admin-openrc.sh" from Horizon on the local directory and would like to get results back in the "res.json" file, you can export the current directory ($PWD), map it to /vmtp/shared in the container in read/write mode, then run the script in the container by using files from the shared directory:
-
-.. code::
-
-    docker run -v $PWD:/vmtp/shared:rw -t <docker-vmtp-image-name> python /vmtp/vmtp.py -c shared/mycfg.yaml -r shared/admin-openrc.sh -p admin --json shared/res.json
-    cat res.json
-
-
-Print VMTP Usage
-----------------
-
-.. code::
-
-    usage: vmtp.py [-h] [-c <config_file>] [-r <openrc_file>]
-                   [-m <gmond_ip>[:<port>]] [-p <password>] [-t <time>]
-                   [--host <user>@<host_ssh_ip>[:<server-listen-if-name>]]
-                   [--external-host <user>@<ext_host_ssh_ip>]
-                   [--access_info {host:<hostip>, user:<user>, password:<pass>}]
-                   [--mongod_server <server ip>] [--json <file>]
-                   [--tp-tool nuttcp|iperf] [--hypervisor name]
-                   [--inter-node-only] [--protocols T|U|I]
-                   [--bandwidth <bandwidth>] [--tcpbuf <tcp_pkt_size1,...>]
-                   [--udpbuf <udp_pkt_size1,...>] [--no-env] [-d] [-v]
-                   [--stop-on-error] [--vm_image_url <url_to_image>]
-
-    OpenStack VM Throughput V2.0.0
-
-    optional arguments:
-      -h, --help            show this help message and exit
-      -c <config_file>, --config <config_file>
-                            override default values with a config file
-      -r <openrc_file>, --rc <openrc_file>
-                            source OpenStack credentials from rc file
-      -m <gmond_ip>[:<port>], --monitor <gmond_ip>[:<port>]
-                            Enable CPU monitoring (requires Ganglia)
-      -p <password>, --password <password>
-                            OpenStack password
-      -t <time>, --time <time>
-                            throughput test duration in seconds (default 10 sec)
-      --host <user>@<host_ssh_ip>[:<server-listen-if-name>]
-                            native host throughput (targets requires ssh key)
-      --external-host <user>@<ext_host_ssh_ip>
-                            external-VM throughput (target requires ssh key)
-      --access_info {host:<hostip>, user:<user>, password:<pass>}
-                            access info for control host
-      --mongod_server <server ip>
-                            provide mongoDB server IP to store results
-      --json <file>         store results in json format file
-      --tp-tool nuttcp|iperf
-                            transport perf tool to use (default=nuttcp)
-      --hypervisor name     hypervisor to use in the avail zone (1 per arg, up to
-                            2 args)
-      --inter-node-only     only measure inter-node
-      --protocols T|U|I     protocols T(TCP), U(UDP), I(ICMP) - default=TUI (all)
-      --bandwidth <bandwidth>
-                            the bandwidth limit for TCP/UDP flows in K/M/Gbps,
-                            e.g. 128K/32M/5G. (default=no limit)
-      --tcpbuf <tcp_pkt_size1,...>
-                            list of buffer length when transmitting over TCP in
-                            Bytes, e.g. --tcpbuf 8192,65536. (default=65536)
-      --udpbuf <udp_pkt_size1,...>
-                            list of buffer length when transmitting over UDP in
-                            Bytes, e.g. --udpbuf 128,2048. (default=128,1024,8192)
-      --no-env              do not read env variables
-      -d, --debug           debug flag (very verbose)
-      -v, --version         print version of this script and exit
-      --stop-on-error       Stop and keep everything as-is on error (must cleanup
-                            manually)
-      --vm_image_url <url_to_image>
-                            URL to a Linux image in qcow2 format that can be
-                            downloaded from
-
-Configuration File
-^^^^^^^^^^^^^^^^^^
-
-VMTP configuration files follow the yaml syntax and contain variables used by VMTP to run and collect performance data.
-
-The default configuration is stored in the cfg.default.yaml file.
-
-Default values should be overwritten for any cloud under test by defining new variable values in a new configuration file that follows the same format. Variables that are not defined in the new configuration file will retain their default values.
-
-Parameters that you are most certainly required to change are:
-
-* The VM image name to use to run the performance tools, you will need to specify any standard Linux image (Ubuntu 12.04, 14.04, Fedora, RHEL7, CentOS...) - if needed you will need to upload an image to OpenStack manually prior to running VMTP
-* VM SSH user name to use (specific to the image)
-* The flavor name to use (often specific to each cloud)
-* Name of the availability zone to use for running the performance test VMs (also specific to each cloud)
-
-Check the content of cfg.default.yaml file as it contains the list of configuration variables and instructions on how to set them.
-
-Create one configuration file for your specific cloud and use the *-c* option to pass that file name to VMTP.
-
-**Note:** the configuration file is not needed if the VMTP only runs the native host throughput option (*--host*)
-
-
-OpenStack openrc file
-^^^^^^^^^^^^^^^^^^^^^
-
-VMTP requires downloading an "openrc" file from the OpenStack Dashboard (Project|Acces&Security!Api Access|Download OpenStack RC File)
-
-This file should then be passed to VMTP using the *-r* option or should be sourced prior to invoking VMTP.
-
-**Note:** the openrc file is not needed if VMTP only runs the native host throughput option (*--host*)
-
-
-Bandwidth Limit for TCP/UDP Flow Measurements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Specify a value in *--bandwidth* will limit the bandwidth when performing throughput tests.
-
-The default behavior for both TCP/UDP are unlimited. For TCP, we are leveraging on the protocol itself to get the best performance; while for UDP, we are doing a binary search to find the optimal bandwidth.
-
-This is useful when running vmtp on production clouds. The test tool will use up all the bandwidth that may be needed by any other live VMs if we don't set any bandwidth limit. This feature will help to prevent impacting other VMs while running the test tool.
-
-
-Host Selection in Availability Zone
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The *--hypervisor* argument can be used to specify explicitly where to run the test VM in the configured availability zone.
-
-This can be handy for example when exact VM placement can impact the data path performance (for example rack based placement when the availability zone spans across multiple racks).
-
-The first *--hypervisor* argument specifies on which host to run the test server VM. The second *--hypervisor* argument (in the command line) specifies on which host to run the test client VMs.
-
-The value of the argument must match the hypervisor host name as known by OpenStack (or as displayed using "nova hypervisor-list")
-
-Example of usage is given below.
-
-Upload Images to Glance
-^^^^^^^^^^^^^^^^^^^^^^^
-
-VMTP requires a Linux image available in Glance to spawn VMs. It could be uploaded manually through Horizon or CLI, or VMTP will try to upload the image defined in the configuration file automatically.
-
-There is a candidate image defined in the default config already. It has been verified working, but of course it is OK to try other Linux distro as well.
-
-**NOTE:** Due to the limitation of the Python glanceclient API (v2.0), it is not able to create the image directly from a remote URL. So the implementation of this feature used a glance CLI command instead. Be sure to source the OpenStack rc file first before running VMTP with this feature.
-
-
-Examples of running VMTP on an OpenStack Cloud
-----------------------------------------------
-
-Preparation
-^^^^^^^^^^^
-
-Download the openrc file from OpenStack Dashboard, and saved it to your local file system. (In Horizon dashboard: Project|Acces&Security!Api Access|Download OpenStack RC File)
-
-Upload the Linux image to the OpenStack controller node, so that OpenStack is able to spawning VMs. You will be prompted an error if the Ubuntu image is not available to use when running the tool. The image can be uploaded using either Horizon dashboard, or the command below:
-
-.. code::
-
-    python vmtp.py -r admin-openrc.sh -p admin --vm_image_url http://<url_to_the_image>
-
-**Note:** Currently, VMTP only supports the Linux image in qcow2 format.
-
-If executing a VMTP Docker image "docker run" (or "sudo docker run") must be placed in front of these commands unless you run a shell script directly from inside the container.
-
-Example 1: Typical Run
-""""""""""""""""""""""
-Run VMTP on an OpenStack cloud with the default configuration file, use "admin-openrc.sh" as the rc file, and "admin" as the password.
-
-.. code::
-
-    python vmtp.py -r admin-openrc.sh -p admin
-
-This will generate 6 standard sets of performance data:
-(1) VM to VM same network (intra-node, private fixed IP)
-(2) VM to VM different network (intra-node, L3 fixed IP)
-(3) VM to VM different network and tenant (intra-node, floating IP)
-(4) VM to VM same network (inter-node, private fixed IP)
-(5) VM to VM different network (inter-node, L3 fixed IP)
-(6) VM to VM different network and tenant (inter-node, floating IP)
-
-By default, the performance data of all three protocols (TCP/UDP/ICMP) will be measured for each scenario mentioned above. However, it can be overridden by providing *--protocols*. E.g.
-
-.. code::
-
-    python vmtp.py -r admin-openrc.sh -p admin --protocols IT
-
-This will tell VMTP to only collect ICMP and TCP measurements.
-
-Example 2: Cloud upload/download performance measurement
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-Run VMTP on an OpenStack cloud with a specified configuration file (mycfg.yaml), and saved the result to a JSON file:
-
-.. code::
-
-    python vmtp.py -c mycfg.yaml -r admin-openrc.sh -p admin --external_host localadmin@172.29.87.29 --json res.json
-
-This run will generate 8 sets of performance data, the standard 6 sets mentioned above, plus two sets of upload/download performance data for both TCP and UDP.
-
-**Note:** In order to perform the upload/download performance test, an external server must be specified and configured with SSH password-less access. See below for more info.
-
-Example 3: Specify which availability zone to spawn VMs
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-Run VMTP on an OpenStack cloud, spawn the test server VM on tme212, and the test client VM on tme210. Save the result, and perform the inter-node measurement only.
-
-.. code::
-
-    python vmtp.py -r admin-openrc.sh -p lab --inter-node-only --json res.json --hypervisor tme212 --hypervisor tme210
-
-Example 4: Collect native host performance data
-"""""""""""""""""""""""""""""""""""""""""""""""
-
-Run VMTP to get native host throughput between 172.29.87.29 and 172.29.87.30 using the localadmin ssh username and run each tcp/udp test session for 120 seconds (instead of the default 10 seconds):
-
-.. code::
-
-    python vmtp.py --host localadmin@172.29.87.29 --host localadmin@172.29.87.30 --time 120
-
-**Note:** This command requires each host to have the VMTP public key (ssh/id_rsa.pub) inserted into the ssh/authorized_keys file in the username home directory, i.e. SSH password-less access. See below for more info.
-
-Example 5: Measurement on pre-existing VMs
-""""""""""""""""""""""""""""""""""""""""""
-
-It is possible to run VMTP between pre-existing VMs that are accessible through SSH (using floating IP).
-
-The first IP passed (*--host*) is always the one running the server side. Optionally a server side listening interface name can be passed if clients should connect using a particular server IP. For example, to measure throughput between 2 hosts using the network attached to the server interface "eth5":
-
-.. code::
-
-    python vmtp.py --host localadmin@172.29.87.29:eth5 --host localadmin@172.29.87.30
-
-**Note:** Prior to running, the VMTP public key must be installed on each VM.
-
-Setups
-======
-
-Public Cloud
-------------
-
-Public clouds are special because they may not expose all OpenStack APIs and may not allow all types of operations. Some public clouds have limitations in the way virtual networks can be used or require the use of a specific external router. Running VMTP against a public cloud will require a specific configuration file that takes into account those specificities.
-
-Refer to the provided public cloud sample configuration files for more information.
-
-SSH Password-less Access
-------------------------
-
-For host throughput (*--host*), VMTP expects the target hosts to be pre-provisioned with a public key in order to allow password-less SSH.
-
-Test VMs are created through OpenStack by VMTP with the appropriate public key to allow password-less ssh. By default, VMTP uses a default VMTP public key located in ssh/id_rsa.pub, simply append the content of that file into the .ssh/authorized_keys file under the host login home directory).
-
-**Note:** This default VMTP public key should only be used for transient test VMs and **MUST NOT** be used to provision native hosts since the corresponding private key is open to anybody! To use alternate key pairs, the 'private_key_file' variable in the configuration file must be overridden to point to the file containing the private key to use to connect with SSH.
-
-
-Implementations
-===============
-
-TCP Throughput Measurement
---------------------------
-
-The TCP throughput reported is measured using the default message size of the test tool (64KB with nuttcp). The TCP MSS (maximum segment size) used is the one suggested by the TCP-IP stack (which is dependent on the MTU).
-
-
-UDP Throughput Measurement
---------------------------
-UDP throughput is tricky because of limitations of the performance tools used, limitations of the Linux kernel used and criteria for finding the throughput to report.
-
-The default setting is to find the "optimal" throughput with packet loss rate within the 2%~5% range. This is achieved by successive iterations at different throughput values.
-
-In some cases, it is not possible to converge with a loss rate within that range and trying to do so may require too many iterations. The algorithm used is empiric and tries to achieve a result within a reasonable and bounded number of iterations. In most cases the optimal throughput is found in less than 30 seconds for any given flow.
-
-**Note:** UDP measurements are only available with nuttcp (not available with iperf).
-
-
-Caveats and Known Issues
-========================
-
-* UDP throughput is not available if iperf is selected (the iperf UDP reported results are not reliable enough for iterating)
-
-* If VMTP hangs for native hosts throughputs, check firewall rules on the hosts to allow TCP/UDP ports 5001 and TCP port 5002
-
-
-Links
-=====
-
-* Documentation: http://docs.openstack.org/developer/vmtp
-* Source: http://git.openstack.org/cgit/stackforge/vmtp
-* Bugs: http://bugs.launchpad.net/vmtp
-
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..a3cd27f
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/vmtp.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/vmtp.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/vmtp"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/vmtp"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/doc/source/conf.py b/doc/source/conf.py
old mode 100755
new mode 100644
index de6fea3..6f93aff
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -1,44 +1,83 @@
 # -*- coding: utf-8 -*-
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
 #
-#    http://www.apache.org/licenses/LICENSE-2.0
+# vmtp documentation build configuration file, created by
+# sphinx-quickstart on Fri Feb 13 14:43:59 2015.
 #
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-# implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
 
-import os
+import datetime
 import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
 
 sys.path.insert(0, os.path.abspath('../..'))
-# -- General configuration ----------------------------------------------------
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
 extensions = [
-    'sphinx.ext.autodoc',
+   'sphinx.ext.autodoc'
     #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    #'oslosphinx'
 ]
 
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
 project = u'vmtp'
-copyright = u'2013, OpenStack Foundation'
+copyright = u"%d, OpenStack Foundation" % datetime.datetime.now().year
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '2.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -47,29 +86,179 @@ add_function_parentheses = True
 # unit titles (such as .. function::).
 add_module_names = True
 
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# -- Options for HTML output --------------------------------------------------
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
 
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
-# html_theme = '_theme'
-# html_static_path = ['static']
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
+htmlhelp_basename = 'vmtpdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
-     u'OpenStack Foundation', 'manual'),
+  ('index', 'vmtp.tex', u'vmtp Documentation',
+   u'OpenStack Foundation', 'manual'),
 ]
 
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'vmtp', u'vmtp Documentation',
+     [u'OpenStack Foundation'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'vmtp', u'vmtp Documentation',
+   u'OpenStack Foundation', 'vmtp', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2041757..8dbbfa2 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,10 +1,10 @@
 .. vmtp documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+   sphinx-quickstart on Fri Feb 13 14:43:59 2015.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
 Welcome to vmtp's documentation!
-========================================================
+================================
 
 Contents:
 
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 5a57705..ea288ec 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -2,11 +2,17 @@
 Installation
 ============
 
-At the command line::
+For people who wants to do development for VMTP, it is recommended to set up the develop environments as below. However, for people who just wants to run the tool, or without root access, please refer to the "How to Run VMTP Tool" section and use VMTP Docker Image instead.
 
-    $ pip install vmtp
+Here is an example for Ubuntu developers, and similar packages can be found and installed on RPM-based distro as well.
 
-Or, if you have virtualenvwrapper installed::
+.. code::
 
-    $ mkvirtualenv vmtp
-    $ pip install vmtp
+    $ sudo apt-get install python-dev python-virtualenv git git-review
+    $ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev
+    $ virtualenv vmtpenv
+    $ source vmtpenv/bin/activate
+    $ git clone git://git.openstack.org/stackforge/vmtp
+    $ cd vmtp
+    $ pip install -r requirements-dev.txt
+    $ python vmtp.py -h
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index d80eb84..3f4a729 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,7 +1,323 @@
-========
+=====
 Usage
-========
+=====
 
-To use vmtp in a project::
+VMTP Docker Image
+-----------------
+
+In its Docker image form, VMTP is located under the /vmtp directory in the container and can either take arguments from the host shell, or can be executed from inside the Docker image shell.
+
+To run VMTP directly from the host shell (may require "sudo" up front if not root)::
+
+    docker run <vmtp-docker-image-name> python /vmtp/vmtp.py <args>
+
+To run VMTP from the Docker image shell::
+
+    docker run <vmtp-docker-image-name> /bin/bash
+    cd /vmtp.py
+    python vmtp.py <args>
+
+(then type exit to exit and terminate the container instance)
+
+
+Docker Shared Volume to Share Files with the Container
+------------------------------------------------------
+
+VMTP can accept files as input (e.g. configuration and openrc file) and can generate json results into a file.
+
+It is possible to use the VMTP Docker image with files persisted on the host by using Docker shared volumes.
+
+For example, one can decide to mount the current host directory as /vmtp/shared in the container in read-write mode.
+
+To get a copy of the VMTP default configuration file from the container::
+
+    docker run -v $PWD:/vmtp/shared:rw <docker-vmtp-image-name>  cp /vmtp/cfg.default.yaml /vmtp/shared/mycfg.yaml
+
+Assume you have edited the configuration file "mycfg.yaml" and retrieved an openrc file "admin-openrc.sh" from Horizon on the local directory and would like to get results back in the "res.json" file, you can export the current directory ($PWD), map it to /vmtp/shared in the container in read/write mode, then run the script in the container by using files from the shared directory::
+
+    docker run -v $PWD:/vmtp/shared:rw -t <docker-vmtp-image-name> python /vmtp/vmtp.py -c shared/mycfg.yaml -r shared/admin-openrc.sh -p admin --json shared/res.json
+    cat res.json
+
+
+VMTP Usage
+----------
+
+.. code::
+
+    usage: vmtp.py [-h] [-c <config_file>] [-r <openrc_file>]
+                   [-m <gmond_ip>[:<port>]] [-p <password>] [-t <time>]
+                   [--host <user>@<host_ssh_ip>[:<server-listen-if-name>]]
+                   [--external-host <user>@<ext_host_ssh_ip>]
+                   [--access_info '{"host":"<hostip>", "user":"<user>", "password":"<pass>"}']
+                   [--mongod_server <server ip>] [--json <file>]
+                   [--tp-tool nuttcp|iperf] [--hypervisor name]
+                   [--inter-node-only] [--protocols T|U|I]
+                   [--bandwidth <bandwidth>] [--tcpbuf <tcp_pkt_size1,...>]
+                   [--udpbuf <udp_pkt_size1,...>] [--no-env] [-d] [-v]
+                   [--stop-on-error] [--vm_image_url <url_to_image>]
+
+    OpenStack VM Throughput V2.0.0
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -c <config_file>, --config <config_file>
+                            override default values with a config file
+      -r <openrc_file>, --rc <openrc_file>
+                            source OpenStack credentials from rc file
+      -m <gmond_ip>[:<port>], --monitor <gmond_ip>[:<port>]
+                            Enable CPU monitoring (requires Ganglia)
+      -p <password>, --password <password>
+                            OpenStack password
+      -t <time>, --time <time>
+                            throughput test duration in seconds (default 10 sec)
+      --host <user>@<host_ssh_ip>[:<server-listen-if-name>]
+                            native host throughput (targets requires ssh key)
+      --external-host <user>@<ext_host_ssh_ip>
+                            external-VM throughput (target requires ssh key)
+      --access_info '{"host":"<hostip>", "user":"<user>", "password":"<pass>"}'
+                            access info for the controller node
+      --mongod_server <server ip>
+                            provide mongoDB server IP to store results
+      --json <file>         store results in json format file
+      --tp-tool nuttcp|iperf
+                            transport perf tool to use (default=nuttcp)
+      --hypervisor name     hypervisor to use in the avail zone (1 per arg, up to
+                            2 args)
+      --inter-node-only     only measure inter-node
+      --protocols T|U|I     protocols T(TCP), U(UDP), I(ICMP) - default=TUI (all)
+      --bandwidth <bandwidth>
+                            the bandwidth limit for TCP/UDP flows in K/M/Gbps,
+                            e.g. 128K/32M/5G. (default=no limit)
+      --tcpbuf <tcp_pkt_size1,...>
+                            list of buffer length when transmitting over TCP in
+                            Bytes, e.g. --tcpbuf 8192,65536. (default=65536)
+      --udpbuf <udp_pkt_size1,...>
+                            list of buffer length when transmitting over UDP in
+                            Bytes, e.g. --udpbuf 128,2048. (default=128,1024,8192)
+      --no-env              do not read env variables
+      -d, --debug           debug flag (very verbose)
+      -v, --version         print version of this script and exit
+      --stop-on-error       Stop and keep everything as-is on error (must cleanup
+                            manually)
+      --vm_image_url <url_to_image>
+                            URL to a Linux image in qcow2 format that can be
+                            downloaded from
+
+
+Configuration File
+^^^^^^^^^^^^^^^^^^
+
+VMTP configuration files follow the yaml syntax and contain variables used by VMTP to run and collect performance data.
+
+The default configuration is stored in the cfg.default.yaml file.
+
+Default values should be overwritten for any cloud under test by defining new variable values in a new configuration file that follows the same format. Variables that are not defined in the new configuration file will retain their default values.
+
+Parameters that you are most certainly required to change are:
+
+* The VM image name to use to run the performance tools, you will need to specify any standard Linux image (Ubuntu 12.04, 14.04, Fedora, RHEL7, CentOS...) - if needed you will need to upload an image to OpenStack manually prior to running VMTP
+* VM SSH user name to use (specific to the image)
+* The flavor name to use (often specific to each cloud)
+* Name of the availability zone to use for running the performance test VMs (also specific to each cloud)
+
+Check the content of cfg.default.yaml file as it contains the list of configuration variables and instructions on how to set them.
+
+Create one configuration file for your specific cloud and use the *-c* option to pass that file name to VMTP.
+
+**Note:** the configuration file is not needed if the VMTP only runs the native host throughput option (*--host*)
+
+
+OpenStack openrc File
+^^^^^^^^^^^^^^^^^^^^^
+
+VMTP requires downloading an "openrc" file from the OpenStack Dashboard (Project|Acces&Security!Api Access|Download OpenStack RC File)
+
+This file should then be passed to VMTP using the *-r* option or should be sourced prior to invoking VMTP.
+
+**Note:** the openrc file is not needed if VMTP only runs the native host throughput option (*--host*)
+
+
+Access Info for Controller Node
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, VMTP is not able to get the Linux distro nor the OpenStack version of the cloud deployment. However, by providing the credentials of the controller node, VMTP will try to fetch these information, and output them along in the JSON file or to the MongoDB server.
+
+
+Bandwidth Limit for TCP/UDP Flow Measurements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Specify a value in *--bandwidth* will limit the bandwidth when performing throughput tests.
+
+The default behavior for both TCP/UDP are unlimited. For TCP, we are leveraging on the protocol itself to get the best performance; while for UDP, we are doing a binary search to find the optimal bandwidth.
+
+This is useful when running vmtp on production clouds. The test tool will use up all the bandwidth that may be needed by any other live VMs if we don't set any bandwidth limit. This feature will help to prevent impacting other VMs while running the test tool.
+
+
+Host Selection in Availability Zone
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *--hypervisor* argument can be used to specify explicitly where to run the test VM in the configured availability zone.
+
+This can be handy for example when exact VM placement can impact the data path performance (for example rack based placement when the availability zone spans across multiple racks).
+
+The first *--hypervisor* argument specifies on which host to run the test server VM. The second *--hypervisor* argument (in the command line) specifies on which host to run the test client VMs.
+
+The value of the argument must match the hypervisor host name as known by OpenStack (or as displayed using "nova hypervisor-list")
+
+Example of usage is given below.
+
+Upload Images to Glance
+^^^^^^^^^^^^^^^^^^^^^^^
+
+VMTP requires a Linux image available in Glance to spawn VMs. It could be uploaded manually through Horizon or CLI, or VMTP will try to upload the image defined in the configuration file automatically.
+
+There is a candidate image defined in the default config already. It has been verified working, but of course it is OK to try other Linux distro as well.
+
+**NOTE:** Due to the limitation of the Python glanceclient API (v2.0), it is not able to create the image directly from a remote URL. So the implementation of this feature used a glance CLI command instead. Be sure to source the OpenStack rc file first before running VMTP with this feature.
+
+
+Examples of running VMTP on an OpenStack Cloud
+----------------------------------------------
+
+Preparation
+^^^^^^^^^^^
+
+Download the openrc file from OpenStack Dashboard, and saved it to your local file system. (In Horizon dashboard: Project|Acces&Security!Api Access|Download OpenStack RC File)
+
+Upload the Linux image to the OpenStack controller node, so that OpenStack is able to spawning VMs. You will be prompted an error if the Ubuntu image is not available to use when running the tool. The image can be uploaded using either Horizon dashboard, or the command below:
+
+.. code::
+
+    python vmtp.py -r admin-openrc.sh -p admin --vm_image_url http://<url_to_the_image>
+
+**Note:** Currently, VMTP only supports the Linux image in qcow2 format.
+
+If executing a VMTP Docker image "docker run" (or "sudo docker run") must be placed in front of these commands unless you run a shell script directly from inside the container.
+
+Example 1: Typical Run
+""""""""""""""""""""""
+Run VMTP on an OpenStack cloud with the default configuration file, use "admin-openrc.sh" as the rc file, and "admin" as the password::
+
+    python vmtp.py -r admin-openrc.sh -p admin
+
+This will generate 6 standard sets of performance data:
+(1) VM to VM same network (intra-node, private fixed IP)
+(2) VM to VM different network (intra-node, L3 fixed IP)
+(3) VM to VM different network and tenant (intra-node, floating IP)
+(4) VM to VM same network (inter-node, private fixed IP)
+(5) VM to VM different network (inter-node, L3 fixed IP)
+(6) VM to VM different network and tenant (inter-node, floating IP)
+
+By default, the performance data of all three protocols (TCP/UDP/ICMP) will be measured for each scenario mentioned above. However, it can be overridden by providing *--protocols*. E.g.::
+
+    python vmtp.py -r admin-openrc.sh -p admin --protocols IT
+
+This will tell VMTP to only collect ICMP and TCP measurements.
+
+Example 2: Cloud upload/download performance measurement
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Run VMTP on an OpenStack cloud with a specified configuration file (mycfg.yaml), and saved the result to a JSON file::
+
+    python vmtp.py -c mycfg.yaml -r admin-openrc.sh -p admin --external_host localadmin@172.29.87.29 --json res.json
+
+This run will generate 8 sets of performance data, the standard 6 sets mentioned above, plus two sets of upload/download performance data for both TCP and UDP.
+
+**Note:** In order to perform the upload/download performance test, an external server must be specified and configured with SSH password-less access. See below for more info.
+
+
+Example 3: Store the OpenStack deployment details
+"""""""""""""""""""""""""""""""""""""""""""""""""
+
+Run VMTP on an OpenStack cloud, fetch the defails of the deployment and store it to JSON file. Assume the controlloer node is on 192.168.12.34 with admin/admin::
+
+    pythn vmtp.py -r admin-openrc.sh -p admin --json res.json --access_info '{"host":"192.168.12.34", "user":"admin", "password":"admin"}'
+
+
+Example 4: Specify which availability zone to spawn VMs
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Run VMTP on an OpenStack cloud, spawn the test server VM on tme212, and the test client VM on tme210. Save the result, and perform the inter-node measurement only::
+
+    python vmtp.py -r admin-openrc.sh -p admin --inter-node-only --json res.json --hypervisor tme212 --hypervisor tme210
+
+Example 5: Collect native host performance data
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Run VMTP to get native host throughput between 172.29.87.29 and 172.29.87.30 using the localadmin ssh username and run each tcp/udp test session for 120 seconds (instead of the default 10 seconds)::
+
+    python vmtp.py --host localadmin@172.29.87.29 --host localadmin@172.29.87.30 --time 120
+
+**Note:** This command requires each host to have the VMTP public key (ssh/id_rsa.pub) inserted into the ssh/authorized_keys file in the username home directory, i.e. SSH password-less access. See below for more info.
+
+Example 6: Measurement on pre-existing VMs
+""""""""""""""""""""""""""""""""""""""""""
+
+It is possible to run VMTP between pre-existing VMs that are accessible through SSH (using floating IP).
+
+The first IP passed (*--host*) is always the one running the server side. Optionally a server side listening interface name can be passed if clients should connect using a particular server IP. For example, to measure throughput between 2 hosts using the network attached to the server interface "eth5"::
+
+    python vmtp.py --host localadmin@172.29.87.29:eth5 --host localadmin@172.29.87.30
+
+**Note:** Prior to running, the VMTP public key must be installed on each VM.
+
+
+======
+Setups
+======
+
+Public Cloud
+------------
+
+Public clouds are special because they may not expose all OpenStack APIs and may not allow all types of operations. Some public clouds have limitations in the way virtual networks can be used or require the use of a specific external router. Running VMTP against a public cloud will require a specific configuration file that takes into account those specificities.
+
+Refer to the provided public cloud sample configuration files for more information.
+
+SSH Password-less Access
+------------------------
+
+For host throughput (*--host*), VMTP expects the target hosts to be pre-provisioned with a public key in order to allow password-less SSH.
+
+Test VMs are created through OpenStack by VMTP with the appropriate public key to allow password-less ssh. By default, VMTP uses a default VMTP public key located in ssh/id_rsa.pub, simply append the content of that file into the .ssh/authorized_keys file under the host login home directory).
+
+**Note:** This default VMTP public key should only be used for transient test VMs and **MUST NOT** be used to provision native hosts since the corresponding private key is open to anybody! To use alternate key pairs, the 'private_key_file' variable in the configuration file must be overridden to point to the file containing the private key to use to connect with SSH.
+
+
+===============
+Implementations
+===============
+
+TCP Throughput Measurement
+--------------------------
+
+The TCP throughput reported is measured using the default message size of the test tool (64KB with nuttcp). The TCP MSS (maximum segment size) used is the one suggested by the TCP-IP stack (which is dependent on the MTU).
+
+
+UDP Throughput Measurement
+--------------------------
+UDP throughput is tricky because of limitations of the performance tools used, limitations of the Linux kernel used and criteria for finding the throughput to report.
+
+The default setting is to find the "optimal" throughput with packet loss rate within the 2%~5% range. This is achieved by successive iterations at different throughput values.
+
+In some cases, it is not possible to converge with a loss rate within that range and trying to do so may require too many iterations. The algorithm used is empiric and tries to achieve a result within a reasonable and bounded number of iterations. In most cases the optimal throughput is found in less than 30 seconds for any given flow.
+
+**Note:** UDP measurements are only available with nuttcp (not available with iperf).
+
+
+========================
+Caveats and Known Issues
+========================
+
+* UDP throughput is not available if iperf is selected (the iperf UDP reported results are not reliable enough for iterating)
+
+* If VMTP hangs for native hosts throughputs, check firewall rules on the hosts to allow TCP/UDP ports 5001 and TCP port 5002
+
+
+=====
+Links
+=====
+
+* Documentation: http://vmtp.readthedocs.org/en/latest
+* Source: http://git.openstack.org/cgit/stackforge/vmtp
+* Bugs: http://bugs.launchpad.net/vmtp
 
-    import vmtp
diff --git a/sshutils.py b/sshutils.py
index 39fc227..5927326 100644
--- a/sshutils.py
+++ b/sshutils.py
@@ -386,11 +386,11 @@ class SSH(object):
                 return None
 
             for line in data.splitlines():
-                mobj = re.match(r'PRETTY_NAME=(.*)', line)
+                mobj = re.match(r'NAME=(.*)', line)
                 if mobj:
                     name = mobj.group(1).strip("\"")
 
-                mobj = re.match(r'VERSION.*=(.*)', line)
+                mobj = re.match(r'VERSION_ID=(.*)', line)
                 if mobj:
                     version = mobj.group(1).strip("\"")
 
@@ -433,28 +433,43 @@ class SSH(object):
 
         return None
 
+    def get_openstack_release(self, ver_str):
+        '''
+        Get the release series name from the package version
+        Refer to here for release tables:
+        https://wiki.openstack.org/wiki/Releases
+        '''
+        ver_table = {"2015.1": "Kilo",
+                     "2014.2": "Juno",
+                     "2014.1": "Icehouse",
+                     "2013.2": "Havana",
+                     "2013.1": "Grizzly",
+                     "2012.2": "Folsom",
+                     "2012.1": "Essex",
+                     "2011.3": "Diablo",
+                     "2011.2": "Cactus",
+                     "2011.1": "Bexar",
+                     "2010.1": "Austin"}
+
+        ver_prefix = re.search(r"20\d\d\.\d", ver_str).group(0)
+        if ver_prefix in ver_table:
+            return ver_table[ver_prefix]
+        else:
+            return "Unknown"
+
     def check_openstack_version(self):
         '''
         Identify the openstack version running on the controller.
         '''
-        version_file = "/tmp/version.txt"
-        nova_cmd = "nova --version >> " + version_file
-
+        nova_cmd = "nova-manage --version"
         (status, _, err_output) = self.execute(nova_cmd)
+
         if status:
-            return None
-
-        if err_output.strip() == "2.17.0":
-            return "icehouse"
-        else:
-            return "juno"
-
-
-
-
-
-
+            return "Unknown"
 
+        ver_str = err_output.strip()
+        release_str = self.get_openstack_release(err_output)
+        return release_str + " (" + ver_str + ")"
 
 
 ##################################################
@@ -467,9 +482,11 @@ def main():
     print 'ID=' + ssh.distro_id
     print 'ID_LIKE=' + ssh.distro_id_like
     print 'VERSION_ID=' + ssh.distro_version
+
     ssh.wait()
     print ssh.pidof('bash')
     print ssh.stat('/tmp')
+    print ssh.check_openstack_version()
 
 if __name__ == "__main__":
     main()
diff --git a/test-requirements.txt b/test-requirements.txt
index 101b769..e73033e 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -8,8 +8,9 @@ coverage>=3.6
 discover
 python-subunit>=0.0.18
 sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
-oslosphinx>=2.2.0  # Apache-2.0
-oslotest>=1.2.0  # Apache-2.0
-testrepository>=0.0.18 
+testrepository>=0.0.18
 testscenarios>=0.4
 testtools>=0.9.36,!=1.2.0
+
+oslosphinx>=2.2.0  # Apache-2.0
+oslotest>=1.2.0  # Apache-2.0
diff --git a/vmtp.py b/vmtp.py
index 92408ab..55c78b9 100755
--- a/vmtp.py
+++ b/vmtp.py
@@ -111,22 +111,37 @@ class ResultsCollector(object):
     def pprint(self, res):
         self.ppr.pprint(res)
 
-    def save(self, filename):
+    def save(self, cfg):
         '''Save results in json format file.'''
-        print('Saving results in json file: ' + filename)
-        with open(filename, 'w') as jfp:
+        if cfg.access_username and cfg.access_host:
+            print 'Fetching OpenStack deployment details...'
+            sshcon = sshutils.SSH(cfg.access_username,
+                                  cfg.access_host,
+                                  password=cfg.access_password)
+            if sshcon is not None:
+                self.results['distro'] = sshcon.get_host_os_version()
+                self.results['openstack_version'] = sshcon.check_openstack_version()
+            else:
+                print 'ERROR: Cannot connect to the controlloer node.'
+
+        print('Saving results in json file: ' + cfg.json_file + "...")
+        with open(cfg.json_file, 'w') as jfp:
             json.dump(self.results, jfp, indent=4, sort_keys=True)
 
     def save_to_db(self, cfg):
         '''Save resutls to MongoDB database.'''
-        print "Saving results to MongoDB database."
-        sshcon = sshutils.SSH(cfg.access_username,
-                              cfg.access_host,
-                              password=cfg.access_password)
-        if sshcon is not None:
-            self.results['distro'] = sshcon.get_host_os_version()
-            self.results['openstack_version'] = sshcon.check_openstack_version()
+        if cfg.access_username and cfg.access_host:
+            print 'Fetching OpenStack deployment details...'
+            sshcon = sshutils.SSH(cfg.access_username,
+                                  cfg.access_host,
+                                  password=cfg.access_password)
+            if sshcon is not None:
+                self.results['distro'] = sshcon.get_host_os_version()
+                self.results['openstack_version'] = sshcon.check_openstack_version()
+            else:
+                print 'ERROR: Cannot connect to the controlloer node.'
 
+        print "Saving results to MongoDB database..."
         post_id = pns_mongo.\
             pns_add_test_result_to_mongod(cfg.pns_mongod_ip,
                                           cfg.pns_mongod_port,
@@ -204,13 +219,13 @@ class VmtpTest(object):
                         glance_endpoint, token=keystone.auth_token)
                     self.comp.upload_image_via_url(
                         glance_client, config.image_name, config.vm_image_url)
+                    self.image_instance = self.comp.find_image(config.image_name)
                 else:
                     # Exit the pogram
                     print '%s: image to launch VM not found. ABORTING.' \
                         % (config.image_name)
                     sys.exit(1)
 
-            self.image_instance = self.comp.find_image(config.image_name)
             self.assert_true(self.image_instance)
             print 'Found image %s to launch VM, will continue' % (config.image_name)
             self.flavor_type = self.comp.find_flavor(config.flavor_type)
@@ -501,8 +516,8 @@ if __name__ == '__main__':
 
     parser.add_argument('--access_info', dest='access_info',
                         action='store',
-                        help='access info for control host',
-                        metavar='{host:<hostip>, user:<user>, password:<pass>}')
+                        help='access info for the controller node',
+                        metavar='\'{"host":"<hostip>", "user":"<user>", "password":"<pass>"}\'')
 
     parser.add_argument('--mongod_server', dest='mongod_server',
                         action='store',
@@ -779,7 +794,7 @@ if __name__ == '__main__':
         vmtp.run()
 
     if config.json_file:
-        rescol.save(config.json_file)
+        rescol.save(config)
 
     if config.pns_mongod_ip:
         rescol.save_to_db(config)