Changes between Initial Version and Version 1 of Old/Documentation/OTG/UserManual


Ignore:
Timestamp:
Sep 26, 2005, 2:23:00 AM (19 years ago)
Author:
zhibinwu
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • Old/Documentation/OTG/UserManual

    v1 v1  
     1= OTG Software User Manual For release 1.1.2 (not available for users yet) =
     2== Introduction ==
     3ORBIT 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.
     4== Install OTG Software Package ==
     5Some prerequisites for OTG installation:
     6 * Linux Debian Kernel
     7 * OML Libraries (if you need reporting measurements to the OML database)
     8 * LIBMAC (if you need physical-layer measurements).
     9The installation of Orbit Traffic Generator is simple. On any node of Orbit Testbed, give command
     10{{{
     11apt-get install otg
     12}}}
     13Further installation questions about OS platform and OML, LIBMAC in Orbit Testbed could be sent to orbit-user@winlab.rutgers.edu.
     14
     15== Using Orbit Traffic Generator Software ==
     16=== List of Optioins ===
     17A 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:
     18{{{
     19--option=arg
     20--option arg
     21}}}
     22==== Options could be given at start time for OTG program ====
     23||'''name'''||'''usage''' ||'''default''' ||'''Possible values'''||
     24||protocol|| specify the protocol used by OTG  program.||udp ||udp, tcp, raw||
     25||generator||specify the generator used by OTG program.||cbr ||cbr, expoo||
     26||debuglog|| speficy the logfile for debugging mode (non-OML mode).By default, OTG use OML mode || NULL || tmp/log1 ||
     27||clockref|| speficy the clocking reference for timestamp reporting. hours since 01/01/1970 || -1 || 313171,... ||
     28For UDP or TCP protcol, further options are:
     29||'''name'''||'''usage''' ||'''default''' ||'''Possible values'''||
     30||port|| Specify a unique local port the OTG program binds to.||3000||any unused port number ||
     31||dsthostname||  specify destination host’s name or IP address. IP address is preferred.||||host2,192.168.0.3||
     32||dstport|| specify destination host’s receiving port number.||4000||any valid port number||
     33||broadcast||  use otg send broadcast packets to a broadcast IP address. UDP protocol only.||off|| on,off||
     34For "raw" protocol,
     35||'''name'''||'''usage''' ||'''default''' ||'''Possible values'''||
     36||txdev || the device to tranmsit packets ||   || eth2, ath0...||
     37||dstmacaddr || MAC address of the destination|| ||12:4A:56:D0:E1:75||
     38If generator type is "cbr",
     39||'''name'''||'''usage''' ||'''default''' ||'''Possible values'''||
     40||size||set the packet size of traffic generated. Unit bytes||512||integer<65536||
     41||rate||set the data rate of generated traffic. The unit is Kbps.||4.096 ||0.1,100...||
     42||interval||set the packet interval. Unit: milliseconds||1000||0.1,20...||
     43If generator type is "expoo"
     44||'''name'''||'''usage''' ||'''default''' ||'''Possible values'''||
     45||size|| set the packet size of traffic generated. Unit bytes||512 ||integer ||
     46||rate|| set the data rate of generated traffic. The unit is Kbps.||4.096 ||10,3.3... ||
     47||ontime||average burst length in milliseconds ||1000 ||20000, 2.1... ||
     48||offtime||average idle time in milliseconds ||1000 ||20000,2.2... ||
     49Note that if you set ontime and offtime as 0.0, the traffic will become constant-bit-rate.
     50
     51==== Options could be given at run-time for OTG program ====
     52Note: All traffic generator parameters could be changed at run time.
     53||'''name'''||'''usage''' ||
     54||exit|| terminate or exit the program.||
     55||pause||pause the traffic generator.||
     56||resume||resume the traffic generator.||
     57
     58==== Options could be given at start time for OTR program ====
     59||'''name'''||'''usage''' ||'''default'''||'''possible values'''||
     60||protocol|| specify the protocol used by OTR  program.|| ||udp,tcp,udp_libmac,tcp_libmac, raw, raw_libmac||
     61||debuglog|| speficy the logfile for debugging mode (non-OML mode).By default, OTR use OML mode || NULL || tmp/log1 ||
     62||clockref|| speficy the clocking reference for timestamp reporting. hours since 01/01/1970 || -1 || 313171,... ||
     63
     64If protocol is set as "udp" or "tcp"
     65||'''name'''||'''usage''' ||'''default'''||'''possible values'''||
     66||port|| specify the unique local port the OTR program binds to.||4000||any unused port number||
     67If protocol is set as "raw"
     68||'''name'''||'''usage''' ||'''default'''||'''possible values'''||
     69|| rxdev || Device Name of local host to receive ||  || eth0 ath0...||
     70|| dstfilter ||filter packets with IP destination address ||NULL ||IP address (192.168.0.5)||
     71If protocol is set as "udp_libmac","tcp_libmac" or "raw_libmac", an addition parameter is needed
     72||'''name'''||'''usage''' ||'''default'''||'''possible values'''||
     73||hostname|| IP address of the PHY network interface  || || IP address(192.168.0.3)||
     74
     75==== Options could be given at run-time for OTR ====
     76||'''name'''||'''usage''' ||
     77||exit|| terminate and exit the program.||
     78
     79== Test Scenario Examples ==
     80
     81=== Point-to-point communication (Unicast) ===
     82
     83==== UDP ====
     84{{{
     85node1-2:~#otr --protocol udp 
     86node1-1:~#otg --protocol udp --dsthostname 192.168.1.2
     87}}}
     88
     89==== TCP ====
     90{{{
     91node1-2:~#otr --protocol tcp 
     92node1-1:~#otg --protocol tcp --dsthostname 192.168.1.2
     93}}}
     94In 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).
     95
     96==== Use ports other than default ====
     97{{{
     98node1-2:~#otr --protocol tcp --port 4500
     99node1-1:~#otg --protocol tcp --port 3100 --dsthostname 192.168.1.2
     100}}}
     101In 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.
     102
     103==== Configure generator ====
     104{{{
     105node1-2:~#otr --protocol udp
     106node1-1:~#otg --protocol udp --generator cbr --size 1024 --rate 200 --dsthostname 192.168.1.2
     107}}}
     108This case, CBR traffic are set rate as 200kbps and packet size is 1024 bytes.
     109
     110another example
     111{{{
     112node1-2:~#otr --protocol udp
     113node1-1:~#otg --protocol udp --generator expoo --size 1024 --rate 200 --ontime 0.5 --offtime 0.5 --dsthostname 192.168.1.2
     114}}}
     115
     116====  Raw socket ====
     117{{{
     118node1-2:~#otr --protocol raw  --rxdev ath0
     119node1-1:~#otg --protocol=raw --dstmacaddr=00:60:B3:AC:A1:70 --txdev=ath0
     120}}}
     121
     122==== Use LibMAC to get RSSI and XmitRate ====
     123{{{
     124$node1-1:otg --protocol udp --dsthostname 192.168.2.2
     125$node2-2:otr --protocol udp_libmac --hostname 192.168.2.2 --port 4000
     126}}}
     127In 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.
     128
     129=== Multipoint-to-point communication (Unicast) ===
     130
     131Sender: Node1-1, Node2-2, Node3-3, Node4-4, Node5-5, Node6-6, Node7-7.  Receiver Node8-8
     132{{{
     133$node1-1:otg --protocol udp --dsthostname 192.168.8.8
     134$node2-2:otg --protocol udp --dsthostname 192.168.8.8
     135$node3-3:otg --protocol udp --dsthostname 192.168.8.8
     136$node4-4:otg --protocol udp --dsthostname 192.168.8.8
     137$node5-5:otg --protocol udp --dsthostname 192.168.8.8
     138$node6-6:otg --protocol udp --dsthostname 192.168.8.8
     139$node7-7:otg --protocol udp --dsthostname 192.168.8.8
     140$node8-8:otr --protocol udp
     141}}}
     142In 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.
     143
     144=== Point-to-Multipoint communication (Unicast) ===
     145Sender: Node1-1, Receiver: Node2-2, Node3-3, Node4-4
     146{{{
     147$node1-1:otg --protocol tcp --port 3100 --dsthostname 192.168.2.2
     148$node2-2:otg --protocol tcp --port 3200 --dsthostname 192.168.3.3
     149$node3-3:otg --protocol tcp --port 3300 --dsthostname 192.168.4.4
     150$node2-2:otr --protocol tcp
     151$node3-3:otr --protocol tcp
     152$node4-4:otr --protocol tcp
     153}}}
     154In 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.
     155
     156=== Runtime Parameter Changes and User Control ===
     157
     158Some 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.
     159Traffic generator can be paused by give “pause” option and can be resumed by “resume” option. Type “exit” will simply quit the program.
     160
     161Examples:
     162{{{
     163$node1-1:otg --protocol udp --dsthostname 192.168.2.2
     164Binding to port 3000...
     165size 1000 --rate 1000
     166size is change to 1000
     167rate is set to 1e6bps...
     168pause
     169resume
     170exit
     171$node1-1:
     172}}}
     173
     174== Understanding Measurements  ==
     175
     176We defined three OML tables which contains measurments:
     177||senderport||receiverport||flow||
     178||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||
     179
     180=== Explantation of the Metric ===
     181|| '''name''' || '''usage''' || '''unit''' ||
     182||pkt_seqno || Packet sequence number in the sender stream, this number is stamped in UDP payload and can be recovered in receiver side||  ||
     183||pkt_size|| Packet Payload size|| bytes ||
     184||gen_timestamp ||Deliver time the generator specifies(time offset since otg is started)|| milliseconds ||
     185||tx_timestamp || Time when packet is being sent (offset since 12am today or clockerf parameter)  || milliseconds ||
     186||flow_no||id of the flow. If receiver receiving packets from different sources. we classify them as different flows||  ||
     187||rcvd_packet_size|| Received Payload size || bytes ||
     188||rx_timestamp|| Time when packet is being received (offset since 12am today or clockref parameter) ||milliseconds ||
     189||rssi||received signal strength indicator|| ||
     190||xmit_rate||Xmit rate indicated in the Signal Field of PLCP header of received packet. || 0.1Mbps, 55 indicates 5.5Mbps.||
     191||sender_ip||Sender IP address or hostname|| ||
     192||sender_port|| Sender port of the stream||   ||
     193
     194Note 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.
     195
     196=== Case 1: One-to-One Communication ===
     197
     198http://www.winlab.rutgers.edu/~zhibinwu/image/pointtopoint.gif
     199
     200Figure 1. Point to Point Unicast
     201
     202Suppose one OTG sends packet to one OTR. The senderport table will record all information in sender side.
     203the receiveport table will record per-packet informatino in receiver side.
     204 * '''Offerload''': by summing the pkt_size metric in one second, the value indicates how many Bps traffic is supplied
     205 * '''Throughput''': by summing the rcvd_packet_size metric in one second, the value indicates how many Bps traffic is received
     206 * '''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.
     207 * '''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.
     208 * '''Jitter''': (option feature) by apply a differential filter to rx_timestamp metric, the jitter could be determined.
     209
     210In this case, the 3rd table will not be very useful becasue there is only one flow.
     211
     212=== Case 2: Many-to-One Communication ===
     213http://www.winlab.rutgers.edu/~zhibinwu/image/mptopoint.gif
     214
     215Figure 2. Multipoint to Point Unicast
     216
     217Suppose 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.
     218To 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.
     219