+ All Categories
Home > Documents > Harpoon Manual

Harpoon Manual

Date post: 04-Apr-2018
Category:
Upload: luis-anducho
View: 245 times
Download: 0 times
Share this document with a friend
51
Harpoon A Flow-level Trac Generator User manual Joel Sommers
Transcript

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 1/51

Harpoon

A Flow-level Traffic GeneratorUser manual

Joel Sommers

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 2/51

This manual is for the Harpoon Flow-level Traffic Generator. The followingcopyright notice covers the Harpoon source code, including all documenta-tion, images, and ancillary files.

Copyright c 2004-2005, Joel E. Sommers. All rights reserved.

This file is part of Harpoon, a flow-level traffic generator.

Harpoon is free software; you can redistribute it and/or modify itunder the terms of the GNU General Public License as publishedby the Free Software Foundation; either version 2 of the License,or (at your option) any later version.

Harpoon is distributed in the hope that it will be useful, but WITH-OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-POSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with Harpoon; if not, write to the Free Software Foundation,Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 3/51

i

Table of Contents

1 Overview of Harpoon. . . . . . . . . . . . . . . . . . . . . .

11.1 Architecture of Harpoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Harpoon Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2.1 Building the Harpoon Software . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Basic Configuration . . . . . . . . . . . . . . . . . . . . . . . . 72.1 Validating a Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Modifying Configuration File Addresses . . . . . . . . . . . . . . . . . . . . . . . 92.3 Starting Harpoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.4 Modifying a Configuration to Produce Different Traffic Volumes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3 Advanced Configuration . . . . . . . . . . . . . . . . . . . 153.1 Self-Configuration Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.2 The harpoon_flowproc tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.3 The harpoon_conf.py tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.4 The harpoon_reconf.py tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.5 Configuration File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.5.1 <plugin> Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.5.2 Configuring Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.5.3 Configuring Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.5.4 Putting It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.5.5 Nesting Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 Running Harpoon . . . . . . . . . . . . . . . . . . . . . . . . 244.1 The harpoon executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4.1.1 harpoon command-line parameters . . . . . . . . . . . . . . . . . . . . . . 244.1.2 Signals Handled by Harpoon . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.1.3 Harpoon Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.1.4 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.2 Validating a configuration file with config_validator . . . . . . . . 264.3 Self-configuration Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.3.1 harpoon_flowproc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264.3.2 harpoon_conf.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.3.3 harpoon_reconf.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 4/51

ii

5 Managing harpoon . . . . . . . . . . . . . . . . . . . . . . . . 295.1 Web-based Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.1.1 Using manage_harpoon.php . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295.1.2 Setting up Apache and PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.2 Lower-level Management Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 295.2.1 Supported XML-RPC Methods . . . . . . . . . . . . . . . . . . . . . . . . . 295.2.2 Uploading Files with HTTP PUT . . . . . . . . . . . . . . . . . . . . . . . . 31

Appendix A More Examples . . . . . . . . . . . . . . . . 33A.1 XML Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33A.2 Validation of Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34A.3 Example Using Two Hosts, Unidirectional Traffic. . . . . . . . . . . . . 35A.4 Example Using Two Hosts, Bidirectional Traffic at Different Rates

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36A.5 Example with Three Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Appendix B XML Configuration Schema . . . . 40

Appendix C Creating New Traffic GenerationModules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Postscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 5/51

Chapter 1: Overview of Harpoon 1

1 Overview of Harpoon

Harpoon is a flow-level traffic generator. It uses a set of distributional param-

eters that can be automatically extracted from Netflow traces to generateflows that exhibit the same statistical qualities present in measured Inter-net traces, including temporal and spatial characteristics. Harpoon can beused to generate representative background traffic for application or protocoltesting, or for testing network switching hardware. This manual begins bydescribing the architecture of Harpoon. Subsequent chapters describe howto effectively configure, run, and manage Harpoon.

A suggested roadmap for getting up and running with Harpoon is toread this chapter, Chapter 1 [Overview of Harpoon], page 1, followed by thenext chapter, Chapter 2 [Basic Configuration], page 7, referring as needed to

Chapter 4 [Running Harpoon], page 24 and Appendix A [More Examples],page 33 for command-line parameter, environment variable, and specific ex-amples. Readers wanting to use the self-configuration tools or to deployHarpoon in large testbeds should read the whole manual.

1.1 Architecture of Harpoon

The design objectives of Harpoon are (1) to scalably generate application-independent network traffic at the IP flow level, and (2) to be easily param-eterized to create traffic that is statistically identical to traffic measured at agiven vantage point in the Internet. Figure 1.1 [High-level data flow diagramof Harpoon] depicts a high-level process flow of these objectives. We startwith the basic definition of an IP flow and use this to create a constructivemodel for network traffic generation which we describe below. ¨

. . .

harpoon

harpoon. . .

processing

flow record

capture and

emulation

testbedoperational

network

self

configuration

Figure 1.1: High-level data flow diagram of Harpoon. IP flow records arecollected at a given vantage point in an operational network using standardsoftware like flow-tools. Key aspects of the live flows are extracted duringa self-configuration step. These parameters are used to generate traffic ina testbed that statistically matches the temporal (diurnal) volume charac-teristics as well as the spatial (source and destination IP address frequency)characteristics of the live flows.

©

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 6/51

Chapter 1: Overview of Harpoon 2

An IP flow is typically defined as a unidirectional series of IP packetsof a given protocol traveling between a source and a destination IP/portpair within a certain period of time. The final condition of this statement is

somewhat ambiguous, so we pragmatically tie our definition to Cisco’s imple-mentation of Netflow and to the tools we use to gather and analyze networkflow data. Netflow data includes source and destination AS/IP/port pairs,packet and byte counts, flow start and end times, protocol information, anda bitwise OR of TCP flags for all packets of a flow, in addition to other fields.This data is exported either on timer deadlines or when certain events occur(e.g., a TCP FIN or RST, or a cache becomes full), whichever comes first.While this would seem to pragmatically resolve ambiguity in the definitionof a flow, specific expiration-related timing behaviors can vary (see Cisco Netflow White Paper 1). The result is that flow start time stamps are accu-rate, while flow end time stamps are not. This inaccuracy does not impact

a user of Harpoon, but it does make a difference to the self-configurationtools. For more details, see the Harpoon technical paper.

From this operational definition of a flow, Harpoon’s architecture beginswith the notion of unicast file transfers using either TCP or UDP. Harpoondoes not address the packet level dynamics of TCP file transfers. Rather,it relies on the version(s) of TCP running on end hosts to transfer the re-quested file. Modeling UDP traffic is complicated by the fact that packetemission behaviors are largely application-specific. At present, Harpoon con-tains three models of UDP packet transfer: a simple parameterized constantpacket rate, a fixed-interval periodic ping-pong, and an exponentially dis-

tributed ping-pong. The first source type is similar to some audio and videostreams, while the latter two types are intended to mimic the standard Net-work Time Protocol (NTP) and Domain Name Service (DNS), respectively.UDP traffic in today’s Internet is likely to be made up of a wider variety of application level traffic (including voice, SQL worms, etc.) whose behavioris not captured in our current three source-type model. Development of amodel with a more diverse set of UDP traffic sources is left for future work.

The Harpoon flow model is a two level architecture and is depicted in Fig-ure 1.2 [Harpoon’s flow-based two level hierarchical traffic model]. We referto the lower level of the Harpoon model as the connection level . It is made upof two components that have measurable distributional properties. The firstcomponent is the size of the file transferred, and the second component is thetime interval between consecutive file transfer requests, the inter-connectiontime . Harpoon makes requests for files with sizes drawn from an empiricaldistribution P FileSize. Connection initiations are separated by time intervalsdrawn from an empirical distribution P InterConnection.

The upper level of the Harpoon model is referred to as the session level .Harpoon sessions are divided into either TCP or UDP types that conductdata transfers using the respective protocol during the time that they are

1 http://www.cisco.com/univercd/cc/td/doc/cisintwk/intsolns/netflsol/

nfwhite.htm.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 7/51

Chapter 1: Overview of Harpoon 3

active. The session level has two components: the number of  active sessions and the IP spatial distribution. By modulating the number of sessions thatare active at any point in time, Harpoon can match the byte, packet, and

flow volumes from the original data and realize the temporal (diurnal) traf-fic volumes that are a common characteristic of the Internet2. The averagenumber of sessions of each type (TCP/UDP) that are active at any point ina day is derived from a flow data time series for consecutive non-overlappingintervals of length IntervalDuration seconds to create an empirical modelfor P ActiveSessions. Scalability is naturally achieved by dividing the numberof active sessions across any number of hosts comprising the testbed. Foreach session, Harpoon picks source and destination addresses from rangesof available addresses to make a series of file transfer requests. The ad-dress selection is made preferentially using weights drawn from empiricaldistributions P IPRangesrc and P IPRangedest . A series of file transfer requests

then takes place between the source and destination for IntervalDurationseconds. When Harpoon is started, it begins with the average number of sessions in the first interval and proceeds through consecutive intervals forthe duration of the test.

In summary, the Harpoon model is made up of a combination of five dis-tributional models for TCP sessions: file size, inter-connection time, sourceand destination IP ranges, number of active sessions. There are three dis-tributional models for UDP sessions: constant bit-rate, periodic and expo-nential ping-pong. Each of these distributions can be specified manuallyor, in the case of TCP traffic, extracted from packet traces or Netflow data

collected at a live router. These models enable the workload generated byHarpoon to be application independent or to be tuned to a specific applica-tion. The models are combined in a constructive manner to create a series of file transfer requests that results in representative flow-level network traffic.The parameters for TCP sessions are summarized below:

ParameterDescription

P FileSize Empirical distribution of file sizes transferred.

P InterConnection

Empirical distribution of time between consecutive TCP con-nections initiated by an IP source-destination pair.

P IPRangesrc and P IPRangedestRanges of IP addresses with preferential weights set to matchthe empirical frequency distributions from the original data.

P ActiveSessionsThe distribution of the average number of sessions (IP source-destination pairs) active during consecutive intervals of the mea-

2 See, for example, Vern Paxson’s thesis (ftp://ftp.ee.lbl.gov/papers/vp-thesis/

dis.ps.gz).

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 8/51

Chapter 1: Overview of Harpoon 4

sured data. By modulating this distribution, Harpoon canmatch the temporal byte, packet and flow volumes from theoriginal data.

IntervalDurationTime granularity over which Harpoon matches average byte,packet and flow volumes

¨

is modulated to achieve

number of active sessions

source and destination addresses

are assigned to active sessions to

obtain desired spatial distribution

desired volumes

      

      

      

¡     

¡     

¡     

¢      

¢      

¢      

£     

£     

£     

¤ ¤      

¤ ¤      

¤ ¤      

¥ ¥     

¥ ¥     

¥ ¥     

¦      

¦      

¦      

