= OTG Software User Manual For release 1.1.2 (not available for users yet) =
== 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 availabe.
== 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@winlab.rutgers.edu. 

== Using Orbit Traffic Generator Software ==
=== List of Optioins ===
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|| speficy the logfile for debugging mode (non-OML mode).By default, OTG use OML mode || NULL || tmp/log1 ||
||clockref|| speficy the clocking reference for timestamp reporting. hours since 01/01/1970 || -1 || 313171,... ||
For UDP or TCP protcol, 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 tranmsit 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 Kbps.||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|| speficy the logfile for debugging mode (non-OML mode).By default, OTR use OML mode || NULL || tmp/log1 ||
||clockref|| speficy 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 measurments:
||senderport||receiverport||flow||
||pkt_seqno[[BR]]pkt_size[[BR]]gen_timestamp[[BR]]tx_timestamp||pkt_seqno[[BR]]flow_no[[BR]]rcvd_packet_size[[BR]]rx_timestamp[[BR]]rssi[[BR]]xmit_rate||flow_ no[[BR]]sender_ip[[BR]]sender_port|| 

=== Explantation 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||  ||
||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 clockerf parameter)  || milliseconds ||
||flow_no||id of the flow. If receiver receiving 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|| ||
||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 ===

[[Image(pointtopoint.gif)]]

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 informatino 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 substracting 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 becasue there is only one flow.

=== Case 2: Many-to-One Communication ===
[[Image(mptopoint.gif)]]

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 dsitinguish the souce address of a packet, '''flow_no''' is the approriate identifier.  Then user could check "flow" table for further information about this flow_no, including sender'IP address and port number.