261 lines
8.4 KiB
Groff
261 lines
8.4 KiB
Groff
.\" @(#) $Header: /home/ncvs/src/usr.sbin/tcpdump/tcpslice/tcpslice.1,v 1.3 1995/03/08 12:53:39 olah Exp $ (LBL)
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.TH TCPSLICE 1 "14 Oct 1991"
|
|
.SH NAME
|
|
tcpslice \- extract pieces of and/or glue together tcpdump files
|
|
.SH SYNOPSIS
|
|
.na
|
|
.B tcpslice
|
|
[
|
|
.B \-dRrt
|
|
] [
|
|
.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(1)\fP's
|
|
.B \-w
|
|
flag.
|
|
It can also be used to glue 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 time of the first packet in the first input file; 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 90y9m25d20h51m38s765400u.
|
|
.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
|
|
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
|
|
.I 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
|
|
.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
|
|
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 \-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(1)
|
|
.SH AUTHOR
|
|
Vern Paxson (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'.
|
|
.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 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
|
|
.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).
|