VMTP PyPI Installation and Quick Start Guide

1. Installation

PyPI (The Python Package Index) is the most popular distribution repository for software in Python. The latest stable version of VMTP can be installed from PyPI using pip.

Step 1

Install required libraries. Run the command based on your distro.

Ubuntu/Debian based:

$ sudo apt-get install build-essential python-dev python-pip python-virtualenv git git-review
$ sudo apt-get install libxml2-dev libxslt-dev libffi-dev libz-dev libyaml-dev libssl-dev

RHEL/CentOS based:

$ sudo yum install gcc python-devel python-pip python-virtualenv git
$ sudo yum install libxml2-devel libxslt-devel libffi-devel libyaml-devel openssl-devel

MacOSX:

$ # Download the XCode command line tools from Apple App Store
$ xcode-select --install
$ sudo easy_install pip
$ sudo pip install virtualenv

Step 2

Create a virtual environment for Python, and install VMTP:

$ virtualenv ./vmtpenv
$ . ./vmtpenv/bin/activate
$ pip install vmtp
$ vmtp -h

Note

“A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.” It is optional but recommended. If isolation among multiple Python projects is not needed, we could use instead:

$ sudo pip install vmtp

2. Key Pair

VMTP requires a key pair to use to ssh to the test VMs that it will launch in OpenStack. You can use the current user’s key pair (located in $HOME/.ssh on the host where you run the container) if they exist:

$ ls -l ~/.ssh/id*
-rw------- 1 localadmin localadmin 1679 Mar  9  2015 /home/localadmin/.ssh/id_rsa
-rw-r--r-- 1 localadmin localadmin  400 Mar  9  2015 /home/localadmin/.ssh/id_rsa.pub

Otherwise you need to create a key pair on your host:

ssh-keygen -t rsa

3. Download RC file

VMTP requires downloading an “openrc” file from the OpenStack Dashboard (Project|Acces&Security!Api Access|Download OpenStack RC File). That RC file is required to connect to OpenStack using the OpenStack API. This file should be passed to VMTP using the -r option or should be sourced prior to invoking VMTP. In this example we assume the RC file is saved in the current directory under the name “admin-openrc.sh”.

4. Preparation steps with OpenStack

In the VMTP virtual environment, you can run any OpenStack CLI command (since the virtual environment will have all standard OpenStack client packages installed along with VMTP). Source the RC file so we can execute the CLI commands:

source admin-openrc.sh

4.1. Verify flavor names

If you are planning to reuse an existing flavor, we will have to check the flavor names available to select one flavor that VMTP should use to launch VM instances. List the flavors (results may be different):

$ nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name      | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1  | m1.tiny   | 512       | 1    | 0         |      | 1     | 1.0         | True      |
| 2  | m1.small  | 2048      | 20   | 0         |      | 1     | 1.0         | True      |
| 3  | m1.medium | 4096      | 40   | 0         |      | 2     | 1.0         | True      |
| 4  | m1.large  | 8192      | 80   | 0         |      | 4     | 1.0         | True      |
| 5  | m1.xlarge | 16384     | 160  | 0         |      | 8     | 1.0         | True      |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
$

Otherwise, a temporary flavor can be created for you from the config file specification (Step 5).

4.2. Upload any Linux VM image to OpenStack

VMTP requires a standard Linux VM image to run its tests in OpenStack. You can skip this step if you already have a standard Linux VM image in your OpenStack (Ubuntu, Fedora, RHEL…).

Otherwise, you can upload any Linux VM image using the glance CLI or using the Horizon dashboard. In the example below we will upload the Ubuntu 14.04 cloud image available from the uec-images.ubuntu.com web site using the glance CLI and we will name it “Ubuntu Server 14.04”.

If your OpenStack can access directly the Internet:

glance --os-image-api-version 1 image-create --copy-from http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu Server 14.04'

The glance command will return immediately but it will take some time for the file to get transferred. You will need to check for the status of the image before you can use it (will “queued”, then “saving” then “active” if there is no issue).

If you prefer to make a local copy of the image:

wget http://uec-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-uefi1.img

Then copy it to OpenStack using the glance CLI:

glance --os-image-api-version 1 image-create --file /tmp/vmtp/trusty-server-cloudimg-amd64-uefi1.img --disk-format qcow2 --container-format bare --name 'Ubuntu 14.04'

Then list the images to verify:

