rwpmapcat(1)

NAME
rwpmapcat - Print each range and label present in a prefix map file

SYNOPSIS
  rwpmapcat [--output-types={mapname | type | ranges | labels}]
        [--ignore-label=LABEL] [--ip-label-to-ignore=IP_ADDRESS]
        [--left-justify-labels] [--no-cidr-blocks]
        [--ip-format=FORMAT] [--integer-ips] [--zero-pad-ips]
        [--no-titles] [--no-columns] [--column-separator=C]
        [--no-final-delimiter] [{--delimited | --delimited=C}]
        [--output-path=PATH] [--pager=PAGER_PROG]
        [ { --map-file=PMAP_FILE | PMAP_FILE
            | --address-types | --address-types=MAP_FILE
            | --country-codes | --country-codes=MAP_FILE } ]

  rwpmapcat --help

  rwpmapcat --version

DESCRIPTION
rwpmapcat reads a prefix map file created by rwpmapbuild(1) or rwgeoip2ccmap(1) and prints its contents.

By default, rwpmapcat prints the range/label pairs that exist in the prefix map. Use the --output-types switch to print additional information or information other than the range/label pairs.

When printing the range/label pairs of a prefix map file that contain IP address data, rwpmapcat defaults to printing the range as an address block in CIDR notation and the label associated with that block. To print the ranges as a starting address and ending address, specify the --no-cidr-blocks switch.

If the prefix map file contains protocol/port pairs, rwpmapcat prints three fields: the starting protocol and port separated by a slash ("/"), the ending protocol and port, and the label.

The printing of ranges having a specific label may be suppressed with the --ignore-label switch. To have rwpmapcat to look up a label based on an IP address and then ignore all entries with that label, pass the IP address to the --ip-label-to-ignore switch.

To print the contents of an arbitrary prefix map file, one may pipe the file to rwpmapcat's standard input, name the file as the argument to the --map-file switch, or name the file on the command line.

To print the contents of the default country codes mapping file (see ccfilter(3)), specify the --country-codes switch with no argument. To print the contents of a specific country codes mapping file, name that file as the argument to the --country-codes switch.

For printing the address types mapping file (see addrtype(3)), use the --address-types switch which works similarly to the --country-codes switch.

OPTIONS
Option names may be abbreviated if the abbreviation is unique or is an exact match for an option. A parameter to an option may be specified as --arg=param or --arg param, though the first form is required for options that take optional parameters.

Many of options are ignored unless rwpmapcat is printing the range/label pairs present in the prefix map file.

--map-file=PMAP_FILE
    Specify the path of the prefix map file to print. If this switch is omitted and neither --country-codes nor --address-types is specified, the name of the file to be read is taken as the first non-switch command-line argument. If no argument is given, rwpmapcat attempts to read the map from the standard input.

--address-types
    Print the contents of the address types mapping file (addrtype(3)) specified by the SILK_ADDRESS_TYPES environment variable, or in the default address types mapping file if that environment variable is not set. This switch may not be combined with the --map-file or --country-codes switches.

--address-types=ADDRTYPE_FILE
    Print the contents of the address types mapping file specified by ADDRTYPE_FILE.

--country-codes
    Print the contents of the country code mapping file (ccfilter(3)) specified by the SILK_COUNTRY_CODES environment variable, or in the default country code mapping file if that environment variable is not set. This switch may not be combined with the --map-file or --address-types switches.

--country-codes=COUNTRY_CODE_FILE
    Print the contents of the country code mapping file specified by COUNTRY_CODE_FILE.

--output-types={type | mapname | label | ranges}
    Specify the type(s) of output to produce. When this switch is not provided, the default is to print ranges. Specify multiple types as a comma separated list of names; regardless of the order in which the types are given, the output will appear in the order shown below. Country-code prefix map files only support the "ranges" output type. A type can be specified using the shortest unique prefix for the type. The available types are:

    type
        Print the type of this prefix map file. The value will be one of "IPv4-address", "IPv6-address", or "proto-port". The type will be preceded by the string "TYPE:" and a space character unless --no-titles is specified.

    mapname
        Print the name that is stored in the prefix map file. This mapname is used to generate switch names and field names when this prefix map is used with rwfilter(1), rwcut(1), rwgroup(1), rwsort(1), rwstats(1), and rwuniq(1). See pmapfilter(3) for details. The mapname will be preceded by the string "MAPNAME:" and a space character unless --no-titles is specified.

    label
        Print the names of the labels that exist in the prefix map file. The labels are printed left-justified, one per line, with no delimiter. The labels will be preceded by "LABELS:" on its own line unless --no-titles is specified. If ranges is also specified, a blank line will separate the labels and the range/label columns.

    ranges
        Print the range and label for each block in the prefix map file. If the prefix map contains protocol/port pairs, the output will contain three columns (startPair, endPair, label), where startPair and endPair contain protocol/port. If the prefix map contains IP addresses, the form of the output will depend on whether --no-cidr-blocks is specified. When it is not specified, the output will contain two columns (ipBlock, label), where ipBlock contains the IP range in CIDR notation. If --no-cidr-blocks is specified, the output will contain three columns: startIP, endIP, label.

