NTRC

Section: User Commands (1)
Updated: 12/18/02
Index Return to Main Contents

NAME

ntrc - Network TRace Converter

SYNOPSIS

ntrc [-iinput_format] [-ooutput_format] [ input file ] [ output file ]

DESCRIPTION

Ntrc converts network traffic traces to and from a variety of formats, for import/export to and from network simulators or trace analyzers. Formats currently supported are:

Time Sequenced Headers - tsh files are in binary format, where each 44-byte chunk corresponds to the header of a packet in transmission on the link. This format is described at <http://pma.nlanr.net/Traces/tsh.format.html>. Note that TSH records have a fixed length, and thus may be broken in case some IP options are passed.

Coral/OC3MON - format used by OC3MON from Coral. Binary, 60-byte fixed records per packet, described at <http://pma.nlanr.net/Traces/coral.format.html>

FR - Binary, 24-byte fixed records per packet. See <http://pma.nlanr.net/Traces/fr.format.html>

FR+ - Binary, 44-byte fixed records per packet. See <http://pma.nlanr.net/Traces/fr+.format.html>

Network Simulator version 2 (ns-2) TrafficTrace - Traces used by the Application/Traffic/Trace agent in the ns-2 network simulator. Each record contains to 32-bit fields: the time in microseconds until generation/arrival of the next packet, and the size of the current packet. See <http://www.isi.edu/nsnam/ns/> for more information.

Input and output formats are specified via the -i and -o options (see OPTIONS). By default, ntrc reads from STDIN and writes to STDOUT. Optional arguments may be used to specify the names of the files to read from, and write to, respectively. - is used to denote standard input in case one wants to explictly specify an output file while reading from STDIN. For instance,
ntrc -ifr -insg - trace.ns
converts standard input in FR format to an ns-2 TrafficTrace file stored in trace.ns.

Note that, due to their size, most traffic traces taken from high-speed links are in .gz compressed format. Such traces must therefore be decompressed with gzip(1) prior to use with ntrc.

Upon succesful completion ntrc returns zero. Positive values are returned if either incompatible options were passed or a write error occured. Negative values are returned if a read error occured.

OPTIONS

-i: To specify the format of the input trace. This flag takes a mandatory argument, which is one of crl (Coral/oc3mon format), nsg (ns-2 TrafficTrace format), fr (FR format), fr+ (FR+ format), tsh (Time Sequenced Headers format). If the -i option is omitted, ntrc assumes that the input trace is in Time Sequenced Headers format.
-o: To specify the format of the output trace. This flag takes a mandatory argument, which is one of crl, nsg, fr, fr+, tsh. If the -o option is omitted, ntrc assumes that the output trace is in ns-2 Traffic Trace format.

EXAMPLES

ntrc -ifr -onsg mytrace.fr: ntrc converts the FR trace file mytrace.fr to ns-2 format and sends the resulting trace to the standard output.
ntrc -icrl -ofr a.crl a.fr: ntrc converts the CRL trace file a.crl to the FR trace file a.fr.

PRIVACY ENCODERS

Privacy encoders are sometimes used to anonymize traces prior to public distribution, by changing the source and/or destination addresses and ports (if applicable). ntrc cannot de-anonymize such traces: the functions used to make traces anonymous are typically one-way hashes. However, the output of ntrc will match the anonymized fields. For instance, if all IP source addresses in the input trace have been anonymized and set to 1.2.3.4, all IP source addresses in the output trace will be set to 1.2.3.4.

INCOMPLETE INPUT TRACES

Most input trace formats do not provide complete information about each invididual packet. For instance, ns-2 TrafficTrace traces do not include any field of the transport protocol or network protocol header. When confronted with an input trace missing one (or more) of the fields expected in a packet header (including a timestamping field which is not part of the actual packet, but should have been included in the trace), ntrc assumes the following defaults for the missing fields:

o UDP over IPv4 packet
o No IP options (20-byte IP header)
o IP TOS byte set to zero
o Don't fragment, Last fragment flags set
o No fragment offset
o IP length = 1500 bytes (Payload is padded with zeroes)
o Initial IP identification field set to 25975 (0x6577 hex)
o Time-to-live (TTL) = 64
o IP source address = 10.0.0.1
o IP destination address = 10.0.0.2
o Source port = 1541 (0x0605 hex)
o Destination port = 6519 (0x1977 hex)
o Initial arrival time = 0.0: (Subsequent packets arrive with a 5 ms interarrival time)

BUGS

Link-level headers are not yet implemented correctly, which explains why trace formats which make use of them are not yet supported. This package has been completely untested with non TCP/UDP/IP/ICMP/IGMP traffic. If you're using traces of packets running exotic protocols, this may be a problem. In the case of binary traces, even if the input trace doesn't match the converter used (for instance, using a TSH input trace with the -ifr flag), chances are good that ntrc will happily proceed and generate an output trace regardless. (It's not particularly easy to check the "syntax" of a binary trace.) Of course, the output trace generated under such conditions will be completely erroneous.

Many more common formats that are not supported yet will be supported in future releases of this package.

This manpage was written in a rush, and is therefore quite poorly written. Improvements to this documentation are more than welcome.

Note that this is an alpha version, and bugs are expected. Please contact the author if you notice anything fishy.

Questions regarding ntrc are welcome. Questions regarding the specifics of the trace file formats (other than bug reports) will be silently discarded, and should instead be directed to the relevant mailing-lists (e.g., ns-users@isi.edu).

AUTHOR

Nicolas Christin <nicolas@cs.virginia.edu>.
See also <http://www.cs.virginia.edu/~nicolas>.

COPYRIGHT NOTICE

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment: This product includes software developed by Nicolas Christin.

4. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This document was created by man2html, using the manual pages.
Time: 17:17:46 GMT, December 21, 2002