=pod

=head1 NAME

B<flowcap> - Capture, temporarily store, and forward flow data

=head1 SYNOPSIS

  flowcap --destination-directory=DIR [--freespace-minimum=SIZE]
        [--space-maximum-percent=NUM]
        [--site-config-file=FILENAME]
        --sensor-configuration=FILENAME [--sensors=NAME[,NAME...]]
        --max-file-size=SIZE [--timeout=NUM] [--fc-version=NUM]
        { --log-destination=DESTINATION
          | --log-directory=DIR_PATH [--log-basename=LOG_BASENAME]
          | --log-pathname=FILE_PATH }
        [--log-level=LEVEL] [--log-sysfacility=NUMBER] [--no-daemon]
        [--pidfile=FILE_PATH]

Legacy behavior:

  flowcap --fc-port=NUM --disk-directory=DIR --disk-space=SIZE
        [--ram-directory=DIR] [--ram-space=SIZE] 
        [--ack-timeout=NUM] [--client-address=ADDR]
        [--site-config-file=FILENAME]
        --sensor-configuration=FILENAME [--sensors=NAME[,NAME...]]
        --max-file-size=SIZE [--timeout=NUM] [--fc-version=NUM]
        { --log-destination=DESTINATION
          | --log-directory=DIR_PATH [--log-basename=LOG_BASENAME]
          | --log-pathname=FILE_PATH }
        [--log-level=LEVEL] [--log-sysfacility=NUMBER]
        [--pidfile=FILE_PATH] [--no-daemon]


=head1 DESCRIPTION

B<flowcap> is a daemon that collects data from flow sources (i.e.,
devices that produce flow data, such as a router producing NetFlow),
temporarily stores it, and forwards it to B<rwflowpack(8)> for
packing.

As B<flowcap> receives flow records, it stores them in files in the
location specified by the B<--disk-directory> switch.  These files are
closed on quantum boundaries, with one file per flow source per
quantum.  A quantum is either the amount of time represented by the
B<--timeout> switch or the file size represented by the
B<--max-file-size> switch, whichever is reached first.

To transfer the files to B<rwflowpack>, B<flowcap> works in tandem
with the B<rwsender(8)> program.  B<rwsender> polls the storage
directory and sends the files it finds there to an B<rwreceiver(8)>
process for processing by B<rwflowpack>.  B<flowcap> can also operate
in legacy mode, where B<flowcap> acts as a server that B<rwflowpack>
connects to via TCP.  This behavior is deprecated and will be removed
in a future release.


=head1 OPTIONS

Option names may be abbreviated if the abbreviation is unique or is an
exact match for an option.  A parameter to an option may be specified
as B<--arg>=I<param> or B<--arg> I<param>, though the first form is
required for options that take optional parameters.

For the following options, a I<SIZE> may be given as an ordinary
integer, or as a real number followed by a suffix C<K>, C<M>, C<G>, or
C<T>, which represents the numerical value multiplied by 1,024 (kilo),
1,048,576 (mega), 1,073,741,824 (giga), and 1,099,511,627,776 (tera),
respectively.  For example, 1.5K represents 1,536 bytes, or one and
one-half kilobytes.


=head2 General Purpose Switches

=over 4

=item B<--sensor-configuration>=I<FILENAME>

Give the path to the configuration file that B<flowcap> will consult
to determine how to collect flow records.  The complete syntax of the
configuration file is described in the B<sensor.conf(5)> manual page;
see also the I<SiLK Installation Handbook>.  This switch is required.

=item B<--sensors>=I<NAME[,NAME...]>

Choose which of the sensors described in the sensor configuration file
will be used by B<flowcap>.  The default is to use all of the sensors
defined in the configuration file.

=item B<--max-file-size>=I<SIZE>

Set the cutoff size of B<flowcap> files to I<SIZE>.  If a B<flowcap>
file's exceeds I<SIZE> bytes, it will be closed, and a new file will
be created and used.  This switch is required.

