addrtype(3)

NAME
addrtype - SiLK Plug-In to label IPs as internal or external

SYNOPSIS
  rwfilter [--stype=ID] [--dtype=ID] ...

  rwcut --fields=stype,dtype ...

  rwsort --fields=stype,dtype ...

  rwstats --fields=stype,dtype ...

  rwuniq --fields=stype,dtype ...

DESCRIPTION
The Address Type plug-in provides a way to map an IP address to an integer denoting the IP as internal, external, or non-routable. With this plug-in SiLK flow records can be partitioned (rwfilter(1)), displayed (rwcut(1)), sorted (rwsort(1)), and counted (rwstats(1) and rwuniq(1)) by the "type" of address.

The Address Type is a specialized form of the Prefix Map, pmapfilter(3), where the following labels are assumed to exist and to have the indicated values:

0   denotes a (non-routable) IP addresss

1   denotes an IP address internal to the monitored network

2   denotes an IP address external to the monitored network

Creating the prefix map file that maps IPs to one of these labels is described in the "MAPPING FILE" section below.

OPTIONS
The Address Type plug-in provides the following options to the indicated applications.

  rwfilter Switches

--stype=ID
    When ID is 0, pass the record if its source address is non-routable. When ID is 1, pass the record if its source address is internal. When ID is 2, pass the record if its source address is external (i.e., routable and not internal). When ID is 3, pass the record if its source address is not internal (non-routable or external).

--dtype=ID
    As --stype for the destination IP address.

  rwcut, rwsort, rwstats, and rwuniq Switches

--fields=FIELDS
    FIELDS refers to a list of fields to use for the operation. The Address Type plug-in makes two additional fields, "stype" (alias 16) and "dtype" (17) available for display, sorting, and counting using the rwcut(1), rwsort(1), rwstats(1), and rwuniq(1) tools:

    stype,16
        For the source IP address, prints 0 if the address is non-routable, 1 if it is internal, or 2 if it is routable and external.

    dtype,17
        as stype, except for the destination address

MAPPING FILE
To denote an address as "non-routable", "internal", or "external" at your site, you will need to create the address_types.pmap file and install it in the appropriate location (see the "FILES" section below).

The rwpmapbuild(1) tool creates a prefix map file from a text file. A template for the text file is available in $SILK_PATH/share/silk/addrtype-templ.txt. The text file used to create address_types.pmap must include the following section to ensure that IPs are mapped to the integer values that the addrtype.so expects:

  #    Numerical mappings of labels

  label 0             non-routable
  label 1             internal
  label 2             external

  #    Default to "external" for all un-defined ranges.

  default             external

The remainder of the file can list CIDR blocks and a label for each block:

  # RFC1918 space
  10.0.0.0/8          non-routable
  172.16.0.0/12       non-routable
  192.168.0.0/16      non-routable

  # My IP space (CMU)
  128.2.0.0/16        internal

Once the text file is saved to disk, use rwpmapbuild to create address_types.pmap:

  rwpmapbuild --input addresses.txt --output address_types.pmap

ENVIRONMENT

SILK_ADDRESS_TYPES
    This environment variable allows the user to specify the Address Type mapping file that the addrtype plug-in uses. The value may be a complete path or a file relative to SILK_PATH. If the variable is not specified, the code looks for a file named address_types.pmap as specified in the "FILES" section below.

SILK_PATH
    This environment variable gives the root of the install tree. As part of their search for the Address Type plug-in, addrtype.so, the SiLK applications check the directories $SILK_PATH/lib/silk, $SILK_PATH/share/lib and $SILK_PATH/lib. The SiLK applications check the directories $SILK_PATH/share/silk and $SILK_PATH/share for the Address Type mapping file, address_types.pmap.

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 addrtype.so plug-in.

FILES
SiLK applications look for the Address Type 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/addrtype.so
  $SILK_PATH/share/lib/addrtype.so
  $SILK_PATH/lib/addrtype.so
  /usr/local/lib/silk/addrtype.so
  /usr/local/share/lib/addrtype.so
  /usr/local/lib/addrtype.so

If the fields and/or switches are not available in an application, verify that addrtype.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 addrtype.so.

The tools will look for the data file that maps IPs to labels in the following locations:

  $SILK_PATH/share/silk/address_types.pmap
  $SILK_PATH/share/address_types.pmap
  /usr/local/share/silk/address_types.pmap
  /usr/local/share/address_types.pmap

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

BUGS
Prefix map files do not support IPv6 addresses.