NAME

flowcap - Capture, temporarily store, and forward flow data

SYNOPSIS

  flowcap --destination-directory=DIR [--freespace-minimum=SIZE]
        [--space-maximum-percent=NUM]
        [--site-config-file=FILENAME]
        --sensor-configuration=FILENAME [--probes=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 [--probes=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]

DESCRIPTION

flowcap is a daemon that collects data from devices that produce flow data (such as a router producing NetFlow v5 or a flow meter producing IPFIX (Internet Protocol Flow Information eXport)), temporarily stores the data to files on its local disk, and forwards these files to rwflowpack(8) for packing.

As flowcap receives flow records, it stores them in files in the location specified by the --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 --timeout switch or the file size represented by the --max-file-size switch, whichever is reached first.

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

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 --arg=param or --arg param, though the first form is required for options that take optional parameters.

For the following options, a SIZE may be given as an ordinary integer, or as a real number followed by a suffix K, M, G, or 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.

General Purpose Switches

--sensor-configuration=FILENAME: Give the path to the configuration file that flowcap will consult to determine how to collect flow records. The complete syntax of the configuration file is described in the sensor.conf(5) manual page; see also the SiLK Installation Handbook. This switch is required.
--probes=NAME[,NAME...]: Choose which of the probes described in the sensor configuration file will be used by flowcap. The default is to use all of the probes defined in the configuration file. This switch instructs flowcap to only use the specifically named probes.
--max-file-size=SIZE: Set the cutoff size of flowcap files to SIZE. If a flowcap file's exceeds SIZE bytes, it will be closed, and a new file will be created and used. This switch is required.
--timeout=NUM: Set the cutoff time duration of flowcap files to NUM seconds. The default is 60 seconds.
--fc-version=NUM: Choose the format of files that flowcap produces. Valid values are 2, 3, 4, or 5, and the default is 5.
--site-config-file=FILENAME: Read the SiLK site configuration from the named file FILENAME. When this switch is not provided, the location specified by the SILK_CONFIG_FILE environment variable is used if that variable is not empty. The value of SILK_CONFIG_FILE should include the name of the file. Otherwise, the application looks for a file named silk.conf in the following directories: the directory specified in the SILK_DATA_ROOTDIR environment variable; the data root directory that is compiled into SiLK (use the --version switch to view this value); the directories $SILK_PATH/share/silk/ and $SILK_PATH/share/; and the share/silk/ and share/ directories parallel to the application's directory.

Local Storage Switches

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

--destination-directory=DIR: Store aggregated packed flow files in this directory for processing by rwsender.
--freespace-minimum=SIZE: Set the minimum free space to maintain on the file system where the --destination-directory is located. By default, 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 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 --space-maximum-percent.
--space-maximum-percent=NUM: Use no more than this percentage of the file system containing the --destination-directory. The default is to use no more than 98% of the file system. See also --freespace-minimum.

Server Mode Switches

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

--fc-port=NUM: Listen on port NUM for a connection from rwflowpack. This switch is required.
--disk-directory=DIR: Use DIR as a location to store aggregated, packed flows before they are sent to rwflowpack client. This switch is required.
--disk-space=SIZE: Configure flowcap to use no more than SIZE bytes of space in the disk storage directory (see --disk-directory). Once this space is exhausted, flowcap will not accept any more incoming data until space is available. Flows arriving during this time will be lost. This switch is required.
--ram-directory=DIR: Set the name of the RAM disk mount point to DIR. flowcap will attempt to store files in this directory before using the disk storage directory (see --disk-directory). 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 flowcap is shutdown cleanly). If not provided or if the --ram-space is 0, no RAM storage is used and all files are written to the disk-directory.
--ram-space=SIZE: Configure flowcap to use no more than SIZE bytes of space in the RAM storage directory (see --ram-directory). The default is 0 bytes.
--ack-timeout=NUM: Set the time to wait for an ACK from a connected client. The default is 10 seconds.
--client-address=ADDR: Set the address from which flowcap will allow client connections. The default is to accept connections from any address.

Logging Switches

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

One of the following switches are required:

--log-destination=DESTINATION

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

none: Messages are not written anywhere.
stdout: Messages are written to the standard output.
stderr: Messages are written to the standard error.
syslog: Messages are written using the syslog(3) facility.
both: Messages are written to the syslog facility and to the standard error (this option is not available on all platforms).

--log-directory=DIR_PATH

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

  DIR_PATH/LOG_BASENAME-YYYYMMDD.log

where YYYYMMDD is the current date and LOG_BASENAME is the application name or the value passed to the --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 gzip(1). (Old log files are not removed by 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 --pidfile switch is provided.

--log-pathname=FILE_PATH

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

The following switches are optional:

--log-level=LEVEL: Set the severity of messages that will be logged. The levels from most severe to least are: emerg, alert, crit, err, warning, notice, info, debug. The default is info.
--log-sysfacility=NUMBER: Set the facility that syslog(3) uses for logging messages. This switch takes a number as an argument; the default will be value that corresponds to LOG_USER on the system where flowcap is running. This switch will result in an error unless --log-destination=syslog is specified.
--log-basename=LOG_BASENAME: Use LOG_BASENAME in place of the application name for the files in the log directory; see the description of the --log-directory switch.
--pidfile=FILE_PATH: Set the complete path to the file in which flowcap writes its process ID (PID) when it is running as a daemon. No PID file is written when --no-daemon is given. When this switch is not present, no PID file is written unless the --log-directory switch is specified, in which case the PID is written to LOGPATH/flowcap.pid.
--no-daemon: Set flowcap to run in the foreground, as a non-daemonized process. This is useful for debugging.

FILES

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

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

ENVIRONMENT

SILK_CONFIG_FILE: This environment variable is used as the value for the --site-config-file when that switch is not provided.
SILK_DATA_ROOTDIR: When the --site-config-file switch is not provided and the SILK_CONFIG_FILE environment variable is not set, flowcap looks for the site configuration file in $SILK_DATA_ROOTDIR/silk.conf.
SILK_PATH: This environment variable gives the root of the install tree. As part of its search for the SiLK site configuration file, flowcap checks for a file named silk.conf in the directories $SILK_PATH/share/silk and $SILK_PATH/share.