FLOW-REPORT(1)

πŸ“¦ version 0.68.5.1, in fedora 43, fedora 44

✨ NAME ✨

flow-report β€” Generate reports from flow data.

Okay bestie, welcome to the FLOW-REPORT(1) page. This is the manual for flow-report, and it's about to be your new obsession. πŸ’–βœ¨

πŸ› οΈ SYNOPSIS πŸ› οΈ

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

πŸ’– 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. Slay. 🌈

Reports are defined 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. Obsessed with the organization, fr fr. πŸ’…

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. Variable binding? We love to see it. iykyk. 🫢

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. Main character energy, no cap. πŸ‘‘

πŸ“Š Column titles πŸ“Š

  • +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 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. Periodt. πŸ’…
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. Not me crying over edge cases. 😭

πŸŽ€ stat-report command β€” Description/Example πŸŽ€

  • type β€” Define the report type. Example: type destination-tag
  • filter β€” Apply this filter definition. Example: filter permit-only-tcp
  • scale β€” Scale report by n. Example: scale 100
  • tag-mask β€” Apply source and destination mask to tag. Example: 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. Example: 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. Example: tally 10
  • format β€” Output format. Currently only ascii. Example: format ascii
  • sort β€” Sort on a field. + ascending, - descending. Example: 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. Example: records 10
  • fields β€” Enable/Disable fields with +/-. Fields: index,first,last,flows,octets,packets,duration,pps,bps,other,key,key1,key2,key3,key4,count. Example: 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.
    • Example: options +header,+xheader

πŸŽ€ stat-definition option β€” Description/Example πŸŽ€

  • filter β€” Apply this filter definition. Example: filter default
  • tag β€” Apply this tag definition. Example: tag default
  • mask β€” Apply this mask definition. Example: mask default
  • report β€” Invoke this report. Multiple reports can be set. Example: report foo
  • time-series β€” How often to produce a report in seconds. Example: time-series 60

πŸŽ€ global options β€” Description/Example πŸŽ€

  • include-tag β€” Specify path to include tag definitions. Example: include-tag /flows/tags/test1
  • include-filter β€” Specify path to include filter definitions. Example: include-filter /flows/filters/test1
  • include-mask β€” Specify path to include mask definitions. Example: include-filter /flows/masks/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 Address 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, bestie πŸ’–).
  • 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 Address, IP Protocol, IP ToS, IP Source/Destination Port.

✨ OPTIONS ✨

Like, the actual knobs you get to turn. Not too many, we keep it cute. πŸŽ€

  • -d debug_level β€” Turn on debugging. Yes, the little gremlin logs. πŸ›
  • -s stat_fname β€” The report configuration filename. Defaults to /etc/flow-tools/cfg/stat in case you were wondering, and you were wondering.
  • -S stat_definition β€” Pick which definition is the active one. Main character selection moment. πŸ‘‘
  • -v variable binding β€” Set a variable, like FOO=bar. Very DIY of you.
  • -h β€” Display help. And plot twist: -hh will list the available reports. Double h, double knowledge. 🧠✨

🌸 EXAMPLES 🌸

Okay bestie, here's an example of a report configuration file. Read it like a recipe, it's giving chef vibes πŸ‘©β€πŸ³:

# 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

# filter config file

filter-primitive TCP
  type ip-protocol
  permit TCP

filter-definition tcp
  match ip-protocol TCP

And then you actually run the thing, like so:

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

That pipe is the moment. πŸ’…

🫢 IMPLEMENTATION NOTES 🫢

Okay so the tea β˜• β€” here's how the numbers actually work, no cap:

  • Packet size calculations are dOctets / dPkts, ie an average packet size. Periodt.
  • It is not possible to get a true packet size from flow exports. Like, the data just isn't there. 😭
  • pps and bps calculations are an average of the averages. Averages of averages, bestie. Do with that what you will.
  • 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. Gone. Ghosted. πŸ‘»

πŸ“ FILES πŸ“

Configuration files, all nestled up in their little homes:

  • Symbols β€” /etc/flow-tools/sym/*
  • Tag β€” /etc/flow-tools/cfg/tag.cfg
  • Filter β€” /etc/flow-tools/cfg/filter.cfg
  • Mask β€” /etc/flow-tools/cfg/mask.cfg
  • Report β€” /etc/flow-tools/cfg/stat.cfg
  • Xlate β€” /etc/flow-tools/cfg/xlate.cfg

πŸ’€ BUGS πŸ’€

None known. Not one. Zero. Zilch. The code is, allegedly, flawless. πŸ™ˆβœ¨

πŸ‘‘ AUTHOR πŸ‘‘

Mark Fullmer <maf@splintered.net>

Absolute icon. We stan. 🫢

🌈 SEE ALSO 🌈

And that's the whole page, bestie β€” you made it to the end πŸŽ‰πŸ’– This was FLOW-REPORT(1) from the 26 Август 2010 era, so go forth and report those flows. Slay. βœ¨πŸŽ€πŸ¦‹

πŸ“¦ where this page comes from