1TCPSLICE(8) System Manager's Manual TCPSLICE(8)
2
6 tcpslice - extract pieces of and/or merge together pcap files
7
9 tcpslice [ -DdlhRrtv ] [ -w file ]
10 [ -s types [ -e seconds ] [ -f format ] ]
11 [ start-time [ end-time ] ] file ...
12
14 Tcpslice is a program for extracting portions of packet-trace files
15 generated using tcpdump(1)'s -w flag. It can also be used to merge
16 together several such files, as discussed below.
17 The basic operation of tcpslice is to copy to stdout all packets from
19 its input file(s) whose timestamps fall within a given range. The
20 starting and ending times of the range may be specified on the command
21 line. All ranges are inclusive. The starting time defaults to the
22 earliest time of the first packet in any of the input files; we call
23 this the first time. The ending time defaults to ten years after the
24 starting time. Thus, the command tcpslice trace-file simply copies
25 trace-file to stdout (assuming the file does not include more than ten
26 years' worth of data).
27 There are a number of ways to specify times. The first is using Unix
29 timestamps of the form sssssssss.uuuuuu (this is the format specified
30 by tcpdump's -tt flag). For example, 654321098.7654 specifies 38 sec‐
31 onds and 765,400 microseconds after 8:51PM PDT, Sept. 25, 1990.
32 All examples in this manual are given for PDT times, but when display‐
34 ing times and interpreting times symbolically as discussed below, tcp‐
35 slice uses the local timezone, regardless of the timezone in which the
36 pcap file was generated. The daylight-savings setting used is that
37 which is appropriate for the local timezone at the date in question.
38 For example, times associated with summer months will usually include
39 daylight-savings effects, and those with winter months will not.
40 Times may also be specified relative to either the first time (when
42 specifying a starting time) or the starting time (when specifying an
43 ending time) by preceding a numeric value in seconds with a `+'. For
44 example, a starting time of +200 indicates 200 seconds after the first
45 time, and the two arguments +200 +300 indicate from 200 seconds after
46 the first time through 500 seconds after the first time.
47 Times may also be specified in terms of years (y), months (m), days
49 (d), hours (h), minutes (m), seconds (s), and microseconds(u). For
50 example, the Unix timestamp 654321098.7654 discussed above could also
51 be expressed as 1990y9m25d20h51m38s765400u. 2 or 4 digit years may be
52 used; 2 digits can specify years from 1970 to 2069.
53 When specifying times using this style, fields that are omitted default
55 as follows. If the omitted field is a unit greater than that of the
56 first specified field, then its value defaults to the corresponding
57 value taken from either first time (if the starting time is being spec‐
58 ified) or the starting time (if the ending time is being specified).
59 If the omitted field is a unit less than that of the first specified
60 field, then it defaults to zero (1 for days). For example, suppose
61 that the input file has a first time of the Unix timestamp mentioned
62 above, i.e., 38 seconds and 765,400 microseconds after 8:51PM PDT,
63 Sept. 25, 1990. To specify 9:36PM PDT (exactly) on the same date we
64 could use 21h36m. To specify a range from 9:36PM PDT through 1:54AM
65 PDT the next day we could use 21h36m 26d1h54m.
66 Relative times can also be specified when using the ymdhmsu format.
68 Omitted fields then default to 0 if the unit of the field is greater
69 than that of the first specified field, and to the corresponding value
70 taken from either the first time or the starting time if the omitted
71 field's unit is less than that of the first specified field. Given a
72 first time of the Unix timestamp mentioned above, 22h +1h10m specifies
73 a range from 10:00PM PDT on that date through 11:10PM PDT, and +1h
74 +1h10m specifies a range from 38.7654 seconds after 9:51PM PDT through
75 38.7654 seconds after 11:01PM PDT. The first hour of the file could be
76 extracted using +0 +1h.
77 Note that with the ymdhmsu format there is an ambiguity between using m
79 for `month' or for `minute'. The ambiguity is resolved as follows: if
80 an m field is followed by a d field then it is interpreted as specify‐
81 ing months; otherwise it specifies minutes.
82 If more than one input file is specified then tcpslice merges the pack‐
84 ets from the various input files into the single output file. Nor‐
85 mally, this merge is done based on the value of the time stamps in the
86 packets in the individual files. (Tcpslice assumes that within each
87 input file, packets are in time stamp order.) If the -l option is
88 used, the value used for ordering is the time stamp of a given packet
89 minus the time stamp of the first packet in the input file in which the
90 given packet occurs.
91 When merging files, by default tcpslice will discard any duplicate
93 packet it finds in more than one file. A duplicate is a packet that
94 has an identical timestamp (either relative or absolute) and identical
95 packet contents (for as much as was captured) as another packet previ‐
96 ously seen in a different file. Note that it is possible for the net‐
97 work to generate true replicates of packets, and for systems that can
98 return the same timestamp for multiple packets, these can be mistaken
99 for duplicates and discarded. Accordingly, tcpslice will not discard
100 duplicates in the same trace file. In addition, you can use the -D
101 option to suppress any discarding of duplicates.
102
104 If any of -R, -r or -t are specified then tcpslice reports the time‐
105 stamps of the first and last packets in each input file and exits.
106 Only one of these three options may be specified.
107 -D Do not discard duplicate packets seen when merging multiple
109 trace files.
110 -d Dump the start and end times specified by the given range and
112 exit. This option is useful for checking that the given range
113 actually specifies the times you think it does. If one of -R,
114 -r or -t has been specified then the times are dumped in the
115 corresponding format; otherwise, raw format (-R) is used.
116 -e Specify a number of seconds to wait after the last packet was
118 seen before considering a session to be expired (default: 0 = do
119 not expire inactive sessions). This is only effective when the
120 -s option is used to track sessions.
121 -f Specify the name format of PCAP files to which each session will
123 be extracted (default: NULL = do not extract sessions to sepa‐
124 rate files). This is only effective when the -s option is used
125 to track sessions.
126 -h Print the tcpslice and libpcap version strings, print a usage
128 message, and exit.
129 -l When merging more than one file, merge on the basis of relative
131 time, rather than absolute time. Normally, when merging files
132 is done, packets are merged based on absolute time stamps. With
133 -l packets are merged based on the relative time between the
134 start of the file in which the packet is found and the time
135 stamp of the packet itself. The time stamp of packets in the
136 output file is calculated as the relative time for the packet
137 within its file plus first time.
138 -R Dump the timestamps of the first and last packets in each input
140 file as raw timestamps (i.e., in the form sssssssss.uuuuuu).
141 -r Same as -R except the timestamps are dumped in human-readable
143 format, similar to that used by date(1).
144 -s Enable session tracking for the specified types which is a
146 comma-separated list of the following:
147 tcp track all TCP connections
149 sip track SIP-based VoIP calls, which may enable tracking of
151 TCP connections but only the ones that are related to SIP
152 calls. This feature is only available if tcpslice was
153 linked against Aymeric Moizard's GNU oSIP library; if
154 not, install the latest version of libosip2 from
155 https://www.gnu.org/software/osip/ and recompile tcp‐
156 slice.
157 h323 track H.323-based VoIP calls, which may enable tracking
159 of TCP connections but only the ones that are related to
160 H.323 calls. This feature is only available if tcpslice
161 was linked against Objective Systems' Open H.323 library
162 for C; if not, install the latest version of libooh323c
163 from https://sourceforge.net/projects/ooh323c/ and recom‐
164 pile tcpslice.
165 Session tracking altogether is only available if tcpslice was
167 linked against a recent version (>1.20) of Rafal Wojtczuk's Net‐
168 work Intrusion Detection System library; if not, install the
169 latest version of libnids from http://libnids.sourceforge.net/
170 and recompile tcpslice.
171 -t Same as -R except the timestamps are dumped in tcpslice format,
173 i.e., in the ymdhmsu format discussed above.
174 -v Turn on verbose mode. Currently this only affects session track‐
176 ing (-s) messages: if specified at least once, sessions openings
177 and closings are displayed regardless of the time (by default
178 the closings are only displayed past end-time); if specified at
179 least twice, subsessions (sessions initiated by other sessions)
180 openings and closings are also displayed.
181 -w Direct the output to file rather than stdout.
183
185 tcpdump(1)
186
188 The original author was:
189 Vern Paxson, of Lawrence Berkeley Laboratory, University of California,
191 Berkeley, CA.
192 It is currently being maintained by The Tcpdump Group.
194 The current version is available at:
196 https://github.com/the-tcpdump-group/tcpslice
198 The original distribution is available via anonymous ftp:
200 ftp://ftp.ee.lbl.gov/tcpslice-1.2a3.tar.gz
202
204 Please send problems, bugs, questions, desirable enhancements, etc. to:
205 tcpdump-workers@lists.tcpdump.org
207 Please send source code contributions as git pull requests through the
209 project page above.
210 An input filename that exactly matches the sssssssss.uuuuuu or the
212 ymdhmsu format discussed above can be confused with a start/end time
213 (regardless if the date and the time are valid in the latter case).
214 Such filenames can be specified with a leading `./'; for example, spec‐
215 ify the file `1976y07m04d' as `./1976y07m04d' and `00000123' as
216 `./00000123'. Alternatively, renaming the files to `1976y07m04d.pcap'
217 and `00000123.pcap' respectively would resolve this ambiguity.
218 tcpslice cannot read its input from stdin, since it uses random-access
220 to rummage through its input files.
221 tcpslice refuses to write to its output if it is a terminal (as indi‐
223 cated by isatty(3)). This is not a bug but a feature, to prevent it
224 from spraying binary data to the user's terminal. Note that this means
225 you must either redirect stdout or specify an output file via -w.
226 tcpslice will not work properly on pcap files spanning more than one
228 year; with files containing portions of packets whose original length
229 was more than 65,535 bytes; nor with files containing fewer than two
230 packets. Such files result in the error message: `couldn't find final
231 packet in file'. These problems are due to the interpolation scheme
232 used by tcpslice to greatly speed up its processing when dealing with
233 large trace files. Note that tcpslice can efficiently extract slices
234 from the middle of trace files of any size, and can also work with
235 truncated trace files (i.e., the final packet in the file is only par‐
236 tially present, typically due to tcpdump being ungracefully killed).
237 Adding -l has broken some compatibility with older versions, since tcp‐
239 slice now merges its input files, rather than (approximately) concate‐
240 nating them together as it did previously.
241 It would sometimes be convenient if you could specify a clock offset to
243 use with the -l option.
244 It would be nice if tcpslice supported more general editing of trace
246 files.
247 30 July 2020 TCPSLICE(8)