1tcpflow(1) tcpflow 1.0.4 tcpflow(1)
2
6 tcpflow - TCP flow recorder
7
9 tcpflow [-cCehpsv] [-b max_bytes] [-d debug_level] [-f max_fds]
10 [-i iface] [-r file] [expression]
11
13 tcpflow is a program that captures data transmitted as part of TCP con‐
14 nections (flows), and stores the data in a way that is convenient for
15 protocol analysis or debugging. A program like tcpdump(4) shows a sum‐
16 mary of packets seen on the wire, but usually doesn't store the data
17 that's actually being transmitted. In contrast, tcpflow reconstructs
18 the actual data streams and stores each flow in a separate file for
19 later analysis. tcpflow understands TCP sequence numbers and will cor‐
20 rectly reconstruct data streams regardless of retransmissions or out-
21 of-order delivery.
22 tcpflow stores all captured data in files that have names of the form
24 192.168.101.102.02345-010.011.012.013.45103
25 where the contents of the above file would be data transmitted from
26 host 192.168.101.102 port 2345, to host 10.11.12.13 port 45103.
27
29 -b Max bytes per flow. Capture no more than max_bytes bytes per
30 flow. Any data captured for a flow beyond max_bytes from the
31 first byte captured will be discarded. The default is to store
32 an unlimited number of bytes per flow.
33 -c Console print. Print the contents of packets to stdout as they
35 are received, without storing any captured data to files
36 (implies
37 -C Console print without the packet source and destination details
39 being printed. Print the contents of packets to stdout as they
40 are received, without storing any captured data to files
41 (implies -e When outputting to the console each flow will be
42 output in different colors (blue for client to server flows, red
43 for server to client flows, green for undecided flows). -s ).
44 -d Debug level. Set the level of debugging messages printed to
46 stderr to debug_level. Higher numbers produce more messages.
47 -d 0 causes completely silent operation. -d 1 , the default,
48 produces minimal status messages. -d 10 produces verbose output
49 equivalent to -v . Numbers higher than 10 can produce a large
50 amount of debugging information useful only to developers.
51 -f Max file descriptors used. Limit the number of file descriptors
53 used by tcpflow to max_fds. Higher numbers use more system
54 resources, but usually perform better. If the underlying oper‐
55 ating system supports the setrlimit() system call, the OS will
56 be asked to enforce the requested limit. The default is for
57 tcpflow to use the maximum number of file descriptors allowed by
58 the OS. The -v option will report how many file descriptors
59 tcpflow is using.
60 -h Help. Print usage information and exit.
62 -i Interface name. Capture packets from the network interface
64 named iface. If no interface is specified with -i , a reason‐
65 able default will be used by libpcap automatically.
66 -p No promiscuous mode. Normally, tcpflow attempts to put the net‐
68 work interface into promiscuous mode before capturing packets.
69 The -p option tells tcpflow not to put the interface into pro‐
70 miscuous mode. Note that it might already be in promiscuous
71 mode for some other reason.
72 -r Read from file. Read packets from file, which was created using
74 the -w option of tcpdump(1). Standard input is used if file is
75 ``-''. Note that for this option to be useful, tcpdump's -s
76 option should be used to set the snaplen to the MTU of the
77 interface (e.g., 1500) while capturing packets.
78 -s Strip non-printables. Convert all non-printable characters to
80 the "." character before printing packets to the console or
81 storing them to a file.
82 -v Verbose operation. Verbosely describe tcpflow's operation.
84 Equivalent to -d 10 .
85
87 The expression specified on the command-line specifies which packets
88 should be captured. Because tcpflow uses the the libpcap library,
89 tcpflow has the same powerful filtering language available as programs
90 such as tcpdump(1).
91 The following part of the man page is excerpted from the tcpdump man
93 page.
94 expression selects which packets will be dumped. If no expression is
96 given, all packets on the net will be dumped. Otherwise, only packets
97 for which expression is `true' will be dumped.
98 The expression consists of one or more primitives. Primitives usually
100 consist of an id (name or number) preceded by one or more qualifiers.
101 There are three different kinds of qualifier:
102 type qualifiers say what kind of thing the id name or number refers
104 to. Possible types are host, net and port. E.g., `host foo',
105 `net 128.3', `port 20'. If there is no type qualifier, host is
106 assumed.
107 dir qualifiers specify a particular transfer direction to and/or
109 from id. Possible directions are src, dst, src or dst and src
110 and dst. E.g., `src foo', `dst net 128.3', `src or dst port
111 ftp-data'. If there is no dir qualifier, src or dst is assumed.
112 For `null' link layers (i.e. point to point protocols such as
113 slip) the inbound and outbound qualifiers can be used to specify
114 a desired direction.
115 proto qualifiers restrict the match to a particular protocol. Possi‐
117 ble protos are: ether, fddi, ip, arp, rarp, decnet, lat, sca,
118 moprc, mopdl, tcp and udp. E.g., `ether src foo', `arp net
119 128.3', `tcp port 21'. If there is no proto qualifier, all pro‐
120 tocols consistent with the type are assumed. E.g., `src foo'
121 means `(ip or arp or rarp) src foo' (except the latter is not
122 legal syntax), `net bar' means `(ip or arp or rarp) net bar' and
123 `port 53' means `(tcp or udp) port 53'.
124 [`fddi' is actually an alias for `ether'; the parser treats them iden‐
126 tically as meaning ``the data link level used on the specified network
127 interface.'' FDDI headers contain Ethernet-like source and destination
128 addresses, and often contain Ethernet-like packet types, so you can
129 filter on these FDDI fields just as with the analogous Ethernet fields.
130 FDDI headers also contain other fields, but you cannot name them
131 explicitly in a filter expression.]
132 In addition to the above, there are some special `primitive' keywords
134 that don't follow the pattern: gateway, broadcast, less, greater and
135 arithmetic expressions. All of these are described below.
136 More complex filter expressions are built up by using the words and, or
138 and not to combine primitives. E.g., `host foo and not port ftp and
139 not port ftp-data'. To save typing, identical qualifier lists can be
140 omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly the
141 same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port
142 domain'.
143 Allowable primitives are:
145 dst host host
147 True if the IP destination field of the packet is host, which
148 may be either an address or a name.
149 src host host
151 True if the IP source field of the packet is host.
152 host host
154 True if either the IP source or destination of the packet is
155 host. Any of the above host expressions can be prepended with
156 the keywords, ip, arp, or rarp as in:
157 ip host host
158 which is equivalent to:
159 ether proto \ip and host host
160 If host is a name with multiple IP addresses, each address will
161 be checked for a match.
162 ether dst ehost
164 True if the ethernet destination address is ehost. Ehost may be
165 either a name from /etc/ethers or a number (see ethers(3N) for
166 numeric format).
167 ether src ehost
169 True if the ethernet source address is ehost.
170 ether host ehost
172 True if either the ethernet source or destination address is
173 ehost.
174 gateway host
176 True if the packet used host as a gateway. I.e., the ethernet
177 source or destination address was host but neither the IP source
178 nor the IP destination was host. Host must be a name and must
179 be found in both /etc/hosts and /etc/ethers. (An equivalent
180 expression is
181 ether host ehost and not host host
182 which can be used with either names or numbers for host /
183 ehost.)
184 dst net net
186 True if the IP destination address of the packet has a network
187 number of net. Net may be either a name from /etc/networks or a
188 network number (see networks(5) for details).
189 src net net
191 True if the IP source address of the packet has a network number
192 of net.
193 net net
195 True if either the IP source or destination address of the
196 packet has a network number of net.
197 net net mask mask
199 True if the IP address matches net with the specific netmask.
200 May be qualified with src or dst.
201 net net/len
203 True if the IP address matches net a netmask len bits wide. May
204 be qualified with src or dst.
205 dst port port
207 True if the packet is ip/tcp or ip/udp and has a destination
208 port value of port. The port can be a number or a name used in
209 /etc/services (see tcp(4P) and udp(4P)). If a name is used,
210 both the port number and protocol are checked. If a number or
211 ambiguous name is used, only the port number is checked (e.g.,
212 dst port 513 will print both tcp/login traffic and udp/who traf‐
213 fic, and port domain will print both tcp/domain and udp/domain
214 traffic).
215 src port port
217 True if the packet has a source port value of port.
218 port port
220 True if either the source or destination port of the packet is
221 port. Any of the above port expressions can be prepended with
222 the keywords, tcp or udp, as in:
223 tcp src port port
224 which matches only tcp packets whose source port is port.
225 less length
227 True if the packet has a length less than or equal to length.
228 This is equivalent to:
229 len <= length.
230 greater length
232 True if the packet has a length greater than or equal to length.
233 This is equivalent to:
234 len >= length.
235 ip proto protocol
237 True if the packet is an ip packet (see ip(4P)) of protocol type
238 protocol. Protocol can be a number or one of the names icmp,
239 igrp, udp, nd, or tcp. Note that the identifiers tcp, udp, and
240 icmp are also keywords and must be escaped via backslash (\),
241 which is \\ in the C-shell.
242 ether broadcast
244 True if the packet is an ethernet broadcast packet. The ether
245 keyword is optional.
246 ip broadcast
248 True if the packet is an IP broadcast packet. It checks for
249 both the all-zeroes and all-ones broadcast conventions, and
250 looks up the local subnet mask.
251 ether multicast
253 True if the packet is an ethernet multicast packet. The ether
254 keyword is optional. This is shorthand for `ether[0] & 1 != 0'.
255 ip multicast
257 True if the packet is an IP multicast packet.
258 ether proto protocol
260 True if the packet is of ether type protocol. Protocol can be a
261 number or a name like ip, arp, or rarp. Note these identifiers
262 are also keywords and must be escaped via backslash (\). [In
263 the case of FDDI (e.g., `fddi protocol arp'), the protocol iden‐
264 tification comes from the 802.2 Logical Link Control (LLC)
265 header, which is usually layered on top of the FDDI header.
266 Tcpdump assumes, when filtering on the protocol identifier, that
267 all FDDI packets include an LLC header, and that the LLC header
268 is in so-called SNAP format.]
269 decnet src host
271 True if the DECNET source address is host, which may be an
272 address of the form ``10.123'', or a DECNET host name. [DECNET
273 host name support is only available on Ultrix systems that are
274 configured to run DECNET.]
275 decnet dst host
277 True if the DECNET destination address is host.
278 decnet host host
280 True if either the DECNET source or destination address is host.
281 ip, arp, rarp, decnet
283 Abbreviations for:
284 ether proto p
285 where p is one of the above protocols.
286 lat, moprc, mopdl
288 Abbreviations for:
289 ether proto p
290 where p is one of the above protocols. Note that tcpdump does
291 not currently know how to parse these protocols.
292 tcp, udp, icmp
294 Abbreviations for:
295 ip proto p
296 where p is one of the above protocols.
297 expr relop expr
299 True if the relation holds, where relop is one of >, <, >=, <=,
300 =, !=, and expr is an arithmetic expression composed of integer
301 constants (expressed in standard C syntax), the normal binary
302 operators [+, -, *, /, &, |], a length operator, and special
303 packet data accessors. To access data inside the packet, use
304 the following syntax:
305 proto [ expr : size ]
306 Proto is one of ether, fddi, ip, arp, rarp, tcp, udp, or icmp,
307 and indicates the protocol layer for the index operation. The
308 byte offset, relative to the indicated protocol layer, is given
309 by expr. Size is optional and indicates the number of bytes in
310 the field of interest; it can be either one, two, or four, and
311 defaults to one. The length operator, indicated by the keyword
312 len, gives the length of the packet.
313 For example, `ether[0] & 1 != 0' catches all multicast traffic.
315 The expression `ip[0] & 0xf != 5' catches all IP packets with
316 options. The expression `ip[6:2] & 0x1fff = 0' catches only
317 unfragmented datagrams and frag zero of fragmented datagrams.
318 This check is implicitly applied to the tcp and udp index opera‐
319 tions. For instance, tcp[0] always means the first byte of the
320 TCP header, and never means the first byte of an intervening
321 fragment.
322 Primitives may be combined using:
324 A parenthesized group of primitives and operators (parentheses
326 are special to the Shell and must be escaped).
327 Negation (`!' or `not').
329 Concatenation (`&&' or `and').
331 Alternation (`||' or `or').
333 Negation has highest precedence. Alternation and concatenation have
335 equal precedence and associate left to right. Note that explicit and
336 tokens, not juxtaposition, are now required for concatenation.
337 If an identifier is given without a keyword, the most recent keyword is
339 assumed. For example,
340 not host vs and ace
341 is short for
342 not host vs and host ace
343 which should not be confused with
344 not ( host vs or ace )
345 Expression arguments can be passed to tcpdump as either a single argu‐
347 ment or as multiple arguments, whichever is more convenient. Gener‐
348 ally, if the expression contains Shell metacharacters, it is easier to
349 pass it as a single, quoted argument. Multiple arguments are concate‐
350 nated with spaces before being parsed.
351
353 The following part of the man page is excerpted from the tcpdump man
354 page.
355 To record all packets arriving at or departing from sundown:
357 tcpflow host sundown
358 To record traffic between helios and either hot or ace:
360 tcpflow host helios and \( hot or ace \)
361 To record traffic between ace and any host except helios:
363 tcpflow host ace and not helios
364 To record all traffic between local hosts and hosts at Berkeley:
366 tcpflow net ucb-ether
367 To record all ftp traffic through internet gateway snup: (note that the
369 expression is quoted to prevent the shell from (mis-)interpreting the
370 parentheses):
371 tcpflow 'gateway snup and (port ftp or ftp-data)'
372
374 Please send bug reports to jelson@circlemud.org.
375 tcpflow currently does not understand IP fragments. Flows containing
377 IP fragments will not be recorded correctly.
378 tcpflow never frees state associated with flows that it records, so
380 will grow large if used to capture a very large number of flows (e.g.,
381 on the order of 100,000 flows or more).
382 There appears to be a bug in the way that Linux delivers packets to
384 libpcap when using the loopback interface ("localhost"). When listen‐
385 ing to the Linux loopback interface, selective packet filtering is not
386 possible; all TCP flows on the localhost interface will be recorded.
387
389 Jeremy Elson <jelson@circlemud.org> Simson L. Garfinkel <sim‐
390 song@acm.org> (maintainer)
391 The current version of this software is available at
393 http://www.afflib.org/
394
396 tcpdump(1), nit(4P), bpf(4), pcap(3)
397tcpflow 1.0.4 20 April 1999 tcpflow(1)