flow-report(1)

NAME
flow-report — Generate reports from flow data.

SYNOPSIS

flow-report [-h] [-d debug_level] [-s stat_fname] [-S stat_definition]

DESCRIPTION

The flow-report 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.

Reports are definied 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.

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.

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
records                      Truncate report at n records.
                             records 10
fields                       Enable/Disable fields with +/-.  Fields:
                             flows,octets,packets,duration,pps,bps,
                             other,key,key1,key2,key3,key4,count.
                             fields +key,+flows,+octets,+packets,
                             +duration
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

stat-definition option       Description/Example
-------------------------------------------------------------------------
filter                       Apply this filter definition.
                             filter default
tag                          Apply this tag definition.
                             tag default
report                       Invoke this report.  Multiple reports can
                             be set.
                             report foo

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

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.

OPTIONS

-d debug_level
    Enable debugging.

-s stat_fname
    Report configuration filename. Defaults to /usr/local/etc/flow-tools/stat.

-S stat_definition
    Select the active definition.

-h  Display help.

EXAMPLES

An example of report configuration file

# stat config file
include-filter /tmp/filter
stat-report t1
  type summary-detail
  filter default
  scale 100
  format ascii
  output
    options +header,+xheader,+totals
    fields +other
    path /tmp/output1
stat-report t6
  type ip-source-port
  format ascii
  output
    options +header,+xheader,+totals,+names,+percent-total
    sort +pps
    tally 5
    path /tmp/output6
stat-definition test
  filter tcp
  report t1
  report t6

# filter config file
filter-primitive TCP
  type ip-protocol
  permit TCP
filter-definition tcp
  match ip-protocol TCP

flow-cat flows | flow-report -stest -Stest

IMPLEMENTATION NOTES

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.

BUGS

None known.

AUTHOR

Mark Fullmer maf@splintered.net

SEE ALSO

flow-tools(1)