NAME

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

VERSION

version 0.106

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 WHOIS is run later on any IP that falls within the same netblock, the cached information is returned (unless it's 'stale').

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:

db_filename

SQLite database file name. 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). Otherwise, a 'miss' could cause later nearby requests to suffer a false miss.

whois_table_name

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

Default: 'whois_cache'.

sth_select_request

A pre-built SQL handle for finding requests in the database.

sth_insert_request

SQL handle for inserting or updating requests into the database. See sth_insert_whois below for usage and note.

sth_insert_whois

SQL handle for inserting or updating WHOIS records to the database. Used like this (given a Local::DBRecord object $rec):

my @vals = map { $rec->$_ } $self->whois_sql_columns;
$self->sth_insert_whois->execute(@vals);

NOTE: the SQL uses 'INSERT OR REPLACE', so all @vals should be valid.

timeout

Timeout for running the whois command.

Default: 30 seconds.

stale_timeout

Number of seconds until a cached record is considered stale.

Default: 30 days worth of seconds.

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

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).

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).

whois_sql_columns

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

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.