Net::Intermapper - Interface with the HelpSystems Intermapper HTTP API
use Net::Intermapper; my $intermapper = Net::Intermapper->new(hostname=>"10.0.0.1", username=>"admin", password=>"nmsadmin"); # Options: # hostname - IP or hostname of Intermapper 5.x and 6.x server # username - Username of Administrator user # password - Password of user # ssl - SSL enabled (1 - default) or disabled (0) # port - TCP port for querying information. Defaults to 8181 # modifyport - TCP port for modifying information. Default to 443 # cache - Boolean to enable smart caching or force network queries my %users = $intermapper->users; my $users_ref = $intermapper->users; # Retrieve all users from Intermapper, Net::Intermapper::User instances # Returns hash or hashref, depending on context my %devices = $intermapper->devices; my $devices_ref = $intermapper->devices; # Retrieve all devices from Intermapper, Net::Intermapper::Device instances # Returns hash or hashref, depending on context my %maps = $intermapper->maps; my $maps_ref = $intermapper->maps; # Retrieve all maps from Intermapper, Net::Intermapper::Map instances # Returns hash or hashref, depending on context my %interfaces = $intermapper->interfaces; my $interfaces_ref = $intermapper->interfaces; # Retrieve all interfaces from Intermapper, Net::Intermapper::Interface instances # Returns hash or hashref, depending on context my %vertices = $intermapper->vertices; my $vertices_ref = $intermapper->vertices; # Retrieve all vertices from Intermapper, Net::Intermapper::Vertice instances # Returns hash or hashref, depending on context my $user = $intermapper->users->{"admin"}; # Each class will generate specific header. These are typically only for internal use but are compliant to the import format Intermapper uses. print $user->header; print $device->header; print $map->header; print $interface->header; print $vertice->header; print $user->toTAB; print $device->toXML; # This one is broken still! print $map->toCSV; # Works on ALL subclasses # Produce human-readable output of each record in the formats Intermapper supports my $user = Net::Intermapper::User->new(Name=>"testuser", Password=>"Test12345"); my $response = $intermapper->create($user); # Create new user # Return value is HTTP::Response object my $device = Net::Intermapper::Device->new(Name=>"testDevice", MapName=>"TestMap", MapPath=>"/TestMap", Address=>"10.0.0.1"); my $response = $intermapper->create($device); # Create new device # Return value is HTTP::Response object $user->Password("Foobar123"); my $response = $intermapper->update($user); # Update existing user # Return value is HTTP::Response object my $user = $intermapper->users->{"bob"}; my $response = $intermapper->delete($user); # Delete existing user # Return value is HTTP::Response object my $device = $intermapper->devices->{"UniqueDeviceID"}; my $response = $intermapper->delete($device); # Delete existing device # Return value is HTTP::Response object my $users = { "Tom" => $tom_user, "Bob" => $bob_user }; $intermapper->users($users); # At this point, there is no real reason to do this as update, create and delete work with explicit arguments. # But it can be done with users, devices, interfaces, maps and vertices # Pass a hashref to each method. This will NOT affect the smart-caching (only explicit calls to create, update and delete do this - for now).
Net::Intermapper is a perl wrapper around the HelpSystems Intermapper API provided through HTTP/HTTPS for access to user accounts, device information, maps, interfaces and graphical elements.
All calls are handled through an instance of the Net::Intermapper class.
use Net::Intermapper; my $intermapper = Net::Intermapper->new(hostname => '10.0.0.1', username => 'admin', password => 'nmsadmin');
Class constructor. Returns object of Net::Intermapper on succes. Required fields are:
Optional fields are
IP or hostname of Intermapper server. This is a required value in the constructor but can be redefined afterwards.
Username of Administrator user. This is a required value in the constructor but can be redefined afterwards. As the API is used a different mechanism to query information than it uses to update, this needs to be changed when switching. Typically, the built-in admin user is used for modifying a record. This value is not automatically changed when running create or update.
admin
create
update
Password of user. This is a required value in the constructor but can be redefined afterwards. As the API is used a different mechanism to query information than it uses to update, this needs to be changed when switching. Typically, the built-in admin user is used for modifying a record. This value is not automatically changed when running create or update.
SSL enabled (1 - default) or disabled (0).
Value is passed directly to LWP::UserAgent as ssl_opt. Default value (hash-ref) is
ssl_opt
{ 'SSL_verify_mode' => SSL_VERIFY_NONE, 'verify_hostname' => '0' }
This is an optional value in the constructor and can be redefined afterwards.
TCP port used for queries. This is an optional value in the constructor and can be redefined afterwards. By default, this is set to 8181. As the API is used a different mechanism to query information than it uses to update, the port value is used for queries only and is automatically switched. Set this ONLY if you have customized Intermapper to listen to a different port.
port
TCP port used for modifying values. This is an optional value in the constructor and can be redefined afterwards. By default, this is set to 443. As the API is used a different mechanism to modify (create and update) information than it uses to query, the modifyport value is used for modifying only and is automatically switched. Set this ONLY if you have customized Intermapper to listen to a different port.
modifyport
Set to true (default) to use in-memory dataset to avoid unnecessary queries. Dataset are always queries when changes are made (after delete, create or update), per type. Changes to users dataset will not affect the devices dataset. This is a required value in the constructor but can be redefined afterwards.
$intermapper->cache(0); $intermapper->update($user); # Users have changed. my $users = $intermapper->users; # This will trigger network traffic my $devices = $intermapper->devices # This will NOT trigger network traffic
From the class instance, call the different methods for retrieving values.
Returns all users
my %users = $intermapper->users(); my $user = $users{"Bob"}; print $user->Password;
The returned hash contains instances of Net::Intermapper::User, using the username as the hash key. In scalar context, will return hashref. This method will typically trigger a network connection, depending on caching.
Modify the in-memory users dataset:
my $users = { "Tom" => $tom_user, "Bob" => $bob_user }; $intermapper->users($users); # At this point, there is no real reason to do this as update, create and delete work with explicit arguments. # But it can be done with users, devices, interfaces, maps and vertices # Pass a hashref to each method. This will NOT affect the smart-caching (only explicit calls to create, update and delete do this - for now).
returns all devices
my %devices = $intermapper->devices(); my $device = $devices{"UniqueDeviceID"}; print $device->Address;
The returned hash contains instances of Net::Intermapper::Device, using the device ID as the hash key. In scalar context, will return hashref. This method will typically trigger a network connection, depending on caching.
my $devices = { "MainRouter1" => $main1, "MainRouter2" => $main2 }; $intermapper->devices($devices); # At this point, there is no real reason to do this as update, create and delete work with explicit arguments. # But it can be done with users, devices, interfaces, maps and vertices # Pass a hashref to each method. This will NOT affect the smart-caching (only explicit calls to create, update and delete do this - for now).
returns all maps
my %maps = $intermapper->maps(); my $map = $maps{"MainMap"}; print $map->Name;
The returned hash contains instances of Net::Intermapper::Map, using the map name as the hash key. In scalar context, will return hashref. This method will typically trigger a network connection, depending on caching.
my $maps = { "MainMap" => $main1, "Layer2" => $main2 }; $intermapper->maps($maps); # At this point, there is no real reason to do this as update, create and delete work with explicit arguments. # But it can be done with users, devices, interfaces, maps and vertices # Pass a hashref to each method. This will NOT affect the smart-caching (only explicit calls to create, update and delete do this - for now).
returns all interfaces
my %interfaces = $intermapper->interfaces(); my $interface = $devices{"UniqueInterfaceID"}; print $interface->Address;
The returned hash contains instances of Net::Intermapper::Interface, using the interface ID (generated by Intermapper) as the hash key. In scalar context, will return hashref. This method will typically trigger a network connection, depending on caching.
my $interfaces = { "UniqueKey1" => $iface1, "UniqueKey2" => $iface2 }; $intermapper->interfaces($interfaces); # At this point, there is no real reason to do this as update, create and delete work with explicit arguments. # But it can be done with users, devices, interfaces, maps and vertices # Pass a hashref to each method. This will NOT affect the smart-caching (only explicit calls to create, update and delete do this - for now).
returns all vertices
my %vertices = $intermapper->vertices(); my $vertice = $vertices{"ID"}; # Unique Vertex ID print $vertice->Shape;
The returned hash contains instances of Net::Intermapper::Vertice, using the vertex ID as the hash key. In scalar context, will return hashref. This method will typically trigger a network connection, depending on caching.
my $vertices = { "UniqueVertexID1" => $vid1, "UniqueVertexID2" => $vid2 }; $intermapper->vertices($vertices); # At this point, there is no real reason to do this as update, create and delete work with explicit arguments. # But it can be done with users, devices, interfaces, maps and vertices # Pass a hashref to each method. This will NOT affect the smart-caching (only explicit calls to create, update and delete do this - for now).
This method created a new entry in Intermapper, depending on the argument passed. Record type is detected automatically.
$intermapper->username("admin"); $intermapper->password("nmsadmin"); my $user = Net::Intermapper::User->new(Name=>"testuser", Password=>"Test12345"); my $response = $intermapper->create($user); # Error checking needs to be added # print $Net::Intermapper::ERROR unless $id; # $Net::Intermapper::ERROR contains details about failure # Add more examples # Interfaces and maps cannot be explicitly created!
This method updates an existing entry in Intermapper, depending on the argument passed. Record type is detected automatically.
my $user = $intermapper->users->{"testuser"}; $user->Password("TopSecret"); # Change password. Password policies will be enforced! my $response = $intermapper->update($user); # Error checking needs to be added # Update user based on Net::Intermapper::User instance # print $Net::Intermapper::ERROR unless $id; # $Net::Intermapper::ERROR contains details about failure
This method deletes an existing entry in Intermapper, depending on the argument passed. Record type is detected automatically.
my $user = $intermapper->users->{"bob"}; my $response = $intermapper->delete($user); # Delete existing user my $device = $intermapper->devices->{"UniqueDeviceID"}; # This key is generated by Intermapper $intermapper->delete($device); # Delete existing device
NEEDS TO BE ADDED
This variable will contain detailed error information.
For this library to work, you need an instance with Intermapper (obviously) or a simulator like Net::Intermapper::Mock.
None so far
None so far :)
Hendrik Van Belleghem CPAN ID: BEATNIK hendrik.vanbelleghem@gmail.com
This program is free software licensed under the...
The General Public License (GPL) Version 2, June 1991
The full text of the license can be found in the LICENSE file included with this module.
http://download.intermapper.com/docs/UserGuide/Content/09-Reference/09-05-Advanced_Importing/the_directive_line.htm http://download.intermapper.com/schema/imserverschema.html
To install Net::Intermapper, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Intermapper
CPAN shell
perl -MCPAN -e shell install Net::Intermapper
For more information on module installation, please visit the detailed CPAN module installation guide.