¦      

¦      

§     

§     

§     

§     

§     

¨ ¨      

¨ ¨      

¨ ¨      

¨ ¨      

¨ ¨      

© ©     

© ©     

© ©     

© ©     

© ©     

      

      

      

      

      

     

     

     

     

     

<IP source, IP dest, protocol,

to canonical five−tuple flows:

connections are analogous

sessions are analogous to

canonical three−tuples:

<IP source, IP dest, protocol>

inter−connection times

  .  .  .

individual files source port, dest port>

blocks represent 

A B

session level 

connection level 

Figure 1.2: Harpoon’s flow-based two level hierarchical traffic model.Sessions are comprised of a series of connections separated by durationsdrawn from the inter-connection time distribution. Source and destinationIP address selection (A and B in the figure) is weighted to match the fre-quency distribution of the original flow data. The number of active sessionsdetermines the overall average load offered by Harpoon. A heavy-tailedempirical file size distribution and an ON/OFF transfer model generate self-similar packet-level behavior. ©

1.2 Harpoon Software Components

There are five programs and scripts included with Harpoon:

• harpoon, the main executable, along with traffic generation plugins  forimplementing Harpoon user-level behavior using OS-supplied protocolimplementations (e.g. TCP) or another kind of packet emission pro-cesses,

• config_validator, a utility for validating the structure of a config file.

• harpoon_flowproc, a utility for pre-processing flow records (raw Net-flow version 5 or flow-tools format) for self-configuration, and

• harpoon_conf.py, a utility for generating configuration files forharpoon (the self-configurator).

• harpoon_reconf.py, a utility for tuning existing configuration files toproduce desired traffic volumes.

harpoon, config_validator, and harpoon_flowproc are C++ programs.

Requirements for building Harpoon include a C++ compiler with a functional

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 9/51

Chapter 1: Overview of Harpoon 5

standard template library (recent versions of GCC easily satisfy this require-ment), a POSIX threads implementation, and the eXpat XML parsing li-brary3. The flow-tools4 library is optionally used by harpoon_flowproc.

If no installation of  flow-tools is found, the harpoon_flowproc tool willstill be built, but will only be able to process wire format Netflow 5 records.

The scripts harpoon_conf.py and harpoon_reconf.py require a Pythoninterpreter, version 2.3 or greater5. If a suitable Python interpreter is notfound, the other tools will be built, but a warning will appear when config-uring the software.

The traffic generation plugins exist as dynamically loadable modules (akashared libraries, dynamically linked libraries, bundles). For example, alllogic specific to generating TCP flow traffic is confined to the TCPPluginmodule and all logic specific for UDP constant bit-rate traffic generation is

confined to the UDPcbrPlugin module. (Appendix C [Creating New TrafficGeneration Modules], page 43 describes how to create modules to generateany type of desired traffic.) You do not have to know how these moduleswork to generate basic TCP or UDP-CBR traffic, but you should understandthe basic roles of the distributions used by different Harpoon plugins in orderto feed properly formatted configuration files to Harpoon.

Subsequent chapters describe how to use these tools to produce desiredtraffic. For basic configuration using sample configuration files suppliedwith the Harpoon software distribution, see Chapter 2 [Basic Configura-tion], page 7. For more extensive discussion of configuring Harpoon us-ing the self-configuration tools, see Chapter 3 [Advanced Configuration],

page 15. Command-line options, applicable environment variables, and sig-nal handling for the above tools are covered in Chapter 4 [Running Harpoon],page 24. Finally, more examples on configuring, using, and managing Har-poon are given in Appendix A [More Examples], page 33. Note that thismanual assumes a working knowledge of UNIX-ish systems and shell com-mands. If you need help on those basics, look elsewhere.

1.2.1 Building the Harpoon Software

Building Harpoon consists of the following steps:

1. Unpack the distribution. Using GNU tar, “tar xzvf harpoon_distribution.tgz” will do the trick, substituting the particular filename for “harpoon_distribution.tgz”.

2. Run ./configure in the top-level directory of the unpacked software.This step will build appropriate make files for your system. Optionally,you may use the --prefix flag to specify where the software is to beinstalled. The installation location defaults to /usr/local/harpoon.

3 http://expat.sourceforge.net4 http://www.splintered.net/sw/flow-tools5

http://www.python.org

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 10/51

Chapter 1: Overview of Harpoon 6

3. Run make. By default, the main components of Harpoon, all plugins,and some (presently undocumented) miscellaneous tools are built. If available, use GNU make, since some make programs do not properly

handle some of the constructs in Harpoon’s makefiles.4. (optional) make selfconf. Build the self configuration tool harpoon_flowproc.

5. (optional) make doc. You’ll need the GNU texinfo tools and/or doxygenfor this to work.

6. (optional) make install. Move the appropriate components to theinstallation target directory. By default, the install directory is/usr/local/harpoon.

Harpoon is known to build and run on FreeBSD 5.1-5.4, Linux 2.2-2.6,MacOS X 10.2-10.4, and Solaris 8-10. Harpoon does not build on Windows,

though there is an intent to eventually make that possible.If  configure does not find certain required libraries, you might try the

following syntax:

$ CPPFLAGS=-I/path-to-include-files LDFLAGS=-L/path-to-libs \./configure

This syntax generally works to force configure to look in the right di-rectories.

By default, harpoon is built with optimization level ‘-O2’ and with de-bugging symbols ‘-g’. An easy way to change this is to use the above syntaxrecipe:

$ CXXFLAGS="-g" ./configure

The above example will build Harpoon with debugging symbols but nooptimization. Building Harpoon without debugging symbols and a desiredlevel of optimization can be accomplished in a similar way.

Finally, you’ll very likely have to set LD_LIBRARY_PATH (Linux, FreeBSDand Solaris) or DYLD_LIBRARY_PATH (MacOS X) to the directory where plu-gin objects are installed. See Section 4.1.4 [Environment Variables], page 25for further information.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 11/51

Chapter 2: Basic Configuration 7

2 Basic Configuration

This chapter discusses simple configurations of Harpoon using the supplied

example config files (in the ‘examples’ subdirectory of the software distribu-tion). Simple changes to the config files to accomodate local addressing andtraffic volume requirements are also discussed. The next chapter discussesmore complicated configurations of Harpoon using your own flow records. Itis assumed here that you have successfully built Harpoon (See Section 1.2.1[Building the Harpoon Software], page 5).

Example configurations are found in the ‘examples’ subdirectory. Thereare two TCP traffic configuration examples provided:

‘tcp_client.xml’ and ‘tcp_server.xml’A very simple setup for illustrative purposes only.

‘tcp_client_ex2.xml’ and ‘tcp_server_ex2.xml’A TCP client/server pair with inter-connection times generatedfrom exponential distribution with mean 1 second and file sizesgenerated from Pareto distribution with alpha=1.2 shape=1500(bytes).

2.1 Validating a Configuration

The first step toward running harpoon should be to make sure configuration

files you intend to use are properly formed. A tool, config_validator existsfor this purpose. The tool takes only one argument, the configuration file.Shown below is output of config_validator run on ‘tcp_client_ex2.xml’and ‘tcp_server_ex2.xml’.

$ ./config_validator ../examples/tcp_client_ex2.xml

loading ../examples/tcp_client_ex2.xml

bad address - no prefix len?

Checking load of TcpClient

name: TcpClient

objfile: tcp_plugin.dylib

 maxthreads: 10

personality: client

client source pool:address list:

0.0.0.0 - 0.0.0.0 :0 (1)

client destination pool:

address list:

127.0.0.1 - 127.0.0.1 :10000 (1)

dumping distributions (first 10):

active_sessions: 10

interconnection_times: 3.99391 0.293601 2.12709 1.21451 0.409159 0.1121

0.580837 0.101379 0.724933 0.224031

There are a number of items to note here:

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 12/51

Chapter 2: Basic Configuration 8

• First, each plugin configuration has a name. The name of this pluginis TcpClient. The name must be unique for all plugins loaded andrunning in the same Harpoon process. (Note that you can have multiple

configurations of TCP plugins running as both clients and servers withina single process, but they must each have different names.)

• The shared object file loaded for this plugin is ‘tcp_plugin.dylib’.The operating system loader finds this file by searching the directoriesspecified by LD_LIBRARY_PATH environment variable. See Section 4.1.4[Environment Variables], page 25 for more information.

• In Harpoon, sessions are mapped in a 1-1 fashion onto threads. The maxthreads plugin attribute specifies the maximum number of operat-ing system threads to start in the plugin. To generate a specific levelof traffic, a certain number of threads/sessions are made active oversuccessive intervals of time. This number of active sessions is specifiedby the active_sessions distribution. Note that a specified number of active sessions can be greater than the value given for maxthreads.In this case, the maxthreads parameter acts as a limit; the actualnumber of active sessions is min( maxthreads, ActiveSessionsi), whereActiveSessionsi is the number of active sessions for interval i. See [dis-tributional parameters], page 4 to review the role of sessions in Harpoon.

• personality specifies whether this plugin is acting in a server-side orclient-side role.

• client source pool and client destination pool denote addresspools used by this plugin. Since this is a client-side plugin, the clientsource pool is used to bind the local-side of TCP connections to aspecific local address. In this example, the local address is 0.0.0.0,meaning that the operating system will fill in a default local address.The client destination pool addresses specify remote addresses andports where Harpoon TCP servers are listening.

• Finally, 10 random values from the distributions used by the particu-lar endpoint (client or server) are printed. For TCP clients, there aretwo relevant distributions: active_sessions and interconnection_times. For TCP servers (example shown below), there are two relevantdistributions: active_sessions and file_sizes.

Validation of the server-side configuration file is now shown below:$ ./config_validator ../examples/tcp_server_ex2.xml

loading ../examples/tcp_server_ex2.xml

bad address - no prefix len?

Checking load of TcpServer

name: TcpServer

objfile: tcp_plugin.dylib

 maxthreads: 37

personality: server

server address pool:

address list:

0.0.0.0 - 0.0.0.0 :10000 (1)

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 13/51

Chapter 2: Basic Configuration 9

dumping distributions (first 10):

active_sessions: 37

file_sizes: 18643900 15150 807481 157679 23465 4930 39188 4418 56341 10863

Now that the client-side configuration file has been validated and ex-plained, there is little new to describe. Note that the name of the pluginhas changed to TcpServer and the personality is server, but the pluginshared object file is still tcp_plugin.dylib. For servers, the maxthreadsand active_sessions parameters specify the number of active threads wait-ing to service file requests. These numbers can be set to the same single valuein most cases. (The problem of how many threads/sessions to keep activeis similar to the problem of configuring a web server. Unlike modern webservers, Harpoon does not allocate server threads in a dynamic way, so thisnumber must be statically set in the configuration files to a reasonable value.)

Finally, note that the server address is set to a default address (0.0.0.0)and the port is set to 10000.

