-
Notifications
You must be signed in to change notification settings - Fork 6
Expand file tree
/
Copy pathtrpr.html
More file actions
executable file
·3 lines (3 loc) · 45.2 KB
/
trpr.html
File metadata and controls
executable file
·3 lines (3 loc) · 45.2 KB
1
2
3
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>TRPR User's Guide Version 2.1b5</title><link rel="stylesheet" type="text/css" href="html.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><meta name="description" content="The TRace Plot Real-time (TRPR) is open source software by the Naval Research Laboratory (NRL) PROTocol Engineering Advanced Networking (PROTEAN) group that analyzes output from the tcpdump packet sniffing program and creates output suitable for plotting. It also specifically supports a range of functionality for specific use of the gnuplot graphing program. trpr can operate in a "real-time" plotting mode where tcpdump stdout can be piped into trpr and trpr's stdout in turn can be piped directly into gnuplot for a sort of real-time network oscilloscope. Trpr can also parse tcpdump text trace files and produce files which can be plotted by gnuplot or imported into other plotting or spreadsheet programs. IPv4 and IPv6 traces from tcpdump are supported. Trpr can also perform the same functions with mgen log files (See https://www.nrl.navy.mil/itd/ncs/products/mgen for more information on mgen and the MGEN test tool set) and ns-2 (Berkeley's network simulator - see https://www.isi.edu/nsnam/ns ) trace files. By default, trpr creates a "data rate" versus time plot of the flows specified using the auto and flow (and exclude ) filtering commands. The auto command is used to set filters to automatically detect and enumerate individual flows matching the auto filter parameters (protocol type, source addr/port, and destination addr/port) and the flow command aggregates flows matching its filter specification under a single data plot set. The exclude command is used to specify packet flows trpr should ignore. The flow , auto and exclude commands can each be used multiple times on the command line to specify different combinations of filters to produce different desired output. (In the future, an exclusion filter set will also be provided). If the interarrival command is used, trpr creates a plot of the differential interarrival delay of packets for the specified flows. And for MGEN packets, the latency command can be used to create a plot of the transmission latency (mgen-logged rxTime - txTime ) versus time for the flows. Also, for MGEN packets, the loss command can be used to generate profiles of packet loss over time. MGEN packet payloads contain sequence numbers and time stamps to facilitate these analyses. The count command simply produces counts of the indicate "send" and/or "recv" events for the specified flows. The histogram command causes trpr to output histograms of any of these statistics and the window command determines the averaging window interval to use (with "window -1" over the entire trace file and "window 0" for individual events). Trpr can also "play back" a gnuplot visualization of trace file content at real time rates with the replay command."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="d0e2"></a><span class="inlinemediaobject"><img src="resources/proteanlogo_small.png" width="270"></span>TRPR User's Guide Version 2.1b5</h2></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>The TRace Plot Real-time (TRPR) is open source software by the <a class="ulink" href="https://www.nrl.navy.mil/" target="_top">Naval Research Laboratory</a> (NRL) PROTocol Engineering Advanced Networking (PROTEAN) group that analyzes output from the <span class="emphasis"><em>tcpdump</em></span> packet sniffing program and creates output suitable for plotting. It also specifically supports a range of functionality for specific use of the <span class="emphasis"><em>gnuplot </em></span>graphing program. <span class="emphasis"><em>trpr</em></span> can operate in a "real-time" plotting mode where <span class="emphasis"><em>tcpdump</em></span> <code class="computeroutput">stdout</code> can be piped into <span class="emphasis"><em>trpr</em></span> and <span class="emphasis"><em>trpr's</em></span> <code class="computeroutput">stdout</code> in turn can be piped directly into <span class="emphasis"><em>gnuplot</em></span> for a sort of real-time network oscilloscope. <span class="emphasis"><em>Trpr</em></span> can also parse <span class="emphasis"><em>tcpdump</em></span> text trace files and produce files which can be plotted by <span class="emphasis"><em>gnuplot</em></span> or imported into other plotting or spreadsheet programs. IPv4 and IPv6 traces from <span class="emphasis"><em>tcpdump</em></span> are supported. <span class="emphasis"><em>Trpr</em></span> can also perform the same functions with <span class="emphasis"><em>mgen</em></span> log files (See <a class="ulink" href="https://www.nrl.navy.mil/itd/ncs/products/mgen" target="_top">https://www.nrl.navy.mil/itd/ncs/products/mgen</a> for more information on <span class="emphasis"><em>mgen</em></span> and the MGEN test tool set) and <span class="emphasis"><em>ns-2</em></span> (Berkeley's network simulator - see <a class="ulink" href="https://www.isi.edu/nsnam/ns/" target="_top">https://www.isi.edu/nsnam/ns</a> ) trace files.</p><p>By default, <span class="emphasis"><em>trpr</em></span> creates a "data rate" versus time plot of the flows specified using the <code class="literal">auto</code> and <code class="literal">flow</code> (and <code class="literal">exclude</code> ) filtering commands. The <code class="literal">auto</code> command is used to set filters to automatically detect and <span class="emphasis"><em><span class="emphasis"><em>enumerate</em></span></em></span> individual flows matching the <code class="literal">auto</code> filter parameters (protocol type, source addr/port, and destination addr/port) and the <code class="literal">flow</code> command aggregates flows matching its filter specification under a single data plot set. The <code class="literal">exclude </code>command is used to specify packet flows <span class="emphasis"><em>trpr </em></span>should ignore. The <code class="literal">flow</code> , <code class="literal">auto</code> and <code class="literal">exclude</code> commands can each be used multiple times on the command line to specify different combinations of filters to produce different desired output. (In the future, an exclusion filter set will also be provided).</p><p>If the <code class="literal">interarrival</code> command is used, <span class="emphasis"><em>trpr</em></span> creates a plot of the differential interarrival delay of packets for the specified flows. And for MGEN packets, the <code class="literal">latency</code> command can be used to create a plot of the transmission latency (<span class="emphasis"><em>mgen</em></span>-logged rxTime - txTime ) versus time for the flows. Also, for MGEN packets, the <code class="literal">loss</code> command can be used to generate profiles of packet loss over time. MGEN packet payloads contain sequence numbers and time stamps to facilitate these analyses. The <code class="literal">count</code> command simply produces counts of the indicate "send" and/or "recv" events for the specified flows. The <code class="literal">histogram</code> command causes <span class="emphasis"><em>trpr</em></span> to output histograms of any of these statistics and the <code class="literal">window</code> command determines the averaging window interval to use (with "<code class="literal">window -1</code>" over the entire trace file and "<code class="literal">window 0</code>" for individual events). <span class="emphasis"><em>Trpr </em></span>can also "play back" a <span class="emphasis"><em>gnuplot</em></span> visualization of trace file content at real time rates with the <code class="literal">replay </code>command.</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="#_Mgen_Usage">1. Downloads</a></span></dt><dt><span class="sect1"><a href="#Build">2. Build Instructions:</a></span></dt><dt><span class="sect1"><a href="#QuickStart">3. Quick Start</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e246">3.1. Non-real-time Operation</a></span></dt><dt><span class="sect2"><a href="#d0e345">3.2. Real-time Operation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#MGEN_Run-Time_Remote_Control">4. Usage</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e442">4.1. Command-line Options and Parameters</a></span></dt></dl></dd><dt><span class="sect1"><a href="#tcpdumpHints">5. <span class="emphasis"><em>tcpdump</em></span> Hints</a></span></dt><dt><span class="sect1"><a href="#_MGEN_Script_Format">6. <span class="emphasis"><em>gnuplot</em></span> Hints</a></span></dt><dt><span class="sect1"><a href="#d0e1093">7. Examples of Use</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_Mgen_Usage"></a>1. Downloads</h2></div></div></div><p>The <span class="emphasis"><em>trpr</em></span> package is available at <a class="ulink" href="https://github.com/USNavalResearchLaboratory/trpr" target="_top">https://github.com/USNavalResearchLaboratory/trpr</a></p><p><span class="emphasis"><em>Tcpdump</em></span> can be found at <a class="ulink" href="http://ee.lbl.gov/" target="_top">http://ee.lbl.gov/ </a></p><p><span class="emphasis"><em>Gnuplot's</em></span> official web site is <a class="ulink" href="http://www.gnuplot.info/" target="_top">http://www.gnuplot.info/</a></p><p>The <span class="emphasis"><em>MGEN</em></span> web site is <a class="ulink" href="https://www.nrl.navy.mil/itd/ncs/products/mgen" target="_top">https://www.nrl.navy.mil/itd/ncs/products/mgen </a></p><p>The <span class="emphasis"><em>ns</em></span> web site is <a class="ulink" href="https://www.isi.edu/nsnam/ns/" target="_top">https://www.isi.edu/nsnam/ns</a></p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Build"></a>2. Build Instructions:</h2></div></div></div><p>Simply compile <span class="emphasis"><em>trpr </em></span>with a C++ compiler. It has been primarily built with gcc on Unix platforms. For example, type:</p><p><code class="computeroutput">g++ -o trpr trpr.cpp -lm </code></p><p>to build the executable binary.</p><p>On windows, use the provided Visual Studio Trpr.sln file to build the application. A windows binary file release is also available on the protean forge web site.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="QuickStart"></a>3. Quick Start</h2></div></div></div><p>Here are a couple of examples illustrating use of <span class="emphasis"><em>trpr</em></span> in simple ways. Note that <span class="emphasis"><em>trpr</em></span> has a number of flexible command-line operations to get the results you want and understanding these is strongly recommended. And <span class="emphasis"><em>tcpdump</em></span> has very flexible filtering options for paring down the data captured from the network so that your graphs can focus on the data of interest. The options of <span class="emphasis"><em>tcpdump</em></span> and <span class="emphasis"><em>trpr</em></span> can be coupled together in many different ways. And <span class="emphasis"><em>trpr</em></span> supports options to command <span class="emphasis"><em>gnuplot</em></span> to create Gif or Postscript files for hard output or use in other programs. Detailed usage instructions for <span class="emphasis"><em>trpr </em></span>and hints for <span class="emphasis"><em>tcpdump</em></span> and <span class="emphasis"><em>gnuplot</em></span> usage are given later.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="d0e246"></a>3.1. Non-real-time Operation</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Capture IP packets with <span class="emphasis"><em>tcpdump</em></span> with hexadecimal packet header output. Note you <span class="bold"><strong>must</strong></span> use <span class="emphasis"><em>tcpdump's</em></span> hexadecimal output option (-x):</p><p><code class="literal"><code class="computeroutput">tcpdump -x > <traceFile></code></code></p><p>The <span class="emphasis"><em>trpr</em></span> code parses the <span class="emphasis"><em>tcpdump</em></span> lines and hexadecimal output for additional details (more consistent than the textual content through version updates of <span class="emphasis"><em>tcpdump</em></span>). Alternatively, if you have a binary "pcap" file (e.g. created with "tcpdump -w <pcapFile>"), you can use tcpdump to convert this binary file to the text and hexadecimal output form with:</p><p><code class="literal"><code class="computeroutput">tcpdump -lnx -r <pcapFile> > <traceFile></code></code></p></li><li class="listitem"><p>Use <span class="emphasis"><em>trpr </em></span>to process the captured <traceFile> to create a <plotFile> suitable for plotting with <span class="emphasis"><em>gnuplot</em></span>, automatically creating lines on the graph for each unique "flow" of data discovered in the <traceFile>:</p><p><code class="literal"><code class="computeroutput">trpr input <traceFile> auto X output <plotFile></code></code></p><p>Note you can optionally consolidate Step 1 and Step 2 here into a single step by pipelining the <span class="emphasis"><em>tcpdump</em></span> STDOUT into <span class="emphasis"><em>trpr</em></span> via:</p><p><code class="literal"><code class="computeroutput">tcpdump -lnx -r <pcapFile> | trpr output <plotFile></code></code></p></li><li class="listitem"><p>Use <span class="emphasis"><em>gnuplot </em></span>to display a graph of <span class="emphasis"><em>trpr's</em></span> analysis results (By default trpr puts appropriate headers in the <plotFile> for <span class="emphasis"><em>gnuplot</em></span>:</p><p><code class="literal"><code class="computeroutput">gnuplot -persist <plotFile></code></code></p><p>As examples, mgen log files can be processed with:</p><p><code class="literal"><code class="computeroutput">trpr mgen input <mgenLogFile> auto X output <plotFile> </code></code></p><p>and ns-2 simulation trace files can be processed with:</p><p><code class="computeroutput">trpr ns input <nsTraceFile> link <srcNode>,<dstNode> send auto X output <plotFile> </code></p><p>Note: The link command coupled with the send command specifies to process packets sent over the link from node <src> to node <dst> in the ns-2 simulation. The <src> and/or <dst> arguments can be wildcarded with the 'X' character to process multiple links to/from a particular or any simulation node.</p><p>Note: For ns-2 mobile trace files, the link command should be used in the form:</p><p><code class="computeroutput">link <nodeId>,{AGT | RT | MAC} </code></p><p>to capture the corresponding set of packets (Agent, Router, or MAC) for a mobile ns-2 node).</p><p>We hope to provide more examples for using trpr with ns-2 soon.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="d0e345"></a>3.2. Real-time Operation</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Set up <span class="emphasis"><em>tcpdump</em></span> to capture packets and direct hexadecimal output to <span class="emphasis"><em>trpr</em></span>, in turn piping <span class="emphasis"><em>trpr's</em></span> real-time output directly to <span class="emphasis"><em>gnuplot </em></span>to get continuously updated plots of network traffic flow activity:</p><p><code class="literal"><code class="computeroutput">tcpdump -lnx | trpr real auto X | gnuplot -noraise -persist</code></code></p><p><code class="literal">Or for mgen operation:</code></p><p><code class="literal"><code class="computeroutput">mgen flush output /dev/stdout | trpr mgen real auto X | gnuplot -noraise -persist </code></code></p><p>Note that the "tail -f" option can also be used to pipe a <span class="emphasis"><em>mgen </em></span>log file to <span class="emphasis"><em>trpr </em></span>in parallel with logging. (The <span class="emphasis"><em>mgen </em></span>"flush" option causes <span class="emphasis"><em>mgen</em></span> to "flush" its output line by line for better real time performance. Note this may penalize system performance)</p></li></ol></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="MGEN_Run-Time_Remote_Control"></a>4. Usage</h2></div></div></div><p><span class="markup">Usage:</span></p><p><code class="computeroutput">trpr [version][mgen][ns][raw][key]</code></p><p><code class="computeroutput"> [real][latency][interarrival][loss][count] </code></p><p><code class="computeroutput"> [window <sec>] [history <sec>] </code></p><p><code class="computeroutput"> [flow <type,srcAddr/port,dstAddr/port>,flowId] </code></p><p><code class="computeroutput"> [auto <type,srcAddr/port,dstAddr/port>,flowId] </code></p><p><code class="computeroutput"> [exclude <type,srcAddr/port,dstAddr/port>,flowId] </code></p><p><code class="computeroutput"> [input <inputFile>] [output <outputFile>] </code></p><p><code class="computeroutput"> [link <src>[,<dst>]][send|recv][nodup] </code></p><p><code class="computeroutput"> [range [<startSec>][:<stopSec>]] [yrange [<min>][:<max>]]</code></p><p><code class="computeroutput"> [offset <hh:mm:ss>][absolute] </code></p><p><code class="computeroutput"> [summary][histogram][replay <factor>] </code></p><p><code class="computeroutput"> [png <pngFile>][post <postFile>][gif <gifFile>][multiplot]</code></p><p><code class="computeroutput"> [surname <titlePrefix>][ramp][scale]</code></p><p><code class="computeroutput"> [nolegend] </code></p><p>NOTE: <span class="emphasis"><em>The type, addr, port , and flowId parameters can be "wildcarded" with an 'X' character. For the "auto" enumerated flow, these parameters can also be "trumpcarded" with a 'Y' character. In this case, the "trumped" fields are treated as a "don't care" case for flow enumeration. Thus, "auto Y" is functionally equivalent to "flow X".</em></span></p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="d0e442"></a>4.1. Command-line Options and Parameters</h3></div></div></div><p></p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><tbody><tr><td><code class="literal">version</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to display program version number and exit.</td></tr><tr><td><code class="literal">mgen</code></td><td><span class="emphasis"><em>trpr</em></span> will expect to process a <span class="emphasis"><em>mgen</em></span> log file instead of <span class="emphasis"><em>tcpdump</em></span> hex output.</td></tr><tr><td><code class="literal">ns</code></td><td><span class="emphasis"><em>trpr</em></span> will expect to process a <span class="emphasis"><em>ns</em></span> trace file instead of <span class="emphasis"><em>tcpdump</em></span> hex output</td></tr><tr><td><code class="literal">raw</code></td><td>When this option is given, the <outputFile> will only include unlabeled sets of plotting data without the default <span class="emphasis"><em>gnuplot</em></span> compatible headers. This is useful to get the "raw" plot data for importing into a spreadsheet or other plotting program</td></tr><tr><td><code class="literal">key</code></td><td>With this option, trpr will print a "key" to the data plot sets in the <outputFile>. This consists of one comma-delimited line with a leading "#" character. This line is printed when new flows of data are detected and another data set column is output. The first column is marked "Time". Subsequent columns are labeled with a description of the flow data being plotted.</td></tr><tr><td><code class="literal">rate</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to create plots of data rate versus time. The window command can be used to set <span class="emphasis"><em>trpr</em></span> 's rate averaging window. The rate command is the implicit default plot mode for <span class="emphasis"><em>trpr</em></span>.</td></tr><tr><td><code class="literal">interarrival</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to create plots of differential interarrival packet delays for detected flows instead of the default data rate versus time plot.</td></tr><tr><td><code class="literal">latency</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to create plots of transmission delay for <span class="emphasis"><em>mgen</em></span> flows instead of the default data rate versus time plot. This type of plot is only available for <span class="emphasis"><em>mgen </em></span>operation.</td></tr><tr><td><code class="literal">loss</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to create plots of packet loss based on received sequence numbers for <span class="emphasis"><em>mgen</em></span> flows instead of the default data rate versus time plot. This type of plot is only available for <span class="emphasis"><em>mgen</em></span> operation. The <code class="literal">window</code> command can be used to set <span class="emphasis"><em>trpr</em></span> 's loss averaging window. The "window" specified should be large enough to encompass several expected packet events for desired results.</td></tr><tr><td><code class="literal">count</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to create plots of packet counts versus time instead of the default data rate versus time plot. The window command can be used to set <span class="emphasis"><em>trpr's</em></span> count accumulation window. The rate command is the implicit default plot mode for <span class="emphasis"><em>trpr</em></span>.</td></tr><tr><td><code class="literal">real</code></td><td>When this option is given, <span class="emphasis"><em>trpr</em></span> will output plotting commands and data to its <code class="literal">stdout</code>. This output is intended for the <code class="literal">stdin</code> of <span class="emphasis"><em>gnuplot</em></span> for real-time plotting. However, note that this output can be redirected to a file for storage, and then later that file can be directed to the input of <span class="emphasis"><em>gnuplot</em></span> for "playback". Note that the "real-time" mode can be used simultaneously with <span class="emphasis"><em>trpr</em></span> 's cumulative "non-real-time" output option. Note that the "real time" graph update occurs once per window time. This option can also be used with pre-existing trace files. Use the replay command to limit the actual graph animation rate or the trace file will be parsed at "cartoon rate" (i.e. as fast as possible).</td></tr><tr><td><code class="literal">gif <gifFile></code></td><td>This option commands <span class="emphasis"><em>gnuplot</em></span> to create a "gif" (Graphics Interchange Format) file when it plots instead of the default X11 display. The <gifFile> parameter is the name of the file <span class="emphasis"><em>gnuplot</em></span> will create when it processes <span class="emphasis"><em>trpr's</em></span> output. This can be used in either real-time or non-real-time operation. In real-time operation, the <gifFile> will be periodically overwritten according to window setting.</td></tr><tr><td><code class="literal">post <postFile></code></td><td>This option commands <span class="emphasis"><em>gnuplot</em></span> to create a Postscript file when it plots instead of the default X11 display. The <postFile> parameter is the name of the file <span class="emphasis"><em>gnuplot</em></span> will create when it processes <span class="emphasis"><em>trpr</em></span> 's output. This can be used in either real-time or non-real-time operation. In real-time operation, the <postFile> will be periodically overwritten according to window setting.</td></tr><tr><td><code class="literal">png <pngFile></code></td><td>This option commands <span class="emphasis"><em>gnuplot</em></span> to create a .pngt file when it plots instead of the default X11 display. The <pngFile> parameter is the name of the file <span class="emphasis"><em>gnuplot</em></span> will create when it processes <span class="emphasis"><em>trpr</em></span> 's output. This can be used in either real-time or non-real-time operation. In real-time operation, the <pngFile> will be periodically overwritten according to window setting.</td></tr><tr><td><code class="literal">surname <surName></code></td><td>Prepends "surname" to the plot's title.</td></tr><tr><td><code class="literal">multiplot</code></td><td>With <span class="emphasis"><em>gnuplot</em></span>, <span class="emphasis"><em>trpr</em></span> will create a "multiplot" graph with one graph per detected flow (stacked vertically). (This only works with the real-time updated (real command) graphing mode for now).</td></tr><tr><td><code class="literal">ramp</code></td><td>By default, <span class="emphasis"><em>trpr</em></span> creates "stair step" plots of its averaging window results (i.e. 2 data points per window). The optional ramp command causes <span class="emphasis"><em>trpr</em></span> to create plots with one data point per averaging window (at the window's end), thus "ramping" from one window to the next. This may be useful for alternative post-processing of <span class="emphasis"><em>trpr's</em></span> output files or to reduce the number of data points on plots with an extremely large number of data points where the window start/stop points are indiscernible anyway.</td></tr><tr><td><code class="literal">window <sec></code></td><td>This parameter sets the step size of <span class="emphasis"><em>trpr's</em></span> window-based data rate and packet loss averaging algorithms. The step size unit is time in seconds. This algorithm counts the cumulative quantity of data (or packet loss) in each window of time and calculates the kilobits-per-second (kbps) (or loss fraction) value for each step. These discrete values of data rate (or loss fraction) versus time comprise trpr 's plot data. Two points are plotted, one at each time window's beginning and one at its end, to form a "stair step" plot. The window command also controls the <span class="emphasis"><em>gnuplot</em></span> real-time graph update rate for real command operation. The window <sec> value can be specified as "-1" to cause <span class="emphasis"><em>trpr</em></span> to average across the entire trace file (or the period specified by the range command). Note the negative window value should not be used in combination with the real command. Default = 1 second.</td></tr><tr><td><code class="literal">history <sec></code></td><td>This parameter determines the range (in time units of seconds) of the X-axis of the graphs produced in <span class="emphasis"><em>trpr's</em></span> real-time mode. As time progresses, the <span class="emphasis"><em>gnuplot</em></span> graphs will scroll in "strip-chart" fashion to display the current history of network activity. Default = 20 seconds.</td></tr><tr><td><code class="literal">auto <type,srcAddr/port,dstAddr/port,id></code></td><td>This command instructs <span class="emphasis"><em>trpr</em></span> to automatically discover, enumerate, and plot "flows" of network data according to the matching (type,src,dst,id) criteria provided. Otherwise, <span class="emphasis"><em>trpr</em></span> only plots "flows" given by the flow option described below. Valid values for <type> include "X", "Y", "UDP", "TCP", "ospf", "arp" or the numeric value of the IP protocol type of interest. The "X" value "wildcards" the <type> so that <span class="emphasis"><em>trpr</em></span> will automatically create a plot on the graph for any type of IP protocol which meets the given <source,destination> criteria, if given. The "Y" value for a field (including the "type"), sets a "don't care" state with respect to "auto" enumeration. For example, if the "type" is set to "Y" and the address, etc is wildcarded with an "X" (i.e. "auto Y,X), then unique source/destination flows are enumerated but all the traffic, regardless of protocol "type" is consolidated for each source,destination tuple. The source and destination addresses (srcAddr & dstAddr) must be given in dotted decimal notation or may also be wildcarded with an "X" character. The <source,destination> portion may also be omitted and then will be automatically wildcarded. The optional "id" portion of the flow description corresponds to any "flow id" which may apply to the data analyzed. This currently only applies to <span class="emphasis"><em>mgen</em></span> log files when the user wishes to additionally differentiate <span class="emphasis"><em>mgen</em></span> flows by their "flow id". (See the <span class="emphasis"><em>mgen</em></span> user's guide for more information). As an example, " auto udp" will cause <span class="emphasis"><em>trpr</em></span> to enumerate individual plots for each unique UDP protocol flow detected regardless of source or destination. The source and destination port numbers can be explicitly specified or wildcarded with an "X" or implicitly through omission. Note that flows which match those given with the flow option (see below) will not be tested against the auto criteria. The auto option may be used multiple times on the <span class="emphasis"><em>trpr</em></span> command line to establish multiple sets of automatic flow matching criteria (e.g. <span class="emphasis"><em>trpr</em></span> auto udp auto tcp ... "). "Wildcard" and "trumpcard" flow specification may be abbreviated. For example "auto X" means all filter parameters are wildcarded while "auto X,Y" means the "type" is wildcarded for enumeration while other filter parameters are "trumped", meaning the "auto" enumeration will instantiate one flow per protocol "type". Note that if no flow or auto filters are provided, <span class="bold"><strong>trpr</strong></span> runs with a default wildcard enumeration filter of "auto X"</td></tr><tr><td><code class="literal">flow <type,srcAddr/port,dstAddr/port,id></code></td><td>This command instructs trpr to look for and plot specific "flows" which match the given (type,src,dst) criteria. All flows which match the given criteria are accumulated together onto a single plot line. The address and port criteria are given in the same way as for the auto command and may be wildcarded in the same way. Note the "trumpcard" has no distinct effect for the "flow" command at this time and is equivalent to the "wildcard". For example, the option "flow udp" will cause trpr to accumulate all detected UDP traffic (regardless of source and destination since they are implicitly wildcarded here) into a single plot. Thus the command "<span class="emphasis"><em>trpr</em></span> flow UDP flow TCP ..." will produce a graph with two lines, one plotting cumulative UDP traffic and the other plotting cumulative TCP traffic detected by <span class="emphasis"><em>tcpdump</em></span>. As with the auto option, the flow option may be used multiple times on the command line and may be used in conjunction with the auto option. Flows of network traffic matching the criteria specified with the flow option will be accumulated into a matching flow plot and are also tested against the sets of auto option criteria so redundant plot lines may result depending on the criteria used.</td></tr><tr><td><code class="literal">exclude <type,srcAddr/port,dstAddr/port,id></code></td><td>This command instructs <span class="emphasis"><em>trpr</em></span> to ignore specific "flows" which match the given (type,src,dst) criteria. The address and port criteria are given in the same way as for the auto command and may be wildcarded in the same way. For example, the option "flow udp" will cause <span class="emphasis"><em>trpr</em></span> to ignore all detected UDP traffic (regardless of source and destination since they are implicitly wildcarded here). The exclude command filters are evaluated before the auto and flow command filters.</td></tr><tr><td><code class="literal">input <inputFile></code></td><td>This option instructs <span class="emphasis"><em>trpr</em></span> to use the file name given by <inputFile> for input. Otherwise <span class="emphasis"><em>trpr</em></span> looks for input from stdin . The expected input format is text output from the <span class="emphasis"><em>tcpdump</em></span> program run with its hexadecimal option (-x) given and properly filtered so that only IP protocol data is captured. Non-IP data from <span class="emphasis"><em>tcpdump</em></span> will result in errors in <span class="emphasis"><em>trpr's</em></span> output.</td></tr><tr><td><code class="literal">output <outputFile></code></td><td>This option instructs <span class="emphasis"><em>trpr</em></span> to save cumulative data into the file name given by <outputFile> for later (non-real-time) plotting. The plot data stored here contains data from the entire <span class="emphasis"><em>tcpdump</em></span> run (as opposed to the trpr real-time mode's limited history of data). By default (i.e. unless the raw option is given), the output file contains text header information at its beginning so that <span class="emphasis"><em>gnuplot</em></span> can be used to create a nicely-labeled graph.</td></tr><tr><td><code class="literal">link <src>[,<dst>]</code></td><td>This causes <span class="emphasis"><em>trpr</em></span> to process only packets associated with the identified "link" or "node". For ns trace files, the <src> and <dst> values correspond to simulation node identifiers. For <span class="emphasis"><em>tcpdump</em></span> operation, the MAC address is used. Note that <src> and/or <dst> values can be wildcarded by omission or by designating 'X' as the value. For ns simulations using the wireless/mobility extensions, the <dst> value may be "AGT" or "RTR" corresponding to the wireless transmission type (By default, both "AGT" and"RTR" are counted by trpr) since the notion of "links" is not used in the trace files. Wildcarding the <src> or <dst> values allows the user to analyze all traffic arriving to and/or leaving from a specific simulation node or MAC address. The send and recv commands may be optionally used in combination with the link command to specify whether only arriving packets ( recv ) or departing packets (send ) are processed. By default, only departing packets are processed.</td></tr><tr><td><code class="literal">nodup</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to discard duplicate packets.</td></tr><tr><td><code class="literal">send</code></td><td>Specifies that only "sent" packets are to be processed. In <span class="bold"><strong>ns</strong></span>, this corresponds to 's' events for traced links or nodes. In <span class="emphasis"><em>tcpdump</em></span>, this corresponds to packets whose source MAC address correspond to the <src> value given with the link command. For <span class="emphasis"><em>mgen</em></span> logfiles, this corresponds to packets sent by <span class="emphasis"><em>mgen</em></span>. By default, only "received" packets are counted by trpr . The send and recv commands are generally useful only for <span class="emphasis"><em>ns</em></span> simulations but may be applicable to <span class="emphasis"><em>tcpdump</em></span> trace file analysis in some situations.</td></tr><tr><td><code class="literal">recv</code></td><td>Specifies that only "received" packets are to be processed. In <span class="emphasis"><em>ns</em></span>, this corresponds to 'r' events for traced links or nodes. In <span class="emphasis"><em>tcpdump</em></span>, this corresponds to packets whose destination MAC address corresponds to the <dst> value given with the link command. By default, only "received" packets are counted by <span class="emphasis"><em>trpr</em></span> . The send and recv commands are generally useful only for <span class="emphasis"><em>ns</em></span> simulations but may be applicable to <span class="emphasis"><em>tcpdump</em></span> trace file analysis in some situations.</td></tr><tr><td><code class="literal">range <min>[:max]</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to skip ahead to the "start time" (in seconds) from the first packet event in the trace file and end processing at the optional "stop time" (in seconds). Setting the "stop time" to -1 causes <span class="emphasis"><em>trpr</em></span> to process until the end of the trace input. Note the range command may be used in combination with the offset and/or absolute commands to perform analysis for a specific time period in the trace file. NOTE: the deprecated "xrange" command is still supported.</td></tr><tr><td><code class="literal">yrange <min>[:max]</code></td><td>Will override TRPR's auto-yrange behavior</td></tr><tr><td><code class="literal">offset <hh:mm:ss></code></td><td>This allows the user to specify an absolute analysis start time using a time-of-day reference. The time given is in 24-hour clock time format and must be within 12 hours of the time of the first packet event in the trace file.</td></tr><tr><td><code class="literal">absolute</code></td><td>Causes <span class="emphasis"><em>trpr</em></span> to use the absolute time given in the trace file in its output instead of "normalizing" the time values (generally the plots' x-axis) to zero time for the first packet event or optional offset time.</td></tr><tr><td><code class="literal">summary</code></td><td>This causes <span class="emphasis"><em>trpr</em></span> to output summary statistics of results to <code class="literal">stdout</code> at the end of analysis. These summary results are available with or without the production of data intended for plotting. This options is useful for commanding or scripting <span class="emphasis"><em>trpr</em></span> to collect statistics in addition to or instead of plots.</td></tr><tr><td><code class="literal">histogram</code></td><td>This causes <span class="emphasis"><em>trpr</em></span> to output a histogram of the values of analyses intervals (intervals determined by the window command) for each flow to <code class="literal">stdout</code>. Some percentile information of the histogram content is also provided in the output. The histograms are comma-delimited tables of values. The hcat program provided in the TRPR distribution can be used to query and manipulate these histogram files or they can also be plotted with a graphing tool (e.g. <span class="emphasis"><em>gnuplot</em></span>). The hcat program also allows multiple histogram files from multiple <span class="emphasis"><em>trpr</em></span> analysis runs to be combined together for cumulative statistics collection. Currently the quantization size and curve of the histogram is fixed and adapts in range with data. The histogram output may be useful for packet latency analyses or other kinds of statistics compilations.</td></tr><tr><td><code class="literal">replay <factor></code></td><td>This limits <span class="emphasis"><em>trpr's</em></span> rate of real-time <span class="emphasis"><em>gnuplot</em></span> graph generation to a <factor> of real time when parsing a pre-existing trace file. When the replay command is given, <span class="emphasis"><em>trpr</em></span> generates the same <span class="emphasis"><em>gnuplot</em></span> output as for the real command. The <factor> parameter scales the playback rate with respect to real time. For example, <factor> = 1 is actual real time, while <factor> = 2 is double speed playback. Note that real time update occurs once per window time.</td></tr><tr><td>scale</td><td>Autoscales the plots y axis.</td></tr><tr><td>nolegend</td><td>No key/legend will be created in the gnuplot output. This is particularly useful for smaller displays as well as on certain live displays.</td></tr></tbody></table></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tcpdumpHints"></a>5. <span class="emphasis"><em>tcpdump</em></span> Hints</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>By default, <span class="emphasis"><em>trpr</em></span> expects to process the payload of the captured Ethernet frames from <span class="emphasis"><em>tcpdump</em></span> and can identify IPv4 and IPv6 payload protocols such as UDP, TCP, etc with port number information when applicable. The ARP protocol is also identified by <span class="emphasis"><em>trpr</em></span> and protocol names identified by <span class="emphasis"><em>tcpdump</em></span>. The <span class="emphasis"><em>tcpdump</em></span> "-e" option can be invoked at which point <span class="emphasis"><em>trpr</em></span> uses the Ethernet MAC source and destination addresses for trpr flow identification. This is useful for getting cumulative packet rates and/or counts based on MAC addresses. In this case, the protocol types embedded in the Ethernet frame payloads are ignored. With additional scripting, using <span class="emphasis"><em>trpr</em></span> as a helper command, one could first learn the source and/or destination MAC addresses for flows within a <span class="emphasis"><em>tcpdump</em></span> trace file and then use <span class="emphasis"><em>tcpdump</em></span> filtering in conjunction with <span class="emphasis"><em>trpr</em></span> analysis to identify flows for specific MAC source and/or destination addresses.</p></li><li class="listitem"><p>Always use the "-x" option when using <span class="emphasis"><em>tcpdump</em></span> with <span class="emphasis"><em>trpr</em></span>. (<span class="emphasis"><em>trpr</em></span> looks for and parses the hexadecimal output)</p></li><li class="listitem"><p>Use <span class="emphasis"><em>tcpdump's</em></span> "-n" option to skip DNS lookups and speed up <span class="emphasis"><em>tcpdump's</em></span> performance (<span class="emphasis"><em>trpr</em></span> only uses dotted decimal numeric IP addresses).</p></li><li class="listitem"><p>Use <span class="emphasis"><em>tcpdump's</em></span> line buffering option ("-l") to get output with minimal delay for real time plotting.</p></li><li class="listitem"><p>Read and learn <span class="emphasis"><em>tcpdump's</em></span> man page for the extensive set of filtering options <span class="emphasis"><em>tcpdump</em></span> provides. Uses these filter options in conjunction with <span class="emphasis"><em>trpr's</em></span> own filters to get the graphical results you wan</p></li><li class="listitem"><p>Leverage <span class="emphasis"><em>tcpdump's</em></span> ability to store captured data in a binary file (use <span class="emphasis"><em>tcpdump's</em></span> "-w" option) and then post-process it with <span class="emphasis"><em>tcpdump</em></span> 's filter's (using <span class="emphasis"><em>tcpdump</em></span> to process the stored binary file with its "-r" option and redirecting its output to <span class="emphasis"><em>trpr</em></span>).</p></li></ol></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_MGEN_Script_Format"></a>6. <span class="emphasis"><em>gnuplot</em></span> Hints</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Use <span class="emphasis"><em>gnuplot's</em></span> "-noraise" option when using with <span class="emphasis"><em>trpr</em></span> in "real-time" mode if you don't want the updated plots to continually pop to your display's top level.</p></li><li class="listitem"><p>Use <span class="emphasis"><em>gnuplot's</em></span> "-persist" option if you wish the last plot to remain displayed after exiting.</p></li><li class="listitem"><p><span class="emphasis"><em>trpr's</em></span> output files for <span class="emphasis"><em>gnuplot</em></span> are in text format and easily edited to customize output. <span class="emphasis"><em>Gnuplot</em></span> is a very flexible program with lots of options to get the graphs into almost any format you would like. It is also lightning fast.</p></li></ol></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1093"></a>7. Examples of Use</h2></div></div></div><p>To pipe <span class="emphasis"><em>mgen</em></span> output directly into a real-time <span class="emphasis"><em>gnuplot</em></span> display and create new plots for each src/dst pair:</p><p><code class="computeroutput">mgen flush event "LISTEN TCP 5000" | trpr mgen window 5 history 300 real auto X multiplot rate | gnuplot -noraise -persist</code></p><p>To pipe <span class="emphasis"><em>tcpdump</em></span> output directly into a real-time <span class="emphasis"><em>gnuplot</em></span> display and create new plots for each detected network flow:</p><p><code class="computeroutput">tcpdump -lnx -i eth0 | trpr window 5 history 300 real auto X multiplot rate | gnuplot -noraise -persist</code></p><p>To plot cumulative transmission rates from distinct Ethernet sources:</p><p><code class="computeroutput">tcpdump -elnx -i eth0 | trpr window 5 history 300 real auto X,X,Y multiplot rate | gnuplot -noraise -persist</code></p><p>To plot cumulative transmission rates to distinct Ethernet destinations:</p><p><code class="computeroutput">tcpdump -elnx -i eth0 | trpr window 5 history 300 real auto X,Y,X multiplot rate | gnuplot -noraise -persist</code></p></div></div></body></html>