NAME

Net::Whois::RIPE - a pure-Perl implementation of the RIPE Database client.

VERSION

Version 2.008001

SYNOPSIS

This is an evolution of the module I (Arnaud Assad) inherited from Luis Motta Campos. Which was a complete rewrite of the old version of the module inherited from Paul Gampe. It incorporated new concepts Luis have learned while working at the RIPE NCC between Nov 2007 and Jan 2010.

It intends to provide a cleaner, simpler, and complete implementation of a RIPE Database client.

The usage should remain mostly the same:

  use Net::Whois::RIPE;

  my $whois = Net::Whois::RIPE->new( %options );
  $iterator = $whois->query( 'AS333' );

From version 2.005000 you can also use the Net::Whois::Generic interface that mimics Net::Whois::Object while offering access to data from other sources than RIPE (AFRINIC, APNIC)

  use Net::Whois::RIPE;

  my @objects = Net::Whois::Generic->query( 'ORG-AFNC1-AFRINIC' );

Please see Net::Whois::Generic documentation for more details

Of course, comments are more than welcome. If you believe you can help, please do not hesitate in contacting me.

BACKWARD COMPATIBILITY

I've choose to break backwards compatibility with older versions of the Net::Whois::RIPE module for several different reasons. I will try to explain and justify them here, as design documentation. I will also strive to provide practical solutions for porting problems, if any.

Architecture

The old module provided it's own Iterator implementation. This was common practice 10 years ago, when the module was initially written. I believe Perl has a stable and useful standard implementation of Iterators now, and adopted it instead of maintaining my own. This allows me to reduce the necessary code base without losing features.

Query Options

From release 2.0 onwards, Net::Whois::RIPE will allow almost all query options understanded by the RIPE Database Server. I bumped in the lack of options myself, sometimes, and I believe other programmers can also use the extra features offered.

There are nice, sane defaults provided for most of the options. This should make it possible for a beginner to just ignore all options and settings and still be able to make some use of the module.

Memory Footprint

I had the intention of reducing the memory footprint of this module when doing heavy-lifting. I still don't have measurements, but that was the idea behind adopting an Iterator wrapping the IO::Socket used to return results.

Better Data Structures

A production release of this module will be able to feed a RPSL::Parser with RPSL objects extracted from the RIPE Database and return full-fledged objects containing a parsed version of the text (way more useful than a text blob, I believe). Net::Whois::Object (from release 2.00_010) is the first attempt toward this goal.

  # You can now do
  my @objects = Net::Whois::Object->query( 'AS333' );

  # And manipulate the object the OO ways
  for my $object (@objects) {
    print $object->remarks();
  }

METHODS

new( %options )

Constructor. Returns a new Net::Whois::RIPE object with an open connection to the RIPE Database service of choice (defaulting to "whois.ripe.net:43").

The %options hash migth contain configuration options for the RIPE Database server. Not all options provided by the RIPE Database server are suitable for this implementation, but the idea is to provide everything someone can show a use for. The options currently recognized are:

hostname (IPv4 address or DNS name. Default is "whois.ripe.net"): The hostname or IP address of the service to connect to
port (integer, default is 43): The TCP port of the service to connect to
timeout (integer, default is 5): The time-out (in seconds) for the TCP connection.
keepalive (boolean, default is "false"): Wherever we want ("true") or not ("false") to keep the connection to the server open. This option implements the functionality available through RIPE Database's "-k" parameter.
referral (boolean, default is "false"): When true, prevents the server from using the referral mechanism for domain lookups, so that the RIPE Database server returns an object in the RIPE Database with the exact match with the lookup argument, rather than doing a referral lookup.
recursive (boolean, default is "false"): When set to "true", prevents recursion into queried objects for personal information. This prevents lots of unsolicited objects from showing up on queries.
grouping (boolean, default is "false"): When "true" enables object grouping in server responses. There's little utility to enable this option, as the objects will be parsed and returned on a much reasonable format most of the time. For the brave or more knowledgeable people that want to have they answers in plain text, this can help stablishing a 'good' ordering for the RPSL objects returned by a query ('good' is RIPE NCC's definition of 'good' in this case).
unfiltered (boolean, default is "false"): When "true" enables unfiltered object output responses. This produces objects that can be presented back to the RIPE Database for updating.
types (list of valid RIPE Database object types, default is empty, meaning all types): Restrict the RPSL object types allowed in the response to those in the list. Using this option will cause the Net::Whois::RIPE object to query the RIPE Database for the available object types for validating the list. The response will be cached for speed and bandwidth.
disconnected (boolean, default is "false"): Prevents the constructor from automatically opening a connection to the service specified (conneting the socket is the default behavior). When set ("true"), the programmer is responsible for calling "connect" in order to stablish a connection to the RIPE Database service desired.

