Assure1::Core Perl library
Description
Implements the common public functions for rules.
Synopsis
use Assure1::Core;
Functions
AddDeviceMetaTag
Adds a meta tag & data to a device.
AddDeviceMetaTag(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
DeviceID -> Device to tag
MetaTypeID -> Type of MataTag
MetaData -> Value of MetaTag (e.g. 'Windows')
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = AddDeviceMetaTag({
DBH => \$DBH,
DeviceID => 1,
MetaTypeID => 2,
MetaData => "Some data"
});
AddDeviceToDeviceGroup
Adds a device to a group.
AddDeviceToDeviceGroup(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
DeviceID -> Device to add to Group
DeviceGroupID -> Device Group to add Device to
Move -> Flag to remove device from all other groups before adding to given DeviceGroupID, defaults to 0
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = AddDeviceToDeviceGroup({
DBH => \$DBH,
DeviceID => 1,
DeviceGroupID => 2,
Move => 1
});
AddVirtualDevice
Adds a virtual device.
AddVirtualDevice(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
ParentDeviceID -> Parent device
DNS -> DNS of new virtual device
IP -> IP of new virtual device
ZoneID -> ZoneID to add new virtual device to
GeoLocation -> GeoJSON representation of geographic location
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. New Virtual Device ID (Integer)
Synopsis
my ($ErrorFlag, $Message) = AddVirtualDevice({
DBH => \$DBH,
ParentDeviceID => 1,
DNS => "somehost.com",
IP => "1.2.3.4",
ZoneID => 1,
GeoLocation => '{ "type": "Point", "coordinates": [-96.808891, 32.779167] }'
});
BinaryInsertionSort
Given a reference to an array of sorted data and a reference to a hash of one value, the value is determined to be necessary or unnecessary to the array sequence. If the value is necessary, it is inserted into the array in ascending or descending order (depending on DIRECTION) using a modified Binary Insertion Sort algorithm, maintaining an array size no larger than the max size. If it is unnecessary, the function returns.
BinaryInsertionSort(\@SortedArrayRef, \%DataHashRef, $MaxArraySize, $Direction)
Arguments
SortedArrayRef -> Array containing sorted values
DataHashRef -> Hash of data to be inserted into array (must have a 'Value' key)
MaxArraySize -> Max size of the array; if -1, size of array is indefinite;
Direction -> 'Forward' for lowest values, 'Reverse' for highest values
Returns
1. Reference to properly sorted array
2. Removed value (which defaults to -1 if the value is not necessary)
Synopsis
BinaryInsertionSort($SortedArrayRef, $DataHashRef, $MaxArraySize, 'Forward');
BuildDSN
Builds a DSN string based on passed in database type. Supported types are MySQL, MS SQL. PostgreSQL and Oracle have not been validated
BuildDSN(\%options)
Options
DBHost -> Host to connect to
DBName -> Database/schema to connect to (ignored for MSSQL)
DBPort -> Port to connect on
DBType -> Database type: 'mysql' (default), 'Sybase', 'Pg', 'Oracle'
Returns
1. Appropriate DSN for type (String) or undef if not a supported type
Synopsis
my $dsn = BuildDSN({
DBType => 'mysql',
DBName => 'mydbname',
DBHost => 'myhost.example.com',
DBPort => 3306
});
BuildMySQLSSLDSN
Builds a DSN string for connecting to a MySQL server, including SSL authentication options
BuildMySQLSSLDSN(\%options)
Options
DBHost -> Host to connect to
DBName -> Database/schema to connect to (ignored for MSSQL)
DBPort -> Port to connect on
DBType -> Datbase type: 'mysql' (default), 'Sybase', 'Pg', 'Oracle'
User -> The name of the user to connect as (must be a corresponding User-[User].crt/key on disk)
BaseDir -> The Unified Assurance install's base directory
Returns
1. Appropriate DSN (String)
Synopsis
my $dsn = buildMySQLSSLDSN({
DBType => 'mysql',
DBName => 'mydbname',
DBHost => 'myhost.example.com',
DBPort => 3306,
User => 'assure1'
BaseDir => '/opt/assure1'
});
CallAPI
Use Assure1::API to call methods in procedural way. For advanced usage, use the object-oriented API class and methods directly.
CallAPI(\%options)
Options
url -> Full or relative URL of API (eg. /api/devices/devices or https://assure1pres1.example.com/api/devices/devices)
method -> API method (eg. read, create, update, delete)
params -> Parameters to pass to method
handle -> (optional) Assure1::API handle to reuse for faster responses
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Result (Hash result or Array of hash results or API error message)
Synopsis
my ($error, $result) = CallAPI({
url => '/api/device/devices',
method => 'read',
params => [
...
]
});
OR
my $apiHandle = new Assure1::API;
my ($error, $result) = CallAPI({
handle => $apiHandle,
url => '/api/device/devices',
method => 'create',
params => [{
...
}]
});
CreateGeoLocation
Generates GeoJSON formatted string for Point Geometry
CreateGeoLocation($Lon, $Lat)
Arguments
Lon -> Longitude for location
Lat -> Latitude for location
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. GeoJSON (String) or undef if an error occurred.
Synopsis
my ($errorFlag, $message, $geoLocationGeoJson) = CreateGeoLocation(-96.808891, 32.779167)
CreateGeoPath
Generates GeoJSON formatted string for Linestring Geometry
CreateGeoPath(\@Points)
Arguments
Points -> Array reference of longitude and latitudes for linestring
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. GeoJSON (String) or undef if an error occurred.
Synopsis
my ($errorFlag, $message, $geoPathGeoJson) = CreateGeoPath([[-96.808891, 32.779167], [-87.623177, 41.881832]])
DBConnect
Connects to the database DBName using initial configuration CONFIG and instance parameters in the configuration database.
DBConnect($Config, $DBName, \%Parameters)
Arguments
Config -> Assure1::Config object()
DBName -> Schema name to connect
Parameters -> Extra database connection parameters
Returns
1. Databse Connection Handle (undef on error)
Synopsis
my $dbh = DBConnect($Config, 'Assure1', {AutoCommit => 1})
ExecuteQuery
Helper function to execute queries against multiple shards with aggregate enriched results.
ExecuteQuery(\%options)
Options
Query -> SQL to run
Arguments -> (optional) Array of arguments for SQL placeholders ('?' markers)
Schema -> (optional) Schema Name (from databases) (default: 'Assure1')
Shards -> (optional) Comma separated list of shards. 0 is all shards. (default: 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Results (array ref) of results or undef if error
NOTE: Enriches each row and includes/overrides column 'ShardID' which contains the database shard the record was retrieved from
Synopsis
my ($ErrorFlag, $Message, $Results) = ExecuteQuery({
Query => 'SELECT DeviceID
FROM Devices
WHERE DeviceZoneID = ?',
Arguments => ($DeviceZoneID),
Schema => 'Assure1',
Shards => 0
});
if ($ErrorFlag) {
$Log->Message('INFO', "Error occurred: [$Message]");
}
else {
my $count = scalar @{$Results};
$Log->Message('INFO', "Result had [$count] rows");
}
FindDeviceGroupID
Finds device group by name and returns ID. If Create option set to true (1), will create device group automatically if not found.
FindDeviceGroupID(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
StorageHash -> Cache (i.e. $StorageHash)
GroupName -> Group Name for lookup,
ParentGroupID -> (Optional) Parent Group ID (default=1)
Create -> (Optional) Create Flag (0=don't create if not found, 1=create if not found; default)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Device Group ID (Integer) or undef if not found/created
Synopsis
my ($ErrorFlag, $Message, $DeviceGroupID) = FindDeviceGroupID({
DBH => \$DBH,
StorageHash => $StorageHash,
GroupName => "Customer XYZ",
Create => 1
});
FindDeviceID
Finds device by DNS, IP, and/or CustomName and returns ID if found. If Create option set to true (1), will create device automatically and add to initial device group if not found. Device must be part of at least one device group, if no DeviceGroupID is passed in, defaults to [Root]
FindDeviceID(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
StorageHash -> Cache (i.e. $StorageHash)
DNS -> DNS for lookup
IP -> IPv4 address for lookup
IPv6 -> IPv6 address for lookup
CustomName -> Custom Name for lookup
GeoLocation -> (Optional) GeoJSON representation of geographic location
Create -> (Optional) Create Flag (0=don't create if not found, 1=create if not found)
DeviceGroupID -> (Optional) Initial Device Group ID (defaults to [Root])
DeviceZoneID -> (Optional) Device Zone ID (If not set, searches all Zones and returns the matching Device ID
with the lowest DeviceZoneID. If FindDeviceID is asked to create a Device and
DeviceZoneID isn't set, it will be created in DeviceZoneID 1)
ShardID -> (Optional) ShardID to assign created device (defaults to 1)
Strict -> (Optional) Controls whether a device must match all DNS/IP/IPv6 passed or just the best match (defaults to 0)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Device ID (Integer) or undef if not found/created
Synopsis
my ($ErrorFlag, $Message, $DeviceID) = FindDeviceID({
DBH => \$DBH,
StorageHash => $StorageHash,
DNS => "somehost.com",
IP => "1.2.3.4",
CustomName => "Some Host",
GeoLocation => '{ "type": "Point", "coordinates": [-96.808891, 32.779167] }',
Create => 1
});
FindDeviceZoneID
Finds device and returns ID. If Create option set to true (1), will create device zone automatically if not found.
FindDeviceZoneID(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
StorageHash -> Cache (i.e. $StorageHash)
ZoneName -> Zone Name for lookup
Create -> (Optional) Create Flag (0=don't create if not found, 1=create if not found)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Device Zone ID (Integer) or undef if not found/created
Synopsis
my ($ErrorFlag, $Message, $DeviceZoneID) = FindDeviceZoneID({
DBH => \$DBH,
StorageHash => $StorageHash,
ZoneName => "DMZ",
Create => 1
});
ForwardBinaryInsertionSort
Convenience function to call "BinaryInsertionSort" with arguments and setting direction to "Forward".
ForwardBinaryInsertionSort(\@SortedArrayRef, \%DataHashRef, $MaxArraySize)
SortedArrayRef -> Array containing sorted values
DataHashRef -> Hash of data to be inserted into array (must have a 'Value' key)
MaxArraySize -> Max size of the array; if -1, size of array is indefinite;
Returns
1. Reference to properly sorted array
2. Removed value (which defaults to -1 if the value is not necessary)
Synopsis
ForwardBinaryInsertionSort($SortedArrayRef, $DataHashRef, $MaxArraySize);
GetDatabases
Retrieves database connection details from Unified Assurance db and returns a reference to a list of db connect info hashes.
GetDatabases($Config, $DBH, $Schema)
Arguments
Config -> Assure1::Config Reference (i.e. $Config)
DBH -> Unified Assurance Database Handle (i.e. $DBH)
Schema -> Database Schema to connect
Returns
1. Database connection strings (Array Reference)
Synopsis
my $dbs = GetDatabases($Config, $DBH, "Assure1");
GetDeviceByID
Returns device information for a given DeviceID.
GetDeviceByID(\%options)
Options
DeviceID -> DeviceID of the Device to be looked up
DBH -> (Optional) Unified Assurance database handle reference (i.e. \$DBH) (performance will improve if used)
IncludeSNMPAccess -> (Optional) Boolean. Enrich the returned data with the Device's SNMP Access profile (default false)
IncludeMetaData -> (Optional) Boolean. Enrich the returned data with the Device's meta data (default false)
StorageHash -> (Optional)Cache (i.e. $StorageHash) (performance will improve if used)
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. DeviceInfo (Hash Reference) or undef if an error occurred.
DeviceInfo => {
DeviceID => INTEGER,
ParentDeviceID => INTEGER,
DNSName => STRING,
CustomName => STRING,
IPv4Address => STRING,
IPv6Address => STRING,
GeoLocation => STRING, # GeoJSON representation of Geometry Point ex: '{ "type": "Point", "coordinates": [<longitude>, <latidude>] }'
DeviceZoneID => INTEGER,
DevicePriority => INTEGER,
DeviceStateID => INTEGER,
DeviceTypeCategoryID => INTEGER,
ShardID => INTEGER,
TimestampAdded => INTEGER (epoch time),
TimestampModified => INTEGER (epoch time),
TimestampLastFound => INTEGER (epoch time),
SysObjectID => STRING,
SysName => STRING,
SysDescr => STRING,
SysLocation => STRING,
SysContact => STRING,
SysServices => STRING,
IPForwarding => BOOLEAN,
SerialNumber => STRING,
DeviceSNMPAccessID => INTEGER,
SNMPAccess => { # Only included if IncludeSNMPAccess is set
AccessID => INTEGER,
ProfileName => STRING,
SNMPVersion => INTEGER,
Community => STRING,
Username => STRING,
SecurityLevel => INTEGER,
AuthPassword => STRING,
AuthProtocol => STRING,
PrivPassword => STRING,
PrivProtocol => STRING,
SNMPPort => INTEGER,
MTU => INTEGER,
ProfileZoneID => STRING
},
MetaData => { # Only included if IncludeMetaData is set
NAME1 => VALUE1,
...
}
}
Synopsis
my ($ErrorFlag, $Message, $DeviceInfo) = GetDeviceByID({
DBH => \$DBH,
DeviceID => $DeviceID,
IncludeSNMPAccess => 1,
IncludeMetaData => 1,
StorageHash => $StorageHash
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Couldn't find device info for $DeviceID: $Message");
}
else {
$Log->Message('INFO', "Found $DeviceID ($DeviceInfo->{DNSName})");
}
GetLocalDeviceID
Returns the DeviceID for the local server that code is being run on.
GetLocalDeviceID(\%options)
Options
DBH -> (Optional) Unified Assurance database handle reference (i.e. \$DBH) (performance will improve if used)
StorageHash -> (Optional)Cache (i.e. $StorageHash) (performance will improve if used)
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. DeviceID (Scalar) or undef if an error occurred.
Synopsis
my ($ErrorFlag, $Message, $DeviceID) = GetLocalDeviceID({
DBH => \$DBH,
StorageHash => $StorageHash
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Couldn't find local DeviceID: $Message");
}
else {
$Log->Message('INFO', "Found $DeviceID");
}
GetOIDIndexes
Returns the indexes of all the OIDs in the referenced table.
GetOIDIndexes(\%options)
Options
TABLEHASHREF -> SNMP Indexed Table Data returned from a poll
Returns
1. SNMP Indexes (Array)
Synopsis
my @indexes = GetOIDIndexes($IndexedData);
GetSNMPIndexes
Alias function for "GetOIDIndexes".
GetSNMPSession
Creates and returns an SNMP Session (a Net::SNMP object) that can be used for SNMP communications with a device. This is a low-level interface. Consider using GetSNMPSessionByDeviceID instead if trying to communicate with a device that is already in the Device Catalog and already SNMP discovered.
GetSNMPSession(\%options)
Options
Target -> The name or address of the device to establish communications with (required)
Version -> SNMP version to use for the session (required, allowed values are 1, 2, 2c, and 3. 2 and 2c are synonyms)
Domain -> The communications domain of the connection (optional, defaults to 'udp')
MTU -> The maximum MTU to use for the session (optional, default varies by Domain)
Port -> Port to use for communications (optional, defaults to 161)
Timeout -> Amount of time in second to wait for a response from the target (optional, defaults to 5)
TestConnection -> Many SNMP Sessions can be instantiated without actual communication with the device. When this value is true,
a simple request is made to the device to tell if the session is working, allowing the test code to be omitted
by the caller (optional, defaults to false)
Community -> The SNMP community string (required for Version 1 and 2)
Username -> The Username to use for SNMP authentication (required for Version 3)
SecurityLevel -> The security level for the session. Acceptable values are 1 or noAuthNoPriv; 2 or authNoPriv; 3 or authPriv (required for Version 3)
AuthPassword -> The authentication password (required for SecurityLevel 2 and 3)
AuthProtocol -> The authentication protocol. Acceptable values are 'md5' and 'sha' (required for SecurityLevel 2 and 3)
PrivPassword -> The privacy password (required for SecurityLevel 3)
PrivProtocol -> The privacy protocol. Acceptable values are 'des', '3des', or 'aes' (required for SecurityLevel 3)
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. Session (Net::SNMP object) or undef if an error occurred.
Synopsis
my ($ErrorFlag, $Message, $Session) = GetSNMPSession({
Target => '172.16.10.12',
Community => 'MyCommunity',
Version => 2,
TestConnection => 1,
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Couldn't create SNMP session: $Message");
}
else {
my $Response = $Session->get_request(-varbindlist => ['1.3.6.1.2.1.1.5.0']);
if (defined($Response)) {
my $SysName = $Response->{$OIDsysName};
$Log->Message('INFO', "Device 172.16.10.12 thinks its SysName is $SysName");
}
else {
$Log->Message('INFO', "No response from 172.16.10.12: " . $Session->error());
}
}
GetSNMPSessionByDeviceID
Creates and returns an SNMP Session (a Net::SNMP object) that can be used for SNMP communications with a device. Will use SNMP Access information from the database to determine connection parameters.
GetSNMPSessionByDeviceID(\%options)
Options
DeviceID -> The DeviceID of the device to connect to (required)
DBH -> A connected database handle for the configuration database (optional)
Timeout -> Amount of time in second to wait for a response from the target (optional, defaults to 5)
TestConnection -> Many SNMP Sessions can be instantiated without actual communication with the device. When this value is true,
a simple request is made to the device to tell if the session is working, allowing the test code to be omitted
by the caller (optional, defaults to false)
PreferDNS -> If true, try to connect to the Device's DNSName instead of an IP (optional, defaults to false)
PreferIPv4 -> If true and the target Device has both an IPv4 and IPv6 address, attempt to use IPv4 (optional, defaults to
false, meaning this function will by default attempt to use an IPv6 address if one is available)
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. Session (Net::SNMP object) or undef if an error occurred.
Synopsis
my ($ErrorFlag, $Message, $Session) = GetSNMPSessionByDeviceID({
DeviceID => $DeviceID,
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Couldn't create SNMP session: $Message");
}
else {
my $Response = $Session->get_request(-varbindlist => ['1.3.6.1.2.1.1.5.0']);
if (defined($Response)) {
my $SysName = $Response->{$OIDsysName};
$Log->Message('INFO', "Device $DeviceID thinks its SysName is $SysName");
}
else {
$Log->Message('INFO', "No response from $DeviceID: " . $Session->error());
}
}
HTMLToText
Replaces <p> and <br> tags with appropriate whitespace and strip all other HTML tags from text
HTMLToText($Html)
Arguments
Html -> HTML string
Returns
1. Plaintext string (String)
Synopsis
my $text = HTMLToText($html);
IDBConnect
Connects to the InfluxDB Metric database using initial configuration CONFIG and instance parameters in the configuration database.
IDBConnect($Config, \%Parameters)
Arguments
Config -> Assure1::Config object()
Parameters -> Extra database connection parameters:
timeout - connect timeout
shard - shard of database to connect to
Returns
1. Databse Connection Handle
Synopsis
my $idb = IDBConnect($Config, {timeout => 5});
if ($idb->error() ne '') {
$Log->Message('ERROR', 'Cannot open connection to Metric database: ' . $idb->error());
}
IPAddrConvNum
Convert an ascii version of an IP address into numeric. This is equivilent to MySQL's INET_ATON().
IPAddrConvNum($Ip)
Arguments
Ip -> IPv4 Address
Returns
1. Numeric IP (Integer)
Synopsis
my $IPNum = IPAddrConvNum($IPAddress);
NDBConnect
Connects to the Neo4j Graph database using initial configuration CONFIG and instance parameters in the configuration database.
NDBConnect($Config, \%Parameters)
Arguments
Config -> Assure1::Config object()
Parameters -> Extra database connection parameters:
timeout - connect timeout
Expire -> Expire time for JWT token. Defaults to 3600 seconds (1 hour)
Returns
1. Database Connection Handle
Synopsis
my $ndb = NDBConnect($Config);
my $ndb = NDBConnect($Config, {timeout => 5});
if (!defined $ndb) {
$Log->Message('ERROR', 'Cannot open connection to Graph database: ' . $main::ndberrstr);
}
Notify
Send Notification simply using the Unified Assurance Profile/Template.
Notify(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (e.g. \$Assure1DBH)
ProfileID -> Core Notification ProfileID (syslog/trap/smtp server info)
TemplateID -> Core Notification TemplateID (Format), overrides Template
Template -> Notification message template
Must have the following keys depending on the type of notification:
Email keys:
- EmailFrom -> Email from e.g. no-reply@example.com
- EmailSubject -> Email subject, supports token replacement based on given entries in Values
- EmailBody -> Email body, supports html and token replacement based on given entries in Values
Syslog keys:
- Syslog -> Syslog message, supports token replacement based on given entries in Values
Trap keys:
- EnterpriseID -> Enterprise OID
- Varbinds -> Array of varbinds to send with trap. A varbind should be a hash of two keys: 'OID' and 'Value',
supports token replacement based on given entries in Values.
e.g. $varbind = { 'OID' => '1.2.3.4', 'Value' => 'example' }
Values -> Name/Value Pairs to map to Template tokens (See application documentation for complete list of its supported Values)
Attach -> Name/Value pairs to map to Template tokens for attaching files using given value meta data. Email types only.
Each Value is a hash containing:
- name -> Filename to use for attachment
- id -> ID of attachment for use when referencing as an inline image in body of email (optional, defaults to name)
- type -> MIME attachment type e.g. 'application/pdf'
- file -> Absolute path to file on disk to attach e.g. /opt/assure1/tmp/myreport.pdf
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = Notify({
DBH => \$Assure1DBH,
ProfileID => '1', # Generic Email
TemplateID => '1', # Generic Email
Values => {
EmailTo => 'example@mycompany.com',
SEVERITY_TEXT => 'Critical',
DATE_TEXT => localtime,
FirstReported => time(),
Node => 'hello',
EventID => '5',
Summary => 'world',
Severity => '5',
EventType => 'test'
}
});
OR
my ($ErrorFlag, $Message) = Notify({
DBH => \$Assure1DBH,
ProfileID => 1, # Generic Email
Template => {
EmailFrom => 'no-reply@example.com',
EmailSubject => 'Critical test - $DATE_TEXT',
EmailBody => 'This is a test email $SEVERITY_TEXT (<Severity>)'
},
Values => {
EmailTo => 'example@mycompany.com',
SEVERITY_TEXT => 'Critical',
DATE_TEXT => localtime,
Severity => '5',
}
});
ODBConnect
Connects to the OrientDB Graph database using initial configuration CONFIG and instance parameters in the configuration database.
ODBConnect($Config, \%Parameters)
Arguments
Config -> Assure1::Config object()
Parameters -> Extra database connection parameters:
timeout - connect timeout
Returns
1. Database Connection Handle
Synopsis
my $odb = ODBConnect($Config);
my $odb = ODBConnect($Config, {timeout => 5});
if ($odb->error() ne '') {
$Log->Message('ERROR', 'Cannot open connection to Metric database: ' . $odb->error());
}
OidToIP
Convert an oid-encoded IPv4 or IPv6 address to standard IP notation
OidToIP(\%options)
Options
OID -> OID-encoded IP (eg 172.21.23.24 or 254.128.0.0.0.0.0.0.2.80.86.255.254.157.171.146)
Returns
1. ErrorFlag (Boolean) If true, an error occurred. Check Message for more details.
2. Message (String)
3. IPAddress (String) or undef if an error occurred.
Synopsis
my ($ErrorFlag, $Message, $IPAddress) = OidToIP($OID);
if ($ErrorFlag) {
print "Couldn't convert $OID to IP: $Message\n";
}
else {
print "converted $OID to $IPAddress\n";
}
ResolveIPAddress
Resolve an IP to Name
ResolveIPAddress(\%options)
Options
IPAddress -> IPv4 Address
StorageHash -> shared hashref for name caching
Returns
1. Numeric IP (String) or undef on error
Synopsis
my $DNS = ResolveIPAddress({
IPAddress => $IPAddress,
StorageHash => $StorageHash
});
ReverseBinaryInsertionSort
Convenience function to call "BinaryInsertionSort" with arguments and setting direction to "Reverse".
ReverseBinaryInsertionSort(\@SortedArrayRef, \%DataHashRef, $MaxArraySize)
Arguments
SortedArrayRef -> Array containing sorted values
DataHashRef -> Hash of data to be inserted into array (must have a 'Value' key)
MaxArraySize -> Max size of the array; if -1, size of array is indefinite;
Returns
1. Reference to properly sorted array
2. Removed value (which defaults to -1 if the value is not necessary)
Synopsis
ReverseBinaryInsertionSort($SortedArrayRef, $DataHashRef, $MaxArraySize);
SetDeviceShardID
Sets the Device ShardID. Updates definition only, does NOT migrate associated metric data to the new shard
SetDeviceShardID(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$DBH)
DeviceID -> Device to update
ShardID -> ShardID to set
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = SetDeviceShardID({
DBH => \$DBH,
DeviceID => 1,
ShardID => 2
});
OR
if (SetDeviceShardID({
DBH => \$DBH,
DeviceID => 1,
ShardID => 2
}))
{
$Log->Message('INFO', "ShardID set");
}
else {
$Log->Message('ERROR', "Failed to set device shard");
}
UpdateDeviceProps
Updates a Device Priority and CustomName
UpdateDeviceProps(\%options)
Options
DBH -> Unified Assurance Database Handle Reference (i.e. \$Assure1DBH)
DeviceID -> ID of Device to update
Priority -> Device Priority to set (higher is more important)
CustomName -> Device CustomName to set
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = UpdateDeviceProps({
DBH => \$Assure1DBH,
DeviceID => $DeviceID,
Priority => $Priority,
CustomName => $CustomName
});
WalkOIDs
SNMP Walks the indexed oids and returns the entire walk results as a hash reference.
All oids passed in are assumed to be tables and use the same indexing. If oids are from different tables that use different indexing, separate calls must be made to this function for each table in order to retrieve values correctly.
WalkOIDs($SnmpSession, $DeviceInfo, \@OIDs)
Arguments
SnmpSession -> SNMP Session object
DeviceInfo -> Device Info (DeviceID|DeviceDNS|DeviceID)
OIDs -> Array reference of OID(s) to walk
Returns
1. SNMP Walk results (undef on error)
Synopsis
my $WalkResults = WalkOIDs($Session, '123|router|1.2.3.4', ['1.3.6.1.2.3.4.5', '1.3.6.1.2.3.4.6'])
ZeroPad
Pads a number with a leading zero if less than ten (10) and not already padded.
ZeroPad($Num)
Arguments
Num -> Number less than 10 to pad
Returns
1. Padded Number
Synopsis
my $padded = ZeroPad($number);
ZeroUnPad
Removes a leading zero from a number if less than 10 and padded.
ZeroUnPad($Num)
Arguments
Num -> Number less than 10 to remove padding
Returns
1. Unpadded Number
Synopsis
my $unpadded = ZeroUnPad($padded);