NAME

flowrate - SiLK plug-in providing payload and rate filters and fields

SYNOPSIS

  rwfilter --plugin=flowrate.so [--payload-bytes=INTEGER_RANGE]
        [--payload-rate=DECIMAL_RANGE]
        [--bytes-per-second=DECIMAL_RANGE]
        [--packets-per-second=DECIMAL_RANGE] ...

  rwcut --plugin=flowrate.so --fields=FIELDS ...

  rwsort --plugin=flowrate.so --fields=FIELDS ...

  rwuniq --plugin=flowrate.so --fields=FIELDS ...

DESCRIPTION

When loaded into rwfilter(1), the flowrate plug-in provides switches that can partition flows based on bytes of payload and/or on the rates of data transfer.

For rwcut(1), rwsort(1), and rwuniq(1), the flowrate plug-in provides fields that will print, sort flows by, and group flows by the bytes of payload, bytes-per-packet, bytes-per-second, packets-per-second, and bytes of payload per second.

The payload byte count is determined by subtracting from the total byte count in the flow the bytes of overhead used by the packet headers. The payload calculation assumes minimal packet headers---that is, there are no options in the packets. For TCP, the switch assumes there are no TCP timestamps in the packets. Thus, the calculated payload will be the maximum possible bytes of payload. If the packet-overhead is larger than the reported number of bytes, the value is zero.

The various flow-rate quantities are determined by dividing the payload byte count, packet count, or byte count by the duration of the flow, giving the average rate across the flow. When the flow's reported duration is zero, a duration of one second is assumed (that is, the count is used directly).

The flowrate plug-in must be explicitly loaded into an application via the --plugin switch. The reason for this is due to name clashes with existing switches and fields. For example, adding the --packets-per-second switch to rwfilter means any short-cutting of the current --packets switch will fail.

OPTIONS

The flowrate plug-in provides the following options to the indicated applications.

rwfilter Switches

When the flowrate plug-in has been loaded, the following set of partitioning switches are added to rwfilter. To pass the filter, the record must pass the test implied by each switch. The form of the argument to each switch is described below. The partitioning switches are:

--payload-bytes=INTEGER_RANGE

Check whether the payload byte count is within INTEGER_RANGE.

--payload-rate=DECIMAL_RANGE

Check whether the average number of payload bytes seen per second in the flow is within DECIMAL_RANGE.

--packets-per-second=DECIMAL_RANGE

Check whether the average number of packets per second in the flow is within DECIMAL_RANGE.

--bytes-per-second=DECIMAL_RANGE

Check whether the average number of bytes per second in the flow is within DECIMAL_RANGE.

An INTEGER_RANGE is a range of two non-negative integers, and a DECIMAL_RANGE is a range of two non-negative decimal values with accuracy up to 0.0001. The ranges are specified as two values separated by a hyphen, MIN-MAX; for example 1-500 or 5.0-10.031. If a single value is given (e.g., 3.14), the range consists of that single value. The upper limit of the range may be omitted, such as 1-, in which case the upper limit is set to the maximum possible value.

rwcut, rwsort, and, rwuniq Switches

--fields=FIELDS

FIELDS refers to a list of fields to use for the operation. The flowrate plug-in adds the following fields for display, sorting, and grouping using the rwcut(1), rwsort(1), and rwuniq(1) tools:

payload-bytes

Print, sort by, or group by the number of bytes of payload.

payload-rate

Print, sort by, or group by the bytes of payload seen per second.

pckts/sec

Print, sort by, or group by the packets seen per second.

bytes/sec

Print, sort by, or group by the bytes seen per second.

bytes/packet

Print, sort by, or group by the average number of bytes contained in each packet.

ENVIRONMENT

SILK_PATH

This environment variable gives the root of the install tree. As part of their search for the flowrate.so plug-in, the SiLK applications check the directories $SILK_PATH/lib/silk, $SILK_PATH/share/lib and $SILK_PATH/lib.

SILK_PLUGIN_DEBUG

When set to 1, the SiLK applications print status messages to the standard error as they attempt to find and open the flowrate.so plug-in.

FILES

SiLK applications look for the flowrate.so plug-in the the following locations. ($SILK_PATH is value of the SILK_PATH environment variable, if it is set; the use of /usr/local/ assumes the application is installed in the /usr/local/bin/ directory.)

  $SILK_PATH/lib/silk/flowrate.so
  $SILK_PATH/share/lib/flowrate.so
  $SILK_PATH/lib/flowrate.so
  /usr/local/lib/silk/flowrate.so
  /usr/local/share/lib/flowrate.so
  /usr/local/lib/flowrate.so

If the fields and/or switches are not available in an application, verify that flowrate.so is installed in the correct location. To aid in debugging, one may invoke:

  env SILK_PLUGIN_DEBUG=1 rwcut

to print the directory paths where rwcut is looking for flowrate.so.

SEE ALSO

rwcut(1), rwfilter(1), rwsort(1), rwuniq(1)