Core
The Core library implements the common public functions for rules.
Synopsis
use Assure1::Core;
Functions
The Core library contains the functions described below.
AddDeviceMetaTag
Adds a meta tag and data to a device.
AddDeviceMetaTag(\%options)
Options
DBH -> The Assure1 database handle reference (for example, \$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 -> The Assure1 database handle reference (for example, \$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 -> The Assure1 database handle reference (for example, \$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 => "<VIRTUALDNSNAME>",
IP => "<VIRTUALIPADDRESS>",
ZoneID => 1,
GeoLocation => '{ "type": "Point", "coordinates": [<VIRTUALLONGITUDE>, <VIRTUALLATITUDE>] }'
});
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 -1.
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 the specified 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 => '<DBTYPE>',
DBName => '<DBNAME>',
DBHost => '<DBHOST>',
DBPort => <DBPORT>
});
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 or 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 base installation directory
Returns
1. Appropriate DSN (String)
Synopsis
my $dsn = buildMySQLSSLDSN({
DBType => '<DBTYPE>',
DBName => '<DBNAME>',
DBHost => '<DBHOST>',
DBPort => <DBPORT>,
User => '<DBUSER>'
BaseDir => '<A1BASEDIR>'
});
CallAPI
Uses the Assure1::API library to call methods in a 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 a 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(<LONGITUDE>, <LATITUDE>)
CreateGeoPath
Generates a 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([[<LONGITUDE1>, <LATITUDE1>], [<LONGITUDE2>, <LATITUDE2>]])
DBConnect
Connects to the database specified in 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. Database Connection Handle (undef on error)
Synopsis
my $dbh = DBConnect($Config, 'Assure1', {AutoCommit => 1})
ExecuteQuery
A helper function that runs 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 a device group by name and returns its ID. If the Create option is set to true (1), and no device group with the specified name exists, it will be automatically created.
FindDeviceGroupID(\%options)
Options
DBH -> The Assure1 database handle reference (for example, \$DBH)
StorageHash -> Cache (for example, $StorageHash)
GroupName -> Group Name for lookup
ParentGroupID -> (Optional) Parent Group ID (default=1)
Create -> (Optional) Set to 1 to create the device group if it does not exist, set to 0 otherwise. 1 is the default.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Device Group ID (Integer) or undef if not found or created
Synopsis
my ($ErrorFlag, $Message, $DeviceGroupID) = FindDeviceGroupID({
DBH => \$DBH,
StorageHash => $StorageHash,
GroupName => "<GROUPNAME>",
Create => 1
});
FindDeviceID
Finds a device by DNS, IP, or CustomName and returns its ID.
If the Create option is set to true (1), and no matching device exists, it will be automatically created and added to initial device group. All devices must be part of at least one device group. If no DeviceGroupID is specified, the group defaults to [Root].
FindDeviceID(\%options)
Options
DBH -> The Assure1 database handle reference (for example, \$DBH)
StorageHash -> Cache (for example, $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) Set to 1 to create the device if it does not exist, set to 0 otherwise.
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 or created
Synopsis
my ($ErrorFlag, $Message, $DeviceID) = FindDeviceID({
DBH => \$DBH,
StorageHash => $StorageHash,
DNS => "<DNSNAME>",
IP => "<IPADDRESS>",
CustomName => "<CUSTOMNAME>",
GeoLocation => '{ "type": "Point", "coordinates": [<LONGITUDE>, <LATITUDE>] }',
Create => 1
});
FindDeviceZoneID
Finds a device zone and returns its ID. If the Create option is set to true (1), and no device zone with the specified name exists, it will be automatically created.
FindDeviceZoneID(\%options)
Options
DBH -> The Assure1 database handle reference (for example, \$DBH)
StorageHash -> Cache (for example, $StorageHash)
ZoneName -> Zone Name for lookup
Create -> (Optional) Set to 1 to create the device zone if it does not exist, set to 0 otherwise.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Device Zone ID (Integer) or undef if not found or created.
Synopsis
my ($ErrorFlag, $Message, $DeviceZoneID) = FindDeviceZoneID({
DBH => \$DBH,
StorageHash => $StorageHash,
ZoneName => "<ZONENAME>",
Create => 1
});
ForwardBinaryInsertionSort
A convenience function to call "BinaryInsertionSort" with arguments and set the 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 the Assure1 database and returns a reference to a list of DBConnect info hashes.
GetDatabases($Config, $DBH, $Schema)
Arguments
Config -> Assure1::Config Reference (for example, $Config)
DBH -> Assure1 Database Handle (for example, $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 the specified DeviceID.
GetDeviceByID(\%options)
Options
DeviceID -> DeviceID of the Device to be looked up
DBH -> (Optional) The Assure1 database handle reference (for example, \$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 (for example, $StorageHash) (performance will improve if used)
ExpireTime -> (Optional) Seconds after which the cache should be expired. (default 0, cache does not expire)
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>, <latitude>] }'
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) Assure1 database handle reference (for example, \$DBH) (performance will improve if used)
StorageHash -> (Optional)Cache (for example, $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
An alias function for "GetOIDIndexes".
GetSNMPSession
Creates and returns an SNMP Session (a Net::SNMP object) that can be used for SNMP communication with a device. This is a low-level interface. Consider using GetSNMPSessionByDeviceID 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 => '<IPADDRESS>',
Community => '<COMMUNITY>',
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 <IPADDRESS> thinks its SysName is $SysName");
}
else {
$Log->Message('INFO', "No response from <IPADDRESS>: " . $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 removes 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
Converts an ASCII version of an IP address into numeric. This is equivalent 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
Sends a notification simply using the Unified Assurance Profile/Template.
Notify(\%options)
Options
DBH -> The Assure1 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 => 'email-to@example.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 => 'email-to@example.com',
SEVERITY_TEXT => 'Critical',
DATE_TEXT => localtime,
Severity => '5',
}
});
OidToIP
Converts an OID-encoded IPv4 or IPv6 address to standard IP notation.
OidToIP(\%options)
Options
OID -> OID-encoded IP (eg 192.0.2.1 or 32.1.219.128.0.0.0.0.0.0.0.0.0.0.0.1)
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
Resolves an IP address to a 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
A convenience function to call "BinaryInsertionSort" with arguments and sets the 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's shard ID. Updates the definition only, does NOT migrate associated metric data to the new shard.
SetDeviceShardID(\%options)
Options
DBH -> The Assure1 database handle reference (for example, \$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's priority and custom name.
UpdateDeviceProps(\%options)
Options
DBH -> The Assure1 database handle reference (for example, \$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 specified OIDs are assumed to be tables that use the same indexing. If OIDS are from different tables that use different indexing, make a separate call for each table.
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, '<DEVICEID>|<DNSNAME>|<IPADDRESS>', ['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 it is 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 ten (10) and padded.
ZeroUnPad($Num)
Arguments
Num -> Number less than 10 to remove padding
Returns
1. Unpadded Number
Synopsis
my $unpadded = ZeroUnPad($padded);