TCPSLICE(1)TCPSLICE(1)NAMEtcpslice - extract pieces of and/or merge together tcpdump
files
SYNOPSIStcpslice [ -DdlRrt ] [ -w file ]
[ start-time [ end-time ] ] file ...
DESCRIPTION
Tcpslice is a program for extracting portions of packet-
trace files generated using tcpdump(l)'s -w flag. It can
also be used to merge together several such files, as dis
cussed below.
The basic operation of tcpslice is to copy to 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 first time. The ending time
defaults to ten years after the starting time. Thus, the
command tcpslice trace-file simply copies trace-file to
stdout (assuming the file does not include more than ten
years' worth of data).
There are a number of ways to specify times. The first is
using Unix timestamps of the form sssssssss.uuuuuu (this
is the format specified by tcpdump's -tt flag). For exam
ple, 654321098.7654 specifies 38 seconds and 765,400
microseconds after 8:51PM PDT, Sept. 25, 1990.
All examples in this manual are given for PDT times, but
when displaying times and interpreting times symbolically
as discussed below, tcpslice uses the local timezone,
regardless of the timezone in which the tcpdump 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.
Times may also be specified relative to either the 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 +200 indicates 200 seconds after the
first time, and the two arguments +200 +300 indicate from
200 seconds after the first time through 500 seconds after
the first time.
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
1990y9m25d20h51m38s765400u. 2 or 4 digit years may be
used; 2 digits can specify years from 1970 to 2069.
When specifying times using this style, fields that are
omitted default as follows. If the omitted field is a
unit greater than that of the first specified field, then
its value defaults to the corresponding value taken from
either first time (if the starting time is being speci
fied) or the starting time (if the ending time is being
specified). If the omitted field is a unit less than that
of the first specified field, then it defaults to zero.
For example, suppose that the input file has a 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 21h36m. To specify a range from 9:36PM PDT through
1:54AM PDT the next day we could use 21h36m 26d1h54m.
Relative times can also be specified when using the
ymdhmsu format. Omitted fields then default to 0 if the
unit of the field is greater than that of the first speci
fied field, and to the corresponding value taken from
either the first time or the starting time if the omitted
field's unit is less than that of the first specified
field. Given a first time of the Unix timestamp mentioned
above, 22h +1h10m specifies a range from 10:00PM PDT on
that date through 11:10PM PDT, and +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 +0 +1h.
Note that with the ymdhmsu format there is an ambiguity
between using m for `month' or for `minute'. The ambigu
ity is resolved as follows: if an m field is followed by a
d field then it is interpreted as specifying months; oth
erwise it specifies minutes.
If more than one input file is specified then 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 time stamps in the packets in the indi
vidual files. (Tcpslice assumes that within each input
file, packets are in time stamp order.) If the -l option
is used, the value used for ordering is the time stamp of
a given packet minus the time stamp of the first packet in
the input file in which the given packet occurs.
When merging files, by default tcpslice will discard any
duplicate packet it finds in more than one file. A dupli
cate 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 dis
carded. Accordingly, tcpslice will not discard duplicates
in the same trace file. In addition, you can use the -D
option to suppress any discarding of duplicates.
OPTIONS
If any of -R, -r or -t are specified then 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.
-D Do not discard duplicate packets seen when merging
multiple trace files.
-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 -R, -r or -t has been
specified then the times are dumped in the corre
sponding format; otherwise, raw format ( -R) is
used.
-l When merging more than one file, merge on the basis
of relative time, rather than absolute time. Nor
mally, when merging files is done, packets are
merged based on absolute time stamps. With -l
packets are merged based on the relative time
between the start of the file in which the packet
is found and the time stamp of the packet itself.
The time stamp of packets in the output file is
calculated as the relative time for the packet
within its file plus first time.
-R Dump the timestamps of the first and last packets
in each input file as raw timestamps (i.e., in the
form sssssssss.uuuuuu).
-r Same as -R except the timestamps are dumped in
human-readable format, similar to that used by
date(1).
-t Same as -R except the timestamps are dumped in tcp_
slice format, i.e., in the ymdhmsu format discussed
above.
-w Direct the output to file rather than stdout.
SEE ALSOtcpdump(l)AUTHOR
Vern Paxson, of Lawrence Berkeley Laboratory, University
of California, Berkeley, CA.
The current version is available via anonymous ftp:
ftp://ftp.ee.lbl.gov/tcpslice.tar.Z
BUGS
Please send bug reports to tcpslice@ee.lbl.gov.
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'.
tcpslice cannot read its input from stdin, since it uses
random-access to rummage through its input files.
tcpslice refuses to write to its output if it is a termi
nal (as indicated by isatty(3)). 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 stdout or specify an output file via -w.
tcpslice will not work properly on tcpdump 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 interpola
tion scheme used by tcpslice to greatly speed up its pro
cessing when dealing with large trace files. Note that
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 tcpdump being ungrace
fully killed).
Adding -l has broken some compatibility with older ver
sions, since tcpslice now merges its input files, rather
than (approximately) concatenating them together as it did
previously.
It would sometimes be convenient if you could specify a
clock offset to use with the -l option.
It would be nice if tcpslice supported more general edit
ing of trace files.
24 February 2000 TCPSLICE(1)