=item B<--timeout>=I<NUM>

Set the cutoff time duration of B<flowcap> files to I<NUM> seconds.
The default is 60 seconds.

=item B<--fc-version>=I<NUM>

Choose the format of files that B<flowcap> produces.  Valid values are
2, 3, 4, or 5, and the default is 5.

=item B<--site-config-file>=I<FILENAME>

Read the SiLK site configuration from the named file I<FILENAME>.
When this switch is not provided, the location specified by the
C<$SILK_CONFIG_FILE> environment variable is used if that variable is
not empty.  The value of C<$SILK_CONFIG_FILE> should include the name
of the file.  Otherwise, the application looks for a file named
F<silk.conf> in the following directories: the directory specified in
the F<$SILK_DATA_ROOTDIR> environment variable; the data root
directory that is compiled into SiLK (use the B<--version> switch to
view this value); the directories F<$SILK_PATH/share/silk/>,
F<$SILK_PATH/share/>, or F<$SILK_PATH>; or in the F<share/silk/> and
F<share/> directories parallel to the application's directory.

=back


=head2 Local Storage Switches

This switches in this section are used when B<flowcap> writes the
files to a local directory and expects B<rwsender> to deliver them to
B<rwflowpack>.  These switches are incompatible with those in the next
section.

=over 4

=item B<--destination-directory>=I<DIR>

Store aggregated packed flow files in this directory for processing by
B<rwsender>.

=item B<--freespace-minimum>=I<SIZE>

Set the minimum free space to maintain on the file system where the
B<--destination-directory> is located.  By default, B<flowcap> assumes
that it has full rein over the file system on which it writes its
files.  The default is to leave 1GB of free space.  If B<flowcap>
fills this space, it will not accept any more incoming data until
space is available.  Flows arriving during this time will be lost.
See also B<--space-maximum-percent>.

=item B<--space-maximum-percent>=I<NUM>

Use no more than this percentage of the file system containing the
B<--destination-directory>.  The default is to use no more than 98% of
the file system.  See also B<--freespace-minimum>.

=back

=head2 Server Mode Switches

The switches in this section should only be used when B<flowcap> acts
as a TCP server, and they cannot be mixed with the Local Storage
Switches described in the previous section.

=over 4

=item B<--fc-port>=I<NUM>

Listen on port I<NUM> for a connection from B<rwflowpack>.  This
switch is required.

=item B<--disk-directory>=I<DIR>

Use DIR as a location to store aggregated, packed flows before they
are sent to B<rwflowpack> client.  This switch is required.

=item B<--disk-space>=I<SIZE>

Configure B<flowcap> to use no more than SIZE bytes of space in the
disk storage directory (see B<--disk-directory>).  Once this space is
exhausted, B<flowcap> will not accept any more incoming data until
space is available.  Flows arriving during this time will be lost.
This switch is required.

=item B<--ram-directory>=I<DIR>

Set the name of the RAM disk mount point to DIR.  B<flowcap> will
attempt to store files in this directory before using the disk storage
directory (see B<--disk-directory>).  B<flowcap> treats this directory
as having higher speed access than disk storage, and assumes that it
may not survive between program invocations (i.e., files in the
ram-directory will be moved to the disk-directory when B<flowcap> is
shutdown cleanly).  If not provided or if the B<--ram-space> is 0, no
RAM storage is used and all files are written to the disk-directory.

=item B<--ram-space>=I<SIZE>

Configure B<flowcap> to use no more than SIZE bytes of space in the
RAM storage directory (see B<--ram-directory>).  The default is 0
bytes.

=item B<--ack-timeout>=I<NUM>

Set the time to wait for an ACK from a connected client.  The default
is 10 seconds.

=item B<--client-address>=I<ADDR>

Set the address from which B<flowcap> will allow client connections.
The default is to accept connections from any address.

=back


