rwgeoip2ccmap(1)

NAME
rwgeoip2ccmap - Create a country code prefix map from a GeoIP Legacy file

SYNOPSIS
  rwgeoip2ccmap [--mode={auto|ipv4|ipv6}]
        [--input-file=FILENAME] [--output-file=FILENAME] [--dry-run]
        [--note-add=TEXT] [--note-file-add=FILENAME]
        [--invocation-strip]

  rwgeoip2ccmap --help

  rwgeoip2ccmap --version

Legacy Synopsis

  rwgeoip2ccmap {--csv-input | --v6-csv-input | --encoded-input}
        [--input-file=FILENAME] [--output-file=FILENAME] [--dry-run]
        [--note-add=TEXT] [--note-file-add=FILENAME]
        [--invocation-strip]

DESCRIPTION
Prefix maps provide a way to map field values to string labels based on a user-defined map file. The country code prefix map, typically named country_codes.pmap, is a special prefix map that maps an IP address to a two-letter country code. It uses the country codes defined by the Internet Assigned Numbers Authority (<http://www.iana.org/root-whois/index.html>).

The country code prefix map is based on the GeoIP Legacy Country(R) or free GeoLite Legacy database created by MaxMind(R) and available from <http://www.maxmind.com/>. (Note: You must use the MaxMind legacy database format. rwgeoip2ccmap does not support the GeoIP2 and GeoLite2 databases.)

The database is available several formats, and rwgeoip2ccmap supports the following formats:

GeoIPCountryCSV.zip
    a compressed (zip(1)) textual file containing an IPv4 range, country name, and county code in a comma separated value (CSV) format.

GeoIPv6.csv.gz
    a compressed (gzip(1)) textual file containing an IPv6 range, country name, and county code in a CSV format. This file only contains IPv6 data. If you use this file to create your country code prefix map, any IPv4 addresses will have the unknown value "--". See "EXAMPLES" for a way to merge the IPv6 and IPv4 files.

GeoIP.dat.gz
    a compressed (gzip(1)) binary file containing specially encoded data for IPv4 address ranges.

GeoIPv6.dat.gz
    a compressed (gzip(1)) binary file containing specially encoded data for both IPv4 and IPv6 address ranges.

The country code prefix map file is used by ccfilter(3) to map IP addresses to country codes in various SiLK tools. The ccfilter feature allows you to

•   partition by country codes in rwfilter(1)

•   display the country codes in rwcut(1)

•   sort by the country codes in rwsort(1)

•   bin by the country codes in rwstats(1), rwuniq(1), and rwgroup(1).

The rwpmaplookup(1) command can use the country code mapping file to display the country code for textual IP addresses.

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.

--mode={auto|ipv4|ipv6|binary}
    Specify the type of the input which determines type of prefix map rwgeoip2ccmap creates. When not specified, rwgeoip2ccmap determines the type of prefix map to create based on the first line of input. The modes are:

    auto
        Determine the type of prefix map to create based on the IP addresses appear on the first line of input. This is the default mode.

    ipv4
        Read textual input containing IPv4 addresses in a comma separated value format and create an IPv4 prefix map. Any IPv6 addresses in the ::ffff:0:0/96 netblock are mapped to an IPv4 address and all other IPv6 addresses are ignored.

    ipv6
        Read textual input containing IPv6 addresses in a comma separated value format and create an IPv6 prefix map. Any IPv4 addresses are mapped into the ::ffff:0:0/96 netblock.

    binary
        Read specially-encoded binary input containing either IPv4 or IPv6 addresses and create the appropriate type of prefix map. Since SiLK 3.12.2.

--input-file=FILENAME
    Read the CSV or binary forms of the GeoIP Legacy country code database from FILENAME. You may use "stdin" or "-" to represent the standard input. When this switch is not provided, the input is read from the standard input unless the standard input is a terminal. rwgeoip2ccmap will read textual input from the terminal if the standard input is explicitly specified as the input. Since SiLK 3.12.0.

--output-file=FILENAME
    Write the binary country code prefix map to FILENAME. You may use "stdout" or "-" to represent the standard output. When this switch is not provided, the prefix map is written to the standard output unless the standard output is connected to a terminal. Since SiLK 3.12.0.

--dry-run
    Check the syntax of the input file and do not write the output file. Since SiLK 3.12.0.

--note-add=TEXT
    Add the specified TEXT to the header of the output file as an annotation. This switch may be repeated to add multiple annotations to a file. To view the annotations, use the rwfileinfo(1) tool. Since SiLK 3.12.0.

--note-file-add=FILENAME
    Open FILENAME and add the contents of that file to the header of the output file as an annotation. This switch may be repeated to add multiple annotations. Currently the application makes no effort to ensure that FILENAME contains text; be careful that you do not attempt to add a SiLK data file as an annotation. Since SiLK 3.12.0.

--invocation-strip
    Do not record the command used to create the prefix map in the output. When this switch is not given, the invocation is written to the file's header, and the invocation may be viewed with rwfileinfo(1). Since SiLK 3.12.0.

--csv-input
    Assume the input is the CSV GeoIP Legacy country code data for IPv4. This switch is deprecated, and it should be replaced with --mode=ipv4.

--v6-csv-input
    Assume the input is the CSV GeoIP Legacy country code data for IPv6. This switch is deprecated, and it should be replaced with --mode=ipv6.

--encoded-input
    Assume the input is the specially-encoded binary form of the GeoIP Legacy country code data for either IPv4 or IPv6. This switch is deprecated, and it should be replaced with --mode=binary.

--help
    Print the available options and exit.

--version
    Print the version number and exit the application.

EXAMPLES
The following examples show how to create the country code prefix map file, country_codes.pmap, from various forms of input. Once you have created the country_codes.pmap file, you should copy it to /usr/share/silk/country_codes.pmap so that the ccfilter(3) plug-in can find it. Alternatively, you can set the SILK_COUNTRY_CODES environment variable to the location of the country_codes.pmap file.

In these examples, the dollar sign ($) represents the shell prompt. Some input lines are split over multiple lines in order to improve readability, and a backslash (\) is used to indicate such lines.

  IPv4 Comma Separated Values File
Download the CSV version of the MaxMind GeoIP Legacy Country database for IPv4, GeoIPCountryCSV.zip. (Use the Legacy form of the GeoIP or GeoLite database since the GeoIP2 and GeoLite2 databases are not supported.) Running unzip -l on the zip file should show a single file, GeoIPCountryWhois.csv.) To expand this file, use the unzip(1) utility; by using the -p option to unzip, you can pass the output of unzip directly to rwgeoip2ccmap:

 $ unzip -p GeoIPCountryCSV.zip | \
       rwgeoip2ccmap --mode=ipv4 > country_codes.pmap

  IPv6 Comma Separated Values File
