Functions

Overview

This module provides utility functions, constants, and data structures used throughout the AKIPS system for common tasks including logging, time/date formatting, error handling, networking, database communication, and SNMP-based device discovery.

It includes:

• Predefined arrays for weekdays, months, and metric prefixes.
• Utility functions such as trim, errlog, and get_localtime.
• Wrappers around AKIPS tools for sending syslog and HTTP messages (syslog(), http_send(), etc.).
• A simple interface to the AKIPS database system via adb_send() and adb_result().
• A discovery subsystem (discover_scan(), discover_config(), etc.) for identifying and configuring devices using SNMP.

Useful arrays

@weekday_names_short = (
   "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"
);

@weekday_names_long = (
   "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"
);

@month_names_short = (
   "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
);

@month_names_long = (
   "January", "February", "March", "April", "May", "June",
   "July", "August", "September", "October", "November", "December"
);

@days_of_month = (
   "1st", "2nd", "3rd", "4th", "5th", "6th", "7th", "8th", "9th", "10th",
   "11th", "12th", "13th", "14th", "15th", "16th", "17th", "18th", "19th", "20th",
   "21st", "22nd", "23rd", "24th", "25th", "26th", "27th", "28th", "29th", "30th",
   "31st"
);

@days_in_month = (
   31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31
);

@metric_prefix = (
   'p', 'n', 'u', 'm', '', 'K', 'M', 'G', 'T', 'P', 'E'
);

PRINT_LINE

PRINT_LINE is useful when debugging. It prints the following on a single line to stderr:

• date/time
• process name
• function name
• filename
• line number
• error message.

Example

sub custom_hello_world
{
   PRINT_LINE ("Hello World!");
   return;
}

Jul  4 07:44:53.979347     0 ms nm-site-script-custom_hello_world 50187

Akips::Site::custom_hello_world Site.pm:57

Hello World!

trim

trim strips white space (spaces, line breaks, etc.) from a string.

Example

my $str = " Hello World! ";
$str = trim ($str);
print ($str); # "Hello World!"

errlog

AKIPS uses its own error log. Use the following syntax:

errlog ({LOG_LEVEL}, {log message})

Available log levels:

• $ERR_FATAL
• $ERR_ERROR
• $ERR_WARNING
• $ERR_INFO
• $ERR_USER
• $ERR_DEBUG
• $ERR_CGI

Example

my $error_msg = "it broke";
errlog ($ERR_FATAL, "something went wrong - %s", $error_msg);

To view error messages:

Go to Admin > System > System Log Viewer.

get_localtime()

get_localtime() (epoch timestamp) is a wrapper around the standard localtime()

Example

my $h_ref = get_localtime ();
printf "%s %s %s",
    $days_of_month[$h_ref->{mday} - 1],
    $month_names_long[$h_ref->{mon}],
    $h_ref->{year};

mail()

mail() takes a hash reference containing:

• to
• subject
• body
• attach, optionally.

Example

my @body = (
   "Hello,",
   "Greetings from AKIPS!",
   "Sincerely,",
   "Bob"
);

@files = ("/path/to/graph1.png", "/path/to/report1.pdf", "/path/to/report2.pdf");

mail ({
   to => '[email protected]',
   subject => 'Greetings',
   body => @body,
   attach => @files, #(optional)
});

syslog()

Example

syslog ({
    ipaddr   => "10.50.1.100",
    priority => "error",
    facility => "local3",
    message  => "The quick brown fox has jumped",
});

http_send() and http_result()

These HTTP functions are a wrapper around the nm-http command line tool.

http_send() sends an HTTP request.

http_result() sends an HTTP request and returns response data.

Options

Example

http_send()

# Call remote server to execute scripts
 http_send ({
    url          => "https://www.example.com:8080/script?name=my_script.txt",
    method       => "GET",
    content_type => "text/html",
 });

http_result()

# Call to Opsgenie api that returns some data.
my %request;

# Options for alert.
my %options;
$options{message}      = "Test alert";
$options{priority}     = "low";

$request{url}          = "https://api.opsgenie.com/v2/alerts";
$request{headers}      = ["Authorization: GenieKey xxxxxx-xxxxx-xxxxx-xxxxx"];
$request{method}       = "post";
$request{content_type} = "application/json";
$request{data}         = encode_json (\%options);

my @result = http_result (\%request);

Database interface

The command line tool for the ADB is nm-db.

The ADB module simplifies interacting with nm-db by automatically opening and closing a bidirectional pipe when loading and exiting.

adb_send()

Use adb_send() to write the specified command to nm-db.

Example

adb_send ("add device group CoreRouters");
adb_send ("add device group CoreSwitches");
adb_flush ();

adb_flush()

Use adb_flush() to flush all buffered output to nm-db.

You must do this after calling adb_send()

adb_result()

Use adb_result() to write to nm-db and return the results in either a scalar or array.

You do not need to call adb_flush()

Example

my @cisco_devices = adb_result ("mget device any group Cisco");

Discover

discover_scan()

discover_scan() performs the first stage of the device discover and creates the intermediate files for discover_config()

ping.scan lists the IPv4/6 addresses that responded to a ping scan.

snmp.scan lists the SNMP walk of the SNMPv2-MIB.system for each device.

devices lists the IPv4/6 address, SNMPv2-MIB.sysName, SNMP credentials, SNMPv2-MIB.sysObjectID and SNMPv2-MIB.sysDescr.

Use the following syntax:

discover_scan ( {SNMP Parameters}, {IP Address Range}, ... );

Examples

Scan three IP ranges using existing discover SNMP credentials:

discover_scan (undef, "10.0.0.0/16", "10.3.0.0/24", "10.5.0.0/24");

Scan multiple IP ranges using specified SNMPv2 credentials:

discover_scan ("version 2 community loofah", "10.3.0.0/24", "10.5.0.0/24");

Scan one IP address using specified SNMPv3 credentials:

discover_scan ("version 3 sha passwd1 aes256 passwd1", "10.2.0.1");

discover_config()

discover_config() performs SNMP walks of each device which

discover_scan() locates, then processes the data to configure each device.

discover_device_rewalk()

discover_device_rewalk() performs an SNMP walk for a specified device and then processes the data to configure the device.

It returns:

0 = failure

1 = success

Use the following syntax: FIXME:

discover_device_rewalk (%hash_ref);

Example

discover_device_rewalk ({
    ipaddr = > "10.1.2.3",
    device = > "atlanta-ro",
});