270 lines
8.4 KiB
Groff
270 lines
8.4 KiB
Groff
.\" Copyright (c) 1988-1990 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.
|
|
.\"
|
|
.\" $Id: tcpslice.1,v 1.5 1998/01/20 07:30:26 charnier Exp $
|
|
.\"
|
|
.Dd October 14, 1991
|
|
.Dt TCPSLICE 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tcpslice
|
|
.Nd extract pieces of and/or glue together tcpdump files
|
|
.Sh SYNOPSIS
|
|
.Nm tcpslice
|
|
.Op Fl dRrt
|
|
.Op Fl w Ar file
|
|
.Op Ar start-time Op end-time
|
|
.Ar
|
|
.Sh DESCRIPTION
|
|
.Nm Tcpslice
|
|
is a program for extracting portions of packet-trace files generated using
|
|
.Xr tcpdump 1 Ns 's
|
|
.Fl w
|
|
flag.
|
|
It can also be used to glue together several such files, as discussed
|
|
below.
|
|
.Pp
|
|
The basic operation of
|
|
.Nm
|
|
is to copy to
|
|
.Pa 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 time of the first packet in the first input file; we call
|
|
this the
|
|
.Em first time .
|
|
The ending time defaults to ten years after the starting time.
|
|
Thus, the command
|
|
.Nm
|
|
.Ar trace-file
|
|
simply copies
|
|
.Ar trace-file
|
|
to
|
|
.Pa stdout
|
|
(assuming the file does not include more than
|
|
ten years' worth of data).
|
|
.Pp
|
|
There are a number of ways to specify times. The first is using
|
|
Unix timestamps of the form
|
|
.Em sssssssss.uuuuuu
|
|
(this is the format specified by
|
|
.Xr tcpdump 1 Ns 's
|
|
.Fl tt
|
|
flag).
|
|
For example,
|
|
.Em 654321098.7654
|
|
specifies 38 seconds and 765,400 microseconds
|
|
after 8:51PM PDT, Sept. 25, 1990.
|
|
.Pp
|
|
All examples in this manual are given
|
|
for PDT times, but when displaying times and interpreting times symbolically
|
|
as discussed below,
|
|
.Nm
|
|
uses the local timezone, regardless of the timezone in which the
|
|
.Xr tcpdump 1
|
|
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.
|
|
.Pp
|
|
Times may also be specified relative
|
|
to either the
|
|
.Em 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
|
|
.Em +200
|
|
indicates 200 seconds after the
|
|
.Em first time ,
|
|
and the two arguments
|
|
.Em +200 +300
|
|
indicate from 200 seconds after the
|
|
.Em first time
|
|
through 500 seconds after the
|
|
.Em first time .
|
|
.Pp
|
|
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
|
|
.Em 90y9m25d20h51m38s765400u .
|
|
.Pp
|
|
When specifying times using this style, fields that are omitted default
|
|
as follows. If the omitted field is a unit
|
|
.Em greater
|
|
than that of the first specified field, then its value defaults to
|
|
the corresponding value taken from either
|
|
.Em 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
|
|
.Em less
|
|
than that of the first specified field, then it defaults to zero.
|
|
For example, suppose that the input file has a
|
|
.Em 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
|
|
.Em 21h36m .
|
|
To specify a range from 9:36PM PDT through 1:54AM PDT the next day we
|
|
could use
|
|
.Em 21h36m 26d1h54m .
|
|
.Pp
|
|
Relative times can also be specified when using the
|
|
.Em ymdhmsu
|
|
format. Omitted fields then default to 0 if the unit of the field is
|
|
.Em greater
|
|
than that of the first specified field, and to the corresponding value
|
|
taken from either the
|
|
.Em first time
|
|
or the starting time if the omitted field's unit is
|
|
.Em less
|
|
than that of the first specified field. Given a
|
|
.Em first time
|
|
of the Unix timestamp mentioned above,
|
|
.Em 22h +1h10m
|
|
specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and
|
|
.Em +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
|
|
.Em +0 +1h .
|
|
.Pp
|
|
Note that with the
|
|
.Em ymdhmsu
|
|
format there is an ambiguity between using
|
|
.Em m
|
|
for `month' or for `minute'. The ambiguity is resolved as follows: if an
|
|
.Em m
|
|
field is followed by a
|
|
.Em d
|
|
field then it is interpreted as specifying months; otherwise it
|
|
specifies minutes.
|
|
.Pp
|
|
If more than one input file is specified then
|
|
.Nm
|
|
first copies packets lying in the given range from the first file; it
|
|
then increases the starting time of the range to lie just beyond the
|
|
timestamp of the last packet in the first file, repeats the process
|
|
with the second file, and so on. Thus files with interleaved packets
|
|
are
|
|
.Em not
|
|
merged. For a given file, only packets that are newer than any in the
|
|
preceding files will be considered. This mechanism avoids any possibility
|
|
of a packet occurring more than once in the output.
|
|
.Sh OPTIONS
|
|
.Pp
|
|
If any of
|
|
.Fl R ,
|
|
.Fl r
|
|
or
|
|
.Fl t
|
|
are specified then
|
|
.Nm
|
|
reports the timestamps of the first and last packets in each input file
|
|
and exits. Only one of these three options may be specified.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl 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
|
|
.Fl R ,
|
|
.Fl r
|
|
or
|
|
.Fl t
|
|
has been specified then the times are dumped in the corresponding
|
|
format; otherwise, raw format (
|
|
.Fl R )
|
|
is used.
|
|
.It Fl R
|
|
Dump the timestamps of the first and last packets in each input file
|
|
as raw timestamps (i.e., in the form
|
|
.Em sssssssss.uuuuuu Ns ).
|
|
.It Fl r
|
|
Same as
|
|
.Fl R
|
|
except the timestamps are dumped in human-readable format, similar
|
|
to that used by
|
|
.Xr date 1 .
|
|
.It Fl t
|
|
Same as
|
|
.Fl R
|
|
except the timestamps are dumped in
|
|
.Nm
|
|
format, i.e., in the
|
|
.Em ymdhmsu
|
|
format discussed above.
|
|
.It Fl w Ar file
|
|
Direct the output to
|
|
.Ar file
|
|
rather than
|
|
.Pa stdout .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr tcpdump 1
|
|
.Sh AUTHORS
|
|
.An Vern Paxson Aq vern@ee.lbl.gov ,
|
|
of Lawrence Berkeley Laboratory, University of California, Berkeley, CA.
|
|
.Sh BUGS
|
|
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'.
|
|
.Pp
|
|
.Nm Tcpslice
|
|
cannot read its input from
|
|
.Pa stdin ,
|
|
since it uses random-access
|
|
to rummage through its input files.
|
|
.Pp
|
|
.Nm Tcpslice
|
|
refuses to write to its output if it is a terminal
|
|
(as indicated by
|
|
.Xr 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
|
|
.Pa stdout
|
|
or specify an
|
|
output file via
|
|
.Fl w .
|
|
.Pp
|
|
.Nm Tcpslice
|
|
will not work properly on
|
|
.Xr tcpdump 1
|
|
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 three 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
|
|
.Nm
|
|
to greatly speed up its processing when dealing with large trace files.
|
|
Note that
|
|
.Nm
|
|
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
|
|
.Xr tcpdump 1
|
|
being ungracefully killed).
|