2.2 Modifying Configuration File Addresses

For the client-side configuration file shown above, the destination addresspool is set to a single address of  127.0.0.1 – the loopback interface. Thisisn’t particularly helpful, since we would like to generate traffic over a net-work, not just through some operating system layers. This address pool iseasily changed.

Using your favorite text editor, open the file ‘tcp_client_ex2.xml’. To-

ward the end of the file the following lines are found:...

<address_pool name="client_source_pool">

<address ipv4="0.0.0.0" port="0" />

</address_pool>

<address_pool name="client_destination_pool">

<address ipv4="127.0.0.1/32" port="10000" />

</address_pool>

...

To change the server address (client_destination_pool), change the

address block 127.0.0.1/32 to be the desired address. For host prefixes(/32 masks) the mask is optional; specifying 127.0.0.1 has the same effectas specifying 127.0.0.1/32. (config_validator warns about this lack of prefix, however. See the above examples for the warning: “bad address - noprefix len?”.)

If there are two servers running on separate machines and without con-tiguous addresses, simply add another <address ... /> line with the secondaddress.

Note that for servers, the address pool definition follows the same struc-ture, but there is a current limitation in that only one address is used for

binding. That is, specifying two addresses for a server to listen on will not

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 14/51

Chapter 2: Basic Configuration 10

have the desired effect; only one address will be used. For now, using thedefault address specifier, 0.0.0.0, is the best option.

2.3 Starting HarpoonWe now have two configuration files with addresses set appropriately. Theexamples below show how to start harpoon with these configuration files. Weassume here that the environment variable LD_LIBRARY_PATH has been setproperly (see Section 4.1.4 [Environment Variables], page 25). Alternatively,a shell script run_harpoon.sh is installed when make install is run thatsets the environment variable to the correct directory and then executesharpoon. The examples below use this script, which has been installed inthe default location of ‘/usr/local/harpoon’.

On the server machine:

$ /usr/local/harpoon/run_harpoon.sh -v10 -w300 -c \-f examples/tcp_server.xml

...

10:02:16 sev(07) stopping plugin TcpServer

10:02:16 sev(00) TcpServer: plugin stopped - threads killed and reaped

10:02:16 sev(07) starting plugin TcpServer

10:02:16 sev(02) TcpServer: no plugin state existed on start - created

10:02:16 sev(01) TcpServer: started plugin with 1 threads.

10:02:16 sev(01) <stopping plugins: TcpServer:ok ><starting plugins: \

TcpServer:ok >

10:02:16 sev(09) harpoon started. verbosity<10>warp_factor<60> \

autoincr?<1>continuousrun?<1>

10:02:16 sev(05) 00:00 - emulation time tick...

And on the client machine:$/usr/local/harpoon/run_harpoon.sh -v10 -w300 -f examples/tcp_client.xml

...

10:02:40 sev(07) stopping plugin TcpClient

10:02:40 sev(00) TcpClient: plugin stopped - threads killed and reaped

10:02:40 sev(07) starting plugin TcpClient

10:02:40 sev(02) TcpClient: no plugin state existed on start - created

10:02:40 sev(01) TcpClient: started plugin with 1 threads.

10:02:40 sev(01) <stopping plugins: TcpClient:ok ><starting plugins: \

TcpClient:ok >

10:02:40 sev(09) harpoon started. verbosity<10>warp_factor<300>\

autoincr?<1>continuousrun?<0>

10:02:40 sev(05) 00:00 - emulation time tick

...

The command-line options used above require explanation:

‘-v10’ Turn on verbose messages. You should use this setting (level 10)of verbosity, especially when first getting started with Harpoon.

‘-w300’ Set interval duration length to 300 seconds (also referred to as“warp factor”). Given a specification of  <active_sessions> in

a configuration file, Harpoon will iterate through this list, setting

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 15/51

Chapter 2: Basic Configuration 11

the number of active sessions to each value for durations of 300seconds. If the original intervals were one hour in length (i.e.,the average number of sessions was calculated over successive

intervals of one hour) and the ‘-w’ flag is set to 600 seconds, a24 hour period could be emulated in 14,400 seconds (four hours).It should be clear from this explanation where the term “warpfactor” comes from.

‘-f [examples/tcp_client.xml, examples/tcp_server.xml]’Specify the configuration file to load. Multiple ‘-f’ flags may beused to tell Harpoon to load more than one configuration file.

‘-c’ While the first three options were used for each side (clientand server) of Harpoon, the ‘-c’ parameter is only used for theserver-side. This option tells Harpoon to continuously cycle over

its list of active sessions, specified in <active_sessions>. Nor-mally, Harpoon will iterate only once through this list, thencease activity. For experiments of fixed duration, this is oftenthe desired behavior. However, for servers this behavior is gen-erally to be avoided. The reason is that servers (at least for theplugins provided with the Harpoon software distribution) do notproduce traffic without some request or provocation from clients.It is therefore much easier to simply leave servers running, cy-cling over a list of active sessions (typically set to a single valueanyway), much like a continuously running web server.

More information on command-line parameters is given in [harpooncommand-line parameters], page 24.

Now that the client and server are started, we can get information fromthese processes via XML-RPC. Using the stats.py script in the ‘cli’ sub-directory (and a Python interpreter of version 2.2 or greater):

$ python ./stats.py -u http://servermachine:8180/ \

-u http://clientmachine:8180/

stats for <ServerProxy for servermachine:8180/>

server-wide information:

emulation_interval 1

----

plugin-specific information:

TcpServer is running - up for 81 seconds

target threads = 1 active threads = 1

num_transfer = 36

send_bandwidth_total_bps = 35555.6

send_bandwidth_recent_bps = 35555.6

bytes_sent_total = 360000.0

bytes_sent_recent = 360000.0

personality = server

stats for <ServerProxy for clientmachine:8180/>

server-wide information:

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 16/51

Chapter 2: Basic Configuration 12

emulation_interval 0

----

plugin-specific information:

TcpClient is running - up for 21 secondstarget threads = 1 active threads = 1

num_requests = 10

personality = client

Note that the statistics gathered using the stats.py tool are approximateand only reflect an application point of view. You should not use themin any “real” measurements (like for paper submissions!). They are thereto simply help with diagnosing and monitoring currently running Harpoonprocesses. Other XML-RPC tools are provided in the ‘cli’ subdirectory.More information on them is provided in Chapter 5 [Managing Harpoon],page 29.

2.4 Modifying a Configuration to ProduceDifferent Traffic Volumes

A common requirement is for harpoon to generate a specific average load. Atool, harpoon_reconf.py is provided to assist in determining the appropri-ate number of sessions to configure at a client to produce the desired levelof traffic.

If we wish to set the number of sessions so that the traffic rate (band-width) produced by Harpoon is 5 Mbps averaged over a 10 minute interval,

we can use the harpoon_reconf.py tool as follows (from the top-level Har-poon source directory):

$ python selfconf/harpoon_reconf.py -d -c examples/tcp_client_ex2.xml

-s examples/tcp_server_ex2.xml -i 600 -r 5000000

...

targetbytes 375000000.0 simbytes 378522468 median 4 mean 3 \

stdev 0.771722460186 max 5 flows 4085

number of sessions should be 3 to achieve volume of 375000000 bytes \

(5000000.0 bits/sec)

$

The tool reports that the number of active sessions should be set to 3

(the mean).The options used for harpoon_reconf.py are as follows:

‘-d’ Turn on verbose (debugging) information.

‘-c examples/tcp_client_ex2.xml’Specify the client-side configuration file. This is a required pa-rameter.

‘-s examples/tcp_server_ex2.xml’Specify the server-side configuration file. This is a required pa-

rameter.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 17/51

Chapter 2: Basic Configuration 13

‘-i 600’ Specify the interval duration. The value used for this parametershould be the same as the ‘-w’ parameter passed to harpoon. See[harpoon command-line parameters], page 24 and Section 2.3

[Starting Harpoon], page 10 for more information. This is arequired parameter.

‘-r 5000000’Specify the target traffic rate, in bits per second. Alternatively,you may use the ‘-b’ parameter to specify the total volume (inbytes) that should be generated over the specified interval du-ration (given by ‘-i’). One of ‘-r’ or ‘-b’ is required.

Note that the ‘-d’ flag was used, producing verbose output. The tar-get byte volume to produce over the requested interval of 600 seconds is375000000 (5000000/8× 600 = 375000000). The mean and standard devia-

tion of the sessions needed to produce 5 Mbps are 3 and 0.772, respectively.The output value simbytes is the average amount of traffic (in bytes) esti-mated to be produced for three sessions. This value will always be greaterthan the target (but generally not too much), since the self configurationtools aim to produce at least as much traffic as was originally sent.

After restarting the server and client, we use stats.py one minute later tocheck the server status and see that Harpoon is producing roughly 5Mbps.This tool takes only one option, ‘-u’, to specify the URL of the harpoonXML-RPC listener. By default, port 8180 is used.

$ python cli/stats.py -u http://servermachine:8180/

... TcpServer is running - up for 60 seconds

target threads = 3 active threads = 3

num_transfer = 397

send_bandwidth_total_bps = 4334040.0

send_bandwidth_recent_bps = 6360550.0

bytes_sent_total = 32505300.0

bytes_sent_recent = 13516200.0

personality = server

...

Near the end of the test, we run stats.py again to check progress:$ python cli/stats.py -u http://servermachine:8180/

...TcpServer is running - up for 557 seconds

target threads = 3 active threads = 3

num_transfer = 4217

send_bandwidth_total_bps = 6247000.0

send_bandwidth_recent_bps = 5237350.0

bytes_sent_total = 434947000.0

bytes_sent_recent = 75286800.0

personality = server

...

We see that Harpoon is making a pretty good match to 5 Mbps and is

quite close to the average match_rate calculated above.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 18/51

Chapter 2: Basic Configuration 14

Recall that the matching is done based on some interval of time (see[Harpoon’s flow-based two level hierarchical traffic model]). Note also thatthis matching is approximate, and depends on many factors. The nature

of the underlying distributions (file sizes and interconnection times) havea great impact on the goodness of the match, but selection of the intervalduration also has a significant effect. Generally, longer intervals (i.e. five orten minutes) are best. Very often the match between what you expect andwhat you get is quite good, but it can be “less good” if you pick a shortinterval and have distributions with extreme variability.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 19/51

Chapter 3: Advanced Configuration 15

3 Advanced Configuration

In the previous chapter, basic configuration of Harpoon was discussed, in-

cluding configuration file validation, setting desired endpoint addresses, andtuning Harpoon to produce the desired traffic volume. This chapter fills ingaps from the previous chapter by discussing, in more detail, the structureof Harpoon configuration files (using the TCP traffic generator plugins asthe basis for discussion), and the use of the self-configuration tools.

