pmapfilter(3)

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

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

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

  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.

    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.

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.

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

BUGS
Prefix map files do not support IPv6 addresses.