$ glance image-list
+--------------------------------------+---------------------+
| ID                                   | Name                |
+--------------------------------------+---------------------+
| 5d7899d9-811c-483f-82b3-282a9bf143bf | cirros              |
| 443ee290-b714-4bfe-9acb-b996ed6cc118 | Ubuntu 14.04        |
+--------------------------------------+---------------------+
$ glance image-show 443ee290-b714-4bfe-9acb-b996ed6cc118
+------------------+--------------------------------------+
| Property         | Value                                |
+------------------+--------------------------------------+
| checksum         | 479a314d90cefc163fdcfb875a070cd8     |
| container_format | bare                                 |
| created_at       | 2016-07-04T17:53:20Z                 |
| disk_format      | qcow2                                |
| id               | 443ee290-b714-4bfe-9acb-b996ed6cc118 |
| min_disk         | 0                                    |
| min_ram          | 0                                    |
| name             | Ubuntu 14.04                         |
| owner            | 5d912149f7474804824a463464874a21     |
| protected        | False                                |
| size             | 268829184                            |
| status           | active                               |
| tags             | []                                   |
| updated_at       | 2016-07-04T18:06:38Z                 |
| virtual_size     | None                                 |
| visibility       | private                              |
+------------------+--------------------------------------+
$

5. Create your VMTP config file

Get a copy of the default VMTP configuration file and save it in the local directory:

vmtp -sc > vmtp.cfg

Edit the vmtp.cfg file and make sure the following parameters are set properly:

  • “image_name” must be the image name to use by VMTP (‘Ubuntu Server 14.04’ in the above example)
  • “ssh_vm_username” must be a valid user name for the Linux image (“ubuntu” for Ubuntu images)
  • “flavor_type” must be either an appropriate flavor name (step 4.1 above) or a custom flavor will be created with “flavor_type” name and specification declared in “flavor” config.
  • “flavor” must be the specification of a custom flavor that will be created in case “flavor_type” is non-existing in OpenStack.

6. Run VMTP

VMTP options used:

  • -d : debug mode (more verbose)
  • -c vmtp.cfg : specify the config file to use
  • -r admin-openrc.sh : specify the RC file to use
  • -p secret : specify the OpenStack password to use (replace with your own password)
  • –protocol T : only do TCP throughput test (shorter time)
  • –json test.json : save results in json format to a file
vmtp -d -c vmtp.cfg -r admin-openrc.sh -p secret --protocol T --json test.json

This should produce an output similar to this (a complete run with the above options should take around 15 minutes but may vary based on the control plane speed of your OpenStack cloud):

Using http://172.29.86.28:5000/v2.0
VM public key:  /home/localadmin/.ssh/id_rsa.pub
VM private key: /home/localadmin/.ssh/id_rsa
Found image Ubuntu Server 14.04 to launch VM, will continue
Using external network: ext-net
Found external router: demo-router
Created internal network: pns-internal-net
Created internal network: pns-internal-net2
Ext router associated to pns-internal-net
Ext router associated to pns-internal-net2
OpenStack agent: Open vSwitch agent
OpenStack network type: vlan
[TestServer1] Creating server VM...
[TestServer1] Starting on zone nova:compute-server-2
[TestServer1] VM status=BUILD, retrying 1 of 50...
[TestServer1] VM status=BUILD, retrying 2 of 50...
...
[TestServer1] Floating IP 10.23.220.45 created
[TestServer1] Started - associating floating IP 10.23.220.45
[TestServer1] Internal network IP: 192.168.1.3
[TestServer1] SSH IP: 10.23.220.45
[TestServer1] Setup SSH for ubuntu@10.23.220.45
[TestServer1] Installing nuttcp-7.3.2...
[TestServer1] Copying nuttcp-7.3.2 to target...
[TestServer1] Starting nuttcp-7.3.2 server...
[TestServer1]
[TestClient1] Creating client VM...
[TestClient1] Starting on zone nova:compute-server-2
[TestClient1] VM status=BUILD, retrying 1 of 50...
[TestClient1] VM status=BUILD, retrying 2 of 50...
...
[TestClient1] Floating IP 10.23.220.46 created
[TestClient1] Started - associating floating IP 10.23.220.46
[TestClient1] Internal network IP: 192.168.1.4
[TestClient1] SSH IP: 10.23.220.46
[TestClient1] Setup SSH for ubuntu@10.23.220.46
[TestClient1] Installing nuttcp-7.3.2...
[TestClient1] Copying nuttcp-7.3.2 to target...
============================================================
Flow 1: VM to VM same network fixed IP (intra-node)
[TestClient1] Measuring TCP Throughput (packet size=65536)...
[TestClient1] /tmp/nuttcp-7.3.2 -T10  -l65536 -p5001 -P5002 -fparse 192.168.1.3
[TestClient1] megabytes=20329.1875 real_seconds=10.00 rate_Mbps=17049.6212 tx_cpu=92 rx_cpu=53 retrans=0 rtt_ms=0.47
...
{   'az_from': u'nova:compute-server-2',
    'az_to': u'nova:compute-server-2',
    'desc': 'VM to VM same network fixed IP (intra-node)',
    'distro_id': 'Ubuntu',
    'distro_version': '14.04',
    'ip_from': u'192.168.1.4',
    'ip_to': u'192.168.1.3',
    'results': [   {   'pkt_size': 65536,
                       'protocol': 'TCP',
                       'rtt_ms': 0.47,
                       'throughput_kbps': 17458812,
                       'tool': 'nuttcp-7.3.2'},
                   {   'pkt_size': 65536,
                       'protocol': 'TCP',
                       'rtt_ms': 0.19,
                       'throughput_kbps': 13832383,
                       'tool': 'nuttcp-7.3.2'},
                   {   'pkt_size': 65536,
                       'protocol': 'TCP',
                       'rtt_ms': 0.21,
                       'throughput_kbps': 17130867,
                       'tool': 'nuttcp-7.3.2'}]}