Harpoon uses XML documents for its config files. As described in [vali-dation of config files], page 26, an XML schema is distributed with Harpoonthat defines the structure of config files for the supplied TCP traffic plugin.Tools are provided to automatically generate configuration files from rawflow records. There is also a tool, config_validator, which is a simplevalidator of config files. The validator can’t catch all logical errors, but itwill catch all syntactical errors.

While the self-configuration tool harpoon_conf.py can generate validconfig files for Harpoon, it is often useful to manually tweak the files pro-duced by this script depending on testbed requirements. For this reason,description of how to use the self-configuration tools is followed by a discus-sion of the detailed structure of configuration files.

3.1 Self-Configuration Tools

For self-configuration, there are two required steps, and one optional step.

1. Process flow records using the harpoon_flowproc tool. The flow recordscan be in Netflow version 5 wire format or in flow-tools format. Theoutput of this step is an intermediate flow representation.

2. Process the intermediate format produced in the previous step using theharpoon_conf.py tool to produce Harpoon config files.

3. Optionally, the configuration files produced in step 2 can be processed toproduce a bit rate different from the original flow trace. The harpoon_reconf.py tool takes two Harpoon configuration files as input to per-form this task.

3.2 The harpoon_flowproc tool

The harpoon_flowproc tool takes raw flow records in either Netflow ver-sion 5 wire format, or in flow-tools format. If your system does not haveflow-tools installed, you’ll only be able to use the raw Netflow capability.The tool takes the flow records as standard input and produces an interme-diate format on standard output. This intermediate format is used by thetool harpoon_conf.py (see Section 3.3 [advanced harpoon conf.py], page 16,below) to produce configuration files for Harpoon.

By default, harpoon_flowproc uses an IntervalDuration value of 60

seconds, expects TCP flags in the flow records, and expects the input format

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 20/51

Chapter 3: Advanced Configuration 16

to be flow-tools. See Section 4.3.1 [running harpoon flowproc], page 26 formore information on command line options. The example below shows anhour’s worth of flow records being piped into harpoon_flowproc, with the

output written to ‘flowproc.out’. It shows that there were over 4 millionflows over that hour, with about 1.8 million TCP flows. However, only 1.2million TCP flows had SYN and FIN or RST flags (i.e., were “well-formed”).Finally, flow surgery did not have to be performed on any of the flows. (Notethat it isn’t abnormal that surgery is minimal or not required, at least onflow record traces I’ve looked at.)

$ flow-cat ft-v05.2002-07-31.13* | ./harpoon_flowproc -i 60 > flowproc.out

sorting tcp flow records... took 25 sec.

total flows: 4071060

total TCP flows: 1867860

total well-formed TCP flows: 1216691

surgery performed: 0

$

3.3 The harpoon_conf.py tool

The Python script harpoon_conf.py uses the output from the tool harpoon_conf to produce configuration files for Harpoon. In the example below, aninterval duration of 600 seconds is specified (‘-i’ 600), source and destinationaddress pools are specified (‘-S’ and ‘-D’ options), and output config fileshave a prefix of “testoutput”. See Section 4.3.2 [running harpoon conf.py],page 27 for more information on command line parameters.

$ ./harpoon_conf.py -i 600 -S ’10.54.1.0/24’ -D ’10.54.42.1/32’ \

-p testoutput flowproc.out

got starting time from file header: 1028138318.2

progress (10k lines): . . . . . . . . . . 100000

. . . . . . . . . . . 200000

. . . . done ( 232645 lines)

$

The configuration files resulting from this script may still need to betweaked. In particular, the number of active sessions set in the client config-uration file may exceed the maximum number of threads per process on theoperating system where Harpoon will be run. Either that, or you may wishto set up a multi-host configuration, splitting the load generation over somenumber of machines. For these situations, you will have to manually edit theconfiguration files, changing the number of active sessions to an appropri-ate value, and setting client source and destination addresses to appropriatevalues.

3.4 The harpoon_reconf.py tool

The harpoon_reconf.py is used to tune existing client and server configu-ration files to produce a specified bit rate. The configuration files that thisscript uses can be produced by the harpoon_conf.py tool or can be made

using configuration files based on distributions from known distributions. In

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 21/51

Chapter 3: Advanced Configuration 17

the example below, the target rate is specified as 5 Mbps and the scriptreports that 314 sessions should be configured to produce this volume. Thescript itself does not modify the configuration files, so this value must be

set in the client configuration file. See also Section 2.4 [Modifying a Con-figuration to Produce Different Traffic Volumes], page 12, and Section 4.3.3[running harpoon reconf.py], page 28.

$ ./harpoon_reconf.py -d -c testoutput_tcpclient.xml \

-s testoutput_tcpserver.xml -i 300 -r 5000000

target volume: 187500000.0

interval duration: 300

client conf file: testoutput_tcpclient.xml

server conf file: testoutput_tcpserver.xml

target: 187500000.0 carry: 0

targetbytes 187500000.0 simbytes 187720505 median 320 mean 314 \

stdev 55.02035895 max 415 flows 16174

number of sessions should be 314 to achieve volume of 187500000 bytes \(5000000.0 bits/sec)

$

3.5 Configuration File Structure

The best way to describe the structure of Harpoon config files is through anexample:

<?xml version="1.0"?>

<harpoon_plugins>

<plugin name="Example" objfile="example.so"

 maxthreads="42", personality="server">

...

</plugin>

</harpoon_plugins>

