File	Date	Author	Commit
ClusterGen	2013-07-31	Artyom Poptsov	[f14d82] TargetConfigurationDialog.java: Fix a bug.
pktd	2013-07-30	Artyom Poptsov	[d01ba4] Bump version to 2.1
.gitignore	2013-03-15	Artyom Poptsov	[3a9ccd] .gitignore: Update.
AUTHORS	2013-04-19	Artyom Poptsov	[4bf2da] Update documentation.
COPYING	2012-06-20	Artyom Poptsov	[e6636c] Initial commit
ChangeLog	2013-07-31	Artyom Poptsov	[3f7f49] NEWS: Update.
NEWS	2013-07-31	Artyom Poptsov	[3f7f49] NEWS: Update.
README	2013-04-19	Artyom Poptsov	[4bf2da] Update documentation.
TODO	2013-04-19	Artyom Poptsov	[4bf2da] Update documentation.

Read Me

			ClusterGen

ClusterGen is a traffic generator which uses pktgen Linux kernel
module for packet generation.  To reach high intensity of traffic,
ClusterGen uses set of hosts that generate traffic at the same time.

ClusterGen is capable of:
 - Grouping hosts into cluster and managing this cluster (add more
   hosts, remove hosts, monitoring hosts)
 - Configuring traffic generation parameters for the whole cluster in
   transparent manner (User configures parameters only once and each
   host configuration is handled by ClusterGen)
 - Calculating packet losses (works only with pktgen v2.75).
 - Simultaneous traffic generation on all hosts (start/stop traffic).
 - Collection, accumulation and representation of statistics

Supported traffic model and parameters are determined by pktgen kernel
module capabilities.  ClusterGen is only responsible for interaction
with kernel module.

Project was initially written and being developed by MERA
<http://www.merasws.com/>

It is distributed under GNU General Public License version 3 or (at
your option) any later version.  See COPYING for details.


	1. HOW IT WORKS

ClusterGen contains two parts:
 - Daemon (pktd) written in C for communicating directly with kernel
   pktgen module on a host, and
 - Graphical user interface written in Java which is used for
   configuring cluster, controlling traffic and collecting statistics.

pktd interacts with pktgen through procfs file system. It doesn't do
any processing of data.  Instead all work is done on server side,
where ClusterGen is running.

There are no authorization mechanisms so far - any connection is
considered as valid, so you should care about security.


	2. VERY SHORT DESCRIPTION OF PKTGEN

pktgen is a module for the Linux Kernel which allows to generate
traffic with high intensity.  pktgen uses UDP protocol because it has
smaller overhead than TCP.  If destination port isn't configured,
pktgen uses port number 9 (discard port).  procfs is used to control
it and getting statistics.

If destination IP isn't configured, pktgen will use localhost as
destination.  In this case generated packets won't go out into real
network.


	3. BUILD AND INSTALL

To build pktd, do the following:

    $ cd clustergen/pktd
    $ ./configure
    $ make

For general instructions for building pktd see pktd/INSTALL

To install pktd on host, the Linux kernel should be compiled with
pktgen.  If pktgen compiled as module, you should load it with

    $ modbrobe pktgen

To build ClusterGen, you must have Apache Ant and Java Development Kit
(JDK) installed.  Then, you can build ClusterGen as following:

    $ cd clustergen/ClusterGen
    $ ant

jar-file will be placed in clustergen/ClusterGen/dist/


	4. USAGE

	4.1 Starting up pktd

Just copy pktd on every host that you want to use for traffic
generation.  You must have there the Linux kernel with pktgen
installed.

pktd must be running from root UID, otherwise it will not be able to
communicate with pktgen:

    $ su -
    # pktd

pktd listens connections from ClusterGen on port number 10101 by
default.  You can set a custom port by passing it to pktd from the
command line:

    # pktd 11100

For emergency stop traffic on host, just kill pktd process:

    $ sudo pkill pktd


	4.2 Starting up ClusterGen

Then run ClusterGen on a server and add hosts to the list.

    $ java -jar clustergen/ClusterGen/dist/ClusterGen.jar

ClusterGen will fetch information about hosts (number of CPUs, existed
NICs) as soon as they become available.