The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
IPDR-0.40
River stage zero No dependents
++
/ IPDR::Collection::CiscoSSL

NAME

IPDR::Collection::CiscoSSL - IPDR Collection Client (Cisco Specification)

VERSION

Version 0.40

SYNOPSIS

This is a IPDR module primarily written to connect and collect data using IPDR from a Motorola BSR6400 CMTS. Some work is still required.

It is not very pretty code, nor perhaps the best approach for some of the code, but it does work and will hopefully save time for other people attempting to decode the IPDR protocol (even using the specification it is hard work).

An example configuration for Cisco is

    cable metering destination 192.168.1.1 5000 192.168.1.2 4000 1 15 secure

    crypto ca trustpoint IPDR
      enrollment terminal 
      crl optional
      exit
    crypto ca authenticate IPDR
    <cut and paste your certficate key when promtped>
    quit

To generate a key pair (self signed cert and host key) use the following openssl command

    openssl req -x509 -days 365 -newkey rsa:1024 -keyout hostkey.pem \
           -nodes -out hostcert.pem

You will be prompted to enter some information. If you wish you can just leave them all blank (or default entries). Two files will be created hostkey.pem and hostcert.pem, use these for the variables SSLKeyFile and SSLCertFile respectively.

The IP addresses and ports specified are those of a collector that the CMTS will send data to. The Cisco implementation does not provide all IPDR functionality.

An example on how to use this module is shown below. It is relatively simple use the different module for Cisco and CiscoSSL, all others use Client.

    #!/usr/local/bin/perl

    use strict;
    use IPDR::Collection::CiscoSSL;

    my $ipdr_client = new IPDR::Collection::CiscoSSL (
                        [
                        VendorID => 'IPDR Client',
                        ServerIP => '192.168.1.1',
                        ServerPort => '5000',
                        SSLKeyFile => 'hostkey.pem',
                        SSLCertFile => 'hostcert.pem',
                        Timeout => 2,
                        Type => 'docsis',
                        DataHandler => \&display_data,
                        ]
                        );

    # Check for data from the IPDR server.
    my $status = $ipdr_client->connect();

    if ( !$status )
        {
        print "Status was '".$ipdr_client->return_status()."'\n";
        print "Error was '".$ipdr_client->return_error()."'\n";
        exit(0);
        }

    $ipdr_client->check_data_available();

    exit(0);

    sub display_data
    {
    my ( $remote_ip ) = shift;
    my ( $remote_port ) = shift;
    my ( $data ) = shift;
    my ( $self ) = shift;

    foreach my $host ( sort { $a<=> $b } keys %{$data} )
        {
        print "Host  is '$host' \n";
        foreach my $document_attribute ( keys %{${$data}{$host}{'document'}} )
                {
                print "Document id '$document_attribute' ";
                print "value is '${$data}{$host}{'document'}{$document_attribute}'\n";
                }

        foreach my $sequence ( keys %{${$data}{$host}} )
                {
                next if $sequence=~/^document$/i;
                foreach my $attribute ( keys %{${$data}{$host}{$sequence}} )
                        {
                        print "Sequence is '$sequence' Attribute is '$attribute' ";
                        print "value is '${$data}{$host}{$sequence}{$attribute}'\n";
                        }
                }
        }
    return 1;
    }

This is the most basic way to access the data. There are multiple scripts in the examples directory which will allow you to collect and process the IPDR data.

FUNCTIONS

new

The new construct builds an object ready to used by the rest of the module and can be passed the following variables

    VendorID - This defaults to 'Generic Client' but can be set to any string

    ServerIP -

         Client: This is the IP address of the destination exporter.
         Cisco: This is the IP address of the local server to receive the data

    ServerPort -

         Client: This is the port of the destination exporter.
         Cisco: This is the port on the local server which will be used to
                receive data

    Type -

         Cisco: Only applied to Cisco and currently only 'docsis' works.
                If omitted then the raw XML data is returned

    XMLDirectory -

         Cisco: Only applied to the Cisco module and will force the writing
                of the XML to the directory specific, filename being the IP
                address of the sending router.

    SSLKeyFile
        
         SSL Certificate file, should be fully pathed

    SSLHostFile

         SSL Host filename, should be fully pathed

    RemoteAddr          
        
         IP address of remote server to send on data to

    RemotePort           

         Port of remote server to send on data to

    RemoteTimeOut  

         Timeout for connection

    RemoteSpeed  
        
         Speed at which to send data. It is a number in Mbps, the 
         default is 10. You can use decimal such as 0.5 to mean 500kbps.

    RemoteMulti
      
         This paramter allows multiple destinations to receive XML. The
         list is a comma separate list of remote end points and their
         parameters. An example would be

         10.1.1.1:9000:10,20.1.1.1:9000:50

         The parameters are as follows

         Destination IP:Destination Port:Destination Bandwidth

         You can omit destination bandwidth and it will default to 10

    Force32BitMode

         This turns OFF all 64bit checks. Useful for running with older
         routers such as Cisco7200 UBRs.
    
    KeepAlive - This defaults to 60, but can be set to any value.
    Capabilities - This defaults to 0x01 and should not be set to much else.
    TimeOut - This defaults to 5 and is passed to IO::Socket (usefulness ?!)
    DataHandler - This MUST be set and a pointer to a function (see example)
    DEBUG - Set at your peril, 5 being the highest value.

An example of using new is

    my $ipdr_client = new IPDR::Collection::CiscoSSL (
                        [
                        VendorID => 'IPDR Client',
                        ServerIP => '192.168.1.1',
                        ServerPort => '5000',
                        SSLKeyFile => 'hostkey.pem',
                        SSLCertFile => 'hostcert.pem',
                        DataHandler => \&display_data,
                        Type => 'docsis',
                        Timeout => 2,
                        ]
                        );

connect

This uses the information set with new and attempts to connect/setup a client/server configuration. The function returns 1 on success, 0 on failure. It should be called with

    $ipdr_client->connect();

check_data_available

This function controls all the communication for IPDR. It will, when needed, send data to the DataHandler function. It should be called with

    $ipdr_client->check_data_available();

ALL OTHER FUNCTIONs

The remaining of the functions should never be called and are considered internal only. They do differ between Client and Cisco however both module provide the same generic methods, high level, so the internal workings should not concern the casual user.

AUTHOR

Andrew S. Kennedy, <shamrock at cpan.org>

BUGS

Please report any bugs or feature requests to bug-ipdr-cisco at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPDR-Collection-Cisco. 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 IPDR::Collection::CiscoSSL

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2011 Andrew S. Kennedy, all rights reserved.

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