The PAS package provides a command line utility and a measuring framework for network analysis for the Parallel Object Programming protocol.
The tool allows to start POP-C++ nodes, run measure cases, capture the traffic and produce a complete report of the exchanged TCP packets between the peers.
By default, the test infrastructure is set up using vagrant and some virtual machines automatically configured using chef, but it is possible to use any remote machine with ssh access and some configuration work (involving mainly installing the needed dependencies and creating some shared folders).
Although this tool was developed especially for the C++ implementation of the POP model, it was conceived to make as less assumptions as possible about the underlying implementation and could easily be adapted to measure POP objects offered by other implementations such, for example, as POP-Java
Further information about the POP-C++ project and the POP model can be found on the project’s homepage.
The requirements necessary to install and run the pas utility are the following:
- Python >= 2.6 – http://python.org/;
- vagrant and VirtualBox to run the virtual machines – http://vagrantup.com/;
- A webkit based browser (Safari, Google Chrome,...) to display the reports.
The following libraries and utilities are optional but add some additional features:
- xmllint used to reformat the XML documents produced by the measures;
- tidy used to cleanup the HTML output of the reports (note that the absence of this utility will add more entries to the list of unsupported browsers).
The Python packages that will automatically be installed by setuptools are the following ones:
- fabric to dispatch commands to remote machines through ssh – http://fabfile.org/;
- pygments to highlight the source code and the decoded transactions – http://pygments.org/;
- lxml to transform the different measure xml files – http://codespeak.net/lxml/.
Until a stable release is packaged and uploaded to the cheese shop, the latest development snapshot can be installed directly from the github hosted sources using easy_install or pip:
$ pip install https://github.com/GaretJax/pop-analysis-suite/tarball/master
Note
Often, depending on the target system, the installation of a python package requires root privileges. If the previous command fails, retry to run it with sudo.
To check if the package was correctly installed, run the the pas command on the command line:
$ pas
You should obtain an incorrect usage error similar to the following:
usage: pas [-h] [--version] [-v] [-q] [--settings SETTINGS_MODULE]
{authorize,execute,jobmgr,compile,init,measure} ...
pas: error: too few arguments
It is possible to install the PAS package directly from source. The following commands should get you started:
$ wget --no-check-certificate https://github.com/GaretJax/pop-analysis-suite/tarball/master
$ tar -xzf GaretJax-pop-analysis-suite-*.tar.gz
$ cd GaretJax-pop-analysis-suite-*
$ python setup.py install
To install the PAS package, the setuptools package is required (for both source or remote installation modes). Albeit coming preinstalled on all major unix based operating systems you may need to install it.
You can obtain further information about setuptools either on its pypi project page or on its official homepage.
The whole development of the PAS project happens on github, you can find the source repository at the following address: https://github.com/GaretJax/pop-analysis-suite/
Further development/contribution directives will be added as soon as some interest is manifested by any hacker willing to participate in the development process.
This manual is conceived to offer an incremental approach to all feature which the pas has to offer. It is structured in three main parts:
The first part describes and documents the common usage of the tool, the assumptions it mades about different aspects such as VM setups, object communications, file locations and so on.
Once read and understood this first part, a user should be able to complete a full measure cycle with a custom developed measure case and generate a report to further analyze.
The second part dives in the internals of the pas libraries and documents topics such as command customization, custom type parsing or complex measurement setups, useful if a user want to completely adapt the offered functionalities to his needs.
The third part contains reference documentation useful for both a basic or an advanced usage. There are references for all built-in commands, for the different settings directives or for more advanced topics such as the internal APIs.
This three parts are completed with this introduction, a glossary of common terms and an alphabetical content index.
The present document is written using Sphinx and it can either be read online thanks to readthedocs.org or built locally using the sphinx tool into various different formats.
To create a local build, make sure to have the sphinx package installed and run the following commands:
$ git clone https://github.com/GaretJax/pop-analysis-suite/
$ cd pop-analysis-suite/docs
$ make html # or any other format; run make without arguments to find out
# the supported ones
The documentation builds will then be placed in the _build/<format> subdirectory.