--ignore-label=LABEL
    For the ranges output-type, do not print entries whose label is LABEL. By default, all entries in the prefix map file are printed.

--ip-label-to-ignore=IP_ADDRESS
    For the ranges output-type, find the label associated with the IP address IP_ADDRESS and ignore all ranges that match that label. By default, all entries in the prefix map are printed.

--left-justify-labels
    For the ranges output-type, left-justify the labels when columnar output is printed. Normally, the labels are right-justified.

--no-cidr-blocks
    Cause each IP address block to be printed as a starting and ending IP address. By default, IP addresses are grouped into CIDR blocks. This switch is ignored for prefix map files containing protocol/port pairs.

--ip-format=FORMAT
    Specify how IP addresses are printed, where FORMAT is a comma-separated list of the arguments described below. This switch is ignored for prefix map files containing protocol/port pairs. When this switch is not specified, the SILK_IP_FORMAT environment variable is checked for a value and that format is used if it is valid. The default FORMAT is "canonical" according to whether the prefix map file is IPv4 or IPv6. Since SiLK 3.7.0.

    canonical
        Print IP addresses in the canonical format. For an IPv4 prefix map, use dot-separated decimal (192.0.2.1). For an IPv6 prefix map, use colon-separated hexadecimal ("2001:db8::1") or a mixed IPv4-IPv6 representation for IPv4-mapped IPv6 addresses (the ::ffff:0:0/96 netblock, e.g., "::ffff:192.0.2.1") and IPv4-compatible IPv6 addresses (the ::/96 netblock other than ::/127, e.g., "::192.0.2.1").

    no-mixed
        Print IP addresses in the canonical format (192.0.2.1 or "2001:db8::1") but do not used the mixed IPv4-IPv6 representations. For example, use "::ffff:c000:201" instead of "::ffff:192.0.2.1". Since SiLK 3.17.0.

    decimal
        Print IP addresses as integers in decimal format. For example, print 192.0.2.1 and "2001:db8::1" as 3221225985 and 42540766411282592856903984951653826561, respectively.

    hexadecimal
        Print IP addresses as integers in hexadecimal format. For example, print 192.0.2.1 and "2001:db8::1" as "c00000201" and "20010db8000000000000000000000001", respectively. Note: This setting does not apply to CIDR prefix values which are printed as decimal.

    zero-padded
        Make all IP address strings contain the same number of characters by padding numbers with leading zeros. For example, print 192.0.2.1 and "2001:db8::1" as 192.000.002.001 and "2001:0db8:0000:0000:0000:0000:0000:0001", respectively. For IPv6 addresses, this setting implies "no-mixed", so that "::ffff:192.0.2.1" is printed as "0000:0000:0000:0000:0000:ffff:c000:0201". As of SiLK 3.17.0, may be combined with any of the above, including "decimal" and "hexadecimal". As of SiLK 3.18.0, the values of CIDR prefix are also zero-padded.

    The following arguments modify certain IP addresses prior to printing. These arguments may be combined with the above formats.

    map-v4
        When the prefix map contains only IPv4 addresses, change all IPv4 addresses to IPv4-mapped IPv6 addresses (addresses in the ::ffff:0:0/96 netblock) prior to formatting. Since SiLK 3.17.0.

    unmap-v6
        When the prefix map contains IPv6 addresses, change any IPv4-mapped IPv6 addresses (addresses in the ::ffff:0:0/96 netblock) to IPv4 addresses prior to formatting. Since SiLK 3.17.0.

    The following argument is also available:

    force-ipv6
        Set FORMAT to "map-v4","no-mixed".

--integer-ips
    Print IP addresses as integers. This switch is equivalent to --ip-format=decimal, it is deprecated as of SiLK 3.7.0, and it will be removed in the SiLK 4.0 release

--zero-pad-ips
    Print IP addresses as fully-expanded, zero-padded values in their canonical form. This switch is equivalent to --ip-format=zero-padded, it is deprecated as of SiLK 3.7.0, and it will be removed in the SiLK 4.0 release.

