pmapfilter(3)

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.