NAME

Net::IP::Identifier::WhoisCache - Run whois, cache result in a database

VERSION

version 0.111

SYNOPSIS

use Net::IP::Identifier::WhoisCache;

DESCRIPTION

Net::IP::Identifier::WhoisCache runs WHOIS on an IP or netblock. The result is cached in an SQLite database file. If the same IP or netblock is requested later, the cached information is returned (unless it's 'stale'). Note that different requests must fetch WHOIS again even if the new request falls within a block covered by a previous request because the block may be subdivided such that the new request returns a different WHOIS result.

Methods

run

This module is a modulino, meaning it may be used as a module or as a script. The run method is called when there is no caller and it is used as a script. run parses the command line arguments and calls new() to create the object. If a filename is specified on the command line, that file is read as the input, otherwise the command line is used. If no arguments are provided on the command line, STDIN is used.

Input (from a file, the command line, or STDIN) is scanned for things that look like IP (v4 or v6) addresses or blocks. For each matching item, the Net::IP::Identifier::WhoisCache object's get_whois method (see below) is called on it, and the result is printed to STDOUT.

Example:

Net::IP::Identifier::WhoisCache.pm 8.8.8.8

or

echo 8.8.8.8 | Net::IP::Identifier::WhoisCache.pm

prints WHOIS information about this Google-owned netblock.

For command line help, run:

WhoisCache.pm --help

new( [ options ] )

Creates a new Net::IP::Identifier::WhoisCache object. The following options are available, and are also available as accessors:

verbose

Get/set a flag to produce diagnosics.

db_filename

SQLite database file name. If it doesn't exist, it is created and initialized.

When run as a script, this can be changed on the command line with:

--db_filename new_name.sqlite

Default: '$ENV{HOME}/.whois_cache.sqlite'.

db

The database object (see perldoc DBI).

request_table_name

The table name for the request cache within the database. Requests must map exactly to a previous request (netblocks must match).

whois_table_name

The table name for the WHOIS data cache within the database.

Default: 'whois_cache'.

timeout

Get/set the timeout (in seconds) for running the whois command.

Default: 30 seconds.

stale_timeout

Get/set the number of seconds until a cached record is considered stale.

Default: 30 days worth of seconds.

force_cache_miss

Set/get a flag to force get_whois to suffer a cache miss.

When used from the command line, --miss (or -m) sets this flag.

sth_select_request

Returns an SQL handle for finding requests.

sth_insert_request

Returns an SQL handle for adding request to database.

sth_select_whois_by_id

Returns an SQL handle for finding WHOIS record by ID.

sth_select_whois_by_range_str

Returns an SQL handle for finding WHOIS record by range_str.

sth_delete_ranges

Returns an SQL handle for deleting IPs in the database.

sth_delete_pattern

Returns an SQL handle for deleting IPs based on pattern match.

sth_insert_whois

Returns an SQL handle for adding to the WHOIS database.

sth_max_id

Returns an SQL handle get the max ID value in WHOIS database.

parse_fh ( $file_handle );

Parse input from $file_handle, looking for things that look like IP (v4 or v6) addresses or ranges. Call get_whois on each found item, and print the result to STDOUT.

ip_str_to_net ( $req_str )

Creates and returns a Net::IP::Identifier::Net object from $req_str. If creation dies, prints the error to STDOUT and returns ''.

get_whois ( $ip)

$ip is a string representing a netblock (individual IP, CIDR, or net range), or it can be a Net::IP or a Net::IP::Identifier::Net object. If $ip is already in the cache, and the cached information is not stale, returns a Local::DBRecord object which includes the cached WHOIS result. Otherwise, runs WHOIS and update the cache.

The Local::DBRecord object contains the following methods for retrieving the database information

Can die if $ip is a netblock that cannot be represented by a CIDR (meaning it's boundaries are not on a binary power block).

id

The integer ID for this record. This is an INTEGER PRIMARY KEY (autoincrementing) column.

range_str

The IP range represented by this record.

result

The WHOIS information as a single string

fetch_time

When WHOIS information was fetched (seconds since the epoch)

first_high

High 64 bits of starting IP in range

first_low

Low 64 bits of starting IP in range

last_high

High 64 bits of last IP in range

last_low

Low 64 bits of last IP in range

The same method names, when called on the Net::IP::Identifier::WhoisCache object, return the database column index.

split_ip ( $ip_as_Math::BigInt )

Splits a Math::BigInt. Returns the high 64 bits and the low 64 bits (as Math::BigInts).

combine_ip ( $high, $low, $ipv6 )

The inverse of split_ip, it recombines $high and $low back into an IP address. If $ipv6 is false $high is zero and $low is less than 0x1_0000_0000 it is recombined into an IPv4 address (N.N.N.N), otherwise it will be an IPv6 address (N:N:N:N:N:N:N:N - not condensed).

delete ( $pattern )

Removes one or more cache entries from the database. if $pattern looks like an IP or IP range, then all entries that contain the IP or range are deleted. Otherwise, the WHOIS information of all entries is scanned and if $pattern matches, the entry is deleted. $pattern is an SQL matching expression, so '%' deletes all cache entries (same effect as deleting the database file).

find_in_cache ( $req_net )

Search the database for $req_net. If found, it will point to a particular WHOIS record (unless it's been deleted), and that record is returned (unless it's stale). If the WHOIS record isn't found for any reason, it calls cache_miss.

Returns a Local::DBRecord object (see get_whois above).

fetch_whois_rec( $net )

Runs 'jwhois' attempting to fetch WHOIS information about $net. If no information can be retrieved (after several retries), throws and exception. Otherwise, the returned information is parsed and a Local::DBRecord is created and returned.

parse_failed ( [ 'reason' ] )

Set/get a reason why parsing of the WHOIS information failed. Can be either that no netblock representing the original request was extracted, or because no specific entity could be determined for the netblock.

cache_miss ( $req_net );

Run WHOIS on $req_net (a Net::IP::Identifier::Net object) and cache result. Add a new WHOIS record, or update if there is an old (stale) one.

Returns a Local::DBRecord object (see get_whois above).

request_sql_columns

whois_sql_columns

Return the column names used in the request_cache or whois_cache tables. In array context, return an array of the names. In scalar context, return the names joined by commas (suitable for use in SQL statements).

max_id

Returns the maximum ID field in the whois_cache table.

SEE ALSO

Net::IP

Net::IP::Identifier::Net

Net::IP::Identifier::Plugins::Google (and other plugins in this directory)

Module::Pluggable

AUTHOR

Reid Augustin <reid@hellosix.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Reid Augustin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.