--no-titles
    Turn off column titles. By default, titles are printed.

--no-columns
    Disable fixed-width columnar output.

--column-separator=C
    Use specified character between columns and after the final column. When this switch is not specified, the default of '|' is used.

--no-final-delimiter
    Do not print the column separator after the final column. Normally a delimiter is printed.

--delimited
--delimited=C
    Run as if --no-columns --no-final-delimiter --column-sep=C had been specified. That is, disable fixed-width columnar output; if character C is provided, it is used as the delimiter between columns instead of the default '|'.

--output-path=PATH
    Write the textual output to PATH, where PATH is a filename, a named pipe, the keyword "stderr" to write the output to the standard error, or the keyword "stdout" or "-" to write the output to the standard output (and bypass the paging program). If PATH names an existing file, rwpmapcat exits with an error unless the SILK_CLOBBER environment variable is set, in which case PATH is overwritten. If this switch is not given, the output is either sent to the pager or written to the standard output. Since SiLK 3.15.0.

--pager=PAGER_PROG
    When output is to a terminal, invoke the program PAGER_PROG to view the output one screen full at a time. This switch overrides the SILK_PAGER environment variable, which in turn overrides the PAGER variable. If the --output-path switch is given or if the value of the pager is determined to be the empty string, no paging is performed and all output is written to the terminal.

--help
    Print the available options and exit.

--version
    Print the version number and information about how SiLK was configured, then exit the application.

