1TCPSLICE(8)                 System Manager's Manual                TCPSLICE(8)
2
3
4

NAME

6       tcpslice - extract pieces of and/or merge together pcap files
7

SYNOPSIS

9       tcpslice [ -DdlhRrtv ] [ -w output-file ]
10                [ -s types [ -e seconds ] [ -f format ] ]
11                [ start-time [ end-time ] ] file ...
12

DESCRIPTION

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 to‐
16       gether several such files, as discussed below.
17
18       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

TIME FORMATS

29       There  are  a number of ways to specify times.  The first is using Unix
30       timestamps of the form sssssssss.uuuuuu (this is the  format  specified
31       by  tcpdump's -tt flag).  For example, 654321098.7654 specifies 38 sec‐
32       onds and 765,400 microseconds after 8:51PM PDT, Sept. 25, 1990.
33
34       All examples in this manual are given for PDT times, but when  display‐
35       ing  times and interpreting times symbolically as discussed below, tcp‐
36       slice uses the local timezone, regardless of the timezone in which  the
37       pcap  file  was  generated.   The daylight-savings setting used is that
38       which is appropriate for the local timezone at the  date  in  question.
39       For  example,  times associated with summer months will usually include
40       daylight-savings effects, and those with winter months will not.
41
42       Times may also be specified relative to either  the  first  time  (when
43       specifying  a  starting  time) or the starting time (when specifying an
44       ending time) by preceding a numeric value in seconds with a  `+'.   For
45       example,  a starting time of +200 indicates 200 seconds after the first
46       time, and the two arguments +200 +300 indicate from 200  seconds  after
47       the first time through 500 seconds after the first time.
48
49       Times  may  also  be  specified in terms of years (y), months (m), days
50       (d), hours (h), minutes (m), seconds (s), and microseconds(u).  For ex‐
51       ample,  the Unix timestamp 654321098.7654 discussed above could also be
52       expressed as 1990y9m25d20h51m38s765400u.  2 or 4  digit  years  may  be
53       used; 2 digits can specify years from 1970 to 2069.
54
55       When specifying times using this style, fields that are omitted default
56       as follows.  If the omitted field is a unit greater than  that  of  the
57       first  specified  field,  then  its value defaults to the corresponding
58       value taken from either first time (if the starting time is being spec‐
59       ified)  or  the  starting time (if the ending time is being specified).
60       If the omitted field is a unit less than that of  the  first  specified
61       field,  then  it  defaults  to zero (1 for days).  For example, suppose
62       that the input file has a first time of the  Unix  timestamp  mentioned
63       above,  i.e.,  38  seconds  and  765,400 microseconds after 8:51PM PDT,
64       Sept. 25, 1990.  To specify 9:36PM PDT (exactly) on the  same  date  we
65       could  use  21h36m.   To specify a range from 9:36PM PDT through 1:54AM
66       PDT the next day we could use 21h36m 26d1h54m.
67
68       Relative times can also be specified when  using  the  ymdhmsu  format.
69       Omitted  fields  then  default to 0 if the unit of the field is greater
70       than that of the first specified field, and to the corresponding  value
71       taken  from  either  the first time or the starting time if the omitted
72       field's unit is less than that of the first specified field.   Given  a
73       first  time of the Unix timestamp mentioned above, 22h +1h10m specifies
74       a range from 10:00PM PDT on that date  through  11:10PM  PDT,  and  +1h
75       +1h10m  specifies a range from 38.7654 seconds after 9:51PM PDT through
76       38.7654 seconds after 11:01PM PDT.  The first hour of the file could be
77       extracted using +0 +1h.
78
79       Note that with the ymdhmsu format there is an ambiguity between using m
80       for `month' or for `minute'.  The ambiguity is resolved as follows:  if
81       an  m field is followed by a d field then it is interpreted as specify‐
82       ing months; otherwise it specifies minutes.
83

MULTIPLE INPUT FILES

85       If more than one input file is specified then tcpslice merges the pack‐
86       ets  from  the  various  input files into the single output file.  Nor‐
87       mally, this merge is done based on the value of the time stamps in  the
88       packets  in  the  individual files.  (Tcpslice assumes that within each
89       input file, packets are in time stamp order.)   If  the  -l  option  is
90       used,  the  value used for ordering is the time stamp of a given packet
91       minus the time stamp of the first packet in the input file in which the
92       given packet occurs.
93
94       When  merging  files,  by  default  tcpslice will discard any duplicate
95       packet it finds in more than one file.  A duplicate is  a  packet  that
96       has  an identical timestamp (either relative or absolute) and identical
97       packet contents (for as much as was captured) as another packet  previ‐
98       ously  seen in a different file.  Note that it is possible for the net‐
99       work to generate true replicates of packets, and for systems  that  can
100       return  the  same timestamp for multiple packets, these can be mistaken
101       for duplicates and discarded.  Accordingly, tcpslice will  not  discard
102       duplicates in the same trace file.  In addition, you can use the -D op‐
103       tion to suppress any discarding of duplicates.
104
105       tcpslice will refuse to merge multiple files if  they  don't  have  the
106       same link-layer header type.
107

OPTIONS

109       If  any  of  -R, -r or -t are specified then tcpslice reports the time‐
110       stamps of the first and last packets in  each  input  file  and  exits.
111       Only one of these three options may be specified.
112
113       -D     Do  not  discard  duplicate  packets  seen when merging multiple
114              trace files.
115
116       -d     Dump the start and end times specified by the  given  range  and
117              exit.   This  option is useful for checking that the given range
118              actually specifies the times you think it does.  If one  of  -R,
119              -r  or  -t  has  been specified then the times are dumped in the
120              corresponding format; otherwise, raw format (-R) is used.
121
122       -e seconds
123              Specify a number of seconds to wait after the  last  packet  was
124              seen before considering a session to be expired (default: 0 = do
125              not expire inactive sessions). This is only effective  when  the
126              -s option is used to track sessions.
127
128       -f format
129              Specify the name format of PCAP files to which each session will
130              be extracted (default: NULL = do not extract sessions  to  sepa‐
131              rate  files).  This is only effective when the -s option is used
132              to track sessions.
133
134       -h     Print the tcpslice and libpcap version strings,  print  a  usage
135              message, and exit.
136
137       -l     When  merging more than one file, merge on the basis of relative
138              time, rather than absolute time.  Normally, when  merging  files
139              is done, packets are merged based on absolute time stamps.  With
140              -l packets are merged based on the  relative  time  between  the
141              start  of  the  file  in  which the packet is found and the time
142              stamp of the packet itself.  The time stamp of  packets  in  the
143              output  file  is  calculated as the relative time for the packet
144              within its file plus first time.
145
146       -R     Dump the timestamps of the first and last packets in each  input
147              file as raw timestamps (i.e., in the form  sssssssss.uuuuuu).
148
149       -r     Same  as  -R  except the timestamps are dumped in human-readable
150              format, similar to that used by date(1).
151
152       -s types
153              Enable session tracking for  the  specified  types  which  is  a
154              comma-separated list of the following:
155
156              tcp    track all TCP connections
157
158              sip    track  SIP-based VoIP calls, which may enable tracking of
159                     TCP connections but only the ones that are related to SIP
160                     calls.   This  feature  is only available if tcpslice was
161                     linked against Aymeric Moizard's  GNU  oSIP  library;  if
162                     not,   install   the  latest  version  of  libosip2  from
163                     https://www.gnu.org/software/osip/  and  recompile   tcp‐
164                     slice.
165
166              h323   track  H.323-based  VoIP calls, which may enable tracking
167                     of TCP connections but only the ones that are related  to
168                     H.323  calls.  This feature is only available if tcpslice
169                     was linked against Objective Systems' Open H.323  library
170                     for  C;  if not, install the latest version of libooh323c
171                     from https://sourceforge.net/projects/ooh323c/ and recom‐
172                     pile tcpslice.
173
174              Session  tracking  altogether  is only available if tcpslice was
175              linked against a recent version (>1.20) of Rafal Wojtczuk's Net‐
176              work  Intrusion  Detection  System  library; if not, install the
177              latest version of libnids  from  http://libnids.sourceforge.net/
178              and recompile tcpslice.
179
180       -t     Same  as -R except the timestamps are dumped in tcpslice format,
181              i.e., in the ymdhmsu format discussed above.
182
183       -v     Turn on verbose mode. Currently this only affects session track‐
184              ing (-s) messages: if specified at least once, sessions openings
185              and closings are displayed regardless of the  time  (by  default
186              the  closings are only displayed past end-time); if specified at
187              least twice, subsessions (sessions initiated by other  sessions)
188              openings and closings are also displayed.
189
190       -w output-file
191              Direct the output to output-file rather than stdout.
192

SEE ALSO

194       tcpdump(1)
195

AUTHORS

197       The original author was:
198
199       Vern Paxson, of Lawrence Berkeley Laboratory, University of California,
200       Berkeley, CA.
201
202       It is currently maintained by The Tcpdump Group.
203
204       The current version is available at:
205
206              https://github.com/the-tcpdump-group/tcpslice
207
208       The original distribution is available via anonymous ftp:
209
210              ftp://ftp.ee.lbl.gov/tcpslice-1.2a3.tar.gz
211

BUGS

213       Please send problems, bugs, questions, desirable enhancements, etc. to:
214
215              tcpdump-workers@lists.tcpdump.org
216
217       Please send source code contributions as git pull requests through  the
218       project page above.
219
220       An  input  filename  that  exactly  matches the sssssssss.uuuuuu or the
221       ymdhmsu format discussed above can be confused with  a  start/end  time
222       (regardless  if  the  date  and the time are valid in the latter case).
223       Such filenames can be specified with a leading `./'; for example, spec‐
224       ify  the  file  `1976y07m04d'  as  `./1976y07m04d'  and  `00000123'  as
225       `./00000123'.  Alternatively, renaming the files to  `1976y07m04d.pcap'
226       and `00000123.pcap' respectively would resolve this ambiguity.
227
228       tcpslice  cannot read its input from stdin, since it uses random-access
229       to rummage through its input files.
230
231       tcpslice refuses to write to its output if it is a terminal  (as  indi‐
232       cated  by  isatty(3)).   This is not a bug but a feature, to prevent it
233       from spraying binary data to the user's terminal.  Note that this means
234       you must either redirect stdout or specify an output file via -w.
235
236       tcpslice  will  not  work properly on pcap files spanning more than one
237       year; with files containing portions of packets whose  original  length
238       was  more  than  65,535 bytes; nor with files containing fewer than two
239       packets.  Such files result in the error message: `couldn't find  final
240       packet  in  file'.   These problems are due to the interpolation scheme
241       used by tcpslice to greatly speed up its processing when  dealing  with
242       large  trace  files.  Note that tcpslice can efficiently extract slices
243       from the middle of trace files of any size,  and  can  also  work  with
244       truncated  trace files (i.e., the final packet in the file is only par‐
245       tially present, typically due to tcpdump being ungracefully killed).
246
247       Adding -l has broken some compatibility with older versions, since tcp‐
248       slice  now merges its input files, rather than (approximately) concate‐
249       nating them together as it did previously.
250
251       It would sometimes be convenient if you could specify a clock offset to
252       use with the -l option.
253
254       It  would  be  nice if tcpslice supported more general editing of trace
255       files.
256
257
258
259                                01 January 2022                    TCPSLICE(8)
Impressum