License
=======

 Dataplane Automated Testing System

 Copyright (c) 2015-2016, Intel Corporation.
 Copyright (c) 2016, Viosoft Corporation.
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:

   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in
     the documentation and/or other materials provided with the
     distribution.
   * Neither the name of Intel Corporation nor the names of its
     contributors may be used to endorse or promote products derived
     from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Overview
========
The DATS project is aimed at characterizing dataplane performance of systems
that utilize DPDK for network communication.
DATS consists of a set of scripts written in Python. It uses PROX as
the network traffic generator and receiver at the Tester side.
PROX with corresponding configurations is also used to run workloads on
the System Under Test (SUT).

The dats.py script is the Dataplane Automated Testing System entry point.

All the test scripts are in tests/ and the configuration files that are needed
by the tests are in the tests/prox-configs/ directory.

By default, all tests are run. Test reports are generated into distinctive
dats-report-START_TIME/ directories, where the START_TIME suffix represents the
time when DATS was started, according to the YYYYmmdd_HHMMSS format.

The system requires its dats.cfg config file to run. The example config file
dats.cfg.example provides comments about all settings.


Prerequisites
=============
DATS should work with any DPDK version supported by PROX. It has been tested
using DPDK v2.2.0.

DATS-v033 requires PROX-v033 and the following packages on both the
Tester and the SUT:
    ssh
    killall
    make

Both the Tester and the SUT should also allow network traffic on port 8474.

The following packages, or their equivalents for the Linux distribution in use,
are required on the machine where DATS is run:
    gnuplot
    docutils
    rst2pdf


Installation
============
Install DPDK and PROX-v033, both on the Tester (the machine that will
generate the network traffic) and on the SUT (System Under Test).

DATS can be installed on a third computer, or on the same machine as the Tester.

Create the dats.cfg config file in the DATS directory and, for both the Tester
and the SUT, specify the respective paths to the top level DPDK and PROX
directories.

Make sure that you can connect to both the SUT and the Tester using SSH public
key authentication:
    $ ssh-copy-id <SUT_User>@<SUT_IP>
    $ ssh-copy-id <Tester_User>@<Tester_IP>

If either SUT_User or Tester_User is not root, you also need to configure sudo
on the SUT and/or on the Tester so that this user can sudo without having to
provide a password.


How to run
==========
Start from the example config file and adjust it to your setup:
    $ cp dats.cfg.example dats.cfg
    $ vi dats.cfg

Run DATS:
    $ python dats.py


Reading the report
==================
The main report file is summary.html, generated into the distinctive
dats-report-START_TIME/ directory.