If you download the IPv6 version of the MaxMind GeoIP Legacy Country database, use the following command to create the country_codes.pmap file:

 $ gzip -d -c GeoIPv6.csv.gz | \
       rwgeoip2ccmap --mode=ipv6 > country_codes.pmap

Since the GeoIPv6.csv.gz file only contains IPv6 addresses, the resulting country_codes.pmap file will display the unknown value ("--") for any IPv4 address. See the next example for a solution.

  IPv6 and IPv4 Comma Separated Values Files
To create a country_codes.pmap mapping file that supports both IPv4 and IPv6 addresses, download both of the Legacy CSV files (GeoIPv6.csv.gz and GeoIPCountryCSV.zip) from MaxMind.

You need to uncompress both files and feed the result as a single stream to the standard input of rwgeoip2ccmap. This can be done in a few commands:

 $ gzip -d GeoIPv6.csv.gz
 $ unzip GeoIPCountryCSV.zip
 $ cat GeoIPv6.csv GeoIPCountryWhois.csv | \
       rwgeoip2ccmap --mode=ipv6 > country_codes.pmap

Alternatively, if your shell supports it, you may be able to use a subshell to avoid having to store the uncompressed data:

 $ ( gzip -d -c GeoIPv6.csv.gz ; unzip -p GeoIPCountryCSV.zip ) | \
       rwgeoip2ccmap --mode=ipv6 > country_codes.pmap

SEE ALSO
ccfilter(3), rwpmaplookup(1), rwfilter(1), rwcut(1), rwsort(1), rwstats(1), rwuniq(1), rwgroup(1), rwpmapbuild(1), silk(7), gzip(1), zip(1), unzip(1), <http://dev.maxmind.com/geoip/legacy/geolite/>

NOTES
Support for the binary form of the GeoIP Legacy format was removed in SiLK 3.12.0 and restored in SiLK 3.12.2.