OTG Software User Manual

Introduction

ORBIT Traffic Generator is a tool to generate traffic for testing network performance. It is primary focus is to generate bulk data of various characteristics and use either TCP or UCP protocol to transport data. Also, the properties of each packet such as packet size, packet deliver time are all reported to OML or a local logfile. User can obtain certain measurements like throughput, packet loss by querying the OML database directly. Options to extract physical layer parameters are also available.

Install OTG Software Package

Some prerequisites for OTG installation:

• Linux Debian Kernel
• OML Libraries (if you need reporting measurements to the OML database)
• LIBMAC (if you need physical-layer measurements).

The installation of Orbit Traffic Generator is simple. On any node of Orbit Testbed, give command

apt-get install otg

Further installation questions about OS platform and OML, LIBMAC in Orbit Testbed could be sent to orbit-user@….

Using Orbit Traffic Generator Software

List of Options

A user could give many command-line arguments to configure the OTG and OTR program. The proper usage of all arguments are described in following tables. Note that as long as there is a default value for the option argument, that option could be omitted. Option could be set in either of following format:

--option=arg
--option arg

Options could be given at start time for OTG program

name	usage	default	Possible values
protocol	specify the protocol used by OTG program.	udp	udp, tcp, raw
generator	specify the generator used by OTG program.	cbr	cbr, expoo
debuglog	specify the logfile for debugging mode (non-OML mode).By default, OTG use OML mode	NULL	tmp/log1
clockref	specify the clocking reference for timestamp reporting. hours since 01/01/1970	-1	313171,…

For UDP or TCP protocol, further options are:

name	usage	default	Possible values
port	Specify a unique local port the OTG program binds to.	3000	any unused port number
dsthostname	specify destination host’s name or IP address. IP address is preferred.	host2,192.168.0.3
dstport	specify destination host’s receiving port number.	4000	any valid port number
broadcast	use otg send broadcast packets to a broadcast IP address. UDP protocol only.	off	on,off

For "raw" protocol,

name	usage	default	Possible values
txdev	the device to transmit packets		eth2, ath0…
dstmacaddr	MAC address of the destination		12:4A:56:D0:E1:75

If generator type is "cbr",

name	usage	default	Possible values
size	set the packet size of traffic generated. Unit bytes	512	integer<65536
rate	set the data rate of generated traffic. The unit is bps.	4.096	0.1,100…
interval	set the packet interval. Unit: milliseconds	1000	0.1,20…

If generator type is "expoo"

name	usage	default	Possible values
size	set the packet size of traffic generated. Unit bytes	512	integer
rate	set the data rate of generated traffic. The unit is Kbps.	4.096	10,3.3…
ontime	average burst length in milliseconds	1000	20000, 2.1…
offtime	average idle time in milliseconds	1000	20000,2.2…

Note that if you set ontime and offtime as 0.0, the traffic will become constant-bit-rate.

Options could be given at run-time for OTG program

Note: All traffic generator parameters could be changed at run time.

name	usage
exit	terminate or exit the program.
pause	pause the traffic generator.
resume	resume the traffic generator.

Options could be given at start time for OTR program

name	usage	default	possible values
protocol	specify the protocol used by OTR program.		udp,tcp,udp_libmac,tcp_libmac, raw, raw_libmac
debuglog	specify the logfile for debugging mode (non-OML mode).By default, OTR use OML mode	NULL	tmp/log1
clockref	specify the clocking reference for timestamp reporting. hours since 01/01/1970	-1	313171,…

If protocol is set as "udp" or "tcp"

name	usage	default	possible values
port	specify the unique local port the OTR program binds to.	4000	any unused port number

If protocol is set as "raw"

name	usage	default	possible values
rxdev	Device Name of local host to receive		eth0 ath0…
dstfilter	filter packets with IP destination address	NULL	IP address (192.168.0.5)

If protocol is set as "udp_libmac","tcp_libmac" or "raw_libmac", an addition parameter is needed

