NAME

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

SYNOPSIS

  rwfilter --pmap-file=MAPNAME:FILENAME [--pmap-file=MAPNAME:FILENAME ...]
        [--pmap-src-MAPNAME=LABELS] [--pmap-dst-MAPNAME=LABELS] 
        [--pmap-any-MAPNAME=LABELS] ...

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

  rwgroup --pmap-file=MAPNAME:FILENAME [--pmap-file=MAPNAME:FILENAME ...]
        --id-fields=FIELDS

  rwsort --pmap-file=MAPNAME:FILENAME [--pmap-file=MAPNAME:FILENAME ...]
        --fields=FIELDS

  rwstats --pmap-file=MAPNAME:FILENAME [--pmap-file=MAPNAME:FILENAME ...]
        --fields=FIELDS [--pmap-column-width=NUM]

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

DESCRIPTION

Prefix maps provide a way to map values on a SiLK Flow record to string labels based on a user-defined mapping file. A prefix map is created with the rwpmapbuild(1) application. Using the prefix map plug-in, pmapfilter.so, you can you can partition, group, sort and display records based on arbitrary labels. Two types of maps are currently implemented:

ip: maps a IPv4 CIDR block or a range of IPv4 addresses to a label. Example: 128.2.0.0/16 -> CMU
proto-port: maps a range defined by protocol/port pairs to a label. Example: 6/80 -> http

A prefix map can be a given map-name, either when the prefix map is created or on the command line when the prefix map is read. A map-name provided on the command line overrides the map-name in the file. Multiple prefix map files are supported, as long as each is associated with a unique map-name. When no map-name is provided, pmapfilter.so processes the prefix map in legacy mode. When in legacy mode, only one prefix map file is allowed.

OPTIONS

Generic Prefix Map Switches

When using a prefix map, at least one --pmap-file switch is required:

--pmap-file=MAPNAME:FILENAME: FILENAME refers to a prefix map file generated using rwpmapbuild. MAPNAME is a name that will be used to refer to the fields or options specific to that prefix map.
--pmap-file=FILENAME: When a MAPNAME is not specified as part of the argument, the prefix map file is checked to determine if it a map-name was set when the prefix map was created (see rwpmapbuild). If so, that map-name is used. If not, the prefix map is processed in legacy mode for backward compatibility. See LEGACY below for more information.

Multiple --pmap-file switches are allowed as long as each prefix map is associated with a unique map-name.

rwfilter Switches

--pmap-src-MAPNAME=LABELS: If the prefix map associated with MAPNAME is an IP prefix map, this matches records with a source IPv4 address that maps to a label contained in the list of labels in LABELS.; If the prefix map associated with MAPNAME is a proto-port prefix map, this matches records with a protocol and source port combination that maps to a label contained in the list of labels in LABELS.
--pmap-dst-MAPNAME=LABELS: Similar to --pmap-src-MAPNAME, but uses the destination IP or the protocol and destination port.
--pmap-any-MAPNAME=LABELS: If the prefix map associated with MAPNAME is an IP prefix map, this matches records with a source or destination IPv4 address that maps to a label contained in the list of labels in LABELS.; If the prefix map associated with MAPNAME is a proto-port prefix map, this matches records with a protocol and a source or destination port combination that maps to a label contained in the list of labels in LABELS.

rwcut, rwgroup, rwsort, rwstats, and rwuniq Switches

--fields=FIELDS: FIELDS refers to a list of fields to use for the operation. Each prefix map associated with MAPNAME creates two additional fields, src-MAPNAME and dst-MAPNAME, available for display, sorting, and counting using the rwcut(1), rwgroup(1), rwsort(1), rwstats(1), and rwuniq(1) tools.
--pmap-column-width=NUM: Set the maximum number of characters to use when displaying the textual value of any prefix map field in rwcut, rwstats, and rwuniq to NUM. This switch must precede the --fields switch. This switch is useful for prefix map files that have very long dictionary values.

LEGACY

The following options are deprecated, but are maintained for backwards compatibility. When running in legacy mode, only one prefix map file may be used.

LEGACY SWITCHES

When a prefix map is loaded into rwfilter in legacy mode, the following switches are defined:

--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: As --pmap-saddress for the destination IP.
--pmap-any-address=LABELS: Match records with a source or destination IP address that maps to a label contained in the list of labels in LABELS. Only works with IP prefix maps.
--pmap-sport-proto=LABELS: Match records with a protocol and source port combination that maps to a label contained in the list of labels in LABELS. Only works with proto-port prefix maps.
--pmap-dport-proto=LABELS: As --pmap-saddress for the protocol and destination port.
--pmap-any-port-proto=LABELS: Match records with a protocol and a source or destination port combination that maps to a label contained in the list of labels in LABELS. Only works with proto-port prefix maps.

LEGACY FIELDS

When a prefix map is loaded into rwcut, rwgroup, rwsort, rwstats, or rwuniq in legacy mode, the following fields are made available to the --fields switch:

sval: The value from the prefix map file for the source. For an IP-based prefix map file, this corresponds to the source IP. For a proto-port prefix map, it is the protocol/source-port.
dval: As sval for the destination IP address or protocol/destination-port.

EXAMPLES

Given a prefix map file mynetwork.pmap which maps internal hosts to the label internal and external hosts to the label external, one can select internal-to-internal traffic by their labels:

  rwfilter --pmap-file=mynet:mynetwork.pmap \
           --pmap-src-mynet="internal" --pmap-dst-mynet="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 of the amount of traffic (in bytes) incoming to hosts on those ports:

  rwuniq --pmap-file=service:service.pmap --fields=dst-service \
         incoming.rwf

For more information about constructing prefix maps see the rwpmapbuild documentation.

ENVIRONMENT

SILK_PATH: This environment variable gives the root of the install tree. As part of their search for the prefix map plug-in, pmapfilter.so, 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 pmapfilter.so plug-in.

FILES

SiLK applications look for the Prefix map 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_PLUGIN_DEBUG=1 rwcut

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

BUGS

Prefix map files do not support IPv6 addresses.