ccfilter(3)

NAME
ccfilter - SiLK Plug-In to map IPs to country codes

SYNOPSIS
  rwcut --fields=scc,dcc ...

  rwgroup --fields=scc,dcc ...

  rwsort --fields=scc,dcc ...

  rwstats --fields=scc,dcc ...

  rwuniq --fields=scc,dcc ...

DESCRIPTION
The Country Code plug-in provides a mapping from an IP address to two-letter, lowercase abbreviation of the country that "owns" the IP address. With this plug-in, an IP's country code can displayed (rwcut(1)), sorted (rwsort(1)), grouped (rwgroup(1)), and counted (rwstats(1)) and (rwuniq(1)). (Although rwfilter(1) does not use this plug-in, it does use the same data file.)

The abbreviations used by the Country Code plug-in are those used by the Root-Zone Whois Index (see for example <http://www.iana.org/cctld/cctld-whois.htm>) or one of the following special codes:

--  N/A (e.g. private and experimental reserved addresses)

a1  anonymous proxy

a2  satellite provider

o1  other

Creating the Prefix Map (pamp) file that maps an IP to its country code requires the GeoIP Country(R) or free GeoLite database created by MaxMind, available from <http://www.maxmind.com>, as described in the "MAPPING FILE" section below.

OPTIONS
The Country Code plug-in makes available two additional keys to the --fields switch in the rwcut(1), group(1), rwsort(1), rwstats(1), and rwuniq(1) tools:

scc,18
    Print, sort, and/or count the flow records by the country code designation of the source IP address

dcc,19
    As scc for the destination address

MAPPING FILE
To map from IP addresses to country codes you will need to create the country_codes.pmap data file and install it in the appropriate location (see the "FILES" section below), or specify the path to the file in the SILK_COUNTRY_CODES environment variable.

The prefix map data file is based on the GeoIP Country(R) or free GeoLite database created by MaxMind and available from <http://www.maxmind.com/>. We do not distribute the database nor the data file, but we provide Perl scripts that will convert the GeoIP database to the format that ccfilter.so expects.

MaxMind distributes multiple versions of their GeoIP Country database; one is a free evaluation copy that is "97% accurate". In addition, they sell versions with higher accuracy, and they offer various subscription services.

The rwgeoip2ccmap(1) program converts the MaxMind GeoIP file to the form that the SiLK tools require.

ENVIRONMENT

SILK_COUNTRY_CODES
    This environment variable allows the user to specify the country code mapping file that rwfilter and the ccfilter plug-in use. 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 country_codes.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 Country Code plug-in, ccfilter.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 Country Code mapping file, country_codes.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 ccfilter.so plug-in.

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

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

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

  $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

SEE ALSO
rwcut(1), rwfilter(1), rwgroup(1), rwsort(1), rwstats(1), rwuniq(1), rwgeoip2ccmap(1), rwip2cc(1)

BUGS
Prefix map files do not support IPv6 addresses.