You can find the descriptive table of Perl API calls at Tools icon > Network > API Documentation > API List.

The Perl API functions as a wrapper around the API Core. This wrapper binds the XML output to Perl objects.

Installing the Perl API

The following are required to use the Perl API:

• Unix, Linux, or Windows operating system
• Perl 5.8.8 or later for Unix/Linux, Mac OS X, or ActiveState’s Active Perl for Windows

Perl modules:

• libwww-perl
• JSON
• Scalar::Util => v. 1.18

These can be installed on Debian / Ubuntu using:

% sudo apt-get update
% sudo apt-get install libwww-perl libjson-perl

These can be installed on RedHat / CentOS / Fedora using:

% sudo yum install perl-libwww-perl perl-JSON

Optional Perl modules include:

• JSON::XS
• YAML
• XML::Simple

Install optional modules as follows:

% sudo apt-get install libjson-xs-perl libxml-simple-perl libyaml-perl

These packages should be available on all recent versions of either Debian or Ubuntu. They can also be installed on Red Hat, CentOS, or Fedora using the following:

% sudo yum install perl-XML-Simple

Some of the noted packages may not be available on all recent RPM-based Linux distributions; if that is the case for yours, then the CPAN method (see next) can be used. Use the CPAN shell:

% cpan LWP JSON NetAddr::IP Scalar::Util

For optional modules:

% cpan JSON::XS XML::Simple YAML

Once the prerequisites are met, extract the NetMRI API distribution, and install:

% tar zxf NetMRI-API-3.0.0.0.tar.gz
% cd NetMRI-API-3.0.0.0
% perl Makefile.PL
Installing the Perl API
For NetMRI 7.5.0 NetMRI API 3.8 Developer’s Guide 15
% make
% make test
% sudo make install

On Windows, nmake or dmake can be used instead of make. Nmake is provided with Microsoft Visual Studio.

Authentication

When your script connects to NetMRI, it must pass the URL, user name and password to the client object. The URL and credentials can be passed into the constructor when connecting to NetMRI:

my $client = new NetMRI::API({
api_version => 3.X,
url => 'http://netmri',
username => 'admin',
password => 'secret',
});

Or you can create a .netmri.yml or .netmri.json file with authentication information in your home directory. This requires installation the YAML module.
For .netmri.yml:

---
url: http://netmri
username: admin
password: secret

For .netmri.json:

{"password":"secret","url":"http://netmri","username":"admin"}

The .netmri.yml or .netmri.json file should be appropriately protected if you include a password.
Alternatively, use cookie-based authentication with a .netmri.yml config similar to the following:

---
url: http://netmri
username: admin
persistent: 1

Run netmri-api-login to interactively log in before running any other scripts that use the netmri. Netmri-api-logout can be used to log out.

grunion% netmri-api-login
http://admin@172.23.23.70 password:
grunion% netmri-api-logout
grunion%

You can use the <hidden></hidden> tag to hide the password string and replace it by stars characters ******. For example:

$easy->send_async_command("copy scp://10.10.10.10/$image

$dest_dir:$image\r$scp_user\r\r<hidden>$scp_password</hidden>\r", 7200);

The value of $scp_password will be replaced by stars ****** in logs.

Using the Perl Objects

The Perl API is written using object-oriented Perl. All interactions with the NetMRI device are through a client class called NetMRI::API. An instance of this class must be created before interactions can be performed.

To open a connection with NetMRI:

my $client = new NetMRI::API({ api_version => 3.X });

The api_version must be included and ensures that your script will use the same interface even as the Core API evolves over time.

Because no other parameters are passed when creating the object, the client will attempt to connect and authenticate with NetMRI using the configuration file from the previous section.

For each data type-such as “device,” “interface” or “VLAN”-there is a broker class. This class contains all the routines that query, summarize, or otherwise act on sets of data objects. The NetMRI::API::Broker::ConfigRevision, for instance, is a broker that can be used to query for a specific list of configuration files. Files can be searched across all active saved and running configuration files.

Example 1

Suppose you want to list all routing devices on your network. NetMRI provides (at least) two different ways to identify these devices. First, you can search by device type; querying for devices with types “Router” and “Switch-Router” will list all these devices. To do this, first create a device broker using the NetMRI::API::Client:

my $broker = $client->broker→device;

Next, query for devices having Device Type of “Router” or “Switch-Router”:

my @devices = $broker->index({ DeviceType => [“Router”, “Switch-Router”]});

This will make one or more HTTP requests to retrieve all of the devices from the NetMRI which match the query. When all records have been retrieved, the @devices array contains the complete list of “Device” objects. You can access the fields of the Device object using accessor methods. This loop, for example, prints a list of all the devices returned, including each device name, IP address, and device type:

foreach my $device (@devices)
{
print $device->DeviceName, ' ', $device->DeviceIPDotted, ' ', $device->DeviceType, "\n";
}

The other accessor methods are documented in the Perl documentation for the NetMRI::API::Remote::Device class:

% perldoc NetMRI::API::Remote::Device

As noted, there is an alternative way to identify routing devices. The Device model provides a flag, RoutingInd–which is set to 1 for any device from which NetMRI has successfully collected a routing table. The query would look like the following:

my @devices = $broker->index({ RoutingInd => 1 });S

Additional documentation

Use perldoc to read documentation for individual objects. For example:

% perldoc NetMRI::API

perldoc provides a complete list of methods available in each Perl object.

Another useful document is NetMRI::API::Index, which lists all of the available broker and remote object classes.

% perldoc NetMRI::API::Index.

HTML version of this documentation is also available in the NetMRI Tools > Network > API Documentation > Perl API.

Example scripts

Several example scripts are included with the NetMRI::API distribution in the /examples directory.