diff --git a/README.rst b/README.rst index b45d48b..c8e1a23 100644 --- a/README.rst +++ b/README.rst @@ -4,20 +4,24 @@ VMTP What is VMTP ============ + VMTP is a data path performance tool for OpenStack clouds. Features -------- VMTP is a python application that will automatically perform ping connectivity, ping round trip time measurement (latency) and TCP/UDP throughput measurement for the following flows on any OpenStack deployment: + * VM to VM same network (private fixed IP) * VM to VM different network same tenant (intra-tenant L3 fixed IP) * VM to VM different network and tenant (floating IP inter-tenant L3) Optionally, when an external Linux host is available: + * External host/VM download and upload throughput/latency (L3/floating IP) Optionally, when SSH login to any Linux host (native or virtual) is available: + * Host to host throughput (intra-node and inter-node) Optionally, VMTP can extract automatically CPU usage from all native hosts in the cloud during the throughput tests, provided the Ganglia monitoring service (gmond) is installed and enabled on those hosts. @@ -26,53 +30,64 @@ For VM-related flows, VMTP will automatically create the necessary OpenStack res In the case involving pre-existing native or virtual hosts, VMTP will SSH to the targeted hosts to perform measurements. -Pre-requisite -------------- +Pre-requisite to run VMTP +------------------------- -* For VM related performance measurements: - * Access to the cloud Horizon Dashboard - * 1 working external network pre-configured on the cloud (VMTP will pick the first one found) - * At least 2 floating IP if an external router is configured or 3 floating IP if there is no external router configured - * 1 Linux image available in OpenStack (any distribution) - * A configuration file that is properly set for the cloud to test (see "Configuration File" section below) +For VM related performance measurements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* For native/external host throughput: - * A public key must be installed on the target hosts (see ssh password-less access below) - -* For pre-existing native host throughputs: - * Firewalls must be configured to allow TCP/UDP ports 5001 and TCP port 5002 +* Access to the cloud Horizon Dashboard +* 1 working external network pre-configured on the cloud (VMTP will pick the first one found) +* At least 2 floating IP if an external router is configured or 3 floating IP if there is no external router configured +* 1 Linux image available in OpenStack (any distribution) +* A configuration file that is properly set for the cloud to test (see "Configuration File" section below) + +For native/external host throughputs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* A public key must be installed on the target hosts (see ssh password-less access below) + +For pre-existing native host throughputs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Firewalls must be configured to allow TCP/UDP ports 5001 and TCP port 5002 + +For running VMTP Docker Image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Docker is installed. See `here `_ for instructions. -* Docker is installed if using the VMTP Docker image Sample Results Output --------------------- VMTP will display the results to stdout with the following data: -* Session general information (date, auth_url, OpenStack encaps, VMTP version...) -* List of results per flow, for each flow: +.. code:: - * flow name - * to and from IP addresses - * to and from availability zones (if VM) - * results: - * TCP - * packet size - * throughput value - * number of retransmissions - * round trip time in ms - * CPU usage (if enabled), for each host in the openstack cluster: - * baseline (before test starts) - * 1 or more readings during test - * UDP - * for each packet size - * throughput value - * loss rate - * CPU usage (if enabled) - * ICMP - * average, min, max and stddev round trip time in ms + - Session general information (date, auth_url, OpenStack encaps, VMTP version...) + - List of results per flow, for each flow: + | flow name + | to and from IP addresses + | to and from availability zones (if VM) + | - results: + | | -TCP + | | | packet size + | | | throughput value + | | | number of retransmissions + | | | round trip time in ms + | | | - CPU usage (if enabled), for each host in the openstack cluster + | | | | baseline (before test starts) + | | | | 1 or more readings during test + | | -UDP + | | | - for each packet size + | | | | throughput value + | | | | loss rate + | | | | CPU usage (if enabled) + | | - ICMP + | | | 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. +Detailed results can also be stored in a file in JSON format using the *--json* command line argument. Installation @@ -82,8 +97,10 @@ For people who wants to do development for VMTP, it is recommended to set up the Here is an example for Ubuntu developers, and similar packages can be found and installed on RPM-based distro as well. -.. code-block:: none - $ sudo apt-get install python-dev python-virtualenv git git-review libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev +.. 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 @@ -103,12 +120,14 @@ In its Docker image form, VMTP is located under the /vmtp directory in the conta To run VMTP directly from the host shell (may require "sudo" up front if not root) -.. code-block:: none +.. code:: + docker run python /vmtp/vmtp.py To run VMTP from the Docker image shell: -.. code-block:: none +.. code:: + docker run /bin/bash cd /vmtp.py python vmtp.py @@ -127,85 +146,90 @@ For example, one can decide to mount the current host directory as /vmtp/shared To get a copy of the VMTP default configuration file from the container: -.. code-block:: none +.. code:: + docker run -v $PWD:/vmtp/shared:rw 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-block:: none +.. code:: + docker run -v $PWD:/vmtp/shared:rw -t 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 ---------------- -``` -usage: vmtp.py [-h] [-c ] [-r ] - [-m [:]] [-p ] [-t