1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
|
...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
...\"
...\" transcript compatibility for postscript use.
...\"
...\" synopsis: .P! <file.ps>
...\"
.de P!
\\&.
.fl \" force out current output buffer
\\!%PB
\\!/showpage{}def
...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
.fl \" prolog
.sy cat \\$1\" bring in postscript file
...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
.sp \\$2u \" move below the image
..
.de pF
.ie \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie !\\*(f4 \{\
. ft \\*(f4
. ds f4\"
' br \}
.el .ie !\\*(f3 \{\
. ft \\*(f3
. ds f3\"
' br \}
.el .ie !\\*(f2 \{\
. ft \\*(f2
. ds f2\"
' br \}
.el .ie !\\*(f1 \{\
. ft \\*(f1
. ds f1\"
' br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
.TH "\fBflow-report\fP" "1"
.SH "NAME"
\fBflow-report\fP \(em Generate reports from flow data\&.
.SH "SYNOPSIS"
.PP
\fBflow-report\fP [-h] [-d\fI debug_level\fP] [-s\fI stat_fname\fP] [-S\fI stat_definition\fP] [-v\fI variable binding\fP]
.SH "DESCRIPTION"
.PP
The \fBflow-report\fP utility will generate reports
from flow data\&. The reports are easy to parse ASCII text that
can be used by a front end to produce readable reports, graphs,
and charts\&.
.PP
Reports are definied in a configuration file by the \&'stat-report\&' keyword
followed by a report name\&. Each report has a type defined below and other
commands\&. Reports are grouped into a definition with the \&'stat-definition\&'
keyword followed by a definition name\&. Each definition can invoke a filter
and optionally apply tags\&.
.PP
Words in the configuration file of the form @VAR or @{VAR:default} will be
expanded at run-time by setting variable names with the -v option\&.
.PP
Generated reports consist of comment lines and report lines\&. Comment
lines begin with a # and include details such as the options used, report
name, records in the report, and the report line format\&. Some of the
more verbose comments can be controlled with the +header and +xheader
options\&. By default this information is not displayed\&. A column title
beginning with the string rec precedes the report lines\&. Report lines
consist of key fields, such as an IP address and calculated totals
for that key such as the number of flows\&.
The summary-detail report is a little bit different from other reports
in that it has multiple title lines and no key fields\&.
The column titles are described below\&.
.PP
.nf
+time_real Difference between the real time of the first and last
flow\&.
+aflowtime Total time of the flows / Total number of flows\&.
+aps Total Octets / Total Packets (Average Packet Size)
+afs Total Octets / Total Flows / (Average Flow Size)
+apf Total Packets / Total Flows (Average Packets / Flow)
+fps Total Flows / (Last End Time of Flow -
First Start Time of Flow) (Average Flows / Second)
+fps_real (Average Flows / Second in realtime)
+psizeN Average Packet Size buckets\&.
+fpsizeN Packets / Flow buckets\&.
+fosizeN Octets / Flow buckets\&.
+ftimeN Time / Flow buckets\&.
ignores Flows with a packet count of 0\&.
SSS-count Count of of an item, example source-ip-address-count
SSS* key fields, example source-ip-address
index Report line index\&.
first Time of first flow in unix_secs format\&.
last Time of last flow in unix_secs format\&.
flows Summation of flows/key\&.
octets Summation of octets/key\&.
packets Summation of packets/key\&.
duration End time of Flow - Start time of Flow\&.
avg-bps Average Bits/Second\&.
min-bps Minimum Bits/Second\&.
max-bps Maximum Bits/Second\&.
avg-pps Average Packets/Second\&.
min-pps Minimum Packets/Second\&.
max-pps Maximum Packets/Second\&.
frecs Records used in average calculations\&.
Note fields with a + are only available in the summary-detail report\&.
.fi
The PPS and BPS calculations will not always be correct due to flows
which only have one packet, or some other condition where the start
time is equal to the end time\&. In this case these flows are not
used in the PPS and BPS calculations\&. To facilitate aggregating
multiple reports and retaining the PPS and BPS fields, the number
of flows counted is available in the frecs field\&.
.PP
.PP
.nf
stat-report command Description/Example
------------------------------------------------------------------------
type Define the report type\&.
type destination-tag
filter Apply this filter definition\&.
filter permit-only-tcp
scale Scale report by n\&.
scale 100
tag-mask Apply source and destination mask to tag\&.
tag-mask 0xFF00 0xFF00
ip-source-address-format Format of source IP address\&.
address - address, ie 128\&.146\&.1\&.7
prefix-len - address/len ie 128\&.146\&.1\&.7/24
prefix-mask- prefix/len 128\&.146\&.1/24
ip-destination-address-format
Format of destination IP address\&.
address - address, ie 128\&.146\&.1\&.7
prefix-len - address/len ie 128\&.146\&.1\&.7/24
prefix-mask- prefix/len 128\&.146\&.1/24
output Start an output configuration\&. Multiple
output configurations can be configured
per report\&.
.fi
.PP
.PP
.nf
output option Description/Example
-------------------------------------------------------------------------
path Pathname of output\&. If the path begins
with a | the output is a pipe\&. The
pathname is formatted through strftime()\&.
Directories not in the path are
automatically created\&.
path /tmp/%Y/%m/%d/foo\&.out
time What time to use when formatting the
pathname with strftime\&.
now - current time
start - first flow
end - last flow
mid - average of first and last\&.
tally Emit a % total line every n records\&.
tally 10
format Output format\&. Currently only ascii\&.
format ascii
sort Sort on a field\&. + ascending, - descending\&.
sort +flows - sort on the flows field
Sortable fields are flows,octets,packets,
duration,avg-pps,min-pps,max-pps,avg-bps,
min-bps,max-bps
records Truncate report at n records\&.
records 10
fields Enable/Disable fields with +/-\&. Fields:
index,first,last,flows,octets,packets,
duration,pps,bps,other,key,key1,key2,
key3,key4,count\&.
fields +key,+flows,+octets,+packets,
For reports with one key, the key
field is referenced with key, else
key1,key2,key3,etc
Note that the count field is only available
in select reports, those which end in
-count\&.
options Enable/Disable options with +/-
+header - include header\&.
+xheader - include extra header\&.
+totals - include a totals line\&.
+percent-total - report in % total form\&.
+names - use symbolic names\&.
options +header,+xheader
.fi
.PP
.PP
.nf
stat-definition option Description/Example
-------------------------------------------------------------------------
filter Apply this filter definition\&.
filter default
tag Apply this tag definition\&.
tag default
mask Apply this mask definition\&.
mask default
report Invoke this report\&. Multiple reports can
be set\&.
report foo
time-series How often to produce a report in seconds\&.
time-series 60
.fi
.PP
.PP
.nf
global options Description/Example
-------------------------------------------------------------------------
include-tag Specify path to include tag definitions\&.
include-tag /flows/tags/test1
include-filter Specify path to include filter definitions\&.
include-filter /flows/filters/test1
include-mask Specify path to include mask definitions\&.
include-filter /flows/masks/test1
.fi
.PP
.PP
.nf
Report type Summarization Key Elements\&.
------------------------------------------------------------------------
summary-detail Totals plus quick breakdown\&.
summary-counters Totals only\&.
packet-size Average packet size distribution\&.
octets Octets per flow distribution\&.
packets Packets per flow distribution\&.
ip-source-port IP Source Port\&.
ip-destination-port IP Destination Port\&.
ip-source/destination-port IP Source/Destination Port pair\&.
bps Bits/Second distribution\&.
pps Packets/Second distribution\&.
ip-destination-address-type
IP class with ASM/SSM Multicast breakout\&.
ip-protocol IP Protocol\&.
ip-tos IP Type of Service\&.
ip-next-hop-address IP Next Hop Address\&.
ip-source-address IP Source Address\&.
ip-destination-address IP Destination Address\&.
ip-source/destination-address
IP Source/Destination Address pair\&.
ip-exporter-address IP Exporter Address\&.
input-interface Input Interface\&.
output-interface Output Interface\&.
input/output-interface Input/Output Interface pair\&.
source-as Source AS\&.
destination-as Destination AS\&.
source/destination-as Source/Destination AS\&.
ip-source-address/source-as IP Source Addrss and Source AS\&.
ip-destination-address/source-as
IP Destination Address and Source AS\&.
ip-source-address/destination-as
IP Source Address and Destination AS\&.
ip-destination-address/destination-as
IP Destination Address and Destination AS\&.
ip-source/destination-address/source-as
IP Source/Destination Address and Source AS\&.
ip-source/destination-address/destination-as
IP Source/Destination Address and
Destination AS\&.
ip-source/destination-address/source/destination-as
IP Source/Destination Address and
Source/Destination AS\&.
ip-source-address/input-interface
IP Source Address and Input Interface\&.
ip-destination-address/input-interface
IP Destination Address and Input Interface\&.
ip-source-address/output-interface
IP Source Address and Output Interface\&.
ip-destination-address/output-interface
IP Destination Address and Output Interface\&.
ip-source/destination-address/input-interface
IP Source/Destination Address and
Input Interface\&.
ip-source/destination-address/output-interface
IP Source/Destination Address and
Output Interface\&.
ip-source/destination-address/input/output-interface
IP Source/Destination Address and
Input/Output Interface\&.
input-interface/source-as Input Interface and Source AS\&.
input-interface/destination-as
Input Interface and Destination AS\&.
output-interface/source-as
Output Interface and Source AS\&.
output-interface/destination-as
Output Interface and Destination AS\&.
input-interface/source/destination-as
Input Interface and Source/Destination AS\&.
output-interface/source/destination-as
Output Interface and Source/Destination AS\&.
input/output-interface/source/destination-as
Input/Output Interface and
Source/Destination AS\&.
engine-id Engine ID\&.
engine-type Engine Type\&.
source-tag Source Tag\&.
destination-tag Destination Tag\&.
source/destination-tag Source/Destination Tag\&.
ip-source-address/ip-source-port
IP Source Address and IP Source Port\&.
ip-source-address/ip-destination-port
IP Source Address and IP Destination Port\&.
ip-destination-address/ip-source-port
IP Destination Address and IP Source Port\&.
ip-destination-address/ip-destination-port
IP Destination Address and
IP Destination Port\&.
ip-source-address/ip-source/destination-port
IP Source Address and
IP Source/Destination Port\&.
ip-destination-address/ip-source/destination-port
IP Destination Address and
IP Source/Destination Port\&.
ip-source/destination-address/ip-source-port
IP Source/Destination Address and
IP Source Port\&.
ip-source/destination-address/ip-destination-port
IP Source/Destination Address and
IP Destination Port\&.
ip-source/destination-address/ip-source/destination-port
IP Source/Destination Address and
IP Source/Destination Port\&.
ip-source-address/input/output-interface
IP Source Address and
Input/Output Interface\&.
ip-destination-address/input/output-interface
IP Destination Address and
Input/Output Interface\&.
ip-source-address/source/destination-as
IP Source Address and
Source/Destination AS\&.
ip-destination-address/source/destination-as
IP Destination Address and
Source/Destination AS\&.
ip-address IP Address (both source and destination)\&.
ip-port IP Port (both source and destination)\&.
ip-source-address-destination-count
Count of destination IP addresses associated
with a source IP address\&.
ip-destination-address-source-count
Count of source IP addresses associated
with a destination IP address\&.
linear-interpolated-flows-octets-packets
Linear interpolated distribution of flows,
octets and packets\&. The distribution is
done across the start and end time of the
flow\&.
first First packet of flow distribution\&.
last Last packet of flow distribution\&.
duration Duration of flow distribution\&.
ip-source-address/source-tag
IP Source Address and
Source tag\&.
ip-source-address/destination-tag
IP Source Address and
Destination tag\&.
ip-destination-address/source-tag
IP Destination Address and
Source tag\&.
ip-destination-address/destination-tag
IP Destination Address and
Destination tag\&.
ip-source/destination-address/source/destination-tag
IP Source/Destination Address and
Source/Destination tag\&.
ip-source/destination-address/ip-protocol/ip-tos
IP Source/Destination Address, IP Protocol,
and ToS\&.
ip-source/destination-address/ip-protocol/ip-tos/ip-source/destination-port
IP Source/Destination Addess, IP Protocol,
IP Tos, IP Source/Destination Port\&.
.fi
.SH "OPTIONS"
.IP "-d\fI debug_level\fP" 10
Enable debugging\&.
.IP "-s\fI stat_fname\fP" 10
Report configuration filename\&. Defaults to \fB@localstatedir@/cfg/stat\fP\&.
.IP "-S\fI stat_definition\fP" 10
Select the active definition\&.
.IP "-v\fI variable binding\fP" 10
Set a variable FOO=bar\&.
.IP "-h" 10
Display help\&. -hh will list the available reports\&.
.SH "EXAMPLES"
.PP
An example of report configuration file
.PP
.nf
# stat config file
include-filter /tmp/filter
stat-report t1
type summary-detail
filter default
scale 100
output
format ascii
options +header,+xheader,+totals
fields +other
path /tmp/output1
stat-report t6
type ip-source-port
output
format ascii
options +header,+xheader,+totals,+names,+percent-total
sort +pps
tally 5
path /tmp/output6
stat-definition test
filter tcp
report t1
report t6
.fi
.PP
.nf
# filter config file
filter-primitive TCP
type ip-protocol
permit TCP
filter-definition tcp
match ip-protocol TCP
.fi
\fBflow-cat \fBflows\fP | flow-report -stest -Stest\fP
.SH "IMPLEMENTATION NOTES"
.PP
Packet size calculations are dOctets / dPkts, ie an average packet size\&. It
is not possible to get a true packet size from flow exports\&.
pps and bps calculations are an average of the averages\&.
Flows that do not have a duration (start == end) are not counted in the
pps and bps calculations\&.
Flows without a packet or octet count are ignored\&.
.SH "FILES"
.PP
Configuration files:
Symbols - \fB@localstatedir@/sym/*\fP\&.
Tag - \fB@localstatedir@/cfg/tag\&.cfg\fP\&.
Filter - \fB@localstatedir@/cfg/filter\&.cfg\fP\&.
Mask - \fB@localstatedir@/cfg/mask\&.cfg\fP\&.
Report - \fB@localstatedir@/cfg/stat\&.cfg\fP\&.
Xlate - \fB@localstatedir@/cfg/xlate\&.cfg\fP\&.
.SH "BUGS"
.PP
None known\&.
.SH "AUTHOR"
.PP
Mark Fullmer maf@splintered\&.net
.SH "SEE ALSO"
.PP
\fBflow-tools\fP(1)
...\" created by instant / docbook-to-man, Wed 07 Jan 2004, 23:53
|