name	usage	default	possible values
hostname	IP address of the PHY network interface		IP address(192.168.0.3)

Options could be given at run-time for OTR

name	usage
exit	terminate and exit the program.

Test Scenario Examples

Point-to-point communication (Unicast)

UDP

node1-2:~#otr --protocol udp  
node1-1:~#otg --protocol udp --dsthostname 192.168.1.2 

TCP

node1-2:~#otr --protocol tcp  
node1-1:~#otg --protocol tcp --dsthostname 192.168.1.2 

In both above cases, the default port which OTG program is bind to is 3000. The default port the OTR program binds to is 4000. The default destination port the OTG program is send to is also 4000. The IP address of the node where OTR is running is supposed to 192.168.1.2. Otherwise, no traffic will be received by OTR program. The default traffic is one packet per second. Packet size is 512 bytes (equivalent to 4.096Kbps data rate).

Use ports other than default

node1-2:~#otr --protocol tcp --port 4500 
node1-1:~#otg --protocol tcp --port 3100 --dsthostname 192.168.1.2 

In this case, the default port which OTG program is bind to is 3100. The default port the OTR program binds to is 4500. The default destination port the OTG program is send to is also 4500.

Configure generator

node1-2:~#otr --protocol udp 
node1-1:~#otg --protocol udp --generator cbr --size 1024 --rate 200 --dsthostname 192.168.1.2 

This case, CBR traffic are set rate as 200kbps and packet size is 1024 bytes.

another example

node1-2:~#otr --protocol udp 
node1-1:~#otg --protocol udp --generator expoo --size 1024 --rate 200 --ontime 0.5 --offtime 0.5 --dsthostname 192.168.1.2 

Raw socket

node1-2:~#otr --protocol raw  --rxdev ath0
node1-1:~#otg --protocol=raw --dstmacaddr=00:60:B3:AC:A1:70 --txdev=ath0 

Use LibMAC to get RSSI and XmitRate

$node1-1:otg --protocol udp --dsthostname 192.168.2.2
$node2-2:otr --protocol udp_libmac --hostname 192.168.2.2 --port 4000

In this case, the default port which OTG program is bind to is 3000. The default port the OTR program binds to is 4000. The default destination port the OTG program is send to is also 4000. The IP address of the node where OTR is running is supposed to 192.168.2.2. Otherwise, no traffic will be received by OTR program. The “hostname” option in OTR is mandatory and must be IP address in this scenario. You cannot supply the option like “—hostname node2-2”. Otherwise, the program will fail.

Multipoint-to-point communication (Unicast)

Sender: Node1-1, Node2-2, Node3-3, Node4-4, Node5-5, Node6-6, Node7-7. Receiver Node8-8

$node1-1:otg --protocol udp --dsthostname 192.168.8.8
$node2-2:otg --protocol udp --dsthostname 192.168.8.8
$node3-3:otg --protocol udp --dsthostname 192.168.8.8
$node4-4:otg --protocol udp --dsthostname 192.168.8.8
$node5-5:otg --protocol udp --dsthostname 192.168.8.8
$node6-6:otg --protocol udp --dsthostname 192.168.8.8
$node7-7:otg --protocol udp --dsthostname 192.168.8.8
$node8-8:otr --protocol udp

In this case, the default port which OTG program is bind to is 3000. The default port the OTR program binds to is 4000. The default destination port the OTG program is send to is also 4000. The IP address of the node where OTR is running is supposed to 192.168.8.8. Otherwise, no traffic will be received by OTR program. The default traffic is one packet per second. Packet size is 512 bytes.

Point-to-Multipoint communication (Unicast)

Sender: Node1-1, Receiver: Node2-2, Node3-3, Node4-4

