Agent Plugins Development

The agent plugin is run by Pandora FMS Software Agent so it has to have some special features:

• Each plugin execution may return one or more modules with their corresponding values. The output must be in XML format.
• It will be possible to access local machine resources local or remote machine resources.
• It is possible to use any type of programming language supported by the operating system where the Pandora FMS software agent is installed.
• All dependencies or software needed to run the plugin must be available or installed in the same machine that runs Pandora FMS agent.

Agent plugins may perform a kind of recon task since the plugin may return several modules in one run and the number may change between different runs.

This agent plugin returns the percentage of system filesystem usage.

#!/usr/bin/perl
 
use strict;
 
sub usage() {
        print "\npandora_df.pl v1r1\n\n";
        print "usage: ./pandora_df\n";
        print "usage: ./pandora_df tmpfs /dev/sda1\n\n";
}
 
# Retrieve information from all filesystem
my $all_filesystems = 0;
 
# Check command line parameters
if ($#ARGV <0) {
        $all_filesystems = 1;
}
 
if ($ARGV[0] eq "-h") {
        usage();
        exit(0);
}
 
# Parse command line parameters
my %filesystems;
foreach my $fs (@ARGV) {
        $filesystems{$fs} = '-1%';
}
 
# Retrieve filesystem information
# -P use the POSIX output format for portability
my @df = `df -P`;
shift (@df);
 
# No filesystems? Something went wrong.
if ($#df <0) {
        exit 1;
}
 
# Parse filesystem usage
foreach my $row (@df) {
        my @columns = split (' ', $row);
        exit 1 if ($#columns <4);
        $filesystems{$columns[0]} = $columns[4] if (defined ($filesystems{$columns[0]}) || $all_filesystems == 1);
}
 
while (my ($filesystem, $use) = each (%filesystems)) {
 
        # Remove the trailing %
        chop ($use);
 
        # Print module output
        print "<module>\n";
        print "<name><![CDATA[" . $filesystem . "]]></name>\n";
        print "<type><![CDATA[generic_data]]></type>\n";
        print "<data><![CDATA[" . $use . "]]></data>\n";
        print "<description>% of usage in this volume</description>\n";
        print "</module>\n";
}
 
exit 0;

An important part of the code is the usage function:

sub usage() {
        print "\npandora_df.pl v1r1\n\n";
        print "usage: ./pandora_df\n";
        print "usage: ./pandora_df tmpfs /dev/sda1\n\n";
}

This function describes the version and how to use plugin. It is very important and must always be shown when running the plugin without any parameter or with a -h (or -help) option:

if ($ARGV[0] eq "-h") {
        usage();
        exit(0);
}

Regarding the values returned by the plugin, it is noticed that once the data of the following files have been collected, a part of XML is created and printed by the standard output for each of them. This task is performed in the following lines:

while (my ($filesystem, $use) = each (%filesystems)) {
 
        # Remove the trailing %
        chop ($use);
 
        # Print module output
        print "<module>\n";
        print "<name><![CDATA[" . $filesystem . "]]></name>\n";
        print "<type><![CDATA[generic_data]]></type>\n";
        print "<data><![CDATA[" . $use . "]]></data>\n";
        print "<description>% of usage in this volume</description>\n";
        print "</module>\n";
}

The result returned by this plugin could be:

<module>
  <name><![CDATA[tmpfs]]></name>
  <type><![CDATA[generic_data]]></type>
  <data><![CDATA[0]]></data>
  <description>% of usage in this volume</description>
</module>
<module>
  <name><![CDATA[/dev/mapper/VolGroup-lv_home]]></name>
  <type><![CDATA[generic_data]]></type>
  <data><![CDATA[26]]></data>
  <description>% of usage in this volume</description>
</module>
<module>
  <name><![CDATA[/dev/sda9]]></name>
  <type><![CDATA[generic_data]]></type>
  <data><![CDATA[34]]></data>
  <description>% of usage in this volume</description>
</module>

The number of modules returned by this plugin depends on the number of configured filesystems and may change between executions.

The XML fragment is added to the general XML generated by the software agent and is sent to Pandora FMS server to be processed by the Data Server.

If Pandora FMS does not recognize the agent plugin, it does not get the expected information or the agent just does not work, here are several things that should be taken into account.

The Software Agent requires a line in this file with the correct path of the plugin.

Example:

/etc/pandora/pandora_agent.conf

module_plugin /etc/pandora/plugins/MyMonitor.pl /etc/pandora/plugins/MyMonitor.conf 2> /etc/pandora/plugins/MyMonitor.err

MyMonitor.pl is the agent plugin, MyMonitor.conf is the configuration file added as an argument, and MyMonitor.err is a file that will receive possible errors from the plugin execution and keep the standard output clean.

The Software Agent will run the plugins every 5 minutes and it is possible to restart the Software Agent with the root user or equivalent from the command line:

/etc/init.d/pandora_agent_daemon restart

The plugin and the files to be used must have the correct reading, writing and executing permissions.

chmod 755 <plugin_path >

A better way to find errors is to run the plugin manually in the command line. The result or output of the execution should be carefully checked.

The XML produced by the plugin must have a valid XML syntax. To check it you may follow these two steps from the command line (xmllint must be installed):

1. Create an XML document with the plugin output: ./Plugin.pl> Plugin.xml.
2. Checking the XML document: xmllint Plugin.xml.

You may activate the development mode by changing the value of the debug tag in the pandora_agent.conf file from 0 to 1. Once done, when the Software Agent runs the plugin, the results will be saved in an XML document with all the agent information.

The name of the document will be the name of the agent with the .data extension and it will be located in the 'tmp' directory (you should check PFMS agent log in /var/log/pandora/pandora_agent.log). By rdouble checking the document, you will be able to see whether the plugin data is being collected and if it is as expected.

If after everything else the error persists, you may ask in PFMS forum.

Back to Pandora FMS Documentation Index.