1FLOW-REPORT(1)                                                  FLOW-REPORT(1)
2
3
4

NAME

6       flow-report - Generate reports from flow data.
7

SYNOPSIS

9       flow-report  [  -h  ]   [  -d  debug_level  ]   [ -s stat_fname ]  [ -S
10       stat_definition ]  [ -v variable binding ]
11

DESCRIPTION

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
17       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
23       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
26       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
38        +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
52         ignores     Flows with a packet count of 0.
53
54         SSS-count   Count of of an item, example source-ip-address-count
55
56         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
61         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
73       Note fields with a + are only available in the summary-detail report.
74
75       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
82       stat-report command          Description/Example
83       ------------------------------------------------------------------------
84       type                         Define the report type.
85                                    type destination-tag
86
87       filter                       Apply this filter definition.
88                                    filter permit-only-tcp
89
90
91       scale                        Scale report by n.
92                                    scale 100
93
94
95       tag-mask                     Apply source and destination mask to tag.
96                                    tag-mask 0xFF00 0xFF00
97
98       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
103       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
109       output                       Start an output configuration.  Multiple
110                                    output configurations can be configured
111                                    per report.
112
113
114       output option                Description/Example
115       -------------------------------------------------------------------------
116
117       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
124       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
131
132       tally                        Emit a % total line every n records.
133                                    tally 10
134
135       format                       Output format.  Currently only ascii.
136                                    format ascii
137
138       sort                         Sort on a field.  + ascending, - descending.
139                                    sort +flows    - sort on the flows field
140
141                                    Sortable fields are flows,octets,packets,
142                                    duration,avg-pps,min-pps,max-pps,avg-bps,
143                                    min-bps,max-bps
144
145
146       records                      Truncate report at n records.
147                                    records 10
148
149       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
155                                    For reports with one key, the key
156                                    field is referenced with key, else
157                                    key1,key2,key3,etc
158
159                                    Note that the count field is only available
160                                    in select reports, those which end in
161                                    -count.
162
163
164       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
172
173       stat-definition option       Description/Example
174       -------------------------------------------------------------------------
175       filter                       Apply this filter definition.
176                                    filter default
177
178       tag                          Apply this tag definition.
179                                    tag default
180
181       mask                         Apply this mask definition.
182                                    mask default
183
184       report                       Invoke this report.  Multiple reports can
185                                    be set.
186                                    report foo
187
188       time-series                  How often to produce a report in seconds.
189                                    time-series 60
190
191
192       global options               Description/Example
193       -------------------------------------------------------------------------
194       include-tag                  Specify path to include tag definitions.
195                                    include-tag /flows/tags/test1
196
197       include-filter               Specify path to include filter definitions.
198                                    include-filter /flows/filters/test1
199
200       include-mask                 Specify path to include mask definitions.
201                                    include-filter /flows/masks/test1
202
203
204
205       Report type                  Summarization Key Elements.
206       ------------------------------------------------------------------------
207       summary-detail               Totals plus quick breakdown.
208
209       summary-counters             Totals only.
210
211       packet-size                  Average packet size distribution.
212
213       octets                       Octets per flow distribution.
214
215       packets                      Packets per flow distribution.
216
217       ip-source-port               IP Source Port.
218
219       ip-destination-port          IP Destination Port.
220
221       ip-source/destination-port   IP Source/Destination Port pair.
222
223       bps                          Bits/Second distribution.
224
225       pps                          Packets/Second distribution.
226
227       ip-destination-address-type
228                                    IP class with ASM/SSM Multicast breakout.
229
230       ip-protocol                  IP Protocol.
231
232       ip-tos                       IP Type of Service.
233
234       ip-next-hop-address          IP Next Hop Address.
235
236       ip-source-address            IP Source Address.
237
238       ip-destination-address       IP Destination Address.
239
240       ip-source/destination-address
241                                    IP Source/Destination Address pair.
242
243       ip-exporter-address          IP Exporter Address.
244
245       input-interface              Input Interface.
246
247       output-interface             Output Interface.
248
249       input/output-interface       Input/Output Interface pair.
250
251       source-as                    Source AS.
252
253       destination-as               Destination AS.
254
255       source/destination-as        Source/Destination AS.
256
257       ip-source-address/source-as  IP Source Addrss and Source AS.
258
259       ip-destination-address/source-as
260                                    IP Destination Address and Source AS.
261
262       ip-source-address/destination-as
263                                    IP Source Address and Destination AS.
264
265       ip-destination-address/destination-as
266                                    IP Destination Address and Destination AS.
267
268       ip-source/destination-address/source-as
269                                    IP Source/Destination Address and Source AS.
270
271       ip-source/destination-address/destination-as
272                                    IP Source/Destination Address and
273                                    Destination AS.
274
275       ip-source/destination-address/source/destination-as
276                                    IP Source/Destination Address and
277                                    Source/Destination AS.
278
279       ip-source-address/input-interface
280                                    IP Source Address and Input Interface.
281
282       ip-destination-address/input-interface
283                                    IP Destination Address and Input Interface.
284
285       ip-source-address/output-interface
286                                    IP Source Address and Output Interface.
287
288       ip-destination-address/output-interface
289                                    IP Destination Address and Output Interface.
290
291       ip-source/destination-address/input-interface
292                                    IP Source/Destination Address and
293                                    Input Interface.
294
295       ip-source/destination-address/output-interface
296                                    IP Source/Destination Address and
297                                    Output Interface.
298
299       ip-source/destination-address/input/output-interface
300                                    IP Source/Destination Address and
301                                    Input/Output Interface.
302
303       input-interface/source-as    Input Interface and Source AS.
304
305       input-interface/destination-as
306                                    Input Interface and Destination AS.
307
308       output-interface/source-as
309                                    Output Interface and Source AS.
310
311       output-interface/destination-as
312                                    Output Interface and Destination AS.
313
314       input-interface/source/destination-as
315                                    Input Interface and Source/Destination AS.
316
317       output-interface/source/destination-as
318                                    Output Interface and Source/Destination AS.
319
320       input/output-interface/source/destination-as
321                                    Input/Output Interface and
322                                    Source/Destination AS.
323
324       engine-id                    Engine ID.
325
326       engine-type                  Engine Type.
327
328       source-tag                   Source Tag.
329
330       destination-tag              Destination Tag.
331
332       source/destination-tag       Source/Destination Tag.
333
334       ip-source-address/ip-source-port
335                                    IP Source Address and IP Source Port.
336
337       ip-source-address/ip-destination-port
338                                    IP Source Address and IP Destination Port.
339
340       ip-destination-address/ip-source-port
341                                    IP Destination Address and IP Source Port.
342
343       ip-destination-address/ip-destination-port
344                                    IP Destination Address and
345                                    IP Destination Port.
346
347       ip-source-address/ip-source/destination-port
348                                    IP Source Address and
349                                    IP Source/Destination Port.
350
351       ip-destination-address/ip-source/destination-port
352                                    IP Destination Address and
353                                    IP Source/Destination Port.
354
355       ip-source/destination-address/ip-source-port
356                                    IP Source/Destination Address and
357                                    IP Source Port.
358
359       ip-source/destination-address/ip-destination-port
360                                    IP Source/Destination Address and
361                                    IP Destination Port.
362
363       ip-source/destination-address/ip-source/destination-port
364                                    IP Source/Destination Address and
365                                    IP Source/Destination Port.
366
367       ip-source-address/input/output-interface
368                                    IP Source Address and
369                                    Input/Output Interface.
370
371       ip-destination-address/input/output-interface
372                                    IP Destination Address and
373                                    Input/Output Interface.
374
375       ip-source-address/source/destination-as
376                                    IP Source Address and
377                                    Source/Destination AS.
378
379       ip-destination-address/source/destination-as
380                                    IP Destination Address and
381                                    Source/Destination AS.
382
383       ip-address                   IP Address (both source and destination).
384
385       ip-port                      IP Port (both source and destination).
386
387       ip-source-address-destination-count
388                                    Count of destination IP addresses associated
389                                    with a source IP address.
390
391       ip-destination-address-source-count
392                                    Count of source IP addresses associated
393                                    with a destination IP address.
394
395       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
401       first                        First packet of flow distribution.
402
403       last                         Last packet of flow distribution.
404
405       duration                     Duration of flow distribution.
406
407       ip-source-address/source-tag
408                                    IP Source Address and
409                                    Source tag.
410
411       ip-source-address/destination-tag
412                                    IP Source Address and
413                                    Destination tag.
414
415       ip-destination-address/source-tag
416                                    IP Destination Address and
417                                    Source tag.
418
419       ip-destination-address/destination-tag
420                                    IP Destination Address and
421                                    Destination tag.
422
423       ip-source/destination-address/source/destination-tag
424                                    IP Source/Destination Address and
425                                    Source/Destination tag.
426
427       ip-source/destination-address/ip-protocol/ip-tos
428                                    IP Source/Destination Address, IP Protocol,
429                                    and ToS.
430
431       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
435

OPTIONS

437       -d debug_level
438              Enable debugging.
439
440       -s stat_fname
441              Report   configuration   filename.   Defaults   to    /etc/flow-
442              tools/cfg/stat.
443
444       -S stat_definition
445              Select the active definition.
446
447       -v variable binding
448              Set a variable FOO=bar.
449
450       -h     Display help. -hh will list the available reports.
451

EXAMPLES

453       An example of report configuration file
454
455       # stat config file
456
457       include-filter /tmp/filter
458
459       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
469       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
478       stat-definition test
479         filter tcp
480         report t1
481         report t6
482
483
484       # filter config file
485
486       filter-primitive TCP
487         type ip-protocol
488         permit TCP
489
490       filter-definition tcp
491         match ip-protocol TCP
492
493       flow-cat flows | flow-report -stest -Stest
494

IMPLEMENTATION NOTES

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

FILES

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

BUGS

509       None known.
510

AUTHOR

512       Mark Fullmer <maf@splintered.net>
513

SEE ALSO

515       flow-tools(1)
516
517
518
519                                26 Август 2010                  FLOW-REPORT(1)
Impressum