EXAMPLES
In the following examples, the dollar sign ("$") represents the shell prompt. The text after the dollar sign represents the command line. Lines have been wrapped for improved readability, and the back slash ("\") is used to indicate a wrapped line.

rwpmapbuild(1) creates the prefix map file sample.pmap from the textual input.

 $ cat sample.txt
 mode      ip
 map-name  addrtype
 label     0  non-routable
 label     1  internal
 label     2  external
 default   external
          0.0.0.0/8  non-routable
         10.0.0.0/8  non-routable
        127.0.0.0/8  non-routable
     169.254.0.0/16  non-routable
      172.16.0.0/12  non-routable
       192.0.2.0/24  non-routable
     192.168.0.0/16  non-routable
 255.255.255.255/32  non-routable
 $ rwpmapbuild --input-path=sample.txt --output-path=sample.txt

Invoking rwpmapcat with the name of the file as its only argument prints the range-to-label contents of the prefix map file, and the contents are printed as CIDR blocks if the file contains IP addresses.

 $ rwpmapcat sample.pmap | head -10
            ipBlock|       label|
          0.0.0.0/8|non-routable|
          1.0.0.0/8|    external|
          2.0.0.0/7|    external|
          4.0.0.0/6|    external|
          8.0.0.0/7|    external|
         10.0.0.0/8|non-routable|
         11.0.0.0/8|    external|
         12.0.0.0/6|    external|
         16.0.0.0/4|    external|

Use the --no-cidr-blocks switch to print the range as a pair of IPs. The --map-file switch may be use to specify the name of the file.

 $ rwpmapcat --map-file=sample.pmap --no-cidr-block
         startIP|          endIP|       label|
         0.0.0.0|  0.255.255.255|non-routable|
         1.0.0.0|  9.255.255.255|    external|
        10.0.0.0| 10.255.255.255|non-routable|
        11.0.0.0|126.255.255.255|    external|
       127.0.0.0|127.255.255.255|non-routable|
       128.0.0.0|169.253.255.255|    external|
     169.254.0.0|169.254.255.255|non-routable|
     169.255.0.0| 172.15.255.255|    external|
      172.16.0.0| 172.31.255.255|non-routable|
      172.32.0.0|    192.0.1.255|    external|
       192.0.2.0|    192.0.2.255|non-routable|
       192.0.3.0|192.167.255.255|    external|
     192.168.0.0|192.168.255.255|non-routable|
     192.169.0.0|255.255.255.254|    external|
 255.255.255.255|255.255.255.255|non-routable|

The --output-types switch determines what output is produced. Specifying an argument of "label" prints the labels that were specified when the file was built.

 $ rwpmapcat --map-file=sample.pmap --output-types=label
 LABELS:
 non-routable
 internal
 external

Multiple types of output may be requested

 $ rwpmapcat --map-file=sample.pmap --output-types=type,mapname
 TYPE:  IPv4-address
 MAPNAME:  addrtype

Sometimes the content of the prefix map more clear if you eliminate the ranges that were assigned to the default label. There are two ways to filter a label: either specify the label with the --ignore-label switch or find an IP address that has that label and specify the IP address to the --ip-label-to-ignore switch:

 $ cat sample.pmap | rwpmapcat --ignore-label=external
            ipBlock|       label|
          0.0.0.0/8|non-routable|
         10.0.0.0/8|non-routable|
        127.0.0.0/8|non-routable|
     169.254.0.0/16|non-routable|
      172.16.0.0/12|non-routable|
       192.0.2.0/24|non-routable|
     192.168.0.0/16|non-routable|
 255.255.255.255/32|non-routable|

 $ cat sample.pmap | rwpmapcat --ip-label-to-ignore=0.0.0.0 | head -7
            ipBlock|       label|
          1.0.0.0/8|    external|
          2.0.0.0/7|    external|
          4.0.0.0/6|    external|
          8.0.0.0/7|    external|
         11.0.0.0/8|    external|
         12.0.0.0/6|    external|

rwpmapcat also supports viewing the contents of prefix map files containing protocol/port pairs.

 $ rwpmapcat proto.pmap
 startPair|  endPair|                           label|
 ...
       6/0|      6/0|                             TCP|
       6/1|      6/1|                          tcpmux|
       6/2|      6/3|                     compressnet|
       6/4|      6/4|                             TCP|
       6/5|      6/5|                             rje|
       6/6|      6/6|                             TCP|
       6/7|      6/7|                            echo|
       6/8|      6/8|                             TCP|
 ...

As of SiLK 3.8.0, rwpmapcat supports printing the contents of the country code mapping file created by rwgeoip2ccmap(1) (for use in the country code plug-in ccfilter(3)) when the --country-codes switch is used.

 $ rwpmapcat --no-cidr --country-codes=country_codes.pmap | head
         startIP|          endIP|label|
         0.0.0.0|     2.6.190.55|   --|
      2.6.190.56|     2.6.190.63|   gb|
      2.6.190.64|  2.255.255.255|   --|
         3.0.0.0|    4.17.135.31|   us|
     4.17.135.32|    4.17.135.63|   ca|
     4.17.135.64|   4.17.142.255|   us|
      4.17.143.0|    4.17.143.15|   ca|
     4.17.143.16|     4.18.32.71|   us|
      4.18.32.72|     4.18.32.79|   mx|

ENVIRONMENT

SILK_IP_FORMAT
    This environment variable is used as the value for --ip-format when that switch is not provided. Since SiLK 3.11.0.

SILK_PAGER
    When set to a non-empty string, rwpmapcat automatically invokes this program to display its output a screen at a time. If set to an empty string, rwpmapcat does not automatically page its output.

PAGER
    When set and SILK_PAGER is not set, rwpmapcat automatically invokes this program to display its output a screen at a time.

SILK_COUNTRY_CODES
    This environment variable allows the user to specify the country code mapping file to use when the --country-codes switch is specified without an argument. The variable's value may be a complete path or a file relative to SILK_PATH. See the "FILES" section for standard locations of this file.

SILK_ADDRESS_TYPES
    This environment variable allows the user to specify the address type mapping file to use when the --address-types switch is specified without an argument. The variable's value may be a complete path or a file relative to the SILK_PATH. See the "FILES" section for standard locations of this file.

SILK_CLOBBER
    The SiLK tools normally refuse to overwrite existing files. Setting SILK_CLOBBER to a non-empty value removes this restriction.

SILK_PATH
    This environment variable gives the root of the install tree. When searching for configuration files, rwpmapcat may use this environment variable. See the "FILES" section for details.

FILES

${SILK_COUNTRY_CODES}
${SILK_PATH}/share/silk/country_codes.pmap
${SILK_PATH}/share/country_codes.pmap
/usr/share/silk/country_codes.pmap
/usr/share/country_codes.pmap
    Possible locations for the country codes mapping file when the --country-codes switch is specified without an argument.

${SILK_ADDRESS_TYPES}
${SILK_PATH}/share/silk/address_types.pmap
${SILK_PATH}/share/address_types.pmap
/usr/share/silk/address_types.pmap
/usr/share/address_types.pmap
    Possible locations for the address types mapping file when the --address-types switch is specified without an argument.

SEE ALSO
rwpmapbuild(1), rwgeoip2ccmap(1), addrtype(3), pmapfilter(3), ccfilter(3), rwfilter(1), rwcut(1), rwgroup(1), rwsort(1), rwstats(1), rwuniq(1), silk(7)

NOTES
The --country-codes and --address-types switches were added in SiLK 3.8.0.