hostname( [$hostname] )

Accessor to the hostname. Accepts an optional hostname, always return the current hostname.

port()

Accessor to the port. Accepts an optional port, always return the current port.

timeout()

Accessor to the timeout configuration option. Accepts an optional timeout, always return the current timeout.

keepalive()

Accessor to the keepalive configuration option. Accepts an optional keepalive, always return the current keepalive.

referral()

Accessor to the referral configuration option. Accepts an optional referral, always return the current referral.

recursive()

Accessor to the recursive configuration option. Accepts an optional recursive, always return the current recursive.

grouping()

Accessor to the grouping configuration option. Accepts an optional grouping, always return the current grouping.

unfiltered()

Accessor to the unfiltered configuration option.

connect()

Initiates a connection with the current object's configuration.

ios()

Accessor to the IO::Select object coordinating the I/O to the IO::Socket object used by this module to communicate with the RIPE Database Server. You shouldn't use this object, but the "send()" and "query( $query_string )" methods instead.

socket()

Read-only accessor to the IO::Socket object used by this module.

send()

Sends a message to the RIPE Database server instance to which we're connected to. Dies if it cannot write, or if there's no open connection to the server.

Return "true" if the message could be written to the socket, "false" otherwise.

reconnect()

Reconnects to the server in case we lost connection.

disconnect()

Disconnects this client from the server. This renders the client useless until you call "connect()" again. This method is called by "DESTROY()" as part of an object's clean-up process.

is_connected()

Returns "true" if this instance is connected to the RIPE Database service configured.

DESTROY()

Net::Whois::RIPE object destructor. Called by the Perl interpreter upon destruction of an instance.

query( $query_string )

Sends a query to the server. Returns an Iterator object that will return one RPSL block at a time.

object_types()

Return a list of known object types from the RIPE Database.

RIPE currently returns 21 types (Limerik have been removed): as-block as-set aut-num domain filter-set inet6num inetnum inet-rtr irt key-cert mntner organisation peering-set person poem poetic-form role route route6 route-set rtr-set

Due to some strange mis-behaviour in the protocol (or documentation?) the RIPE Database server won't allow a keep-alive token with this query, meaning the connection will be terminated after this query.

CAVEATS

No IPv6 Support: There's no support for IPv6 still on this module. I'm planning to add it in a future version.
Tests Depend On Connectivity: As this is the initial alpha release, there is still some work to do in terms of testing. One of the first things I must work on is to eliminate the dependency on connectivity to the RIPE Database.
Current Interface is not Backwards-Compatible: I plan to implement a drop-in replacement to the old interface soon, as an extension to this module. For now, this module just breaks compatibility with the old interface. Please read the full discussion about compatibility with older version of the NET::Whois::RIPE in the "BACKWARD COMPATIBILITY" section.

BUGS

Please report any bugs or feature requests to "bug-net-whois-ripe at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=net-whois-ripe>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::Whois::RIPE

You can also look for information at:

RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=net-whois-ripe>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/net-whois-ripe>
CPAN Ratings
<http://cpanratings.perl.org/d/net-whois-ripe>
Search CPAN
<http://search.cpan.org/dist/Net-Whois-RIPE>

AUTHORS

Arnaud Assad, "aassad at cpan.org" Luis Motta Campos, "<lmc at cpan.org>" Paul Gampe Kevin Backer

ACKNOWLEDGEMENTS

Thanks to DOOLTA (<https://www.doolta.com>) for allowing Arnaud Assad to work on this module during some of his office hours.

Thanks to Luis Motta Campos for allowing me (Arnaud Assad) the maintenance of this module on CPAN;

Thanks to RIPE NCC for allowing Luis Motta Campos to work on this during some of his office hours.

Thanks to Paul Gampe for allowing Luis Motta Campos to handle me the maintenance of this module on CPAN;

Thanks to Paul Gampe and Kevin Backer for writing previous versions of this module;

Thanks to Carlos Fuentes for the nice patch with bugfixes for version 2.00_008. Thanks to Moritz Lenz for all his contributions Thanks to Noris Network AG for allowing him to contribute to this module.

COPYRIGHT & LICENSE

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