[TestClient1] Floating IP 10.23.220.46 deleted
[TestClient1] Instance deleted
[TestClient2] Creating client VM...
[TestClient2] Starting on zone nova:compute-server-2
[TestClient2] VM status=BUILD, retrying 1 of 50...
[TestClient2] VM status=BUILD, retrying 2 of 50...

...

---- Cleanup ----
[TestServer1] Terminating nuttcp-7.3.2
[TestServer1] Floating IP 10.23.220.45 deleted
[TestServer1] Instance deleted
Network pns-internal-net deleted
Network pns-internal-net2 deleted
Removed public key pns_public_key
Deleting security group

Summary of results
==================
Total Scenarios:   22
Passed Scenarios:  5 [100.00%]
Failed Scenarios:  0 [0.00%]
Skipped Scenarios: 17
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| Scenario | Scenario Name                                    | Functional Status | Data                                         |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
| 1.1      | Same Network, Fixed IP, Intra-node, TCP          | PASSED            | {'tp_kbps': '16140687', 'rtt_ms': '0.29'}    |
| 1.2      | Same Network, Fixed IP, Intra-node, UDP          | SKIPPED           | {}                                           |
| 1.3      | Same Network, Fixed IP, Intra-node, ICMP         | SKIPPED           | {}                                           |
| 2.1      | Same Network, Fixed IP, Inter-node, TCP          | PASSED            | {'tp_kbps': '4082749', 'rtt_ms': '0.5'}      |
| 2.2      | Same Network, Fixed IP, Inter-node, UDP          | SKIPPED           | {}                                           |
| 2.3      | Same Network, Fixed IP, Inter-node, ICMP         | SKIPPED           | {}                                           |
| 3.1      | Different Network, Fixed IP, Intra-node, TCP     | PASSED            | {'tp_kbps': '2371753', 'rtt_ms': '0.386667'} |
| 3.2      | Different Network, Fixed IP, Intra-node, UDP     | SKIPPED           | {}                                           |
| 3.3      | Different Network, Fixed IP, Intra-node, ICMP    | SKIPPED           | {}                                           |
| 4.1      | Different Network, Fixed IP, Inter-node, TCP     | PASSED            | {'tp_kbps': '2036303', 'rtt_ms': '0.623333'} |
| 4.2      | Different Network, Fixed IP, Inter-node, UDP     | SKIPPED           | {}                                           |
| 4.3      | Different Network, Fixed IP, Inter-node, ICMP    | SKIPPED           | {}                                           |
| 5.1      | Different Network, Floating IP, Intra-node, TCP  | PASSED            | {'tp_kbps': '2260145', 'rtt_ms': '0.476667'} |
| 5.2      | Different Network, Floating IP, Intra-node, UDP  | SKIPPED           | {}                                           |
| 5.3      | Different Network, Floating IP, Intra-node, ICMP | SKIPPED           | {}                                           |
| 6.1      | Different Network, Floating IP, Inter-node, TCP  | PASSED            | {'tp_kbps': '2134303', 'rtt_ms': '0.543333'} |
| 6.2      | Different Network, Floating IP, Inter-node, UDP  | SKIPPED           | {}                                           |
| 6.3      | Different Network, Floating IP, Inter-node, ICMP | SKIPPED           | {}                                           |
| 7.1      | Native Throughput, TCP                           | SKIPPED           | {}                                           |
| 7.2      | Native Throughput, UDP                           | SKIPPED           | {}                                           |
| 7.3      | Native Throughput, ICMP                          | SKIPPED           | {}                                           |
| 8.1      | VM to Host Uploading                             | SKIPPED           | {}                                           |
| 8.2      | VM to Host Downloading                           | SKIPPED           | {}                                           |
+----------+--------------------------------------------------+-------------------+----------------------------------------------+
Saving results in json file: test.json...

8. Generate the results chart from the JSON result file

Assuming the json result file is saved by the container run the vmtp_genchart container command from the host current directory:

$ vmtp_genchart -c test.html test.json
Generating chart drawing code to /tmp/vmtp/test.html...
$

vmtp_genchart options:

  • -c test.html : save the generated html file to the mapped directory
  • test.json : the json file that contains the results of the VMTP run

The fie is available in the current directory and can be viewed with any browser:

$ ls -l test.html
-rw-r--r-- 1 root root 1557 Jul  4 14:10 test.html