=head2 Logging Switches

The switches in this section determine the type of log messages that
B<flowcap> generates and where those messages are written.

One of the following switches are required:

=over 4

=item B<--log-destination>=I<DESTINATION>

Specify the destination where logging messages are written.  When
I<DESTINATION> begins with a slash C</>, it is treated as a file
system path and all log messages are written to that file; there is no
log rotation.  When I<DESTINATION> does not begin with C</>, it must
be one of the following strings:

=over 4

=item C<none>

Messages are not written anywhere.

=item C<stdout>

Messages are written to the standard output.

=item C<stderr>

Messages are written to the standard error.

=item C<syslog>

Messages are written using the B<syslog(3)> facility.

=item C<both>

Messages are written to the syslog facility and to the standard error
(this option is not available on all platforms).

=back

=item B<--log-directory>=I<DIR_PATH>

Use I<DIR_PATH> as the directory to which the log files are written;
I<DIR_PATH> must be a complete directory path.  The log files have the
form

  DIR_PATH/LOG_BASENAME-YYYYMMDD.log

where I<YYYYMMDD> is the current date and I<LOG_BASENAME> is the
application name or the value passed to the B<--log-basename> switch
when provided.  The log files will be rotated.  At midnight local time,
a new log will be opened and the previous day's log file will be
compressed using B<gzip(1)>.  (Old log files are not removed by
B<flowcap>; the administrator should use another tool to remove them.)
When this switch is provided, a process-ID file (PID) will also be written
in this directory unless the B<--pidfile> switch is provided.

=item B<--log-pathname>=I<FILE_PATH>

Use I<FILE_PATH> as the complete path to the log file.  The log file
will not be rotated.

=back

The following switches are optional:

=over 4

=item B<--log-level>=I<LEVEL>

Set the severity of messages that will be logged.  The levels from
most severe to least are: C<emerg>, C<alert>, C<crit>, C<err>,
C<warning>, C<notice>, C<info>, C<debug>.  The default is C<info>.

=item B<--log-sysfacility>=I<NUMBER>

Set the facility that B<syslog(3)> uses for logging messages.  This
switch takes a number as an argument; the default will be value that
corresponds to C<LOG_USER> on the system where B<flowcap> is running.
This switch will result in an error unless B<--log-destination>=syslog
is specified.

=item B<--log-basename>=I<LOG_BASENAME>

Use I<LOG_BASENAME> in place of the application name for the files in
the log directory; see the description of the B<--log-directory>
switch.

=item B<--pidfile>=I<FILE_PATH>

Set the complete path to the file in which B<flowcap> writes its
process ID (PID) when it is running as a daemon.  No PID file is
written when B<--no-daemon> is given.  When this switch is not
present, no PID file is written unless the B<--log-directory> switch
is specified, in which case the PID is written to
F<I<LOGPATH>/flowcap.pid>>.

=item B<--no-daemon>

Set B<flowcap> to run in the foreground, as a non-daemonized process.
This is useful for debugging.

=back


=head1 FILES

File names follow the following naming scheme:
I<SENSOR>_I<PROBE>_I<YYYYMMDDhhmmss>.I<XXXXXX>, where I<SENSOR> is the
name of the sensor, I<PROBE> is the name of the probe, I<YYYY> is the
current year, I<MM> is the current month, I<DD> is the current day,
I<hh> is the current hour, I<mm> is the current minute, I<ss> is the
current second, and I<XXXXXX> is a random six-character string.

When B<flowcap> exits, it will copy any files in the ram-directory to
the disk-directory.

=head1 SEE ALSO

I<SiLK Installation Handbook>, B<sensor.conf(5)>, B<rwflowpack(8)>,
B<rwsender(8)>, B<syslog(3)>

=cut

$SiLK: flowcap.pod 6868 2007-04-12 15:32:23Z mthomas $

Local Variables:
mode:text
indent-tabs-mode:nil
End: