Net::IP::Identifier::WhoisCache - Run whois, cache result in a database
version 0.111
use Net::IP::Identifier::WhoisCache;
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.
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
Creates a new Net::IP::Identifier::WhoisCache object. The following options are available, and are also available as accessors:
Get/set a flag to produce diagnosics.
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'.
The database object (see perldoc DBI).
The table name for the request cache within the database. Requests must map exactly to a previous request (netblocks must match).
The table name for the WHOIS data cache within the database.
Default: 'whois_cache'.
Get/set the timeout (in seconds) for running the whois command.
Default: 30 seconds.
Get/set the number of seconds until a cached record is considered stale.
Default: 30 days worth of seconds.
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.
Returns an SQL handle for finding requests.
Returns an SQL handle for adding request to database.
Returns an SQL handle for finding WHOIS record by ID.
Returns an SQL handle for finding WHOIS record by range_str.
Returns an SQL handle for deleting IPs in the database.
Returns an SQL handle for deleting IPs based on pattern match.
Returns an SQL handle for adding to the WHOIS database.
Returns an SQL handle get the max ID value in WHOIS database.
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.
Creates and returns a Net::IP::Identifier::Net object from $req_str. If creation dies, prints the error to STDOUT and returns ''.
$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).
The integer ID for this record. This is an INTEGER PRIMARY KEY (autoincrementing) column.
The IP range represented by this record.
The WHOIS information as a single string
When WHOIS information was fetched (seconds since the epoch)
High 64 bits of starting IP in range
Low 64 bits of starting IP in range
High 64 bits of last IP in range
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.
Splits a Math::BigInt. Returns the high 64 bits and the low 64 bits (as Math::BigInts).
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).
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).
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).
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.
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.
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.
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).
Returns the maximum ID field in the whois_cache table.
Reid Augustin <reid@hellosix.com>
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.
To install Local::Payload, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Local::Payload
CPAN shell
perl -MCPAN -e shell install Local::Payload
For more information on module installation, please visit the detailed CPAN module installation guide.