RWTOTAL(1)

NAME
rwtotal - Count how much traffic matched specific keys

SYNOPSIS
  rwtotal {--sip-first-8 | --sip-first-16 | --sip-first-24 |
        --sip-last-8 | --sip-last-16 | --dip-first-8 |
        --dip-first-16 | --dip-first-24 | --dip-last-8 |
        --dip-last-16 | --sport | --dport | --proto | --packets |
        --bytes | --duration | --icmp-code}
        [--summation] [--min-bytes=COUNT] [--max-bytes=COUNT]
        [--min-packets=COUNT] [--max-packets=COUNT]
        [--min-records=COUNT] [--max-records=COUNT] [--skip-zeroes]
        [--no-titles] [--no-columns] [--column-separator=CHAR]
        [--no-final-delimiter] [{--delimited | --delimited=CHAR}]
        [--print-filenames] [--copy-input=PATH] [--output-path=PATH]
        [--pager=PAGER_PROG] [--site-config-file=FILENAME] [FILES...]

  rwtotal --help

  rwtotal --version

DESCRIPTION
rwtotal reads SiLK Flow records from files named on the command line or from the standard input, bins those records by the user-specified specified key, computes the volume per bin (record count and sums of packets and bytes), and prints the bins and their volumes.

By default, rwtotal prints a bin for every possible key, even when the volume for that bin is zero. Use the --skip-zeroes switch to suppress the printing of these empty bins.

Use the --summation switch to include a row giving the volume for all flow records.

The maximum key value that rwtotal supports is 16,777,215. When the key field is --bytes or --packets, rwtotal will create a bin for all unique values up to 16,777,214. The final bin (16,777,215) will consist of all values greater than 16,777,214.

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.

One and only one of the following counting keys is required:

--sip-first-8
    Key on the first 8 bits of the source IP address

--sip-first-16
    Key on the first 16 bits of the source IP address

--sip-first-24
    Key on the first 24 bits of the source IP address

--sip-last-8
    Key on the last 8 bits of the source IP address

--sip-last-16
    Key on the last 16 bits of the source IP address

--dip-first-8
    Key on the first 8 bits of the destination IP address

--dip-first-16
    Key on the first 16 bits of the destination IP address

--dip-first-24
    Key on the first 24 bits of the destination IP address

--dip-last-8
    Key on the last 8 bits of the destination IP address

--dip-last-16
    Key on the last 16 bits of the destination IP address

--sport
    Key on the source port.

--dport
    Key on the destination port.

--proto
    Key on the protocol.

--packets
    Key on the number of packets in the record

--bytes
    Key on the number of bytes in the record

--duration
    Key on the duration of the record.

--icmp-code
    Key on the ICMP type and code. This switch will assume that all incoming records are ICMP.

The following options affect the output:

--summation
    Print as the final row a total of the values in each column.

--min-bytes=COUNT
    Disable printing of bins with fewer than COUNT bytes. By default, all bins are printed.

--max-bytes=COUNT
    Disable printing of bins with more than COUNT bytes. By default, all bins are printed.

--min-packets=COUNT
    Disable printing of bins with fewer than COUNT packets. By default, all bins are printed.

--max-packets=COUNT
    Disable printing of bins with more than COUNT packets. By default, all bins are printed.

--min-records=COUNT
    Disable printing of bins with fewer than COUNT flow records. By default, all bins are printed.

--max-records=COUNT
    Disable printing of bins with more than COUNT flow records. By default, all bins are printed.

--skip-zeroes
    Disable printing of bins with no traffic. By default, all bins are printed.

--no-titles
    Turn off column titles. By default, titles are printed.

--no-columns
    Disable fixed-width columnar output.

--column-separator=C
    Use specified character between columns and after the final column. When this switch is not specified, the default of '|' is used.

--no-final-delimiter
    Do not print the column separator after the final column. Normally a delimiter is printed.

--delimited
--delimited=C
    Run as if --no-columns --no-final-delimiter --column-sep=C had been specified. That is, disable fixed-width columnar output; if character C is provided, it is used as the delimiter between columns instead of the default '|'.

--print-filenames
    Print to the standard error the names of input files as they are opened.

--copy-input=PATH
    Copy all binary input to the specified file or named pipe. PATH can be "stdout" to print flows to the standard output as long as the --output-path switch has been used to redirect rwtotal's ASCII output.

--output-path=PATH
    Determine where the output of rwtotal (ASCII text) is written. If this option is not given, output is written to the standard output.

--pager=PAGER_PROG
    When output is to a terminal, invoke the program PAGER_PROG to view the output one screen full at a time. This switch overrides the SILK_PAGER environment variable, which in turn overrides the PAGER variable. If the value of the pager is determined to be the empty string, no paging will be performed and all output will be printed to the terminal.

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

--help
    Print the available options and exit.

--version
    Print the version number and information about how SiLK was configured, then exit the application.

EXAMPLES
To see all the addresses hit in a network:

  rwfilter --start-date=2003/03/01:00 --end-date=2003/03/01:00 \
        --proto=6 --pass=stdout --daddress=10.10.10.x | \
        rwtotal --dip-last-8 --skip-zero
    dIP_Last8|        Records|          Bytes|        Packets|
            3|              1|             40|              1|
           20|             28|           9480|            160|
          129|              1|             40|              1|
          138|              1|             96|              2|
          143|              4|            160|              4|
          234|              1|             40|              1|

To see all the protocols:

  rwfilter --start-date=2003/03/01:00 --end-date=2003/03/01:00 \
        --pass=stdout --proto=0-255 | \
        rwtotal --proto --skip-zero
     protocol|        Records|          Bytes|        Packets|
            1|           1655|         252323|           3200|
            6|          34891|      257610646|         334912|
           17|           2940|         831567|           5032|
           50|            294|         397875|           1899|

To see all the source class a's:

  rwfilter --start-date=2003/03/01:00 --end-date=2003/03/01:00 \
        --pass=stdout --proto=0-255 | \
        rwtotal --sip-first-8 --skip-zero
   sip_First8|        Records|          Bytes|        Packets|
            0|              2|            192|              3|
           10|          32290|      195154985|         601424|
           ...

ENVIRONMENT

SILK_PAGER
    When set to a non-empty string, rwtotal automatically invokes this program to display its output a screen at a time. If set to an empty string, rwtotal does not automatically page its output.

PAGER
    When set and SILK_PAGER is not set, rwtotal automatically invokes this program to display its output a screen at a time.

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, rwtotal 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, rwtotal checks for a file named silk.conf in the directories $SILK_PATH/share/silk and $SILK_PATH/share.

SEE ALSO
rwfilter(1), rwaddrcount(1), rwstats(1), rwuniq(1)

BUGS
rwtotal replicates some functionality in rwuniq(1) (most notably when rwuniq checks by port or protocol), but rwtotal uses an array internally instead of a hash-table, so access is faster and the output is sorted. The use of an array prevents rwtotal from using complete IP addresses, the way rwuniq does, but it also ensures that rwtotal will not run out of memory.

When used in an IPv6 environment, rwtotal will process every record as long as the IP address is not part of the key. When aggregating by the IP address, rwstats will attempt to convert any IPv6 addresses to IPv4. Records that can be converted will be processed, all other records will be silently ignored. rwtotal will not be modified to support IPv6 addresses; use rwuniq(1) instead.

rwtotal is also similar to rwaddrcount(1) and rwstats(1).