NAME

pmapfilter - SiLK Prefix map plug-in (pmapfilter.so)

SYNOPSIS

  rwfilter --pmap-file=FILENAME [--pmap-saddress=LABELS]
        [--pmap-daddress=LABELS] ...

  rwfilter --pmap-file=FILENAME [--pmap-sport-proto=LABELS]
        [--pmap-dport-proto=LABELS] ...

  rwcut --pmap-file=FILENAME --fields=FIELDS
        [--pmap-column-width=NUM]

  rwuniq --pmap-file=FILENAME --fields=FIELDS
        [--pmap-column-width=NUM]

  rwsort --pmap-file=FILENAME --fields=FIELDS

DESCRIPTION

Prefixmaps provide a way to map field values to string labels based on a user-defined map file. Using the prefixmap plug-in you can you can partition, count, sort and display records based on arbitrary labels. Two types of maps are currently implemented:

IP maps

map IP ranges (e.g., 128.2.0.0/16 -> CMU)

protocol/port maps

map protocol/port ranges (e.g., 6/80 -> http)

For more information on generating a map file for use with the plug-in see the manual page for rwpmapbuild(1).

OPTIONS

Generic Prefixmap Switches

When using a prefixmap, the following switch is required:

--pmap-file=FILENAME

FILENAME refers to a prefixmap file generated using rwpmapbuild(1).

rwfilter Switches - IP Prefix Maps

--pmap-saddress=LABELS

Match records with a source IP address that maps to a label contained in the list of labels in LABELS. Only works with IP prefix maps.

--pmap-daddress=LABELS

Match records with a destination IP address that maps to a label contained in the list of labels in LABELS. Only works with IP prefix maps.

rwfilter Switches - Port/protocol Prefix Maps

--pmap-sport-proto=LABELS

Match records with a source port and protocol combination that maps to a label contained in the list of labels in LABELS. Only works with port/protocol prefix maps.

--pmap-dport-proto=LABELS

Match records with a destination port and protocol combination that maps to a label contained in the list of labels in LABELS. Only works with port/protocol prefix maps.

rwcut, rwuniq and rwsort Switches

--fields=FIELDS

FIELDS refers to a list of fields to use for the operation. The prefixmap plug-in makes two additional fields, sval and dval available for display, counting and sorting using the rwcut(1), rwuniq(1) and rwsort(1) tools.

sval

The value from the mapping file for the source. For an IP-based pmap file, this corresponds to the source IP. For a proto-port pmap, it is the protocol/source-port.

dval

As sval for the destination IP address or protocol/destination-port. It is possible to encode type and code in a proto-port pmap, but it will only work if used for the dport-proto.

--pmap-column-width=NUM

Set the maximum number of characters to use when displaying the textual value of any field in rwcut and rwuniq to NUM. This switch must precede the --fields switch. This switch is useful for pmap files that have very long dictionary values.

EXAMPLES

Given a map called mynetwork.pmap which maps internal hosts to internal and external hosts to external, look for strictly internal traffic.

  rwfilter --pmap-file=mynetwork.pmap \
           --pmap-saddress="internal" --pmap-daddress="internal" \
           --pass=output.rwf \
           input.rwf

Given a mapping from protocol/ports pairs to well-known services associated with those pairs (e.g., based on /etc/services), display counts amount of traffic (in bytes) incoming to hosts on those ports:

  rwuniq --fields=dval incoming.rwf

For more information about constructing maps see the rwpmapbuild documentation.

FILES

SiLK applications look for the Prefixmap 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 tool exists in the /usr/local/bin/ directory.)

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

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

  env SILK_DYNLIB_DEBUG=1 rwcut

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

NOTES

The prefixmap code is still preliminary; although the basic interface to the plug-in will very likely remain the same, including the continued support of the sval and dval fields, users should be prepared to update scripts when a new version of prefixmap is made available. Planned improvements to pmapfilter will include support more than one pmap at a time, better column names for output, and other convenience features.

SEE ALSO

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

BUGS

Prefix map files do not support IPv6 addresses.