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 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
16       together 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
28       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
33       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
41       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
48       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
54       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
67       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
78       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
83       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
92       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

OPTIONS

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
108       -D     Do not discard duplicate  packets  seen  when  merging  multiple
109              trace files.
110
111       -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
117       -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
122       -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
127       -h     Print  the  tcpslice  and libpcap version strings, print a usage
128              message, and exit.
129
130       -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
139       -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
142       -r     Same as -R except the timestamps are  dumped  in  human-readable
143              format, similar to that used by date(1).
144
145       -s     Enable  session  tracking  for  the  specified  types which is a
146              comma-separated list of the following:
147
148              tcp    track all TCP connections
149
150              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
158              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
166              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
172       -t     Same as -R except the timestamps are dumped in tcpslice  format,
173              i.e., in the ymdhmsu format discussed above.
174
175       -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
182       -w     Direct the output to file rather than stdout.
183

SEE ALSO

185       tcpdump(1)
186

AUTHORS

188       The original author was:
189
190       Vern Paxson, of Lawrence Berkeley Laboratory, University of California,
191       Berkeley, CA.
192
193       It is currently being maintained by The Tcpdump Group.
194
195       The current version is available at:
196
197              https://github.com/the-tcpdump-group/tcpslice
198
199       The original distribution is available via anonymous ftp:
200
201              ftp://ftp.ee.lbl.gov/tcpslice-1.2a3.tar.gz
202

BUGS

204       Please send problems, bugs, questions, desirable enhancements, etc. to:
205
206              tcpdump-workers@lists.tcpdump.org
207
208       Please  send source code contributions as git pull requests through the
209       project page above.
210
211       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
219       tcpslice cannot read its input from stdin, since it uses  random-access
220       to rummage through its input files.
221
222       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
227       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
238       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
242       It would sometimes be convenient if you could specify a clock offset to
243       use with the -l option.
244
245       It would be nice if tcpslice supported more general  editing  of  trace
246       files.
247
248
249
250                                 30 July 2020                      TCPSLICE(8)
Impressum