* Introduction

This is flowz - a netflow statistics aggregator.

* How to install

As usual -- ./configure && make && make install.  See INSTALL for the 
generic instructions.

* Operation

** General

Three levels of aggregation are supported.  The aggregation level is
specified using -l (--level) command line option.  The default aggregation
level is 1.  Simplest examples:

# Read file input.dat and produce level 1 dump at the standard output:
flowz input.dat

# Read standard input and produce level 2 dump at the standard output:
flowz --level 2 -

Alternative output file can be specified using -o (--output) option,
for example:

flowz -o dump1.dat dump.dat

To obtain additional statistics at the end of the run, use --verbose
(-v) option.  The statistics will be printed to the standard output.

** Memory consumption

By default program will try to process the whole input file.  If this
raises memory concerns, you can instruct it to process the file in
chunks by using --max-memory command line option.  This option takes a
single argument, specifying the maximum amount of memory to be used
for internal storage.  Usual size suffixes are allowed: k or kb for
kilobytes, m or mb for megabytes and g or gb for gigabytes.  Case is
not significant: kB and KB mean the same.

Notice that using --max-memory option increases the size of the output
file as well as the execution time.

** Input format

Input files are line oriented.  Blank lines and lines starting with
'#' (optionally preceded by any amount of whitespace) are ignored.
Each line consists of a comma-separated list of data, as described
below.

*** For level 1:

Input format: unix_secs,doctets,srcaddr,dstaddr,tos,src_mask,dst_mask,
src_as,dst_as,src_tag,dst_tag

Output format: first-last,doctets,srcaddr,dstaddr,tos,src_mask,dst_mask,
src_as,dst_as,src_tag,dst_tag

where first-last is a dash-separated pair of UNIX timestamps.

Level 1 output is a valid input for level 2. 

*** For level 2:

Input format: first-last,doctets,srcaddr,dstaddr,tos,src_mask,dst_mask,
src_as,dst_as,src_tag,dst_tag

Output format: first-last,doctets,srcaddr,dstaddr,tos,src_mask,dst_mask,
src_as,dst_as,src_tag,dst_tag

Level 2 output is a valid input for level 3.

*** For level 3:

Input format: first-last,doctets,srcaddr,dstaddr,tos,src_mask,dst_mask,
src_as,dst_as,src_tag,dst_tag

Output format: first-last,doctets,tos,src_as,dst_as,src_tag,dst_tag

** Error handling

The utility will report to the standard error the locations of  erroneous
input lines, along with the diagnostics.  By default such lines are
ignored.  The command line option --max-errors is used to set the maximum
number of errors the utility should tolerate.  After encountering that many
errors it will exit with status 1.  For example, the following invocation will
make flowz exit after the first unparsable line:

flowz --max-errors 1 -

** Exit code

Flowz exits with code 0 if no errors were detected.  If the input file
contained any malformed lines, it will exit with code 2.  If any fatal
error occurred or if the number of errors exceeded that set with --max-errors
option, the utility will exit with code 3.

* Documentation

This file is the only documentation available.

* Copying

Copyright (C) 2006 Sergey Poznyakoff

Permission is granted to anyone to make or distribute verbatim
copies of this document as received, in any medium, provided that
the copyright notice and this permission notice are preserved,
thus giving the recipient permission to redistribute in turn.

Permission is granted to distribute modified versions
of this document, or of portions of it,
under the above conditions, provided also that they
carry prominent notices stating who last changed them.


Local Variables:
mode: outline
paragraph-separate: "[ 	]*$"
version-control: never
End:
