= 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@winlab.rutgers.edu. == 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[[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|| === 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 === [[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 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 === [[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 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.