NAME

IP::Country::DB_File - IP to country translation based on DB_File

SYNOPSIS

perl -MIP::Country::DB_File -e IP::Country::DB_File::update -- \
    -f -b -r

my $ipcc = IP::Country::DB_File->new();
$ipcc->inet_atocc('1.2.3.4');
$ipcc->inet_atocc('host.example.com');

my $ipcc = IP::Country::DB_File->new('ipcc.db', 1);
IP::Country::DB_File::fetchFiles();
$ipcc->build();
IP::Country::DB_File::removeFiles();

DESCRIPTION

IP::Country::DB_File is a light-weight module for fast IP address to country translation based on DB_File. The country code database is stored in a Berkeley DB file.

The database is built from the publically available statistics files of the Regional Internet Registries. Currently, the files are downloaded from the following hard-coded locations:

ftp://ftp.arin.net/pub/stats/arin/delegated-arin-latest
ftp://ftp.ripe.net/pub/stats/ripencc/delegated-ripencc-latest
ftp://ftp.afrinic.net/pub/stats/afrinic/delegated-afrinic-latest
ftp://ftp.apnic.net/pub/stats/apnic/delegated-apnic-latest
ftp://ftp.lacnic.net/pub/stats/lacnic/delegated-lacnic-latest

You have to build the database before you can lookup country codes. This can be done directly in Perl, or by calling the update subroutine from the command line. Since the country code data changes constantly, you should consider updating the database from time to time. It should be no problem to use a database built on a different machine as long as the libdb versions are compatible.

This module tries to be API compatible with the other IP::Country modules. The installation of IP::Country is not required.

CONSTRUCTOR

new

my $ipcc = IP::Country::DB_File->new([ $dbFile ], [ $writeAccess ]);

Creates a new object and opens the database file $dbFile. $dbFile defaults to ipcc.db.

$writeAccess is a boolean that should be true if you plan to build or modify the database. If you only make lookups you should pass a false value. $writeAccess defaults to false.

OBJECT METHODS

build

$ipcc->build([ $dir ]);

Builds a database from geo IP source files in directory $dir. $dir defaults to the current directory. This method creates or overwrites the database file.

inet_atocc

$ipcc->inet_atocc($string);

Looks up the country code of host $string. $string can either be an IP address in dotted quad notation or a hostname. Returns a country code as defined in the geo IP source files. This code consists of two uppercase letters. In most cases it is an ISO-3166-1 alpha-2 country code, but there are also codes like 'EU' for Europe.

Returns undef if there's no country code listed for the IP address.

inet_ntocc

$ipcc->inet_ntocc($string);

Like inet_atocc but works with a stringified numeric IP address.

db_time

$ipcc->db_time();

Returns the mtime of the DB file.

FUNCTIONS

fetchFiles

IP::Country::DB_File::fetchFiles([ $dir ]);

Fetches geo IP source files from the FTP servers of the RIR and stores them in $dir. $dir defaults to the current directory. This method requires Net::FTP.

This method only fetches files and doesn't build the database yet.

removeFiles

IP::Country::DB_File::removeFiles([ $dir ]);

Deletes the previously fetched geo IP source files in $dir. $dir defaults to the current directory.

update

You can call this subroutine from the command line to update the country code database like this:

perl -MIP::Country::DB_File -e IP::Country::DB_File::update -- \
    [options] [dbfile]

dbfile is the database file and defaults to ipcc.db. Options include

-f

fetch files

-b

build database

-r

remove files

-d [dir]

set directory for geo IP source files

You should provide at least one of the -f, -b or -r options, otherwise this routine does nothing.

SEE ALSO

IP::Country

AUTHOR

Nick Wellnhofer <wellnhofer@aevum.de>

COPYRIGHT AND LICENSE

Copyright (C) Nick Wellnhofer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.

cpanm IP::Country::DB_File

perl -MCPAN -e shell
install IP::Country::DB_File