Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
flow-report(1)		    General Commands Manual		flow-report(1)

NAME
       flow-report -- Generate reports from flow data.

SYNOPSIS
       flow-report  [-h]   [-d debug_level]  [-s stat_fname]  [-S stat_defini-
       tion]  [-v variable binding]

DESCRIPTION
       The flow-report utility will generate reports from flow data.  The  re-
       ports  are  easy	to parse ASCII text that can be	used by	a front	end to
       produce readable	reports, graphs, and charts.

       Reports are definied in a configuration file by the 'stat-report'  key-
       word  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 defini-
       tion can	invoke a filter	and optionally apply tags.

       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.

       Generated  reports  consist of comment lines and	report lines.  Comment
       lines begin with	a # and	include	details	such as	the options used,  re-
       port  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	calcu-
       lated 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.

	+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.

       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.

       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

				    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

       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

       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

       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.

OPTIONS
       -d debug_level
		 Enable	debugging.

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

       -S stat_definition
		 Select	the active definition.

       -v variable binding
		 Set a variable	FOO=bar.

       -h	 Display help.	-hh will list the available reports.

EXAMPLES
       An example of report configuration file

       # 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

       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.

FILES
	 Configuration files:
	   Symbols - /usr/local/share/flow-tools/*.
	   Tag - /usr/local/etc/flow-tools/tag.cfg.
	   Filter - /usr/local/etc/flow-tools/filter.cfg.
	   Mask	- /usr/local/etc/flow-tools/mask.cfg.
	   Report - /usr/local/etc/flow-tools/stat.cfg.
	   Xlate - /usr/local/etc/flow-tools/xlate.cfg.

BUGS
       None known.

AUTHOR
       Mark Fullmer maf@splintered.net

SEE ALSO
       flow-tools(1)

								flow-report(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | IMPLEMENTATION NOTES | FILES | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=flow-report&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help