Miner | Salzburg Research > Documentation > Sample application

Sample application

Introduction

The following MINER sample application shows a Scenario that makes use of some MinerTools and illustrates several concepts of MINER with still being a simple application. The Scenario is then executed in a private testbed. The figure depicts the setup of the scenario.

 

Setup of the sample application
Between ToolProxies al40-202 and al40-201 delay, jitter, and loss are actively measured according to an IPPM standard.

On ToolProxy al40-51, 2 different MinerTools are employed. The SnifferTool is used to capture network traffic on the interface that faces router R1. The libpcap-based tool produces a binary trace in pcap format as well as throughput data (in pkt/s) averaged over 1s intervals. Additionally, the NetemTool, which is based on the Linux NETEM functionality, is used to emulate delay.

Finally, an SNMPTool is employed on ToolProxy al40-204. It periodically sends SNMP queries to router R1.

The MINER Core is located on host al40-47 which is not shown in the figure.

Application code

Below is a listing of the sample application.

/**
 * (C) Salzburg Research Forschungsgesellschaft mbH.  All rights reserved.
 */
package at.srfg.miner;

import java.io.File;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import at.srfg.miner.clientlib.Action;
import at.srfg.miner.clientlib.Condition;
import at.srfg.miner.clientlib.Execution;
import at.srfg.miner.clientlib.Proxy;
import at.srfg.miner.clientlib.Result;
import at.srfg.miner.clientlib.ResultHandle;
import at.srfg.miner.clientlib.Results;
import at.srfg.miner.clientlib.Scenario;
import at.srfg.miner.clientlib.Task;
import at.srfg.miner.clientlib.resultformat.ResultFormatter;

/**
 * This application uses various Tools in a Scenario executed in a Salzburg
 * Research testbed.
 */
public class ManualApp {

	private static final int DURATION = 120;   // [s]

	public static void main(String[] args) throws Exception {

		System.setProperty("miner.rest", "http://al40-47:8008/rest");

		Scenario s = new Scenario("A MINER sample application");
		s.setDescription("This application is used as a sample in the manual.");
		s.addKeyword("Manual");
		Task active = s.addTask("Active");
		Task passive = s.addTask("Passive");
		Task emulation = s.addTask("Emulation");

		//
		// All actions in the 'active' task start 10 seconds after the start of
		// the execution.
		//
		active.setDeltaStart(10);

		//
		// IPPMTool: active traffic generation from al40-202 to al40-201
		//
		Action aIPPM = active.addAction("IPPM");
		Proxy receiver = aIPPM.addProxy("al40-201");
		aIPPM.addProxy("al40-202");
		aIPPM.setTool("IPPMTool");
		aIPPM.setToolconfig(new File("etc/ippm.xml"));

		// IPPM lossAvg
		ResultHandle hLoss = aIPPM.produce("lossRatio")
				.configure("interval", 5)
				.configure("lossThreshold", 10)
				.setSavePattern("ippmLoss")
				.setQueryProxies(receiver);

		// IPPM 1-way delay measured via kernel-level timestamps
		ResultHandle hOwdPcap = aIPPM.produce("owdPcap");

		// Trigger an alarm if the delay >= 100ms
		aIPPM.addCondition(Condition.ALL).addSubcondition(hOwdPcap, "<", 50000);

		//
		// SnifferTool on al40-51 / eth1
		//
		Action aSniffer = passive.addAction("SnifferIngress");
		aSniffer.addProxy("al40-51");
		aSniffer.setTool("SnifferTool");
		aSniffer.setToolconfig(new File("etc/sniffer.xml"));

		// Sniffer throughput as pkt/s
		ResultHandle hTputPkt = aSniffer.produce("tputPkt")
				.configure("interval", 1);

		// Sniffer pcap dump file
		ResultHandle hTrace = aSniffer.produce("raw")
				.setSavePattern("tcpdump-.pcap");

		//
		// SNMPTool on al40-168
		//
		Action aSNMP = passive.addAction("SNMP");
		aSNMP.addProxy("al40-204");
		aSNMP.setTool("SNMPTool");
		aSNMP.setToolconfig(new File("etc/snmp.xml"));

		// SNMP query ipForward
		ResultHandle hIpForward = aSNMP.produce("SNMPValue")
				.setSelector("1.3.6.1.2.1.4.6.0")
				.setSavePattern("ipForward");

		// SNMP query routerInfo
		ResultHandle hRouterInfo = aSNMP.produce("SNMPTree")
				.setSelector("1.3.6.1.2.1")
				.setSavePattern("snmpTree");

		//
		// NETEMTool on al40-51
		// emulates delay of 100ms
		//

		Action aNetem = emulation.addAction("Netem");
		aNetem.setDeltaStart(60);
		aNetem.setDuration(30);
		aNetem.addProxy("al40-51");
		aNetem.setTool("NetemTool");
		aNetem.setToolconfig(new File("etc/netem.xml"));

		// we request no result from this tool

		//
		//
		// The Scenario specification is complete.
		//
		// SUBMIT it to the Server
		//
		s.submit();

		//
		// Schedule the Scenario for execution
		// start now and run for DURATION seconds
		//
		Date start = new Date();
		Date stop = new Date(start.getTime() + DURATION * 1000);
		Execution exec = s.schedule(start, stop, "My first scenario execution");

		// During the execution we query the tputPkt every 5 seconds and print
		// timestamp / value pairs.

		List<Result> tputResults = new ArrayList<Result>();

		while (!exec.isFinished()) {
			Thread.sleep(5000);

			List<Result> results = exec.nextResults(hTputPkt);
			if (!results.isEmpty()) {
				Results.print(results);
				tputResults.addAll(results);
			}
		}

		// get the remaining tputPkt results (if any)
		tputResults.addAll(exec.nextResults(hTputPkt));

		// Get and print the excecutionlog
		System.out.println(exec.getLog());

		// Save all results to subdirectory 'results'
		Results.setSaveDir(new File("results"));

		// get the binary pcap trace
		// note that binary results are automatically saved to disk
		exec.allResults(hTrace);

		// Finally, save some results to the filesystem
		Results.save(tputResults, "tput.txt");
		Results.getAndSave(exec, hOwdPcap, hLoss, hIpForward);
	}

}

Configuration files

ippm.xml
<?xml version="1.0" encoding="UTF-8"?>
<IPPMTool xmlns="https://miner.salzburgresearch.at/xml/ns/tool/ippmtool">
	<srcIP>10.1.0.202</srcIP>
	<dstIP>10.2.0.201</dstIP>
	<srcPort>40000</srcPort>
	<dstPort>40000</dstPort>
	<payloadSize>100</payloadSize>
	<const>100000</const>
</IPPMTool>
 sniffer.xml
<?xml version="1.0" encoding="UTF-8"?>
<SnifferTool xmlns="https://miner.salzburgresearch.at/xml/ns/tool/sniffertool">
	<IP>10.16.0.2</IP>
	<filterString>udp and port 40000</filterString>
</SnifferTool>
snmp.xml
<?xml version="1.0" encoding="UTF-8"?>
<SNMPTool xmlns="https://miner.salzburgresearch.at/xml/ns/tool/snmptool">
	<Community>topsecret</Community>
	<Address>192.168.40.2</Address>
	<Timeout>2000</Timeout>
	<Retries>3</Retries>
	<Pause>5000</Pause>
</SNMPTool>

netem.xml

<?xml version="1.0" encoding="UTF-8"?>
<NetemTool xmlns="https://miner.salzburgresearch.at/xml/ns/tool/netemtool">
	<device>eth2</device>
	<action>
		<delay>
			<value>100</value>
		</delay>
	</action>
</NetemTool>

Comments

IPPM lossRatio result request
  • The result class lossRatio has a required configuration parameter interval: the time interval over which the average is computed.
  • Additionally we set the optional configuration parameter lossThreshold: if a packet is received with a delay > lossThreshold it is considered as lost.
  • As the IPPMTool results are exclusively produced at the receiver, we restrict the result query to the receiver ToolProxy.
Condition on the delay result

We define that the measured delay must be smaller than 95ms. As NETEM is configured to emulate a delay of 100ms between 60-90s of the experiment, we expect condition violation alarms in the Executionlog.

SNMP results

The SNMPTool can be used to retrieve a huge number of different results, depending on the OID used in an SNMP GET and WALK, for example. The number of available queries is so large, that they are not registered individually as single results at the MINER Core. Instead, the SNMP tool makes use of the selector mechanism that is available to MinerTool developers. Instead of registering an individual result, the tool developer registers a result “template” like SNMPValue. This result must then be requested with additional selector to provide a fully specified result request. For the SNMPTool, the selector is the OID to be used for the query. Therefore, the result request for ipForwarding statistics looks like:

aSNMP.produce("SNMPValue").setSelector("1.3.6.1.2.1");
Getting results during the execution

To see some results during the execution, the tputPkt result is queried every 5 seconds. As we want to save those results to a file later on, we collect them (to avoid an additional query for all results after the execution has finished).

Execution aftermath

After the execution has finished, we first get and print the executionlog. Note that the log contains the condition violations as expected.

Then we make various uses of the Results class to demonstrate some of its capabilities. The binary pcap trace is retrieved and automatically saved to disk. Before proceeding, the directory for saving results is set. This directory is used in the subsequent save/getAndSave calls. The binary pcap trace is retrieved and saved automatically because binary results are always saved to disk.  The tputPkt results that were collected during the execution are then saved to a file. Finally, the hOwdPcap, hLoss, and hIpForward results are retrieved and saved to individual files. Note that the savePatterns of hLoss and hIpForward are used. The result hRouterInfo is not loaded from the MINER Core in this scenario.

Results

Executionlog

The Executionlog contained the following output.

2011-09-01 14:28:04.0 INFO  Execution 7 deployed
2011-09-01 14:28:04.0 INFO  Tool init ok  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:28:04.0 INFO  Tool init ok  [execId=7/al40-204/SNMP/SNMPTool]
2011-09-01 14:28:04.0 INFO  Tool init ok  [execId=7/al40-201/IPPM/IPPMTool]
2011-09-01 14:28:04.0 INFO  Tool init ok  [execId=7/al40-202/IPPM/IPPMTool]
2011-09-01 14:28:04.0 INFO  Tool init ok  [execId=7/al40-51/SnifferIngress/SnifferTool]
2011-09-01 14:28:04.0 INFO  Entering tool run  [execId=7/al40-51/SnifferIngress/SnifferTool]
2011-09-01 14:28:04.0 INFO  Entering tool run  [execId=7/al40-204/SNMP/SNMPTool]
2011-09-01 14:28:13.0 INFO  Entering tool run  [execId=7/al40-201/IPPM/IPPMTool]
2011-09-01 14:28:13.0 INFO  Entering tool run  [execId=7/al40-202/IPPM/IPPMTool]
2011-09-01 14:29:03.0 INFO  Entering tool run  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:29:03.0 INFO  Netem options reset for device eth2 successfully completed  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:29:03.0 INFO  Adding options  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:29:03.0 INFO  All options set  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:29:04.0 WARN  Condition violation: subcondition 'owdPcap < 50000.0' violated by owdPcap value of '100303.0'.
2011-09-01 14:29:14.0 WARN  Condition violation: subcondition 'owdPcap < 50000.0' violated by owdPcap value of '100235.0'.
2011-09-01 14:29:25.0 WARN  Condition violation: subcondition 'owdPcap < 50000.0' violated by owdPcap value of '100285.0'.
2011-09-01 14:29:33.0 INFO  Entering tool finish  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:29:33.0 INFO  Netem options reset for device eth2 successfully completed  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:29:33.0 INFO  Action finished  [execId=7/al40-51/Netem/NetemTool]
2011-09-01 14:30:03.0 INFO  Entering tool finish  [execId=7/al40-202/IPPM/IPPMTool]
2011-09-01 14:30:03.0 INFO  Sender capture statistic
Received packets: 1100
Dropped packets : 0
Sent 1100  [execId=7/al40-202/IPPM/IPPMTool]
2011-09-01 14:30:03.0 INFO  Action finished  [execId=7/al40-202/IPPM/IPPMTool]
2011-09-01 14:30:03.0 INFO  Entering tool finish  [execId=7/al40-51/SnifferIngress/SnifferTool]
2011-09-01 14:30:03.0 INFO  Sniffer info:
Packets received : 1100
Packets captured : 1100
Packets dropped  : 0
  [execId=7/al40-51/SnifferIngress/SnifferTool]
2011-09-01 14:30:03.0 INFO  Action finished  [execId=7/al40-51/SnifferIngress/SnifferTool]
2011-09-01 14:30:03.0 INFO  Entering tool finish  [execId=7/al40-201/IPPM/IPPMTool]
2011-09-01 14:30:03.0 INFO  Receiver capture statistic
Received packets: 1100
Dropped packets : 0  [execId=7/al40-201/IPPM/IPPMTool]
2011-09-01 14:30:04.0 INFO  Action finished  [execId=7/al40-201/IPPM/IPPMTool]
2011-09-01 14:30:04.0 INFO  Entering tool finish  [execId=7/al40-204/SNMP/SNMPTool]
2011-09-01 14:30:04.0 INFO  Action finished  [execId=7/al40-204/SNMP/SNMPTool]
2011-09-01 14:30:04.0 INFO  Execution 7 finished

Note that the condition violations are reported as expected.  The MINER Core was configured to report the violation of a Condition at most once every 10 seconds.

Result files

The results directory contains the following files:

$ ls results/
ipForward.txt  owdPcap.txt                               tput.txt
ippmLoss.txt   tcpdump-al40-51-raw-1314880203700-0.pcap

Visualisation of result data

Throughput

The following figure shows the throughput measured by the SnifferTool.

One-way delay

The following figure shows the one-way delay measured by the IPPMTool. Note that the delay is virtually 0 (all hosts are located in the same room) unless for the period between 60 and 90 seconds where the WAN emulator NETEM emulated a delay of 100ms.

IP forwarding

The following figure shows the IP forwarding numbers of the router R1. They were obtained by periodic SNMP queries of the router.

Pcap trace

The following figure shows a screenshot where the binary pcap trace which was produced by the SnifferTool is loaded in wireshark.