2
6 flow-report — Generate reports from flow data.
7
9 flow-report [-h] [-d debug_level] [-s stat_fname] [-S stat_defini‐
10 tion] [-v variable binding]
11
13 The flow-report utility will generate reports from flow data. The
14 reports are easy to parse ASCII text that can be used by a front end to
15 produce readable reports, graphs, and charts.
16 Reports are definied in a configuration file by the 'stat-report' key‐
18 word followed by a report name. Each report has a type defined below
19 and other commands. Reports are grouped into a definition with the
20 'stat-definition' keyword followed by a definition name. Each defini‐
21 tion can invoke a filter and optionally apply tags.
22 Words in the configuration file of the form @VAR or @{VAR:default} will
24 be expanded at run-time by setting variable names with the -v option.
25 Generated reports consist of comment lines and report lines. Comment
27 lines begin with a # and include details such as the options used,
28 report name, records in the report, and the report line format. Some
29 of the more verbose comments can be controlled with the +header and
30 +xheader options. By default this information is not displayed. A
31 column title beginning with the string rec precedes the report lines.
32 Report lines consist of key fields, such as an IP address and calcu‐
33 lated totals for that key such as the number of flows.
34 The summary-detail report is a little bit different from other reports
36 in that it has multiple title lines and no key fields.
37 The column titles are described below.
39 +time_real Difference between the real time of the first and last
42 flow.
43 +aflowtime Total time of the flows / Total number of flows.
44 +aps Total Octets / Total Packets (Average Packet Size)
45 +afs Total Octets / Total Flows / (Average Flow Size)
46 +apf Total Packets / Total Flows (Average Packets / Flow)
47 +fps Total Flows / (Last End Time of Flow -
48 First Start Time of Flow) (Average Flows / Second)
49 +fps_real (Average Flows / Second in realtime)
50 +psizeN Average Packet Size buckets.
51 +fpsizeN Packets / Flow buckets.
52 +fosizeN Octets / Flow buckets.
53 +ftimeN Time / Flow buckets.
54 ignores Flows with a packet count of 0.
56 SSS-count Count of of an item, example source-ip-address-count
58 SSS* key fields, example source-ip-address
60 index Report line index.
61 first Time of first flow in unix_secs format.
62 last Time of last flow in unix_secs format.
63 flows Summation of flows/key.
65 octets Summation of octets/key.
66 packets Summation of packets/key.
67 duration End time of Flow - Start time of Flow.
68 avg-bps Average Bits/Second.
69 min-bps Minimum Bits/Second.
70 max-bps Maximum Bits/Second.
71 avg-pps Average Packets/Second.
72 min-pps Minimum Packets/Second.
73 max-pps Maximum Packets/Second.
74 frecs Records used in average calculations.
75 Note fields with a + are only available in the summary-detail report.
77 The PPS and BPS calculations will not always be correct due to flows
79 which only have one packet, or some other condition where the start
80 time is equal to the end time. In this case these flows are not used
81 in the PPS and BPS calculations. To facilitate aggregating multiple
82 reports and retaining the PPS and BPS fields, the number of flows
83 counted is available in the frecs field.
84 stat-report command Description/Example
88 ------------------------------------------------------------------------
89 type Define the report type.
90 type destination-tag
91 filter Apply this filter definition.
93 filter permit-only-tcp
94 scale Scale report by n.
97 scale 100
98 tag-mask Apply source and destination mask to tag.
101 tag-mask 0xFF00 0xFF00
102 ip-source-address-format Format of source IP address.
104 address - address, ie 128.146.1.7
105 prefix-len - address/len ie 128.146.1.7/24
106 prefix-mask- prefix/len 128.146.1/24
107 ip-destination-address-format
109 Format of destination IP address.
110 address - address, ie 128.146.1.7
111 prefix-len - address/len ie 128.146.1.7/24
112 prefix-mask- prefix/len 128.146.1/24
113 output Start an output configuration. Multiple
115 output configurations can be configured
116 per report.
117 output option Description/Example
119 -------------------------------------------------------------------------
120 path Pathname of output. If the path begins
122 with a | the output is a pipe. The
123 pathname is formatted through strftime().
124 Directories not in the path are
125 automatically created.
126 path /tmp/%Y/%m/%d/foo.out
127 time What time to use when formatting the
129 pathname with strftime.
130 now - current time
131 start - first flow
132 end - last flow
133 mid - average of first and last.
134 tally Emit a % total line every n records.
137 tally 10
138 format Output format. Currently only ascii.
140 format ascii
141 sort Sort on a field. + ascending, - descending.
143 sort +flows - sort on the flows field
144 Sortable fields are flows,octets,packets,
146 duration,avg-pps,min-pps,max-pps,avg-bps,
147 min-bps,max-bps
148 records Truncate report at n records.
151 records 10
152 fields Enable/Disable fields with +/-. Fields:
154 index,first,last,flows,octets,packets,
155 duration,pps,bps,other,key,key1,key2,
156 key3,key4,count.
157 fields +key,+flows,+octets,+packets,
158 For reports with one key, the key
160 field is referenced with key, else
161 key1,key2,key3,etc
162 Note that the count field is only available
164 in select reports, those which end in
165 -count.
166 options Enable/Disable options with +/-
169 +header - include header.
170 +xheader - include extra header.
171 +totals - include a totals line.
172 +percent-total - report in % total form.
173 +names - use symbolic names.
174 options +header,+xheader
175 stat-definition option Description/Example
177 -------------------------------------------------------------------------
178 filter Apply this filter definition.
179 filter default
180 tag Apply this tag definition.
182 tag default
183 mask Apply this mask definition.
185 mask default
186 report Invoke this report. Multiple reports can
188 be set.
189 report foo
190 time-series How often to produce a report in seconds.
192 time-series 60
193 global options Description/Example
195 -------------------------------------------------------------------------
196 include-tag Specify path to include tag definitions.
197 include-tag /flows/tags/test1
198 include-filter Specify path to include filter definitions.
200 include-filter /flows/filters/test1
201 include-mask Specify path to include mask definitions.
203 include-filter /flows/masks/test1
204 Report type Summarization Key Elements.
207 ------------------------------------------------------------------------
208 summary-detail Totals plus quick breakdown.
209 summary-counters Totals only.
211 packet-size Average packet size distribution.
213 octets Octets per flow distribution.
215 packets Packets per flow distribution.
217 ip-source-port IP Source Port.
219 ip-destination-port IP Destination Port.
221 ip-source/destination-port IP Source/Destination Port pair.
223 bps Bits/Second distribution.
225 pps Packets/Second distribution.
227 ip-destination-address-type
229 IP class with ASM/SSM Multicast breakout.
230 ip-protocol IP Protocol.
232 ip-tos IP Type of Service.
234 ip-next-hop-address IP Next Hop Address.
236 ip-source-address IP Source Address.
238 ip-destination-address IP Destination Address.
240 ip-source/destination-address
242 IP Source/Destination Address pair.
243 ip-exporter-address IP Exporter Address.
245 input-interface Input Interface.
247 output-interface Output Interface.
249 input/output-interface Input/Output Interface pair.
251 source-as Source AS.
253 destination-as Destination AS.
255 source/destination-as Source/Destination AS.
257 ip-source-address/source-as IP Source Addrss and Source AS.
259 ip-destination-address/source-as
261 IP Destination Address and Source AS.
262 ip-source-address/destination-as
264 IP Source Address and Destination AS.
265 ip-destination-address/destination-as
267 IP Destination Address and Destination AS.
268 ip-source/destination-address/source-as
270 IP Source/Destination Address and Source AS.
271 ip-source/destination-address/destination-as
273 IP Source/Destination Address and
274 Destination AS.
275 ip-source/destination-address/source/destination-as
277 IP Source/Destination Address and
278 Source/Destination AS.
279 ip-source-address/input-interface
281 IP Source Address and Input Interface.
282 ip-destination-address/input-interface
284 IP Destination Address and Input Interface.
285 ip-source-address/output-interface
287 IP Source Address and Output Interface.
288 ip-destination-address/output-interface
290 IP Destination Address and Output Interface.
291 ip-source/destination-address/input-interface
293 IP Source/Destination Address and
294 Input Interface.
295 ip-source/destination-address/output-interface
297 IP Source/Destination Address and
298 Output Interface.
299 ip-source/destination-address/input/output-interface
301 IP Source/Destination Address and
302 Input/Output Interface.
303 input-interface/source-as Input Interface and Source AS.
305 input-interface/destination-as
307 Input Interface and Destination AS.
308 output-interface/source-as
310 Output Interface and Source AS.
311 output-interface/destination-as
313 Output Interface and Destination AS.
314 input-interface/source/destination-as
316 Input Interface and Source/Destination AS.
317 output-interface/source/destination-as
319 Output Interface and Source/Destination AS.
320 input/output-interface/source/destination-as
322 Input/Output Interface and
323 Source/Destination AS.
324 engine-id Engine ID.
326 engine-type Engine Type.
328 source-tag Source Tag.
330 destination-tag Destination Tag.
332 source/destination-tag Source/Destination Tag.
334 ip-source-address/ip-source-port
336 IP Source Address and IP Source Port.
337 ip-source-address/ip-destination-port
339 IP Source Address and IP Destination Port.
340 ip-destination-address/ip-source-port
342 IP Destination Address and IP Source Port.
343 ip-destination-address/ip-destination-port
345 IP Destination Address and
346 IP Destination Port.
347 ip-source-address/ip-source/destination-port
349 IP Source Address and
350 IP Source/Destination Port.
351 ip-destination-address/ip-source/destination-port
353 IP Destination Address and
354 IP Source/Destination Port.
355 ip-source/destination-address/ip-source-port
357 IP Source/Destination Address and
358 IP Source Port.
359 ip-source/destination-address/ip-destination-port
361 IP Source/Destination Address and
362 IP Destination Port.
363 ip-source/destination-address/ip-source/destination-port
365 IP Source/Destination Address and
366 IP Source/Destination Port.
367 ip-source-address/input/output-interface
369 IP Source Address and
370 Input/Output Interface.
371 ip-destination-address/input/output-interface
373 IP Destination Address and
374 Input/Output Interface.
375 ip-source-address/source/destination-as
377 IP Source Address and
378 Source/Destination AS.
379 ip-destination-address/source/destination-as
381 IP Destination Address and
382 Source/Destination AS.
383 ip-address IP Address (both source and destination).
385 ip-port IP Port (both source and destination).
387 ip-source-address-destination-count
389 Count of destination IP addresses associated
390 with a source IP address.
391 ip-destination-address-source-count
393 Count of source IP addresses associated
394 with a destination IP address.
395 linear-interpolated-flows-octets-packets
397 Linear interpolated distribution of flows,
398 octets and packets. The distribution is
399 done across the start and end time of the
400 flow.
401 first First packet of flow distribution.
403 last Last packet of flow distribution.
405 duration Duration of flow distribution.
407 ip-source-address/source-tag
409 IP Source Address and
410 Source tag.
411 ip-source-address/destination-tag
413 IP Source Address and
414 Destination tag.
415 ip-destination-address/source-tag
417 IP Destination Address and
418 Source tag.
419 ip-destination-address/destination-tag
421 IP Destination Address and
422 Destination tag.
423 ip-source/destination-address/source/destination-tag
425 IP Source/Destination Address and
426 Source/Destination tag.
427 ip-source/destination-address/ip-protocol/ip-tos
429 IP Source/Destination Address, IP Protocol,
430 and ToS.
431 ip-source/destination-address/ip-protocol/ip-tos/ip-source/destination-port
433 IP Source/Destination Addess, IP Protocol,
434 IP Tos, IP Source/Destination Port.
435
437 -d debug_level
438 Enable debugging.
439 -s stat_fname
441 Report configuration filename. Defaults to /var/flow-
442 tools/cfg/stat.
443 -S stat_definition
445 Select the active definition.
446 -v variable binding
448 Set a variable FOO=bar.
449 -h Display help. -hh will list the available reports.
451
453 An example of report configuration file
454 # stat config file
456 include-filter /tmp/filter
458 stat-report t1
460 type summary-detail
461 filter default
462 scale 100
463 output
464 format ascii
465 options +header,+xheader,+totals
466 fields +other
467 path /tmp/output1
468 stat-report t6
470 type ip-source-port
471 output
472 format ascii
473 options +header,+xheader,+totals,+names,+percent-total
474 sort +pps
475 tally 5
476 path /tmp/output6
477 stat-definition test
479 filter tcp
480 report t1
481 report t6
482 # filter config file
484 filter-primitive TCP
486 type ip-protocol
487 permit TCP
488 filter-definition tcp
490 match ip-protocol TCP
491 flow-cat flows | flow-report -stest -Stest
493
495 Packet size calculations are dOctets / dPkts, ie an average packet
496 size. It is not possible to get a true packet size from flow exports.
497 pps and bps calculations are an average of the averages.
499 Flows that do not have a duration (start == end) are not counted in the
501 pps and bps calculations.
502 Flows without a packet or octet count are ignored.
504
506 Configuration files:
507 Symbols - /var/flow-tools/sym/*.
508 Tag - /var/flow-tools/cfg/tag.cfg.
509 Filter - /var/flow-tools/cfg/filter.cfg.
510 Mask - /var/flow-tools/cfg/mask.cfg.
511 Report - /var/flow-tools/cfg/stat.cfg.
512 Xlate - /var/flow-tools/cfg/xlate.cfg.
513
515 None known.
516
518 Mark Fullmer maf@splintered.net
519
521 flow-tools(1)
522 flow-report(1)