The top-level tag in any config file must be <harpoon_plugins>. Withinthat element, any number of traffic generation <plugin>s may be defined.Every Harpoon configuration file must be structured this way - the XMLparser that Harpoon uses (expat — http://expat.sourceforge.net/) en-forces this requirement.

3.5.1 <plugin> Definitions

For the <plugin> element, there are three require attributes, and one op-tional attribute:

name An identifier for this plugin. It must be unique for all incarna-tions of a traffic generator module running under the control of a single harpoon executable. That is, you must have separate<plugin> tags defined for client and server portions of the sametraffic generator if they are running in the same harpoon pro-

cess. For example, for the client-side of a TCP plugin you might

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 22/51

Chapter 3: Advanced Configuration 18

use the name “TCPClient” and for the server-side you mightuse “TCPServer”.

objfile The object file into which traffic generation code is compiled.

For most UNIX-like operating systems, this file will end in theextension .so. For MacOS X, this extension is normally .dylib.

maxthreadsAn integer defining the maximum number of threads to create forthis plugin. One thread represents one Harpoon session. Notethat different operating systems impose limits on the maximumnumber of threads per process. Harpoon will happily attemptto create one million threads if you ask it to — it is up to youto make sure this number makes sense. If Harpoon is unable tocreate the number of threads you ask for it will croak, leaving

both you and the formerly running harpoon quite miserable.personality

This attribute should contain the value ‘server’ or ‘client’.Harpoon is organized as a client-server application. This at-tribute specifies how the traffic generator named in the con-figuration file should behave, either as a client or as a server.More specifically, each plugin module has two code entrypoints:server_session and client_session. The entrypoint takendepends on this attribute. See Appendix C [Creating New Traf-fic Generation Modules], page 43 for more details.

3.5.2 Configuring Distributions

Within a <plugin> element, you define the distribution data used by theplugin. Depending on the “personality” of the plugin and on the particulartraffic generator, different distributions may be required. For example, forthe TCP client, file sizes are irrelevant since it is the server that generatesfiles. Note that the config_validator tool does not assume that all  distri-butions are required and checks only for the existence of distributions thatmake sense based on the configured personality.

As described in Chapter 1 [Overview of Harpoon], page 1 and summarized

in [distributional parameters], page 4, there are five distributions comprisingHarpoon’s architectural model for TCP flows. Configuration of three of those parameters is described here. Addressing is described in the followingsection.

Each of the parameters P FileSize, P InterConnection, P ActiveSessions,P IPRangesrc , and P IPRangedest are configured using XML tags <file_sizes>,<interconnection_times>, <active_sessions>, and <address_pool>,respectively, also shown in the example below. Whitespace-separated valuesfor each distribution should be written between start and end tags for therespective element. There is no required order among these tags. For the

TCP plugin, servers expect <file_sizes> and <active_sessions>. File

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 23/51

Chapter 3: Advanced Configuration 19

sizes values are given in bytes. Clients expect <interconnection_times>and <active_sessions>. Interconnection times are given in (floatingpoint) seconds. Both endpoints require <address_pool> tags, as described

below.The <active_sessions> tag identifies the number of Harpoon sessions(threads) that should be active for a given interval. By default, this intervalis assumed to be an 60 seconds, though it need not be so. By adjusting the“warp factor” (‘-w’ option, [harpoon command-line parameters], page 24)on the harpoon command-line, any mapping between emulation time andwall-clock time may be made. The Harpoon plugin controller will adjust thenumber of active threads per interval according to the distribution given in<active_sessions>. By default, Harpoon will iterate once through the listof <active_sessions>, then plugin activity will cease (i.e., number of activesessions will be set to 0). For clients, this is often the desired behavior. For

servers, however, this is very often not desirable. The ‘-c’ flag can be givento Harpoon so that it cycles continuously over its list of <active_sessions>.

The maxthreads attribute described above serves as a cap to the numberof threads to be created for a plugin. If values given for <active_sessions>exceeds maxthreads, no threads beyond maxthreads will be created. For theclient-side, the relationship between the values given for <active_sessions>and load generated by Harpoon should be straightforward. For servers, it isoften best to simply supply one value (which should usually be the same asthe value given for maxthreads) so that enough server handlers are runningat all times. Choosing this value is akin to provisioning a web server, and

the default values set by the Harpoon configuration tools may or may notneed tuning in different environments.

The next two examples show how the three distributions described aboveappear in configuration files. For these examples, the plugin headers (at-tributes) are not specified, only the applicable distributions.

For a TCP server, only the <active_sessions> and <file_sizes> ele-ments are required:

<plugin ... >

<!-- for a TCP server configuration -->

<active_sessions>

47

</active_sessions>

<file_sizes>

200 42000 300 1200 5400 ...

</file_sizes>

...

</plugin>

For a TCP client, only the <active_sessions> and <interconnection_times> elements are required:

<plugin ... >

<!-- for a TCP client configuration -->

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 24/51

Chapter 3: Advanced Configuration 20

<active_sessions>

50 58 60 61 70 75 ...

</active_sessions>

<interconnection_times>1.2 0.3 4.95 1.5 0.1 0.9 ...

</interconnection_times>

...

</plugin>

3.5.3 Configuring Addresses

This section introduces the XML tags for configuring client source and des-tinations addresses, and server addresses. The basic ideas are:

• when clients make requests to servers, they bind to local source ad-dresses  and ports, and connect to remote destination addresses  andports;

• servers bind to a server address and port, waiting for client requests;client source addresses can be specified, or can be set to allow the oper-ating system to assign a default local address (the same goes for servers).

All addresses (client source addresses, client destination addresses, andserver addresses) are defined using the XML tag <address_pool>, but withdifferent values for the required attribute name. Within each address pool,there may be any number of  <address> elements. Each <address> element

must contain exactly two attributes: ipv4 and port. The address elementmust be in a CIDR-style format1. The port value of 0 is a special valuewhich indicates that the operating system should automatically choose alocal ephemeral port for the connection. Likewise, the address “0.0.0.0”means that the client should bind to the default local address, and the servershould bind to “*”. For server addresses, only one address and port shouldbe defined: multihoming in this way is not implemented yet.

Note that these addresses say nothing about protocol. Protocol-specificitems are defined within plugin code.

The address attribute name “ipv4” suggests that other kinds of addresses

are possible. At present, only IPv4 addresses are supported but it is con-ceivable that IPv6 will be supported in the future. Using any attribute foran address except “ipv4” will generate a configuration file parse error.

Continuing with the examples from above, the server address pool mightdefined as:

<plugin ... >

<!-- for a TCP server configuration -->

<active_sessions>

1 A current limitation with this scheme is that all four bytes of an IPv4 addressmust be given even for short prefixes. Instead of writing 10.5/16, you should write

10.5.0.0/16.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 25/51

Chapter 3: Advanced Configuration 21

47

</active_sessions>

<file_sizes>

200 42000 300 1200 5400 ...</file_sizes>

<address_pool name="server_address">

<address ipv4=’0.0.0.0’ port=’10000’/>

</address_pool>

</plugin>

In this case, the server binds to “*.10000”. That is, port 10000 for anylocal address on the server. For the client configuration, we define a sourceaddress pool of 64 address (actually, 62 usable addresses, not including thehost and broadcast addresses) and for destination addresses we define two

separate class C networks (254 usable addresses):<plugin ... >

<!-- for a TCP client configuration -->

<active_sessions>

50 58 60 61 70 75 ...

</active_sessions>

<interconnection_times>

1.2 0.3 4.95 1.5 0.1 0.9 ...

</interconnection_times>

<address_pool name="client_source_addresses">

<address ipv4=’192.168.1.0/26’ port=’0’ /></address_pool>

<address_pool name="client_destination_addresses">

<address ipv4=’192.168.47.0/24’ port=’10000’/>

<address ipv4=’192.168.46.0/24’ port=’9900’/>

...

</address_pool>

</plugin>

3.5.4 Putting It All Together

To wrap up the examples in this section, we fill in the main plugin attributesto complete the configuration files. For the server:

<plugin name="ServerExample" objfile="tcp_plugin.so"

 maxthreads="47", personality="server">

<!-- for a TCP server configuration -->

<active_sessions>

47

</active_sessions>

<file_sizes>

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 26/51

Chapter 3: Advanced Configuration 22

200 42000 300 1200 5400 ...

</file_sizes>

<address_pool name="server_address">

<address ipv4=’0.0.0.0’ port=’10000’/></address_pool>

</plugin>

And for the client:<plugin name="ClientExample" objfile="tcp_plugin.so"

 maxthreads="75", personality="client">

<!-- for a TCP client configuration -->

<active_sessions>

50 58 60 61 70 75 ...

</active_sessions>

<interconnection_times>

1.2 0.3 4.95 1.5 0.1 0.9 ...

</interconnection_times>

<address_pool name="client_source_addresses">

<address ipv4=’192.168.1.0/26’ port=’0’ />

</address_pool>

<address_pool name="client_destination_addresses">

<address ipv4=’192.168.47.0/24’ port=’10000’/>

<address ipv4=’192.168.46.0/24’ port=’9900’/>...

</address_pool>

</plugin>

3.5.5 Nesting Configuration Files

A feature of Harpoon configuration files is that one file may include another,allowing a user of Harpoon to nest configuration files and reuse identicaldistribution data in more than one plugin without duplicating the data itself.

Using the tag <config_file> as in the example below causes the namedfile to be substituted in place:

<plugin ... >

...

<config_file> file_sizes.xml </config_file>

...

</plugin>

Assume the file file_sizes.xml contains:<file_sizes> 500 23423 837 7735 </file_sizes>

The resulting configuration would “behave” as if you had written:<plugin ... >

...

<file_sizes> 500 23423 837 7735 </file_sizes>

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 27/51

Chapter 3: Advanced Configuration 23

...

</plugin>

A very important thing to note is that each configuration file used by

Harpoon (whether it is a “top-level” configuration file or one that is includedby another) must be a well-formed XML document. One consequence is thatfiles can contain only one top-level element. Essentially, this means that afile containing exactly the following:

<active_users> 55 67 79 80 100 140 142 130 110 </active_users>

<file_sizes> 500 23423 837 7735 </file_sizes>

is illegal — the XML parser that Harpoon uses will complain loudly. Youmust structure your config files to accomodate this restriction.

Another point to note (which will be described again below) is that whileyou may use file names that include full or relative paths, any relative pathswill be relative to the working directory of the harpoon executable. Anyplugin object files referenced in configuration files will also be referred torelative to the working directory of  harpoon.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 28/51

Chapter 4: Running Harpoon 24

4 Running Harpoon

4.1 The harpoon executableharpoon is the executable used to load modules for traffic generation. Trafficgeneration is not implemented directly in harpoon, it is rather a manager of traffic generation plugins. Using command line parameters and an externalmanagement interface (XML-RPC) you can load, unload, start, stop, andquery traffic generation modules.

4.1.1 harpoon command-line parameters

Most configuration is done through the external management interface, butthere are a few command line parameters for initial loading and configuration

of  harpoon. These parameters are:‘-f filename’

With the ‘-f’ switch you specify Harpoon config files to be ini-tially loaded. You may specify multiple ‘-f’ parameters in orderto load more than one config file.

‘-l logfile’The argument to the ‘-l’ switch is a file name to which logmessages will be appended. By default, log messages are writtento STDERR.

‘-p port’ The ‘-p’ flag sets the port that Harpoon’s internal HTTP serverlistens on. By default, this port is 8180.

‘-s seed’ The ‘-s’ option sets a specific seed for random number genera-tion. If this option is not set, the random number generator isseeded using a combination of the current time and Harpoon’sprocess ID.

‘-v verbiage_level’The ‘-v’ option sets the level of verbosity for log messagesspewed by Harpoon. The argument to ‘-v’ should be an in-teger from 0 to 10, with 0 meaning minimal log messages are

emitted, and 10 meaning lots of program chatter is logged.

‘-w warp_factor’With the ‘-w’ switch, you may set the number of seconds thatcomprise an IntervalDuration. By default, this value is 60 sec-onds, so if the values given in P ActiveUsers represent the numberof active users per hour, it will take 24 minutes to emulate a fullday. See the full Harpoon paper for some of the issues in settingthis parameter.

‘-c’ Use the ‘-c’ flag to tell Harpoon to continuously cycle over its

values of P ActiveSessions. The default behavior is for Harpoon to

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 29/51

Chapter 4: Running Harpoon 25

spend IntervalDuration time on each value of  P ActiveSessions,successively stepping through the series of number of active ses-sions and stopping after the final value. With the ‘-c’ flag,

Harpoon will cycle indefinitely over these P ActiveUsers values.‘-a’ Use the ‘-a’ switch to cause Harpoon to not automatically cycle

through the values in P ActiveUsers. Using this flag, it is possibleto manually (through the XML-RPC interface) cycle throughintervals. Harpoon will ignore the ‘-w’ switch if ‘-a’ is set.

‘-?’ This option dumps usage information on the above command-line parameters. Unrecognized options given to harpoon alsohave this effect.

In addition to harpoon command-line parameters described in [harpooncommand-line parameters], page 24, two run-time features to be aware of 

are signal handlers implemented by Harpoon, and event logging capabilityof Harpoon.

4.1.2 Signals Handled by Harpoon

The following table describes signals handled by Harpoon. All other signalsare blocked.

SIGINTSIGTERM Sending an interrupt signal to Harpoon has the effect of shutting

Harpoon down. First, all user-level threads running plugin codeare shut down, then the HTTP/XML-RPC listener is stopped.Finally, Harpoon crumples in a heap.

SIGUSR1 Sending the USR1 signal has the effect of shutting down all user-level plugin threads. All plugins are returned to the idle state.Harpoon itself continues to process remote-interface methodcalls.

SIGUSR2 Sending the USR2 signal to Harpoon causes all plugins to be re-set (analogous to the resetAll() XML-RPC method describedbelow.) First, all plugin threads are stopped, second, the emu-lated hour is reset to 0, finally, plugin threads are restarted for

all loaded plugins.4.1.3 Harpoon Event Logging

Logging capability within Harpoon is currently quite limited. Using the ‘-v’option to the harpoon executable causes different levels of log messages tobe written or suppressed. All log messages are currently written to STDERRby default, unless an ‘-l’ switch is given to harpoon.

4.1.4 Environment Variables

While there are no environment variables required specifically by Harpoon,

many operating systems will require setting the variable LD_LIBRARY_PATH

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 30/51

Chapter 4: Running Harpoon 26

(or a similar variable, e.g , DYLD_LIBRARY_PATH on MacOS X) in order tomake dynamic loading of plugins work properly. Before starting Harpoon,this variable should be set to include the directory where plugin modules are

installed (often the same directory as Harpoon, but not necessarily.) You areadvised to consult the relevant manual pages for reference (e.g., ldconfigand ld.so for Linux, ld and ld.so.1 for Solaris, and dyld for MacOS X.)

A script, run_harpoon.sh, is supplied with the software distribution toautomatically set the above environment variable and then invoke the har-poon executable. If you perform a make install when building Harpoon,this script will get installed and have the correct paths. If you do not in-stall Harpoon, the script won’t work (because of default installation pathsettings). If you want to use the script, simply edit it to suit your needs.

4.2 Validating a configuration file with config_validator

config_validator takes only one argument, the config file to be checked.It parses the given config file and prints diagnostics on what was parsed.Examples of config file validation are given in see Section A.2 [Validation of Configuration Files], page 34. The config_validator uses the same codeinternally as Harpoon (and can be quite picky!) so it really is a good ideato validate your config files using this tool.

Another way to validate your config files is to use a general-purposeXML schema validation tool. One such tool on the Web is at

http://apps.gotdotnet.com/xmltools/xsdvalidator/Default.aspx .The file harpoon_plugins.xsd (see [XML Configuration Schema],page 39), in the documentation directory of the Harpoon distribution,is an XML schema defining the structure of Harpoon configuration filesfor the TCP plugin. (Note that this file only  defines the structure forTCP plugins, therefore its use is limited. It is kept with the softwaredistribution mainly for historical reasons.) For reference on XML schemas,see http://www.w3.org/XML/Schema. Note that schemas serve a similarpurpose as SGML DTDs, but are written entirely in XML.

4.3 Self-configuration ToolsThis section describes the command-line options for the threeself-configuration tools, harpoon_flowproc, harpoon_conf.py, andharpoon_reconf.py.

4.3.1 harpoon_flowproc

The flow record processor tool takes the flow records as standard input andproduces a reformatted series of records (in ASCII) on standard output.There are a number of limitations to this program, making it unsuitable forvery large flow record traces.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 31/51

Chapter 4: Running Harpoon 27

‘-i’ One of the main tasks of  harpoon_flowproc is to organize flowrecords into a series of “sessions”, which are connections betweenthe same IP host pair initiated within some duration of time.

The ‘-i’ option allows the user to specify this duration of timein seconds. By default, a value of 60 seconds is used. This valueshould also match the value used for the ‘-i’ to the harpoon_conf.py script.

‘-n’ harpoon_flowproc, by default, expects to use flow-tools for-mat flow records (unless the flow-tools library is not found).To use Netflow 5 wire format records, use the ‘-n’ flag.

‘-w’ harpoon_flowproc performs “flow surgery” to coalesce flowrecords adjacent in time that are very likely referencing the sameflow. By default, only records containing SYN and FIN or RST

flags will be used (“well-formed” flows). To relax this require-ment, use the ‘-w’ flag. Using this option, no flow records will beignored based on lack of TCP flags. Note that flow surgery willnot be performed if there are no TCP flags present, regardlesswhether the ‘-w’ option is set.

4.3.2 harpoon_conf.py

The harpoon_conf.py Python script takes the output of harpoon_flowprocand produces XML configuration files that can be used by Harpoon. Whilethe configuration files may need some manual tweaking for a particular en-

vironment, they can often be used right away. harpoon_conf.py has onerequired argument, the file produced from running harpoon_flowproc. Alloptions listed below are not required.

‘-s’ Specify the point in time (floating point seconds) after whichitems from the input file should be used. This is an absolutetime (i.e., not relative to the beginning of the trace). You mightuse this flag if you want to restrict harpoon_conf.py to onlyprocess output records for a particular time interval.

‘-e’ Specify the point in time (floating point seconds) before which

items from the input file should be used. This is an absolutetime (i.e., not relative to the beginning of the trace). You’dprobably use this flag in conjunction with ‘-e’ to only processoutput records for a particular time interval.

‘-i’ Specify the value of   IntervalDuration to use. By default, avalue of 300 seconds is used. Generally, a longer value such as300 or 600 seconds is best.

‘-m’ Specify the maximum number of lines to process from the inputfile. This option is probably less useful unless you’re doing some

debugging. Normally, using the ‘-s’ and ‘-e’ options are what

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 32/51

Chapter 4: Running Harpoon 28

you should really use if you want to only process records over aparticular time interval.

‘-p’ Specify a string to use as a prefix for output files. If  

the string ‘testprefix’ is used, for example, the XMLconfiguration files ‘testprefix_tcpclient.xml’ and‘testprefix_tcpserver.xml’ will be produced. The defaultprefix is harpoonconf.

‘-d’ Turn on some debugging chatter. Multiple ‘-d’ options causemore chatter.

‘-D’ Specify a client destination address pool as a CIDR prefix. Forexample, -D ’192.168.1.0/24’. The ‘-D’ option may be speci-fied multiple times.

‘-S’ Specify a client source address pool as a CIDR prefix. For ex-ample, -S ’192.168.2.0/24’. The ‘-D’ option may be specifiedmultiple times. Note that the server address defaults to 0.0.0.0with port 10000.

4.3.3 harpoon_reconf.py

The harpoon_reconf.py Python script reads existing client and server con-fig files and retunes them to produce specific traffic volumes. Only bitratescan be specified at this time.

‘-c’ Use this option to specify the client config file. This is a requiredoption.

‘-s’ Use this option to specify the server config file. This is a requiredoption.

‘-i’ Specify the value of  IntervalDuration with the ‘-i’ option. De-fault value is 300 seconds.

‘-r’ Specify the target rate in bits per second using this option. Thisis a required option.

‘-d’ Turn on debugging chatter.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 33/51

Chapter 5: Managing harpoon 29

5 Managing harpoon

In addition to using XML for its config files, Harpoon includes a restricted

HTTP daemon which understands POST commands for XML-RPC, andPUT commands for upload of configuration and plugin files. These interfacescan be used to remotely manage Harpoon daemons. This chapter describesa usage of a PHP script for web-based Harpoon management. We also givedetails on the XML-RPC / HTTP interfaces to Harpoon.

5.1 Web-based Management

A PHP (http://www.php.net) script ( manage_harpoon.php) and someJavascript and CSS support files are included with Harpoon to facilitatelarge-scale management of Harpoon. This section describes usage and de-

sign of this feature.Sorry - this script is not documented yet (and not fully tested anyway).

5.1.1 Using manage_harpoon.php

FIXME

5.1.2 Setting up Apache and PHP

FIXME

5.2 Lower-level Management InterfacesA restricted HTTP server is embedded in Harpoon which allows remotemanagement using XML-RPC. The HTTP PUT method is also understood,allowing upload of XML configuration files and plugin binaries to remoteHarpoon daemons. This section describes these low-level details of managingHarpoon. Normally, you do not need to be concerned with these detailsunless the supplied web interface is insufficient for your needs.

5.2.1 Supported XML-RPC Methods

The following table lists all XML-RPC methods recognized by Harpoon.

The harpoon executable listens to port 8180 by default for requests. Thiscan be changed with the ‘-p’ switch, described in See [harpoon command-line parameters], page 24. There are simple Python scripts supplied withthe Harpoon distribution that demonstrate the basics of making manage-ment RPCs. For further reference, see http://www.xmlrpc.org/ (there isa very useful tutorial available at this site) and the Python documentation,available at http://www.python.org/.

A restriction to be aware of with the XML-RPC interface of Harpoonis that it is single-threaded. That is, it can only handle one request ata time. This implementation has the side-effect that any call that blocks

for some amount of time will prevent any subsequent calls from executing

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 34/51

Chapter 5: Managing harpoon 30

until the blocked call finishes. (The primary reason for implementing thelistener as a single thread is to limit the number of threads used by harpoonitself, leaving as many resources available as possible for user-level traffic

generation threads.)Simple scripts using each of the interfaces described below are providedin the ‘cli’ subdirectory. You may also wish to look briefly the [stats.pytool example], page 13 for a concrete reference using one of these interfaces.

system.listMethodsList all methods recognized by the server. Other standardsystem interfaces, such as system.methodSignature andsystem.methodHelp are not (yet) available.

system.null

Ping the server. Returns the string null. No parameters areexpected.

loadConfigLoad an XML configuration file. The file name is given as aparameter to this method. The file name may include a rel-ative path from the working directory of  harpoon. Note thatany configuration files nested in the one currently being loaded(named by this method) must also be named with paths rela-tive to the working directory of  harpoon. A boolean value isreturned indicating success or failure.

unloadConfigUnload a plugin configuration. The plugin name is supplied asa parameter to this method. Any plugin state is destroyed (ala unloadPlugin() — see below), and configuration data for theplugin is also destroyed. The plugin must be idle for this methodto succeed. A boolean value is returned indicating success orfailure.

queryPluginsReturns a list of structures describing all plugin configurationsthat have been loaded. No parameters are expected.

unloadPluginUnload the shared object implementing a plugin, leaving theconfiguration in-tact. One parameter is expected, the name of the plugin. The plugin must have been previously stopped forthis call to succeed. Returns a string indicating success or fail-ure. This call can be useful to destroy any static state retainedby the plugin across calls to startPlugin and stopPlugin.That is, any statistics held in static variables of the class imple-menting the plugin are wiped clean as a side-effect. A boolean

value is returned to indicate success or failure.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 35/51

Chapter 5: Managing harpoon 31

loadPluginOne parameter is required, the plugin name. Load the sharedobject for the plugin named in the parameter. The plugin con-

figuration must already have been loaded for this call to succeed.A boolean value is returned indicating success or failure.

stopPluginOne parameter is required, the plugin name. Stop all threadsrunning for the named plugin. Returns a boolean indicatingsuccess or failure. Note that this call may take non-negligibletime because of delay in gracefully stopping traffic generationthreads. Be patient.

startPluginOne parameter is required, the plugin name. Starts user-level

threads for the named plugin. If the shared object for the pluginhas not already been loaded, this loading is done as a side-effectof this call. The plugin must be idle and/or unloaded for thiscall to succeed. A boolean value is returned indicating successor failure.

getStats No parameters are expected. Returns an array of structures in-dicating status and statistics of Harpoon and all loaded plugins.

resetAll No parameters are expected. Stops all running plugins, resetsthe emulated hour to 0 (zero) and restarts all plugins. A booleanvalue indicating success or failure is returned.

suicide No parameters are expected. Initiates a shutdown of all threadsinside Harpoon, including Harpoon itself. A meaningless stringis returned.

5.2.2 Uploading Files with HTTP PUT

In addition to processing XML-RPC methods using the HTTP POST com-mand over port 8180, Harpoon also recognizes HTTP PUT commands. Us-ing PUT can be useful in distributing configuration and plugin files acrossa number of Harpoon processes. No tools are distributed with Harpoon for

distributing files. You are advised to use existing free tool such as curl orwget for this task. The destination file name is given as the URI, and mayinclude a relative path. Any preceeding forward slashes are discarded.

Examples of uploading configuration files and plugins using curl aregiven below:

$ curl --upload-file dummy_plugin.xml \

http://10.2.0.2:8180/dummy_plugin.xml

% Total % Recvd % Xferd Average Speed Time Curr.

Dload Upload Total Current Left Speed

100 961 0 0 100 961 0 961 0:00:01 0:00:00 0:00:01 961

100 963 0 2 100 961 2 961 0:00:01 0:00:00 0:00:01 0

$

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 36/51

Chapter 5: Managing harpoon 32

$ curl --upload-file dummy_plugin.so \

http://10.2.0.2:8180/test/dummy_plugin.so

% Total % Recvd % Xferd Average Speed Time Curr.

Dload Upload Total Current Left Speed

54 37563 0 0 54 20480 0 20480 0:00:01 0:00:00 0:00:01 20480100 37565 0 2 100 37563 2 37563 0:00:01 0:00:00 0:00:01 2780k

$

In the first example, an XML configuration file (dummy_plugin.xml) iswritten to the working directory of Harpoon. In the second example, ashared object plugin dummy_plugin.so is written to the test subdirectoryunder the working directory of  harpoon.

Note that there are clear security consequences of the PUT command. Atpresent there is no support for authentication or encryption of transactionsusing SSL. There is also at present no way disable the XML-RPC interface.

These features may be added at a later date.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 37/51

Appendix A: More Examples 33

Appendix A More Examples

A.1 XML Configuration FilesThe following examples show portions of the configurations‘tcp_client_ex2.xml’ and ‘tcp_server_ex2.xml’ provided in the‘examples’ subdirectory of the Harpoon software distribution. Not alldistribution data is printed (noted by the ellipses in the examples).

First, the client configuration:<harpoon_plugins>

<plugin name="TcpClient" objfile="tcp_plugin.dylib"

 maxthreads="10" personality="client">

<active_sessions> 10 </active_sessions>

<interconnection_times>

...

3.993905 0.293601 2.127093 0.174206 0.391431

2.579116 0.273442 0.358623 0.173357 1.454077

...

</interconnection_times>

<address_pool name="client_source_pool">

<address ipv4="10.54.40.2/32" port="0" />

</address_pool>

<address_pool name="client_destination_pool">

<address ipv4="10.54.40.1/32" port="10000" />

</address_pool>

</plugin>

</harpoon_plugins>

Now, for the server configuration:<harpoon_plugins>

<plugin name="TcpServer" objfile="tcp_plugin.dylib"

 maxthreads="37" personality="server">

<file_sizes>...

1034 9710 559390 52641 2122 2643 16167 22667 23660 20271790 14009

...

</file_sizes>

<active_sessions> 37 </active_sessions>

<address_pool name="server_pool">

<address ipv4="0.0.0.0" port="10000" />

</address_pool>

</plugin>

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 38/51

Appendix A: More Examples 34

</harpoon_plugins>

If you wish to use these files to produce a specific traffic volume (bit rate),see Section 3.4 [[tuning traffic volume with harpoon reconf.py]], page 16,

Section 4.3.3 [[harpoon reconf.py command-line parameters ]], page 28, orSection 2.4 [[basic use of harpoon reconf.py]], page 12. You may also wish tochange the addresses to match your environment. See Section 2.2 [[modifyingconfiguration file addresses]], page 9 or Section 3.5.3 [[address configuration]],page 20 for that information.

A.2 Validation of Configuration Files

We now validate the above configuration files and show the output of config_validator for each. (Note that there are slight local modificationsto these config files so the output will not exactly match running config_

validator on these same files in the Harpoon software distribution.)$ config_validator tcp_client_ex2.xml

loading ../examples/tcp_client_ex2.xml

bad address - no prefix len?

Checking load of TcpClient

name: TcpClient

objfile: tcp_plugin.dylib

 maxthreads: 50

personality: client

client source pool:

address list:

10.54.0.22 - 10.54.0.22 :0 (1)

client destination pool:

address list:

10.54.46.0 - 10.54.46.255 :10000 (256)

dumping distributions (first 10):

active_sessions: 12 27 40 41 36 48 50 50 49 25

interconnection_times: 3.99391 0.293601 2.12709 1.21451 0.409159 0.1121

0.580837 0.101379 0.724933 0.224031

$

$ config_validator tcp_server_ex2.xml

loading ../examples/tcp_server_ex2.xml

bad address - no prefix len?Checking load of TcpServer

name: TcpServer

objfile: tcp_plugin.dylib

 maxthreads: 37

personality: server

server address pool:

address list:

0.0.0.0 - 0.0.0.0 :10000 (1)

dumping distributions (first 10):

active_sessions: 37

file_sizes: 18643900 15150 807481 157679 23465 4930 39188 4418 56341 10863

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 39/51

Appendix A: More Examples 35

A.3 Example Using Two Hosts, UnidirectionalTraffic

For the above client and server configuration files, assuming that the client

source and destination addresses are set up correctly, we’re ready to startup Harpoon and generate traffic.

For the server, you should see something like this:

$ export LD_LIBRARY_PATH=\

$LD_LIBRARY_PATH:/home/jsommers/harpoon/src/plugins

$ ./harpoon -f ../examples/tcp_server_ex2.xml -v10 -w300 -c

loading ../examples/tcp_server_ex2.xml... bad address - no prefix len?

finished.

Checking load of TcpServer

name: TcpServer

objfile: tcp_plugin.so

 maxthreads: 37personality: server

server address pool:

address list:

0.0.0.0 - 0.0.0.0 :10000 (1)

dumping distributions (first 10):

active_sessions: 37

file_sizes: 15150 807481 157679 23465 4930 39188 4418 56341 10863

11:06:04 sev(07) stopping plugin TcpServer

11:06:04 sev(00) TcpServer: plugin stopped - threads killed and reaped

11:06:04 sev(07) starting plugin TcpServer

11:06:04 sev(02) TcpServer: no plugin state existed on start - created11:06:04 sev(01) TcpServer: started plugin with 37 threads.

11:06:04 sev(01) <stopping plugins: TcpServer:ok >\

<starting plugins: TcpServer:ok >

11:06:04 sev(09) harpoon started. verbosity<10>warp_factor<300>\

autoincr?<1>continuousrun?<0>

11:06:04 sev(05) 000.00 - emulation time tick

...

CTRL-cgoing down in a ball of flames...

$

Note that:

1. the variable LD_LIBRARY_PATH was set prior to starting Harpoon, andwas specified using Bourne shell syntax;

2. the start up script was not used, so the above variable had to be set;

3. the ‘-c’ flag was used so that Harpoon will continuously cycle over itslist of active sessions—this is typically what is desired for a server;

4. the sixth log line (starting “11:06:04 sev(01) <stopping plugins:

TcpServer:ok >” indicated that initial starting of the plugin was suc-

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 40/51

Appendix A: More Examples 36

cessful (note that the plugin is first stopped and then started—this isnormal);

5. each log line has the wall-clock time (hour:minute:second), a severity

indication (ranging from 0, most important, to 10, debug jabber), Har-poon emulation time (epoch.fractional epoch), and the actual log mes-sage (note that the severity levels are currently rather inconsistent—sorry);

6. the process was stopped by hitting CTRL-c.

The client side startup looks very similar, so it is not shown. Using eitheryour own monitoring tools or the XML-RPC scripts (e.g., stats.py), youshould be able to see evidence of traffic flowing.

A.4 Example Using Two Hosts, Bidirectional

Traffic at Different RatesTaking the previous example, we now want to do the following:

1. move the installation to two different hosts;

2. generate traffic in two directions;

3. set up traffic so 10 Mbps is generated in one direction and 20 Mbps isgenerated in the other direction.

Assume that host A has an IP address of  10.0.1.1, and host B has anaddress of  10.0.1.2. Assume also that we want the volume to be relatively

steady over 300 second intervals. It’s easiest if we work backwards based onthe requirements above. First, we want to find out how many active sessionswe need for generating 10Mbps, and how many sessions for 20 Mbps. Toaccomplish this, we need to use the harpoon_reconf.py script:

$ harpoon_reconf.py -c tcp_client_ex2.xml -s tcp_server_ex2.xml -i 300 \

-r 10000000 -d

target volume: 375000000.0

interval duration: 300

client conf file: ../examples/tcp_client_ex2.xml

server conf file: ../examples/tcp_server_ex2.xml

target: 375000000.0 carry: 0

targetbytes 375000000.0 simbytes 407692953 median 7 mean 6 \

stdev 1.50339682726 max 9 flows 3758number of sessions should be 6 to achieve volume of 375000000 bytes \

(10000000.0 bits/sec)

As arguments to harpoon_reconf.py, we supply the two existing config-uration files (‘tcp_client_ex2.xml’ and ‘tcp_server_ex2.xml’), the inter-val duration (300 seconds), and the desired rate (10000000 bits per second).(We also supplied the ‘-d’ flag to get a little more verbose output.) We seethat there should be 6 sessions configured to produce 10 Mbps. In a similarway, we find that there should be 11 sessions configured to produce 20 Mbps.

Next, we need to create some new configuration files based on our existing

files. Since the source and destination addresses for our clients are different,

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 41/51

Appendix A: More Examples 37

we need two separate client configuration files. We’ll use default addressesfor the server, so we only need one server config file for both machines.

The steps should be:

1. copy ‘tcp_client_ex2.xml’ to ‘clientA.xml’ and ‘clientB.xml’;2. edit ‘clientA.xml’ to have source address of  10.0.1.1, destination ad-

dress of  10.0.1.2, and number of active sessions as the single value 6(also make sure that maxthreads attribute is set to at least 6);

3. edit ‘clientB.xml’ to have source address of  10.0.1.2, destination ad-dress of  10.0.1.1, and number of active sessions as the single value 11(also make sure that maxthreads attribute is set to at least 11);

4. move ‘clientA.xml’ and a copy of ‘tcp_server_ex2.xml’ to host A,and ‘clientB.xml’ and a copy of ‘tcp_server_ex2.xml’ to host B;

5. start up servers;6. start up clients.

Once we start things up, we see that the 10 second averages over one 50second period (in the 10Mbps direction) are: 15212977, 10309469, 9073456,9846232, 14869665, which gives an average of about 11.8Mbps. Over a longerperiod, the average comes closer to 10Mbps, though generally will never beexactly 10Mbps. It should, however, be close over the range of an inter-val duration. Again, the quality of the match depends on a number of things, including the interval duration, the maximum inter-connection time(specified when using the self-configuration tools), and the nature of the

inter-connection and file size distributions (heavy-tailed distributions needto be sampled over a long duration for the sample mean to come close to thedistributional mean).

For the 20Mbps direction, we also take 10 second averages using SNMP.Over a 160 second duration, the samples are: 14028319, 23009625, 19027488,20827397, 31798955, 32786164, 13115353, 15678779, 13945478, 11020225,14158496, 10773346, 15449599, 18931181, 24803243, 26993437 which givesan average of 19.1Mbps—pretty close to 20Mbps, even over a shorter intervaland the specified 300 seconds.

A.5 Example with Three HostsFinally, we want to do the following:

1. set up two client machines (A and B) to make requests to a single server;

2. generate 10 Mbps on reverse path to client A, and 5 Mbps on reversepath to client B;

3. set up two server processes to handle the load, so that one process servesclient A, and the other process serves client B.

To our network of hosts A and B, we add a new machine, host C, with

IP address 10.0.1.3. We’ll use host C as our server.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 42/51

Appendix A: More Examples 38

The easiest thing is to set up the server config files. Since we want toset up two processes to handle the server load, we’ll need two configurationfiles:

1. copy the original server config file ‘tcp_server_ex2.xml’ to‘serverA.xml’ and ‘serverB.xml’;

2. edit ‘serverA.xml’ to listen on port 10001 for client connections fromhost A (find the address pool toward the end of the file);

3. edit ‘serverB.xml’ to listen on port 10002 for client connections fromhost B (find the address pool toward the end of the file);

4. move these two config files to host C.

The server processes can now be started. You may wish to start themin the background, writing to separate log files. The other item you should

be aware of is that the XML-RPC ports should be set differently from thedefault, otherwise these servers will clash. Assuming we’ve already set LD_LIBRARY_PATH, the start up lines should be something like:

$ harpoon -f serverA.xml -p 8181 -l serverA.log -w300 -c -v10 &

$ harpoon -f serverB.xml -p 8182 -l serverB.log -w300 -c -v10 &

Now, we need to set up the client config files. Since we already set theclient source address in the previous example (see see Section A.4 [ExampleUsing Two Hosts], page 36), we just need to set the destination addressesand ports correctly, and set the number of active sessions to produce thedesired volumes.

First, we need to find out how many sessions should be active to produce5Mbps:

$ harpoon_reconf.py -c clientB.xml -s serverB.xml -i 300 -r 5000000 -d

target volume: 187500000.0

interval duration: 300

client conf file: ../examples/tcp_client_ex2.xml

server conf file: ../examples/tcp_server_ex2.xml

target: 187500000.0 carry: 0

targetbytes 187500000.0 simbytes 209525866 median 4 mean 3 \

stdev 0.891882585016 max 5 flows 2050

number of sessions should be 3 to achieve volume of 187500000 bytes \

(5000000.0 bits/sec)

harpoon_reconf.py shows that there should be three sessions active toproduce 5Mbps.

Now, we can edit the client config files and start the clients up:

1. edit ‘clientA.xml’ to have host C (10.0.1.3) as the destination ad-dress and 10001 for the destination port (note that we already have thenumber of active sessions set to produce 10Mbps);

2. edit ‘clientB.xml’ to have host C (10.0.1.3) as the destination addressand 10002 for the destination port;

3. also in ‘clientB.xml’, set the number of active sessions to three.

Now, start up the clients:

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 43/51

Appendix A: More Examples 39

hostA$ harpoon -f clientA.xml -w300 -v10

...

hostB$ harpoon -f clientB.xml -w300 -v10

After a while, we check the server A process to see how much traffic isbeing generated using the stats.py script:

$ stats.py -u http://hostC:8181/

stats for <ServerProxy for hostC:8181/>

server-wide information:

emulation_interval 0

----

plugin-specific information:

TcpServer is running - up for 117 seconds

target threads = 37 active threads = 37

num_transfer = 639

send_bandwidth_total_bps = 4588290.0send_bandwidth_recent_bps = 5593370.0

bytes_sent_total = 67103700.0

bytes_sent_recent = 53137000.0

personality = server

We see that about 5Mbps is being generated, which is what we wanted.

Note that for all these examples, we have not specified any physical con-nections, any emulated round-trip times, routes, or the like. These config-uration settings are outside the domain of Harpoon. You should set theseparameters based on requirements for your tests. You should also be awarethat changing these network parameters (as opposed to application layer

parameters in Harpoon) can make very significant differences in the natureof the generated traffic. Refer to the Harpoon technical paper for examplesof such differences.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 44/51

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 45/51

Appendix B: XML Configuration Schema 41

also, there are different elements required for different

sources. refer to the manual...

NB: also, defining the sub-elements of the plugin as a sequence

is overly restrictive, since they must appear in the same orderas below. in the actual code, we don’t make that restriction;

elements can appear in any order.

-->

<xsd:element name="interconnection_times" type="float_list"

 minOccurs="0" maxOccurs="unbounded" />

<xsd:element name="active_sessions" type="int_list"

 minOccurs="0" maxOccurs="unbounded" />

<xsd:element name="file_sizes" type="int_list"

 minOccurs="0" maxOccurs="unbounded" />

<xsd:element name="address_pool" type="addressList"

 minOccurs="0" maxOccurs="unbounded" />

</xsd:sequence>

<xsd:attribute name="name" type="xsd:string" use="required"/>

<xsd:attribute name="objfile" type="xsd:string" use="required"/>

<xsd:attribute name="maxthreads" type="xsd:int" use="required"/>

<xsd:attribute name="personality" type="personalityType"

use="optional"/>

</xsd:complexType>

<xsd:simpleType name="int_list">

<xsd:list itemType="xsd:unsignedLong"/>

</xsd:simpleType>

<xsd:simpleType name="float_list">

<xsd:list itemType="xsd:float"/>

</xsd:simpleType>

<xsd:simpleType name="personalityType"><xsd:restriction base="xsd:string">

<xsd:enumeration value="client"/>

<xsd:enumeration value="server"/>

<xsd:enumeration value="unknown"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name="addressPoolType">

<xsd:restriction base="xsd:string">

<xsd:enumeration value="client_source_pool"/>

<xsd:enumeration value="client_destination_pool"/>

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 46/51

Appendix B: XML Configuration Schema 42

<xsd:enumeration value="server_pool"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:complexType name="addressList"><xsd:sequence>

<xsd:element name="address"

 minOccurs="1" maxOccurs="unbounded"

type="addressSpecifier"/>

</xsd:sequence>

<xsd:attribute name="name" type="addressPoolType" use="required"/>

</xsd:complexType>

<xsd:complexType name="addressSpecifier">

<xsd:attribute name="ipv4" type="ipv4Type" use="required"/>

<!-- NB: not restrictive enough --><xsd:attribute name="port" type="xsd:nonNegativeInteger"

use="required"/>

</xsd:complexType>

<xsd:simpleType name="ipv4Type">

<xsd:restriction base="xsd:string">

<!-- NB: not completely accurate, but sufficient for now -->

<xsd:pattern value="\d{1,3}(\.\d{1,3}){0,3}(\/(\d+)){0,1}" />

</xsd:restriction>

</xsd:simpleType>

</xsd:schema>

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 47/51

Appendix C: Creating New Traffic Generation Modules 43

Appendix C Creating New TrafficGeneration Modules

Creating a new traffic generation module can be as simple as subclassingthe HarpoonPlugin class. There are five pure virtual methods that must beoverwritten to accomplish this:

• bool init(HarpoonPluginConfig*)

• void client_session(void)

• void server_session(void)

• void stats(std::ostream&)

• void shutdown(void)

A toy example is given below. It is a good idea to review the docu-

mentation and code for the TCPPlugin before attempting to write your ownplugin.

Note in the example below that the C symbol factory_generator is thesymbol for which harpoon searches. This function returns just returns a newtraffic generator object that implements the five specific entrypoints namedabove.

There are some tricks to maintaining common data structures for a plu-gin. See the TCPPlugin for documentation and an example of this behavior.

class DummyPlugin : public HarpoonPlugin

{

public:DummyPlugin() : HarpoonPlugin() {}

virtual ~DummyPlugin() {}

// plugin general, and thread specific configuration. this method

// is called for every thread, so you must be careful not to

// re-initialize anything.

virtual bool init(HarpoonPluginConfig *hpc)

{

HarpoonPlugin::init(hpc);

return true;

}

// if plugin personality is client, this method is called

virtual void client_session()

{

std::cerr << "dummy client session begin" << std::endl;

sleep(10);

std::cerr << "dummy client session end" << std::endl;

}

// if plugin personality is server, this method is called

virtual void server_session()

{

std::cerr << "dummy server session begin" << std::endl;

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 48/51

Appendix C: Creating New Traffic Generation Modules 44

sleep(10);

std::cerr << "dummy server session end" << std::endl;

}

// called for all threads when the plugin is being shut down.virtual void shutdown()

{

std::cerr << "dummy shutdown" << std::endl;

return;

}

// best to check your own personality here to decide what stats

// to return.

virtual void stats(std::ostream &os)

{

XmlRpcUtil::encode_struct_value(os, "dummystats", "no stats!");

}};

/*

* factory function. "factory_generator" is the C symbol we look for

* when loading harpoon plugins. (We use a C factory function to get

* around C++ name mangling issues.)

*/

extern "C"

{

Harpoon::DummyPlugin *factory_generator(void)

{

return (new Harpoon::DummyPlugin());}

}

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 49/51

Appendix C: Postscript 45

Postscript

The full technical paper describing Harpoon appeared in the Internet

Measurement Conference, Taormina, Sicily, Italy, in October 2004(http://www.cs.wisc.edu/~jsommers/pubs/p173-sommers.pdf ).Harpoon first appeared as an extended poster at the SIGMET-RICS conference, New York, New York, USA, in June 2004(http://portal.acm.org/citation.cfm?doid=1005686.1005733 ).

Thanks to Jeff Sommers for making the Harpoon icon. Thanks to DavePlonka at the University of Wisconsin for help understanding limitations of flow records.

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 50/51

Appendix C: Index 46

7/29/2019 Harpoon Manual

http://slidepdf.com/reader/full/harpoon-manual 51/51

Appendix C: Index 47

Index

Aactive sessions distribution

. . . . . . . . .

3, 19address range distributions . . . . . . . . . 3, 20addressing . . . . . . . . . . . . . . . . . . . . . . . . 9, 20

Bbuilding the software . . . . . . . . . . . . . . . . . . 5

Ccompiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

config file validation. . . . . . . . . . . .

7, 26, 34configuration file distribution . . . . . . . . . 31configuration file example . . 17, 21, 33, 34configuration file structure . . 7, 14, 17, 22,

33, 34configuring. . . . . . . . . . . . . . . . . . . . . . . 15, 26

Ddistributional parameters . . . . . . . . . . 4, 18distributions . . . . . . . . . . . . . . . . . . . . . . 3, 18

Eenvironment variables . . . . . . . . . . . . . . 6, 25event logging . . . . . . . . . . . . . . . . . . . . . . . . 25example configurations . . . . . . . . . . . . . . . . 7

Ffile size distribution . . . . . . . . . . . . . . . . 3, 19flow-level architecture . . . . . . . . . . . . . . . . . 1

Ggetting started . . . . . . . . . . . . . . . . . . . . . . . . 1

H

Iinter-connection time distribution

. . .

3, 19interval duration . . . . . . . . . . . . . . . . . . . . . . 4

Mmanaging harpoon . . . . . . . . . . . . . . . . 28, 31modifying addresses . . . . . . . . . . . . . . . . . . . 9

Pparameters. . . . . . . . . . . . . . . . . . . . . . . . . 3, 4

plugin code example. . . . . . . . . . . . . . . . .

43plugin file . . . . . . . . . . . . . . . . . . . . . . . . 31, 43plugins . . . . . . . . . . . . . . . . . . . . . . . . 5, 17, 43

Rremote management . . . . . . . . . . . . . . 28, 31running harpoon . . . . . . . . . . . . . . . . . . . . . 24running harpoon, example . . . . . . . . 10, 34

Sself-configuration

. . . . . . . . . . . . . . . . . . . .

15self-configuration tools . . . . . . . . . . . . . . . 26signal handling . . . . . . . . . . . . . . . . . . . . . . 25software components . . . . . . . . . . . . . . . . . . 4stats.py tool . . . . . . . . . . . . . . . . . . 11, 13, 39

Ttraffic generation plugins . . . . . . . . . . . . . 42traffic generator plugins . . . . . . . . . . . . . . . 5traffic volume, tuning . . . . . . . . . . . . . 12, 36

Vvalidating configuration files . . . . . . . . 7, 26

X


Recommended