1FLOW-REPORT(1) FLOW-REPORT(1)
2
6 flow-report - Generate reports from flow data.
7
9 flow-report [ -h ] [ -d debug_level ] [ -s stat_fname ] [ -S
10 stat_definition ] [ -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 of
29 the more verbose comments can be controlled with the +header and
30 +xheader options. By default this information is not displayed. A col‐
31 umn 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. The summary-
34 detail report is a little bit different from other reports in that it
35 has multiple title lines and no key fields. The column titles are
36 described below.
37 +time_real Difference between the real time of the first and last
39 flow.
40 +aflowtime Total time of the flows / Total number of flows.
41 +aps Total Octets / Total Packets (Average Packet Size)
42 +afs Total Octets / Total Flows / (Average Flow Size)
43 +apf Total Packets / Total Flows (Average Packets / Flow)
44 +fps Total Flows / (Last End Time of Flow -
45 First Start Time of Flow) (Average Flows / Second)
46 +fps_real (Average Flows / Second in realtime)
47 +psizeN Average Packet Size buckets.
48 +fpsizeN Packets / Flow buckets.
49 +fosizeN Octets / Flow buckets.
50 +ftimeN Time / Flow buckets.
51 ignores Flows with a packet count of 0.
53 SSS-count Count of of an item, example source-ip-address-count
55 SSS* key fields, example source-ip-address
57 index Report line index.
58 first Time of first flow in unix_secs format.
59 last Time of last flow in unix_secs format.
60 flows Summation of flows/key.
62 octets Summation of octets/key.
63 packets Summation of packets/key.
64 duration End time of Flow - Start time of Flow.
65 avg-bps Average Bits/Second.
66 min-bps Minimum Bits/Second.
67 max-bps Maximum Bits/Second.
68 avg-pps Average Packets/Second.
69 min-pps Minimum Packets/Second.
70 max-pps Maximum Packets/Second.
71 frecs Records used in average calculations.
72 Note fields with a + are only available in the summary-detail report.
74 The PPS and BPS calculations will not always be correct due to flows
76 which only have one packet, or some other condition where the start
77 time is equal to the end time. In this case these flows are not used in
78 the PPS and BPS calculations. To facilitate aggregating multiple
79 reports and retaining the PPS and BPS fields, the number of flows
80 counted is available in the frecs field.
81 stat-report command Description/Example
83 ------------------------------------------------------------------------
84 type Define the report type.
85 type destination-tag
86 filter Apply this filter definition.
88 filter permit-only-tcp
89 scale Scale report by n.
92 scale 100
93 tag-mask Apply source and destination mask to tag.
96 tag-mask 0xFF00 0xFF00
97 ip-source-address-format Format of source IP address.
99 address - address, ie 128.146.1.7
100 prefix-len - address/len ie 128.146.1.7/24
101 prefix-mask- prefix/len 128.146.1/24
102 ip-destination-address-format
104 Format of destination IP address.
105 address - address, ie 128.146.1.7
106 prefix-len - address/len ie 128.146.1.7/24
107 prefix-mask- prefix/len 128.146.1/24
108 output Start an output configuration. Multiple
110 output configurations can be configured
111 per report.
112 output option Description/Example
115 -------------------------------------------------------------------------
116 path Pathname of output. If the path begins
118 with a | the output is a pipe. The
119 pathname is formatted through strftime().
120 Directories not in the path are
121 automatically created.
122 path /tmp/%Y/%m/%d/foo.out
123 time What time to use when formatting the
125 pathname with strftime.
126 now - current time
127 start - first flow
128 end - last flow
129 mid - average of first and last.
130 tally Emit a % total line every n records.
133 tally 10
134 format Output format. Currently only ascii.
136 format ascii
137 sort Sort on a field. + ascending, - descending.
139 sort +flows - sort on the flows field
140 Sortable fields are flows,octets,packets,
142 duration,avg-pps,min-pps,max-pps,avg-bps,
143 min-bps,max-bps
144 records Truncate report at n records.
147 records 10
148 fields Enable/Disable fields with +/-. Fields:
150 index,first,last,flows,octets,packets,
151 duration,pps,bps,other,key,key1,key2,
152 key3,key4,count.
153 fields +key,+flows,+octets,+packets,
154 For reports with one key, the key
156 field is referenced with key, else
157 key1,key2,key3,etc
158 Note that the count field is only available
160 in select reports, those which end in
161 -count.
162 options Enable/Disable options with +/-
165 +header - include header.
166 +xheader - include extra header.
167 +totals - include a totals line.
168 +percent-total - report in % total form.
169 +names - use symbolic names.
170 options +header,+xheader
171 stat-definition option Description/Example
174 -------------------------------------------------------------------------
175 filter Apply this filter definition.
176 filter default
177 tag Apply this tag definition.
179 tag default
180 mask Apply this mask definition.
182 mask default
183 report Invoke this report. Multiple reports can
185 be set.
186 report foo
187 time-series How often to produce a report in seconds.
189 time-series 60
190 global options Description/Example
193 -------------------------------------------------------------------------
194 include-tag Specify path to include tag definitions.
195 include-tag /flows/tags/test1
196 include-filter Specify path to include filter definitions.
198 include-filter /flows/filters/test1
199 include-mask Specify path to include mask definitions.
201 include-filter /flows/masks/test1
202 Report type Summarization Key Elements.
206 ------------------------------------------------------------------------
207 summary-detail Totals plus quick breakdown.
208 summary-counters Totals only.
210 packet-size Average packet size distribution.
212 octets Octets per flow distribution.
214 packets Packets per flow distribution.
216 ip-source-port IP Source Port.
218 ip-destination-port IP Destination Port.
220 ip-source/destination-port IP Source/Destination Port pair.
222 bps Bits/Second distribution.
224 pps Packets/Second distribution.
226 ip-destination-address-type
228 IP class with ASM/SSM Multicast breakout.
229 ip-protocol IP Protocol.
231 ip-tos IP Type of Service.
233 ip-next-hop-address IP Next Hop Address.
235 ip-source-address IP Source Address.
237 ip-destination-address IP Destination Address.
239 ip-source/destination-address
241 IP Source/Destination Address pair.
242 ip-exporter-address IP Exporter Address.
244 input-interface Input Interface.
246 output-interface Output Interface.
248 input/output-interface Input/Output Interface pair.
250 source-as Source AS.
252 destination-as Destination AS.
254 source/destination-as Source/Destination AS.
256 ip-source-address/source-as IP Source Addrss and Source AS.
258 ip-destination-address/source-as
260 IP Destination Address and Source AS.
261 ip-source-address/destination-as
263 IP Source Address and Destination AS.
264 ip-destination-address/destination-as
266 IP Destination Address and Destination AS.
267 ip-source/destination-address/source-as
269 IP Source/Destination Address and Source AS.
270 ip-source/destination-address/destination-as
272 IP Source/Destination Address and
273 Destination AS.
274 ip-source/destination-address/source/destination-as
276 IP Source/Destination Address and
277 Source/Destination AS.
278 ip-source-address/input-interface
280 IP Source Address and Input Interface.
281 ip-destination-address/input-interface
283 IP Destination Address and Input Interface.
284 ip-source-address/output-interface
286 IP Source Address and Output Interface.
287 ip-destination-address/output-interface
289 IP Destination Address and Output Interface.
290 ip-source/destination-address/input-interface
292 IP Source/Destination Address and
293 Input Interface.
294 ip-source/destination-address/output-interface
296 IP Source/Destination Address and
297 Output Interface.
298 ip-source/destination-address/input/output-interface
300 IP Source/Destination Address and
301 Input/Output Interface.
302 input-interface/source-as Input Interface and Source AS.
304 input-interface/destination-as
306 Input Interface and Destination AS.
307 output-interface/source-as
309 Output Interface and Source AS.
310 output-interface/destination-as
312 Output Interface and Destination AS.
313 input-interface/source/destination-as
315 Input Interface and Source/Destination AS.
316 output-interface/source/destination-as
318 Output Interface and Source/Destination AS.
319 input/output-interface/source/destination-as
321 Input/Output Interface and
322 Source/Destination AS.
323 engine-id Engine ID.
325 engine-type Engine Type.
327 source-tag Source Tag.
329 destination-tag Destination Tag.
331 source/destination-tag Source/Destination Tag.
333 ip-source-address/ip-source-port
335 IP Source Address and IP Source Port.
336 ip-source-address/ip-destination-port
338 IP Source Address and IP Destination Port.
339 ip-destination-address/ip-source-port
341 IP Destination Address and IP Source Port.
342 ip-destination-address/ip-destination-port
344 IP Destination Address and
345 IP Destination Port.
346 ip-source-address/ip-source/destination-port
348 IP Source Address and
349 IP Source/Destination Port.
350 ip-destination-address/ip-source/destination-port
352 IP Destination Address and
353 IP Source/Destination Port.
354 ip-source/destination-address/ip-source-port
356 IP Source/Destination Address and
357 IP Source Port.
358 ip-source/destination-address/ip-destination-port
360 IP Source/Destination Address and
361 IP Destination Port.
362 ip-source/destination-address/ip-source/destination-port
364 IP Source/Destination Address and
365 IP Source/Destination Port.
366 ip-source-address/input/output-interface
368 IP Source Address and
369 Input/Output Interface.
370 ip-destination-address/input/output-interface
372 IP Destination Address and
373 Input/Output Interface.
374 ip-source-address/source/destination-as
376 IP Source Address and
377 Source/Destination AS.
378 ip-destination-address/source/destination-as
380 IP Destination Address and
381 Source/Destination AS.
382 ip-address IP Address (both source and destination).
384 ip-port IP Port (both source and destination).
386 ip-source-address-destination-count
388 Count of destination IP addresses associated
389 with a source IP address.
390 ip-destination-address-source-count
392 Count of source IP addresses associated
393 with a destination IP address.
394 linear-interpolated-flows-octets-packets
396 Linear interpolated distribution of flows,
397 octets and packets. The distribution is
398 done across the start and end time of the
399 flow.
400 first First packet of flow distribution.
402 last Last packet of flow distribution.
404 duration Duration of flow distribution.
406 ip-source-address/source-tag
408 IP Source Address and
409 Source tag.
410 ip-source-address/destination-tag
412 IP Source Address and
413 Destination tag.
414 ip-destination-address/source-tag
416 IP Destination Address and
417 Source tag.
418 ip-destination-address/destination-tag
420 IP Destination Address and
421 Destination tag.
422 ip-source/destination-address/source/destination-tag
424 IP Source/Destination Address and
425 Source/Destination tag.
426 ip-source/destination-address/ip-protocol/ip-tos
428 IP Source/Destination Address, IP Protocol,
429 and ToS.
430 ip-source/destination-address/ip-protocol/ip-tos/ip-source/destination-port
432 IP Source/Destination Addess, IP Protocol,
433 IP Tos, IP Source/Destination Port.
434
437 -d debug_level
438 Enable debugging.
439 -s stat_fname
441 Report configuration filename. Defaults to /etc/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
485 filter-primitive TCP
487 type ip-protocol
488 permit TCP
489 filter-definition tcp
491 match ip-protocol TCP
492 flow-cat flows | flow-report -stest -Stest
494
496 Packet size calculations are dOctets / dPkts, ie an average packet
497 size. It is not possible to get a true packet size from flow exports.
498 pps and bps calculations are an average of the averages. Flows that do
499 not have a duration (start == end) are not counted in the pps and bps
500 calculations. Flows without a packet or octet count are ignored.
501
503 Configuration files: Symbols - /etc/flow-tools/sym/*. Tag - /etc/flow-
504 tools/cfg/tag.cfg. Filter - /etc/flow-tools/cfg/filter.cfg. Mask -
505 /etc/flow-tools/cfg/mask.cfg. Report - /etc/flow-tools/cfg/stat.cfg.
506 Xlate - /etc/flow-tools/cfg/xlate.cfg.
507
509 None known.
510
512 Mark Fullmer <maf@splintered.net>
513
515 flow-tools(1)
516 26 Август 2010 FLOW-REPORT(1)