tcpslice(1) man page
Return to Main Contents
This man page documents tcpslice version 1.7-PRE-GIT (see also: 1.6, 1.5, 1.4, 1.3).Your system may have a different version installed, possibly with some local modifications. To achieve the best results, please make sure this version of this man page suits your needs. If necessary, try to look for a different version on this web site or in the man pages available in your installation.
[ -s types [ -e seconds ] [ -f format ] ]
[ start-time [ end-time ] ] file ...
is a program for extracting portions of packet-trace files generated using
It can also be used to merge together several such files, as discussed
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
(this is the format specified by tcpdump's
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 pcap 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
(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
indicates 200 seconds after the
and the two arguments
indicate from 200 seconds after the
through 500 seconds after the
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
2 or 4 digit years may be used; 2 digits can specify years from 1970 to
When specifying times using this style, fields that are omitted default
as follows. If the omitted field is a unit
than that of the first specified field, then its value defaults to
the corresponding value taken from either
(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
than that of the first specified field, then it defaults to zero (1 for days).
For example, suppose that the input file has a
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
To specify a range from 9:36PM PDT through 1:54AM PDT the next day we
Relative times can also be specified when using the
format. Omitted fields then default to 0 if the unit of the field is
than that of the first specified field, and to the corresponding value
taken from either the
or the starting time if the omitted field's unit is
than that of the first specified field. Given a
of the Unix timestamp mentioned above,
specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and
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
Note that with the ymdhmsu format there is an ambiguity between using m for `month' or for `minute'. The ambiguity is resolved as follows: if an m field is followed by a d field then it is interpreted as specifying months; otherwise it specifies minutes.
MULTIPLE INPUT FILES
If more than one input file is specified then
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 individual files.
(Tcpslice assumes that
each input file, packets are in time stamp order.)
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
will discard any
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,
will not discard duplicates in the same trace file. In addition,
you can use the
option to suppress any discarding of duplicates.
tcpslice will refuse to merge multiple files if they don't have the same link-layer header type.
If any of
are specified then
reports the timestamps of the first and last packets in each input file
and exits. Only one of these three options may be specified.
- Do not discard duplicate packets seen when merging multiple trace files.
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
-thas been specified then the times are dumped in the corresponding format; otherwise,
-R(raw format) is used.
Specify a number of
to wait after the last packet was seen before considering a session
to be expired (default: 0 = do not expire inactive sessions). This
is only effective when the
-soption is used to track sessions.
Specify the name
of PCAP files to which each session will be extracted (default: NULL = do
not extract sessions to separate files). This is only effective when the
-soption is used to track sessions.
- Print the tcpslice and libpcap version strings, print a usage message, and exit.
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 time stamps. With
-lpackets 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.
- Dump the timestamps of the first and last packets in each input file as raw timestamps (i.e., in the form sssssssss.uuuuuu).
-Rexcept the timestamps are dumped in human-readable format, similar to that used by date(1).
Enable session tracking for the specified
which is a comma-separated list of the following:
- track all TCP connections
- track SIP-based VoIP calls, which may enable tracking of TCP connections but only the ones that are related to SIP calls. This feature is only available if tcpslice was linked against Aymeric Moizard's GNU oSIP library; if not, install the latest version of libosip2 from https://www.gnu.org/software/osip/ and recompile tcpslice.
- track H.323-based VoIP calls, which may enable tracking of TCP connections but only the ones that are related to H.323 calls. This feature is only available if tcpslice was linked against Objective Systems' Open H.323 library for C; if not, install the latest version of libooh323c from https://sourceforge.net/projects/ooh323c/ and recompile tcpslice.
Session tracking altogether is only available if tcpslice was linked against a recent version (>1.20) of Rafal Wojtczuk's Network Intrusion Detection System library; if not, install the latest version of libnids from http://libnids.sourceforge.net/ and recompile tcpslice.
-Rexcept the timestamps are dumped in tcpslice format, i.e., in the ymdhmsu format discussed above.
- Turn on verbose mode. Currently this only affects session tracking (-s) messages: if specified at least once, sessions openings and closings are displayed regardless of the time (by default the closings are only displayed past end-time); if specified at least twice, subsessions (sessions initiated by other sessions) openings and closings are also displayed.
- Direct the output to output-file rather than stdout.
Vern Paxson, of Lawrence Berkeley Laboratory, University of California, Berkeley, CA.
It is currently maintained by The Tcpdump Group.
The current version is available at:
The original distribution is available via anonymous ftp:
Please send source code contributions as git pull requests through the project page above.
An input filename that exactly matches the
format discussed above can be confused with a start/end time (regardless if
the date and the time are valid in the latter case). Such filenames can be
specified with a leading `./'; for example, specify the file
Alternatively, renaming the files to
respectively would resolve this ambiguity.
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 terminal (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 pcap 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 tcpslice to greatly speed up its processing 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 ungracefully killed).
has broken some compatibility with older versions, since
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
It would be nice if tcpslice supported more general editing of trace files.