Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
rwpmapcat(1)			SiLK Tool Suite			  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/local/share/silk/country_codes.pmap
       /usr/local/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/local/share/silk/address_types.pmap
       /usr/local/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.

SiLK 3.19.1			  2021-02-28			  rwpmapcat(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | ENVIRONMENT | FILES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rwpmapcat&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help