pmapfilter - User-defined labels for IPs and protocol/port pairs

  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]

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 file, 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, SiLK processes the prefix map in legacy mode. When in legacy mode, only one prefix map file is allowed.

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 explicitly as part of the argument, the prefix map file is checked to determine if 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.

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

src-MAPNAME

The value for the source from the prefix map file associated with MAPNAME. 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.

dst-MAPNAME

As src-MAPNAME for the destination IP address or protocol/destination-port. It is possible to encode type and code in a proto-port prefix map, but it will only work when used for the protocol/destination-port.

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

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

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.

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.

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.

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

Prefix map files do not support IPv6 addresses.