.\" @(#) $Id: tcpslice.1,v 1.7 2002/10/08 22:32:26 vern Exp $ (LBL)
.\"
.\" Copyright (c) 1991, 1996, 2000
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that: (1) source code distributions
.\" retain the above copyright notice and this paragraph in its entirety, (2)
.\" distributions including binary code include the above copyright notice and
.\" this paragraph in its entirety in the documentation or other materials
.\" provided with the distribution, and (3) all advertising materials mentioning
.\" features or use of this software display the following acknowledgement:
.\" ``This product includes software developed by the University of California,
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
.\" the University nor the names of its contributors may be used to endorse
.\" or promote products derived from this software without specific prior
.\" written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.TH TCPSLICE 1  "24 February 2000"
.SH NAME
tcpslice \- extract pieces of and/or merge together tcpdump files
.SH SYNOPSIS
.na
.B tcpslice
[
.B \-DdlRrt
] [
.B \-w
.I file
]
.br
.ti +9
[
.I start-time
[
.I end-time
] ]
.I file ...
.br
.ad
.SH DESCRIPTION
.LP
.I Tcpslice
is a program for extracting portions of packet-trace files generated using
\fItcpdump(l)\fP's
.B \-w
flag.
It can also be used to merge together several such files, as discussed
below.
.LP
The basic operation of
.I tcpslice
is to copy to
.I stdout
all packets from its input file(s) whose timestamps fall
within a given range.  The starting and ending times of the range
may be specified on the command line.  All ranges are inclusive.
The starting time defaults
to the earliest time of the first packet in
any of the input files; we call
this the
.I first time.
The ending time defaults to ten years after the starting time.
Thus, the command
.I tcpslice trace-file
simply copies
.I trace-file
to \fIstdout\fP (assuming the file does not include more than
ten years' worth of data).
.LP
There are a number of ways to specify times.  The first is using
Unix timestamps of the form
.I sssssssss.uuuuuu
(this is the format specified by \fItcpdump\fP's
.B \-tt
flag).
For example,
.B 654321098.7654
specifies 38 seconds and 765,400 microseconds
after 8:51PM PDT, Sept. 25, 1990.
.LP
All examples in this manual are given
for PDT times, but when displaying times and interpreting times symbolically
as discussed below,
.I tcpslice
uses the local timezone, regardless of the timezone in which the \fItcpdump\fP
file was generated.  The daylight-savings setting used is that which is
appropriate for the local timezone at the date in question.  For example,
times associated with summer months will usually include daylight-savings
effects, and those with winter months will not.
.LP
Times may also be specified relative
to either the
.I first time
(when specifying a starting time)
or the starting time (when specifying an ending time)
by preceding a numeric value in seconds with a `+'.
For example, a starting time of
.B +200
indicates 200 seconds after the
.I first time,
and the two arguments
.B +200 +300
indicate from 200 seconds after the
.I first time
through 500 seconds after the
.I first time.
.LP
Times may also be specified in terms of years (y), months (m), days (d),
hours (h), minutes (m), seconds (s), and microseconds(u).  For example,
the Unix timestamp 654321098.7654 discussed above could also be expressed
as
.B 1990y9m25d20h51m38s765400u.
2 or 4 digit years may be used; 2 digits can specify years from 1970 to
2069.
.LP
When specifying times using this style, fields that are omitted default
as follows.  If the omitted field is a unit
.I greater
than that of the first specified field, then its value defaults to
the corresponding value taken from either
.I first time
(if the starting time is being specified) or the starting time
(if the ending time is being specified).
If the omitted field is a unit
.I less
than that of the first specified field, then it defaults to zero.
For example, suppose that the input file has a
.I first time
of the Unix timestamp mentioned above, i.e., 38 seconds and 765,400 microseconds
after 8:51PM PDT, Sept. 25, 1990.  To specify 9:36PM PDT (exactly) on the
same date we could use
.B 21h36m.
To specify a range from 9:36PM PDT through 1:54AM PDT the next day we
could use
.B 21h36m 26d1h54m.
.LP
Relative times can also be specified when using the
.I ymdhmsu
format.  Omitted fields then default to 0 if the unit of the field is
.I greater
than that of the first specified field, and to the corresponding value
taken from either the
.I first time
or the starting time if the omitted field's unit is
.I less
than that of the first specified field.  Given a
.I first time
of the Unix timestamp mentioned above,
.B 22h +1h10m
specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and
.B +1h +1h10m
specifies a range from 38.7654 seconds after 9:51PM PDT through 38.7654
seconds after 11:01PM PDT.  The first hour of the file could be extracted
using
.B +0 +1h.
.LP
Note that with the
.I ymdhmsu
format there is an ambiguity between using
.I m
for `month' or for `minute'.  The ambiguity is resolved as follows: if an
.I m
field is followed by a
.I d
field then it is interpreted as specifying months; otherwise it
specifies minutes.
.LP
If more than one input file is specified then
.I tcpslice
merges the packets from the various input files into the single
output file.  Normally, this merge is done based on the
value of the timestamps in the packets in the individual files.
(Tcpslice assumes that
.I within
each input file, packets are in timestamp order.)
If the
.B \-l
option is used, the value used for ordering is the timestamp of
a given packet minus the timestamp of the first packet in the
input file in which the given packet occurs.
.LP
When merging files, by default
.I tcpslice
will discard any
.I duplicate
packet it finds in more than one file.  A duplicate is a packet
that has an identical timestamp (either relative or absolute) and
identical packet contents (for as much as was captured) as another
packet previously seen in a different file.  Note that it is possible
for the network to generate true replicates of packets, and for
systems that can return the same timestamp for multiple packets,
these can be mistaken for duplicates and discarded.  Accordingly,
.I tcpslice
will not discard duplicates in the same trace file.  In addition,
you can use the
.B \-D
option to suppress any discarding of duplicates.
.LP
A different issue arises if a file contains timestamps that skip
backwards.
.I tcpslice
will include these in the output, even if they precede the minimum
time requested.  There should probably be an option to suppress these.
.LP
Another problem relating to backwards timestamps is that
.I tcpslice
uses random access to seek through a file looking for packets
corresponding to the desired range of time.  While doing so leads
to a major performance benefit for very large trace files, it also
means that in the presence of backwards timestamps
.I
tcpslice
can fail to find the true earliest occurrence of a packet matching
the time interval criteria.  There should probably be an option
to specify not to use random access but just read the file linearly.
.SH OPTIONS
.LP
If any of
.B \-R,
.B \-r
or
.B \-t
are specified then
.I tcpslice
reports the timestamps of the first and last packets in each input file
and exits.  Only one of these three options may be specified.
.TP
.B \-D
Do not discard duplicate packets seen when merging multiple trace files.
.TP
.B \-d
Dump the start and end times specified by the given range and
exit.  This option is useful for checking that the given range actually
specifies the times you think it does.  If one of
.B \-R,
.B \-r
or
.B \-t
has been specified then the times are dumped in the corresponding
format; otherwise, raw format (\fB \-R\fP) is used.
.TP
.B \-l
When merging more than one file, merge on the basis of
relative time, rather than absolute time.
Normally, when merging
files is done, packets are merged based on absolute timestamps.  With
.B \-l
packets are merged based on the relative time between
the start of the file in which the packet is found and the timestamp
of the packet itself.
The timestamp of packets in the output file is calculated
as the relative time for the packet within its file plus
.I first time.
.TP
.B \-R
Dump the timestamps of the first and last packets in each input file
as raw timestamps (i.e., in the form \fI sssssssss.uuuuuu\fP).
.TP
.B \-r
Same as
.B \-R
except the timestamps are dumped in human-readable format, similar
to that used by \fI date(1)\fP.
.TP
.B \-t
Same as
.B \-R
except the timestamps are dumped in
.I tcpslice
format, i.e., in the
.I ymdhmsu
format discussed above.
.TP
.B \-w
Direct the output to \fIfile\fR rather than \fIstdout\fP.
.SH "SEE ALSO"
tcpdump(l)
.SH AUTHOR
Vern Paxson, of
Lawrence Berkeley Laboratory, University of California, Berkeley, CA.
.LP
The current version is available via anonymous ftp:
.LP
.RS
.I ftp://ftp.ee.lbl.gov/tcpslice.tar.Z
.RE
.SH BUGS
Please send bug reports to tcpslice@ee.lbl.gov.
.LP
An input filename that beings with a digit or a `+' can be confused
with a start/end time.  Such filenames can be specified with a
leading `./'; for example, specify the file `04Jul76.trace' as
`./04Jul76.trace'.
.LP
.I tcpslice
cannot read its input from \fIstdin\fP, since it uses random-access
to rummage through its input files.
.LP
.I tcpslice
refuses to write to its output if it is a terminal
(as indicated by \fIisatty(3)\fP).  This is not a bug but a feature,
to prevent it from spraying binary data to the user's terminal.
Note that this means you must either redirect \fIstdout\fP or specify an
output file via \fB\-w\fP.
.LP
.I tcpslice
will not work properly on \fItcpdump\fP files spanning more than one year;
with files containing portions of packets whose original length was
more than 65,535 bytes; nor with files containing fewer than two packets.
Such files result in
the error message: `couldn't find final packet in file'.  These problems
are due to the interpolation scheme used by
.I tcpslice
to greatly speed up its processing when dealing with large trace files.
Note that
.I tcpslice
can efficiently extract slices from the middle of trace files of any
size, and can also work with truncated trace files (i.e., the final packet
in the file is only partially present, typically due to \fItcpdump\fP
being ungracefully killed).
.LP
Adding
.B \-l
has broken some compatibility with older versions, since
.I tcpslice
now merges its input files, rather than (approximately) concatenating
them together as it did previously.
.LP
It would sometimes be convenient if you could specify a clock offset
to use with the
.B \-l
option.
.LP
It would be nice if
.I tcpslice
supported more general editing of trace files.