1TCPSLICE(8) System Manager's Manual TCPSLICE(8)
2
6 tcpslice - extract pieces of and/or merge together tcpdump files
7
9 tcpslice [ -DdlRrt ] [ -w file ]
10 [ start-time [ end-time ] ] file ...
11
13 Tcpslice is a program for extracting portions of packet-trace files
14 generated using tcpdump(l)'s -w flag. It can also be used to merge
15 together several such files, as discussed below.
16 The basic operation of tcpslice is to copy to stdout all packets from
18 its input file(s) whose timestamps fall within a given range. The
19 starting and ending times of the range may be specified on the command
20 line. All ranges are inclusive. The starting time defaults to the
21 earliest time of the first packet in any of the input files; we call
22 this the first time. The ending time defaults to ten years after the
23 starting time. Thus, the command tcpslice trace-file simply copies
24 trace-file to stdout (assuming the file does not include more than ten
25 years' worth of data).
26 There are a number of ways to specify times. The first is using Unix
28 timestamps of the form sssssssss.uuuuuu (this is the format specified
29 by tcpdump's -tt flag). For example, 654321098.7654 specifies 38 sec‐
30 onds and 765,400 microseconds after 8:51PM PDT, Sept. 25, 1990.
31 All examples in this manual are given for PDT times, but when display‐
33 ing times and interpreting times symbolically as discussed below, tcp‐
34 slice uses the local timezone, regardless of the timezone in which the
35 tcpdump file was generated. The daylight-savings setting used is that
36 which is appropriate for the local timezone at the date in question.
37 For example, times associated with summer months will usually include
38 daylight-savings effects, and those with winter months will not.
39 Times may also be specified relative to either the first time (when
41 specifying a starting time) or the starting time (when specifying an
42 ending time) by preceding a numeric value in seconds with a `+'. For
43 example, a starting time of +200 indicates 200 seconds after the first
44 time, and the two arguments +200 +300 indicate from 200 seconds after
45 the first time through 500 seconds after the first time.
46 Times may also be specified in terms of years (y), months (m), days
48 (d), hours (h), minutes (m), seconds (s), and microseconds(u). For
49 example, the Unix timestamp 654321098.7654 discussed above could also
50 be expressed as 1990y9m25d20h51m38s765400u. 2 or 4 digit years may be
51 used; 2 digits can specify years from 1970 to 2069.
52 When specifying times using this style, fields that are omitted default
54 as follows. If the omitted field is a unit greater than that of the
55 first specified field, then its value defaults to the corresponding
56 value taken from either first time (if the starting time is being spec‐
57 ified) or the starting time (if the ending time is being specified).
58 If the omitted field is a unit less than that of the first specified
59 field, then it defaults to zero. For example, suppose that the input
60 file has a first time of the Unix timestamp mentioned above, i.e., 38
61 seconds and 765,400 microseconds after 8:51PM PDT, Sept. 25, 1990. To
62 specify 9:36PM PDT (exactly) on the same date we could use 21h36m. To
63 specify a range from 9:36PM PDT through 1:54AM PDT the next day we
64 could use 21h36m 26d1h54m.
65 Relative times can also be specified when using the ymdhmsu format.
67 Omitted fields then default to 0 if the unit of the field is greater
68 than that of the first specified field, and to the corresponding value
69 taken from either the first time or the starting time if the omitted
70 field's unit is less than that of the first specified field. Given a
71 first time of the Unix timestamp mentioned above, 22h +1h10m specifies
72 a range from 10:00PM PDT on that date through 11:10PM PDT, and +1h
73 +1h10m specifies a range from 38.7654 seconds after 9:51PM PDT through
74 38.7654 seconds after 11:01PM PDT. The first hour of the file could be
75 extracted using +0 +1h.
76 Note that with the ymdhmsu format there is an ambiguity between using m
78 for `month' or for `minute'. The ambiguity is resolved as follows: if
79 an m field is followed by a d field then it is interpreted as specify‐
80 ing months; otherwise it specifies minutes.
81 If more than one input file is specified then tcpslice merges the pack‐
83 ets from the various input files into the single output file. Nor‐
84 mally, this merge is done based on the value of the timestamps in the
85 packets in the individual files. (Tcpslice assumes that within each
86 input file, packets are in timestamp order.) If the -l option is used,
87 the value used for ordering is the timestamp of a given packet minus
88 the timestamp of the first packet in the input file in which the given
89 packet occurs.
90 When merging files, by default tcpslice will discard any duplicate
92 packet it finds in more than one file. A duplicate is a packet that
93 has an identical timestamp (either relative or absolute) and identical
94 packet contents (for as much as was captured) as another packet previ‐
95 ously seen in a different file. Note that it is possible for the net‐
96 work to generate true replicates of packets, and for systems that can
97 return the same timestamp for multiple packets, these can be mistaken
98 for duplicates and discarded. Accordingly, tcpslice will not discard
99 duplicates in the same trace file. In addition, you can use the -D
100 option to suppress any discarding of duplicates.
101 A different issue arises if a file contains timestamps that skip back‐
103 wards. tcpslice will include these in the output, even if they precede
104 the minimum time requested. There should probably be an option to sup‐
105 press these.
106 Another problem relating to backwards timestamps is that tcpslice uses
108 random access to seek through a file looking for packets corresponding
109 to the desired range of time. While doing so leads to a major perfor‐
110 mance benefit for very large trace files, it also means that in the
111 presence of backwards timestamps tcpslice can fail to find the true
112 earliest occurrence of a packet matching the time interval criteria.
113 There should probably be an option to specify not to use random access
114 but just read the file linearly.
115
117 If any of -R, -r or -t are specified then tcpslice reports the time‐
118 stamps of the first and last packets in each input file and exits.
119 Only one of these three options may be specified.
120 -D Do not discard duplicate packets seen when merging multiple
122 trace files.
123 -d Dump the start and end times specified by the given range and
125 exit. This option is useful for checking that the given range
126 actually specifies the times you think it does. If one of -R,
127 -r or -t has been specified then the times are dumped in the
128 corresponding format; otherwise, raw format ( -R) is used.
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 timestamps. 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 timestamp
135 of the packet itself. The timestamp of packets in the output
136 file is calculated as the relative time for the packet within
137 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 -t Same as -R except the timestamps are dumped in tcpslice format,
146 i.e., in the ymdhmsu format discussed above.
147 -w Direct the output to file rather than stdout.
149
151 tcpdump(l)
152
154 Vern Paxson, of Lawrence Berkeley Laboratory, University of California,
155 Berkeley, CA.
156 The current version is available via anonymous ftp:
158 ftp://ftp.ee.lbl.gov/tcpslice.tar.Z
160
162 Please send bug reports to tcpslice@ee.lbl.gov.
163 An input filename that beings with a digit or a `+' can be confused
165 with a start/end time. Such filenames can be specified with a leading
166 `./'; for example, specify the file `04Jul76.trace' as
167 `./04Jul76.trace'.
168 tcpslice cannot read its input from stdin, since it uses random-access
170 to rummage through its input files.
171 tcpslice refuses to write to its output if it is a terminal (as indi‐
173 cated by isatty(3)). This is not a bug but a feature, to prevent it
174 from spraying binary data to the user's terminal. Note that this means
175 you must either redirect stdout or specify an output file via -w.
176 tcpslice will not work properly on tcpdump files spanning more than one
178 year; with files containing portions of packets whose original length
179 was more than 65,535 bytes; nor with files containing fewer than two
180 packets. Such files result in the error message: `couldn't find final
181 packet in file'. These problems are due to the interpolation scheme
182 used by tcpslice to greatly speed up its processing when dealing with
183 large trace files. Note that tcpslice can efficiently extract slices
184 from the middle of trace files of any size, and can also work with
185 truncated trace files (i.e., the final packet in the file is only par‐
186 tially present, typically due to tcpdump being ungracefully killed).
187 Adding -l has broken some compatibility with older versions, since tcp‐
189 slice now merges its input files, rather than (approximately) concate‐
190 nating them together as it did previously.
191 It would sometimes be convenient if you could specify a clock offset to
193 use with the -l option.
194 It would be nice if tcpslice supported more general editing of trace
196 files.
197 24 February 2000 TCPSLICE(8)