Installing Additional Perl Libraries

Unified Assurance uses Perl to parse rules. While many Perl libraries are already included, some modules must be externally linked. This section documents how to link in third party Perl modules.

Dependencies

Installing Additional Perl Libraries

This section describes two methods for installing additional Perl libraries in the update-safe $A1BASEDIR/local/lib/perl directory. The first method uses CPAN to install the required library. The second method downloads, builds, tests, and installs a library manually when additional control or troubleshooting is required.

Note:

You still need to rebuild compiled Perl modules after a major Perl upgrade because they may not be binary-compatible with the new Perl version.

Installing Perl Libraries Using CPAN

To install Perl libraries using CPAN:

  1. Log in to the command line of the server as the root user.

  2. Set the Unified Assurance base directory and configure CPAN to install libraries in the update-safe directory:

    export A1BASEDIR=/opt/assure1
export PERL_MM_OPT="INSTALLSITELIB=$A1BASEDIR/local/lib/perl INSTALLSITEARCH=$A1BASEDIR/local/lib/perl"

    Replace /opt/assure1 with the value of $A1BASEDIR if your Unified Assurance base directory differs.

  3. Install the required library. Replace <MODULE> with the Perl module name.

    $A1BASEDIR/vendor/perl/bin/cpan -i <MODULE>

    For example, to install Data::Validate::CSV, run:

    $A1BASEDIR/vendor/perl/bin/cpan -i Data::Validate::CSV

  4. Repeat step 3 for each required dependency before installing the required library.

Installing Perl Libraries Manually

To install Perl libraries manually:

  1. Log in to the command line of the server as the root user.

  2. Create a build directory.

    mkdir -p /opt/src/perl/pm5

  3. Give assure1 user ownership of this directory.

    chown -R assure1:assure1 /opt/src

  4. Switch to the assure1 user:

    su - assure1

  5. Download and extract the required library source archive using the following commands.

    cd /opt/src/perl/pm5
wget <MODULE-ARCHIVE-URL>
tar -zxvf <MODULE-ARCHIVE>
cd <MODULE-DIRECTORY>

    Replace <MODULE-ARCHIVE-URL>, <MODULE-ARCHIVE>, and <MODULE-DIRECTORY> with the applicable values. For example, to download and extract the Data::Validate::IP library, run:

    cd /opt/src/perl/pm5
wget https://cpan.metacpan.org/authors/id/D/DR/DROLSKY/Data-Validate-IP-0.31.tar.gz
tar -zxvf Data-Validate-IP-0.31.tar.gz
cd Data-Validate-IP-0.31

  6. Build the library:

    /opt/assure1/vendor/perl/bin/perl Makefile.PL INSTALLSITELIB=$A1BASEDIR/local/lib/perl INSTALLSITEARCH=$A1BASEDIR/local/lib/perl

  7. Compile the library:

    make

  8. Test the library:

    make test

  9. If the tests complete successfully, install the library in the update-safe directory:

    make install

    Note:

    Make sure to complete the steps from 5 to 9 for all the required dependencies of a library before you install the specific library. For example, Data::Validate::IP requires NetAddr::IP. Its test suite also requires Test::Requires, so install both modules before installing Data::Validate::IP.

  10. Verify each module is installed and can be found by vendorPerl-app by replacing with the Perl module name.

    $A1BASEDIR/vendor/perl/bin/perl -M<MODULE> -le "print $<MODULE>::VERSION"

    For example, to verify if the module for Data::Validate::IP is installed, run: 

    $A1BASEDIR/vendor/perl/bin/perl -MData::Validate::IP -le 'print $Data::Validate::IP::VERSION'

    Note:

    The command completes without errors if vendorPerl-app can locate the library. It does not verify that Unified Assurance scripts or rules can use it.

Verifying Module Access with RunScript

You need to verify if RunScript can access the installed modules for both methods of installation.

To verify if RunScript can find the modules you installed:

  1. Create a temporary test script:

    cd $A1BASEDIR/tmp
vi test.pl

  2. Add the following content to test.pl.

    Replace /opt/assure1 with the value of $A1BASEDIR if it differs.

    #!/opt/assure1/bin/RunScript

use strict;
use warnings;
use <MODULE>;

print "<MODULE> Version: $<MODULE>::VERSION\n";

exit;

    For example, to verify if the module for Data::Validate::IP is accessible by RunScript, run:

    #!/opt/assure1/bin/RunScript

use strict;
use warnings;
use Data::Validate::IP;

print "Data::Validate::IP Version: $Data::Validate::IP::VERSION\n";

exit;

  3. Save the file and run the script:

    $A1BASEDIR/bin/RunScript $A1BASEDIR/tmp/test.pl

  4. Verify that the output displays the installed version of Data::Validate::IP.

Using Additional Libraries

This example shows how to use the installed Net::NTP Perl library in a rules file for the Syslog Aggregator, but similar changes are also supported in the other rules-based applications, such as the SNMP Poller. Several updates must be made in order to use the new library.

  1. Login to the Unified Assurance UI.

  2. Navigate to the Rules UI:

    From the main navigation menu, select Configuration, and then Rules.

  3. Expand the following folders:

    Core Rules (core)/Default read-write branch (default)/collection/event/syslog

    You can verify the path by checking the application configuration that is used by the application.

  4. Open the base.load file.

  5. At the very top of the rules file, add the following line of code.

    BEGIN {
      require Assure1::Config;
      $Config //= Assure1::Config->new();
      unshift(@INC,
          $Config->{BaseDir} . '/local/lib/perl',
          $Config->{BaseDir} . '/vendor/perl/site/lib',
          $Config->{BaseDir} . '/vendor/perl/lib'
      );
      require Net::NTP;
      Net::NTP->import();  # only needed if you use imported symbols
}

    Note:

    • This change is made in base.load to avoid excessive unshifting within the application, which may cause slowness issues, especially on systems processing a large number of events.

    • This change is made in base.load to avoid excessive unshifting within the application, which may cause slowness issues, especially on systems processing a large number of events.

    • By the time the rules files are loaded in the application, the variable $Config->{BaseDir} will contain the base directory that was used to install Unified Assurance. This variable should be used instead of hard coding the paths to be included.

  6. Under the BEGIN block, add the necessary require <LIBRARY> logic to include the additional libraries.

    require <LIBRARY>;

    For example, to bring in the Net::NTP library, the following logic must be added.

    require Net::NTP;

    Note:

    This change is made in base.load to avoid excessive require calls within the application, which may cause slowness issues, especially on systems processing a large number of events.

  7. Save the changes made to the base.load file.

  8. Expand the following folders, if they are not already expanded:

    Core Rules (core)/Default read-write branch (default)/collection/event/syslog

    You can verify the path by checking the application configuration that is used by the application.

  9. Open the base.rules file.

  10. Update the rules file (or files) to use the additional libraries. This example uses the new library to poll the specified NTP server. After the poll is complete, the data in the %response variable can be used as needed within the rules file.

    my %response = get_ntp_response('0.pool.ntp.org', 123);

  11. Save the changes made to the base.rules file or other modified files.

  12. Restart the application via the Services UI.

  13. Monitor the application log files to verify functionality.