$node1-1:otg --protocol tcp --port 3100 --dsthostname 192.168.2.2
$node2-2:otg --protocol tcp --port 3200 --dsthostname 192.168.3.3
$node3-3:otg --protocol tcp --port 3300 --dsthostname 192.168.4.4
$node2-2:otr --protocol tcp
$node3-3:otr --protocol tcp
$node4-4:otr --protocol tcp

In this case, there are three OTG program running on port 3100,3200,3300 respectively. The default port for each OTR program binds to is 4000. The default destination port the OTG program is send to is also 4000. The default traffic is one packet per second. Packet size is 512 bytes.

Runtime Parameter Changes and User Control

Some parameters can be changed at runtime in the shell where program is started. To given an option in the runtime, you do not need to give the starting two hyphens. “—“. However, if you give more than one option in one command, the hyphen is still needed since the second option. Traffic generator can be paused by give “pause” option and can be resumed by “resume” option. Type “exit” will simply quit the program.

Examples:

$node1-1:otg --protocol udp --dsthostname 192.168.2.2
Binding to port 3000...
size 1000 --rate 1000
size is change to 1000
rate is set to 1e6bps...
pause
resume
exit
$node1-1:

Understanding Measurements

We defined three OML tables which contains measurements:

senderport	receiverport	flow
pkt_seqno pkt_size gen_timestamp tx_timestamp	pkt_seqno flow_no rcvd_packet_size rx_timestamp rssi xmit_rate	flow_ no sender_ip sender_port

Explanation of the Metric

name	usage	unit
pkt_seqno	Packet sequence number in the sender stream, this number is stamped in UDP payload and can be recovered in receiver side (not available in raw_socket receiver)
pkt_size	Packet Payload size	bytes
gen_timestamp	Deliver time the generator specifies(time offset since otg is started)	milliseconds
tx_timestamp	Time when packet is being sent (offset since 12am today or clockref parameter)	milliseconds
flow_no	id of the flow. If receiver received packets from different sources. we classify them as different flows
rcvd_packet_size	Received Payload size	bytes
rx_timestamp	Time when packet is being received (offset since 12am today or clockref parameter)	milliseconds
rssi	received signal strength indicator
xmit_rate	Xmit rate indicated in the Signal Field of PLCP header of received packet.	0.1Mbps, 55 indicates 5.5Mbps.
sender_ip	Sender IP address or hostname (not available temporarily)
sender_port	Sender port of the stream

Note that the gen_timestamp is referred to the starting time of the OTG program. But the rx_ tx_ timestamps are referred to an absolute time value. This absolute clock reference is the 12am of the day when the experiment is executed. It's possible that the program running duration is around 12am clock. So, it is better to have an external absolute clock reference by —clockref parameter.

Case 1: One-to-One Communication

Figure 1. Point to Point Unicast

Suppose one OTG sends packet to one OTR. The senderport table will record all information in sender side. the receiveport table will record per-packet information in receiver side.

• Offerload: by summing the pkt_size metric in one second, the value indicates how many Bps traffic is supplied
• Throughput: by summing the rcvd_packet_size metric in one second, the value indicates how many Bps traffic is received
• Packet loss : A good use of pkt_seqno is that by comparing the pkt_seqno of this two tables, you could find exactly what packet gets lost in the LUT (Link Under Test). But this feature cannot be used for TCP traffic.
• Delay: The packet delay could be determined by subtracting rx_timestamp with tx_stamp of the same packet. This feature cannot be used for TCP traffic because TCP does not receive packets in frames.
• Jitter: (option feature) by apply a differential filter to rx_timestamp metric, the jitter could be determined.

In this case, the 3rd table will not be very useful because there is only one flow.

Case 2: Many-to-One Communication

Figure 2. Multipoint to Point Unicast

Suppose multiple OTGs run in different stations and all send packets to one OTR. In this case, the receiverport table will record all packets from different OTG clients. To distinguish the source address of a packet, flow_no is the appropriate identifier. Then user could check "flow" table for further information about this flow_no, including sender'IP address and port number.