tyler.durden
/
centreon-plugins
mirror of https://github.com/centreon/centreon-plugins.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
centreon-plugins/docs/en/developer/guide.rst

1799 lines
62 KiB
ReStructuredText
Raw Blame History

***********
Description
***********
This document introduces the best practices in the development of "centreon-plugins".
As all plugins are written in Perl, “there is more than one way to do it”.
But to avoid reinventing the wheel, you should first take a look at the “example” directory, you will get an overview of how to build your own plugin and associated modes.
The lastest version is available on following git repository: http://git.centreon.com/centreon-plugins.git
***********
Quick Start
***********
------------------
Directory creation
------------------
First of all, you need to create a directory on the git to store the new plugin.
Root directories are organized by section:
* Application : apps
* Database : database
* Hardware : hardware
* network equipment : network
* Operating System : os
* Storage equipment : storage
According to the monitored object, it exists an organization which can use:
* Type
* Constructor
* Model
* Monitoring Protocol
For example, if you want to add a plugin to monitor Linux by SNMP, you need to create this directory:
::
$ mkdir -p os/linux/snmp
You also need to create a "mode" directory for futures modes:
::
$ mkdir os/linux/snmp/mode
---------------
Plugin creation
---------------
Once the directory is created, create the plugin file inside it:
::
$ touch plugin.pm
Then, edit plugin.pm to add **license terms** by copying it from an other plugin. Don't forget to put your name at the end of it:
.. code-block:: perl
# ...
# Authors : <your name> <<your email>>
Next, describe your **package** name : it matches your plugin directory.
.. code-block:: perl
package path::to::plugin;
Declare used libraries (**strict** and **warnings** are mandatory). Centreon libraries are described later:
.. code-block:: perl
use strict;
use warnings;
use base qw(**centreon_library**);
The plugin need a **new** constructor to instantiate the object:
.. code-block:: perl
sub new {
my ($class, %options) = @_;
my $self = $class->SUPER::new(package => __PACKAGE__, %options);
bless $self, $class;
...
return $self;
}
Plugin version must be declared in the **new** constructor:
.. code-block:: perl
$self->{version} = '0.1';
Several modes can be declared in the **new** constructor:
.. code-block:: perl
%{$self->{modes}} = (
'mode1' => '<plugin_path>::mode::mode1',
'mode2' => '<plugin_path>::mode::mode2',
...
);
Then, declare the module:
.. code-block:: perl
1;
A description of the plugin is needed to generate the documentation:
.. code-block:: perl
__END__
=head1 PLUGIN DESCRIPTION
<Add a plugin description here>.
=cut
.. tip::
You can copy-paste an other plugin.pm and adapt some lines (package, arguments...).
.. tip::
The plugin has ".pm" extension because it's a Perl module. So don't forget to add **1;** at the end of the file.
-------------
Mode creation
-------------
Once **plugin.pm** is created and modes are declared in it, create modes in the **mode** directory:
::
cd mode
touch mode1.pm
Then, edit mode1.pm to add **license terms** by copying it from an other mode. Don't forget to put your name at the end of it:
.. code-block:: perl
# ...
# Authors : <your name> <<your email>>
Next, describe your **package** name: it matches your mode directory.
.. code-block:: perl
package path::to::plugin::mode::mode1;
Declare used libraries (always the same):
.. code-block:: perl
use strict;
use warnings;
use base qw(centreon::plugins::mode);
The mode needs a **new** constructor to instantiate the object:
.. code-block:: perl
sub new {
my ($class, %options) = @_;
my $self = $class->SUPER::new(package => __PACKAGE__, %options);
bless $self, $class;
...
return $self;
}
Mode version must be declared in the **new** constructor:
.. code-block:: perl
$self->{version} = '1.0';
Several options can be declared in the **new** constructor:
.. code-block:: perl
$options{options}->add_options(arguments =>
{
"option1:s" => { name => 'option1' },
"option2:s" => { name => 'option2', default => 'value1' },
"option3" => { name => 'option3' },
});
Here is the description of arguments used in this example:
* option1 : String value
* option2 : String value with default value "value1"
* option3 : Boolean value
.. tip::
You can have more informations about options format here: http://perldoc.perl.org/Getopt/Long.html
The mode need a **check_options** method to validate options:
.. code-block:: perl
sub check_options {
my ($self, %options) = @_;
$self->SUPER::init(%options);
...
}
For example, Warning and Critical thresholds must be validate in **check_options** method:
.. code-block:: perl
if (($self->{perfdata}->threshold_validate(label => 'warning', value => $self->{option_results}->{warning})) == 0) {
$self->{output}->add_option_msg(short_msg => "Wrong warning threshold '" . $self->{option_results}->{warning} . "'.");
$self->{output}->option_exit();
}
if (($self->{perfdata}->threshold_validate(label => 'critical', value => $self->{option_results}->{critical})) == 0) {
$self->{output}->add_option_msg(short_msg => "Wrong critical threshold '" . $self->{option_results}->{critical} . "'.");
$self->{output}->option_exit();
}
In this example, help is printed if thresholds do not have a correct format.
Then comes the **run** method, where you perform measurement, check thresholds, display output and format performance datas.
This is an example to check a SNMP value:
.. code-block:: perl
sub run {
my ($self, %options) = @_;
$self->{snmp} = $options{snmp};
$self->{hostname} = $self->{snmp}->get_hostname();
my $result = $self->{snmp}->get_leef(oids => [$self->{option_results}->{oid}], nothing_quit => 1);
my $value = $result->{$self->{option_results}->{oid}};
my $exit = $self->{perfdata}->threshold_check(value => $value,
threshold => [ { label => 'critical', 'exit_litteral' => 'critical' }, { label => 'warning', exit_litteral => 'warning' } ]);
$self->{output}->output_add(severity => $exit,
short_msg => sprintf("SNMP Value is %s.", $value));
$self->{output}->perfdata_add(label => 'value', unit => undef,
value => $value,
warning => $self->{perfdata}->get_perfdata_for_output(label => 'warning'),
critical => $self->{perfdata}->get_perfdata_for_output(label => 'critical'),
min => undef, max => undef);
$self->{output}->display();
$self->{output}->exit();
}
In this example, we check a SNMP OID that we compare to warning and critical thresholds.
There are the methods which we use:
* get_leef : get a SNMP value from an OID
* threshold_check : compare SNMP value to warning and critical thresholds
* output_add : add output
* perfdata_add : add perfdata to output
* display : display output
* exit : exit
Then, declare the module:
.. code-block:: perl
1;
A description of the mode and its arguments is needed to generate the documentation:
.. code-block:: perl
__END__
=head1 PLUGIN DESCRIPTION
<Add a plugin description here>.
=cut
---------------
Commit and push
---------------
Before committing the plugin, you need to create an **enhancement ticket** on the centreon-plugins forge : http://forge.centreon.com/projects/centreon-plugins
Once plugin and modes are developed, you can commit (commit messages in english) and push your work:
::
git add path/to/plugin
git commit -m "Add new plugin for XXXX refs #<ticked_id>"
git push
*******************
Libraries reference
*******************
This chapter describes Centreon libraries which you can use in your development.
------
Output
------
This library allows you to build output of your plugin.
output_add
----------
Description
^^^^^^^^^^^
Add string to output (print it with **display** method).
If status is different than 'ok', output associated with 'ok' status is not printed.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| severity | String | OK | Status of the output. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| separator | String | \- | Separator between status and output string. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| short_msg | String | | Short output (first line). |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| long_msg | String | | Long output (used with --verbose option). |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to manage output:
.. code-block:: perl
$self->{output}->output_add(severity => 'OK',
short_msg => 'All is ok');
$self->{output}->output_add(severity => 'Critical',
short_msg => 'There is a critical problem');
$self->{output}->output_add(long_msg => 'Port 1 is disconnected');
$self->{output}->display();
Output displays :
::
CRITICAL - There is a critical problem
Port 1 is disconnected
perfdata_add
------------
Description
^^^^^^^^^^^
Add performance data to output (print it with **display** method).
Performance data are displayed after '|'.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| label | String | | Label of the performance data. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| value | Int | | Value of the performance data. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| unit | String | | Unit of the performance data. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| warning | String | | Warning threshold. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| critical | String | | Critical threshold. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| min | Int | | Minimum value of the performance data. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| max | Int | | Maximum value of the performance data. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to add performance data:
.. code-block:: perl
$self->{output}->output_add(severity => 'OK',
short_msg => 'Memory is ok');
$self->{output}->perfdata_add(label => 'memory_used',
value => 30000000,
unit => 'B',
warning => '80000000',
critical => '90000000',
min => 0,
max => 100000000);
$self->{output}->display();
Output displays:
::
OK - Memory is ok | 'memory_used'=30000000B;80000000;90000000;0;100000000
--------
Perfdata
--------
This library allows you to manage performance data.
get_perfdata_for_output
-----------------------
Description
^^^^^^^^^^^
Manage thresholds of performance data for output.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+-----------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+===========================================================+
| **label** | String | | Threshold label. |
+-----------------+-----------------+-------------+-----------------------------------------------------------+
| total | Int | | Percent threshold to transform in global. |
+-----------------+-----------------+-------------+-----------------------------------------------------------+
| cast_int | Int (0 or 1) | | Cast absolute to int. |
+-----------------+-----------------+-------------+-----------------------------------------------------------+
| op | String | | Operator to apply to start/end value (uses with 'value'). |
+-----------------+-----------------+-------------+-----------------------------------------------------------+
| value | Int | | Value to apply with 'op' option. |
+-----------------+-----------------+-------------+-----------------------------------------------------------+
Example
^^^^^^^
This is an example of how to manage performance data for output:
.. code-block:: perl
my $format_warning_perfdata = $self->{perfdata}->get_perfdata_for_output(label => 'warning', total => 1000000000, cast_int => 1);
my $format_critical_perfdata = $self->{perfdata}->get_perfdata_for_output(label => 'critical', total => 1000000000, cast_int => 1);
$self->{output}->perfdata_add(label => 'memory_used',
value => 30000000,
unit => 'B',
warning => $format_warning_perfdata,
critical => $format_critical_perfdata,
min => 0,
max => 1000000000);
.. tip::
In this example, instead of print warning and critical thresholds in 'percent', the function calculates and prints these in 'bytes'.
threshold_validate
------------------
Description
^^^^^^^^^^^
Validate and affect threshold to a label.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| label | String | | Threshold label. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| value | String | | Threshold value. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This example checks if warning threshold is correct:
.. code-block:: perl
if (($self->{perfdata}->threshold_validate(label => 'warning', value => $self->{option_results}->{warning})) == 0) {
$self->{output}->add_option_msg(short_msg => "Wrong warning threshold '" . $self->{option_results}->{warning} . "'.");
$self->{output}->option_exit();
}
.. tip::
You can see the correct threshold format here: https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT
threshold_check
---------------
Description
^^^^^^^^^^^
Check performance data value with threshold to determine status.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| value | Int | | Performance data value to compare. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| threshold | String array | | Threshold label to compare and exit status if reached. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This example checks if performance data reached thresholds:
.. code-block:: perl
$self->{perfdata}->threshold_validate(label => 'warning', value => 80);
$self->{perfdata}->threshold_validate(label => 'critical', value => 90);
my $prct_used = 85;
my $exit = $self->{perfdata}->threshold_check(value => $prct_used, threshold => [ { label => 'critical', 'exit_litteral' => 'critical' }, { label => 'warning', exit_litteral => 'warning' } ]);
$self->{output}->output_add(severity => $exit,
short_msg => sprint("Used memory is %i%%", $prct_used));
$self->{output}->display();
Output displays:
::
WARNING - Used memory is 85% |
change_bytes
------------
Description
^^^^^^^^^^^
Convert bytes to human readable unit.
Return value and unit.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| value | Int | | Performance data value to convert. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| network | | 1024 | Unit to divide (1000 if defined). |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This example change bytes to human readable unit:
.. code-block:: perl
my ($value, $unit) = $self->{perfdata}->change_bytes(value => 100000);
print $value.' '.$unit."\n";
Output displays:
::
100 KB
----
Snmp
----
This library allows you to use SNMP protocol in your plugin.
To use it, add the following line at the beginning of your **plugin.pm**:
.. code-block:: perl
use base qw(centreon::plugins::script_snmp);
get_leef
--------
Description
^^^^^^^^^^^
Return hash table table of SNMP values for multiple OIDs (do not work with SNMP table).
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| **oids** | String array | | Array of OIDs to check (Can be set by 'load' method). |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| dont_quit | Int (0 or 1) | 0 | Don't quit even if an snmp error occured. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| nothing_quit | Int (0 or 1) | 0 | Quit if no value is returned. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to get 2 SNMP values:
.. code-block:: perl
my $oid_hrSystemUptime = '.1.3.6.1.2.1.25.1.1.0';
my $oid_sysUpTime = '.1.3.6.1.2.1.1.3.0';
my $result = $self->{snmp}->get_leef(oids => [ $oid_hrSystemUptime, $oid_sysUpTime ], nothing_quit => 1);
print $result->{$oid_hrSystemUptime}."\n";
print $result->{$oid_sysUpTime}."\n";
load
----
Description
^^^^^^^^^^^
Load a range of OIDs to use with **get_leef** method.
Parameters
^^^^^^^^^^
+-----------------+----------------------+--------------+----------------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+======================+==============+================================================================+
| **oids** | String array | | Array of OIDs to check. |
+-----------------+----------------------+--------------+----------------------------------------------------------------+
| instances | Int array | | Array of OID instances to check. |
+-----------------+----------------------+--------------+----------------------------------------------------------------+
| instance_regexp | String | | Regular expression to get instances from **instances** option. |
+-----------------+----------------------+--------------+----------------------------------------------------------------+
| begin | Int | | Instance to begin |
+-----------------+----------------------+--------------+----------------------------------------------------------------+
| end | Int | | Instance to end |
+-----------------+----------------------+--------------+----------------------------------------------------------------+
Example
^^^^^^^
This is an example of how to get 4 instances of a SNMP table by using **load** method:
.. code-block:: perl
my $oid_dskPath = '.1.3.6.1.4.1.2021.9.1.2';
$self->{snmp}->load(oids => [$oid_dskPercentNode], instances => [1,2,3,4]);
my $result = $self->{snmp}->get_leef(nothing_quit => 1);
use Data::Dumper;
print Dumper($result);
This is an example of how to get multiple instances dynamically (memory modules of Dell hardware) by using **load** method:
.. code-block:: perl
my $oid_memoryDeviceStatus = '.1.3.6.1.4.1.674.10892.1.1100.50.1.5';
my $oid_memoryDeviceLocationName = '.1.3.6.1.4.1.674.10892.1.1100.50.1.8';
my $oid_memoryDeviceSize = '.1.3.6.1.4.1.674.10892.1.1100.50.1.14';
my $oid_memoryDeviceFailureModes = '.1.3.6.1.4.1.674.10892.1.1100.50.1.20';
my $result = $self->{snmp}->get_table(oid => $oid_memoryDeviceStatus);
$self->{snmp}->load(oids => [$oid_memoryDeviceLocationName, $oid_memoryDeviceSize, $oid_memoryDeviceFailureModes],
instances => [keys %$result],
instance_regexp => '(\d+\.\d+)$');
my $result2 = $self->{snmp}->get_leef();
use Data::Dumper;
print Dumper($result2);
get_table
---------
Description
^^^^^^^^^^^
Return hash table of SNMP values for SNMP table.
Parameters
^^^^^^^^^^
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+======================+================+==============================================================+
| **oid** | String | | OID of the snmp table to check. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| start | Int | | First OID to check. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| end | Int | | Last OID to check. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| dont_quit | Int (0 or 1) | 0 | Don't quit even if an SNMP error occured. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| nothing_quit | Int (0 or 1) | 0 | Quit if no value is returned. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| return_type | Int (0 or 1) | 0 | Return a hash table with one level instead of multiple. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
Example
^^^^^^^
This is an example of how to get a SNMP table:
.. code-block:: perl
my $oid_rcDeviceError = '.1.3.6.1.4.1.15004.4.2.1';
my $oid_rcDeviceErrWatchdogReset = '.1.3.6.1.4.1.15004.4.2.1.2.0';
my $results = $self->{snmp}->get_table(oid => $oid_rcDeviceError, start => $oid_rcDeviceErrWatchdogReset);
use Data::Dumper;
print Dumper($results);
get_multiple_table
------------------
Description
^^^^^^^^^^^
Return hash table of SNMP values for multiple SNMP tables.
Parameters
^^^^^^^^^^
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+======================+================+==============================================================+
| **oids** | Hash table | | Hash table of OIDs to check (Can be set by 'load' method). |
| | | | Keys can be: "oid", "start", "end". |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| dont_quit | Int (0 or 1) | 0 | Don't quit even if an SNMP error occured. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| nothing_quit | Int (0 or 1) | 0 | Quit if no value is returned. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
| return_type | Int (0 or 1) | 0 | Return a hash table with one level instead of multiple. |
+-----------------+----------------------+----------------+--------------------------------------------------------------+
Example
^^^^^^^
This is an example of how to get 2 SNMP tables:
.. code-block:: perl
my $oid_sysDescr = ".1.3.6.1.2.1.1.1";
my $aix_swap_pool = ".1.3.6.1.4.1.2.6.191.2.4.2.1";
my $results = $self->{snmp}->get_multiple_table(oids => [
{ oid => $aix_swap_pool, start => 1 },
{ oid => $oid_sysDescr },
]);
use Data::Dumper;
print Dumper($results);
get_hostname
------------
Description
^^^^^^^^^^^
Get hostname parameter (useful to get hostname in mode).
Parameters
^^^^^^^^^^
None.
Example
^^^^^^^
This is an example of how to get hostname parameter:
.. code-block:: perl
my $hostname = $self->{snmp}->get_hostname();
get_port
--------
Description
^^^^^^^^^^^
Get port parameter (useful to get port in mode).
Parameters
^^^^^^^^^^
None.
Example
^^^^^^^
This is an example of how to get port parameter:
.. code-block:: perl
my $port = $self->{snmp}->get_port();
oid_lex_sort
------------
Description
^^^^^^^^^^^
Return sorted OIDs.
Parameters
^^^^^^^^^^
+-----------------+-------------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+===================+=============+=========================================================+
| **-** | String array | | Array of OIDs to sort. |
+-----------------+-------------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This example prints sorted OIDs:
.. code-block:: perl
foreach my $oid ($self->{snmp}->oid_lex_sort(keys %{$self->{results}->{$my_oid}})) {
print $oid;
}
----
Misc
----
This library provides a set of miscellaneous methods.
To use it, you can directly use the path of the method:
.. code-block:: perl
centreon::plugins::misc::<my_method>;
trim
----
Description
^^^^^^^^^^^
Strip whitespace from the beginning and end of a string.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| **-** | String | | String to strip. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **trim** method:
.. code-block:: perl
my $word = ' Hello world ! ';
my $trim_word = centreon::plugins::misc::trim($word);
print $word."\n";
print $trim_word."\n";
Output displays :
::
Hello world !
change_seconds
--------------
Description
^^^^^^^^^^^
Convert seconds to human readable text.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| **-** | Int | | Number of seconds to convert. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **change_seconds** method:
.. code-block:: perl
my $seconds = 3750;
my $human_readable_time = centreon::plugins::misc::change_seconds($seconds);
print 'Human readable time : '.$human_readable_time."\n";
Output displays:
::
Human readable time : 1h 2m 30s
backtick
--------
Description
^^^^^^^^^^^
Execute system command.
Parameters
^^^^^^^^^^
+-----------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+=================+=================+=============+=========================================================+
| **command** | String | | Command to execute. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| arguments | String array | | Command arguments. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| timeout | Int | 30 | Command timeout. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| wait_exit | Int (0 or 1) | 0 | Command process ignore SIGCHLD signals. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
| redirect_stderr | Int (0 or 1) | 0 | Print errors in output. |
+-----------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **backtick** method:
.. code-block:: perl
my ($error, $stdout, $exit_code) = centreon::plugins::misc::backtick(
command => 'ls /home',
timeout => 5,
wait_exit => 1
);
print $stdout."\n";
Output displays files in '/home' directory.
execute
-------
Description
^^^^^^^^^^^
Execute command remotely.
Parameters
^^^^^^^^^^
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| Parameter | Type | Default | Description |
+==================+=================+=============+=================================================================+
| **output** | Object | | Plugin output ($self->{output}). |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| **options** | Object | | Plugin options ($self->{option_results}) to get remote options. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| sudo | String | | Use sudo command. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| **command** | String | | Command to execute. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| command_path | String | | Command path. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| command_options | String | | Command arguments. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **execute** method.
We suppose ``--remote`` option is enabled:
.. code-block:: perl
my $stdout = centreon::plugins::misc::execute(output => $self->{output},
options => $self->{option_results},
sudo => 1,
command => 'ls /home',
command_path => '/bin/',
command_options => '-l');
Output displays files in /home using ssh on a remote host.
windows_execute
---------------
Description
^^^^^^^^^^^
Execute command on Windows.
Parameters
^^^^^^^^^^
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| Parameter | Type | Default | Description |
+==================+=================+=============+=================================================================+
| **output** | Object | | Plugin output ($self->{output}). |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| **command** | String | | Command to execute. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| command_path | String | | Command path. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| command_options | String | | Command arguments. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| timeout | Int | | Command timeout. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
| no_quit | Int | | Don't quit even if an error occured. |
+------------------+-----------------+-------------+-----------------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **windows_execute** method.
.. code-block:: perl
my $stdout = centreon::plugins::misc::windows_execute(output => $self->{output},
timeout => 10,
command => 'ipconfig',
command_path => '',
command_options => '/all');
Output displays IP configuration on a Windows host.
---------
Statefile
---------
This library provides a set of methods to use a cache file.
To use it, add the following line at the beginning of your **mode**:
.. code-block:: perl
use centreon::plugins::statefile;
read
----
Description
^^^^^^^^^^^
Read cache file.
Parameters
^^^^^^^^^^
+-------------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+===================+=================+=============+=========================================================+
| **statefile** | String | | Name of the cache file. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
| **statefile_dir** | String | | Directory of the cache file. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
| memcached | String | | Memcached server to use. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **read** method:
.. code-block:: perl
$self->{statefile_value} = centreon::plugins::statefile->new(%options);
$self->{statefile_value}->check_options(%options);
$self->{statefile_value}->read(statefile => 'my_cache_file',
statefile_dir => '/var/lib/centreon/centplugins'
);
use Data::Dumper;
print Dumper($self->{statefile_value});
Output displays cache file and its parameters.
get
---
Description
^^^^^^^^^^^
Get data from cache file.
Parameters
^^^^^^^^^^
+-------------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+===================+=================+=============+=========================================================+
| name | String | | Get a value from cache file. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **get** method:
.. code-block:: perl
$self->{statefile_value} = centreon::plugins::statefile->new(%options);
$self->{statefile_value}->check_options(%options);
$self->{statefile_value}->read(statefile => 'my_cache_file',
statefile_dir => '/var/lib/centreon/centplugins'
);
my $value = $self->{statefile_value}->get(name => 'property1');
print $value."\n";
Output displays value for 'property1' of the cache file.
write
-----
Description
^^^^^^^^^^^
Write data to cache file.
Parameters
^^^^^^^^^^
+-------------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+===================+=================+=============+=========================================================+
| data | String | | Data to write in cache file. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **write** method:
.. code-block:: perl
$self->{statefile_value} = centreon::plugins::statefile->new(%options);
$self->{statefile_value}->check_options(%options);
$self->{statefile_value}->read(statefile => 'my_cache_file',
statefile_dir => '/var/lib/centreon/centplugins'
);
my $new_datas = {};
$new_datas->{last_timestamp} = time();
$self->{statefile_value}->write(data => $new_datas);
Then, you can read the result in '/var/lib/centreon/centplugins/my_cache_file', timestamp is written in it.
----
HTTP
----
This library provides a set of methodss to use HTTP protocol.
To use it, add the following line at the beginning of your **mode**:
.. code-block:: perl
use centreon::plugins::httplib;
Some options must be set in **plugin.pm**:
+-----------------+-----------------+---------------------------------------------------------+
| Option | Type | Description |
+=================+=================+=========================================================+
| **hostname** | String | IP Addr/FQDN of the webserver host. |
+-----------------+-----------------+---------------------------------------------------------+
| **port** | String | HTTP port. |
+-----------------+-----------------+---------------------------------------------------------+
| **proto** | String | Used protocol ('http' or 'https'). |
+-----------------+-----------------+---------------------------------------------------------+
| credentials | | Use credentials. |
+-----------------+-----------------+---------------------------------------------------------+
| ntlm | | Use NTLM authentication (if ``--credentials`` is used). |
+-----------------+-----------------+---------------------------------------------------------+
| username | String | Username (if ``--credentials`` is used). |
+-----------------+-----------------+---------------------------------------------------------+
| password | String | User password (if ``--credentials`` is used). |
+-----------------+-----------------+---------------------------------------------------------+
| proxyurl | String | Proxy to use. |
+-----------------+-----------------+---------------------------------------------------------+
| url_path | String | URL to connect (start to '/'). |
+-----------------+-----------------+---------------------------------------------------------+
connect
-------
Description
^^^^^^^^^^^
Test a connection to an HTTP url.
Return content of the webpage.
Parameters
^^^^^^^^^^
This method use plugin options previously defined.
Example
^^^^^^^
This is an example of how to use **connect** method.
We suppose these options are defined :
* --hostname = 'google.com'
* --urlpath = '/'
* --proto = 'http'
* --port = 80
.. code-block:: perl
my $webcontent = centreon::plugins::httplib::connect($self);
print $webcontent;
Output displays content of the webpage '\http://google.com/'.
---
DBI
---
This library allows you to connect to databases.
To use it, add the following line at the beginning of your **plugin.pm**:
.. code-block:: perl
use base qw(centreon::plugins::script_sql);
connect
-------
Description
^^^^^^^^^^^
Connect to databases.
Parameters
^^^^^^^^^^
+-------------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+===================+=================+=============+=========================================================+
| dontquit | Int (0 or 1) | 0 | Don't quit even if errors occured. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **connect** method.
The format of the connection string can have the following forms:
::
DriverName:database_name
DriverName:database_name@hostname:port
DriverName:database=database_name;host=hostname;port=port
In plugin.pm:
.. code-block:: perl
$self->{sqldefault}->{dbi} = ();
$self->{sqldefault}->{dbi} = { data_source => 'mysql:host=127.0.0.1;port=3306' };
In your mode:
.. code-block:: perl
$self->{sql} = $options{sql};
my ($exit, $msg_error) = $self->{sql}->connect(dontquit => 1);
Then, you are connected to the MySQL database.
query
-----
Description
^^^^^^^^^^^
Send query to database.
Parameters
^^^^^^^^^^
+-------------------+-----------------+-------------+---------------------------------------------------------+
| Parameter | Type | Default | Description |
+===================+=================+=============+=========================================================+
| query | String | | SQL query to send. |
+-------------------+-----------------+-------------+---------------------------------------------------------+
Example
^^^^^^^
This is an example of how to use **query** method:
.. code-block:: perl
$self->{sql}->query(query => q{SHOW /*!50000 global */ STATUS LIKE 'Slow_queries'});
my ($name, $result) = $self->{sql}->fetchrow_array();
print 'Name : '.$name."\n";
print 'Value : '.$value."\n";
Output displays count of MySQL slow queries.
fetchrow_array
--------------
Description
^^^^^^^^^^^
Return Array from sql query.
Parameters
^^^^^^^^^^
None.
Example
^^^^^^^
This is an example of how to use **fetchrow_array** method:
.. code-block:: perl
$self->{sql}->query(query => q{SHOW /*!50000 global */ STATUS LIKE 'Uptime'});
my ($dummy, $result) = $self->{sql}->fetchrow_array();
print 'Uptime : '.$result."\n";
Output displays MySQL uptime.
fetchall_arrayref
-----------------
Description
^^^^^^^^^^^
Return Array from SQL query.
Parameters
^^^^^^^^^^
None.
Example
^^^^^^^
This is an example of how to use **fetchrow_array** method:
.. code-block:: perl
$self->{sql}->query(query => q{
SELECT SUM(DECODE(name, 'physical reads', value, 0)),
SUM(DECODE(name, 'physical reads direct', value, 0)),
SUM(DECODE(name, 'physical reads direct (lob)', value, 0)),
SUM(DECODE(name, 'session logical reads', value, 0))
FROM sys.v_$sysstat
});
my $result = $self->{sql}->fetchall_arrayref();
my $physical_reads = @$result[0]->[0];
my $physical_reads_direct = @$result[0]->[1];
my $physical_reads_direct_lob = @$result[0]->[2];
my $session_logical_reads = @$result[0]->[3];
print $physical_reads."\n";
Output displays physical reads on Oracle database.
fetchrow_hashref
----------------
Description
^^^^^^^^^^^
Return Hash table from SQL query.
Parameters
^^^^^^^^^^
None.
Example
^^^^^^^
This is an example of how to use **fetchrow_hashref** method:
.. code-block:: perl
$self->{sql}->query(query => q{
SELECT datname FROM pg_database
});
while ((my $row = $self->{sql}->fetchrow_hashref())) {
print $row->{datname}."\n";
}
Output displays Postgres databases.
*****************
Complete examples
*****************
-------------------
Simple SNMP request
-------------------
Description
-----------
| This example explains how to check a single SNMP value on a PfSense firewall (memory dropped packets).
| We use cache file because it's a SNMP counter. So we need to get the value between 2 checks.
| We get the value and compare it to warning and critical thresholds.
Plugin file
-----------
First, create the plugin directory and the plugin file:
::
$ mkdir -p apps/pfsense/snmp
$ touch apps/pfsense/snmp/plugin.pm
.. tip::
PfSense is a firewall application and we check it using SNMP protocol
Then, edit **plugin.pm** and add the following lines:
.. code-block:: perl
################################################################################
# Copyright 2005-2015 MERETHIS
# Centreon is developped by : Julien Mathis and Romain Le Merlus under
# GPL Licence 2.0.
#
# This program is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation ; either version 2 of the License.
#
# This program is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE. See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# this program; if not, see <http://www.gnu.org/licenses>.
#
# Linking this program statically or dynamically with other modules is making a
# combined work based on this program. Thus, the terms and conditions of the GNU
# General Public License cover the whole combination.
#
# As a special exception, the copyright holders of this program give MERETHIS
# permission to link this program with independent modules to produce an executable,
# regardless of the license terms of these independent modules, and to copy and
# distribute the resulting executable under terms of MERETHIS choice, provided that
# MERETHIS also meet, for each linked independent module, the terms and conditions
# of the license of that module. An independent module is a module which is not
# derived from this program. If you modify this program, you may extend this
# exception to your version of the program, but you are not obliged to do so. If you
# do not wish to do so, delete this exception statement from your version.
#
# For more information : contact@centreon.com
# Authors : your name <your@mail>
#
####################################################################################
# Path to the plugin
package apps::pfsense::snmp::plugin;
# Needed libraries
use strict;
use warnings;
# Use this library to check using SNMP protocol
use base qw(centreon::plugins::script_snmp);
.. tip::
Don't forget to edit 'Authors' line.
Add **new** method to instantiate the plugin:
.. code-block:: perl
sub new {
my ($class, %options) = @_;
my $self = $class->SUPER::new(package => __PACKAGE__, %options);
bless $self, $class;
# $options->{options} = options object
# Plugin version
$self->{version} = '0.1';
# Modes association
%{$self->{modes}} = (
# Mode name => path to the mode
'memory-dropped-packets' => 'apps::pfsense::snmp::mode::memorydroppedpackets',
);
return $self;
}
Declare this plugin as a perl module:
.. code-block:: perl
1;
Add a description to the plugin:
.. code-block:: perl
__END__
=head1 PLUGIN DESCRIPTION
Check pfSense in SNMP.
=cut
.. tip::
This description is printed with '--help' option.
Mode file
---------
Then, create the mode directory and the mode file:
::
$ mkdir apps/pfsense/snmp/mode
$ touch apps/pfsense/snmp/mode/memorydroppedpackets.pm
Edit **memorydroppedpackets.pm** and add the following lines:
.. code-block:: perl
################################################################################
# Copyright 2005-2015 MERETHIS
# Centreon is developped by : Julien Mathis and Romain Le Merlus under
# GPL Licence 2.0.
#
# This program is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation ; either version 2 of the License.
#
# This program is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE. See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# this program; if not, see <http://www.gnu.org/licenses>.
#
# Linking this program statically or dynamically with other modules is making a
# combined work based on this program. Thus, the terms and conditions of the GNU
# General Public License cover the whole combination.
#
# As a special exception, the copyright holders of this program give MERETHIS
# permission to link this program with independent modules to produce an executable,
# regardless of the license terms of these independent modules, and to copy and
# distribute the resulting executable under terms of MERETHIS choice, provided that
# MERETHIS also meet, for each linked independent module, the terms and conditions
# of the license of that module. An independent module is a module which is not
# derived from this program. If you modify this program, you may extend this
# exception to your version of the program, but you are not obliged to do so. If you
# do not wish to do so, delete this exception statement from your version.
#
# For more information : contact@centreon.com
# Authors : your name <your@mail>
#
####################################################################################
# Path to the plugin
package apps::pfsense::snmp::mode::memorydroppedpackets;
# Needed library for modes
use base qw(centreon::plugins::mode);
# Needed libraries
use strict;
use warnings;
# Custom library
use POSIX;
# Needed library to use cache file
use centreon::plugins::statefile;
Add **new** method to instantiate the mode:
.. code-block:: perl
sub new {
my ($class, %options) = @_;
my $self = $class->SUPER::new(package => __PACKAGE__, %options);
bless $self, $class;
# Mode version
$self->{version} = '1.0';
# Declare options
$options{options}->add_options(arguments =>
{
# option name => variable name
"warning:s" => { name => 'warning', },
"critical:s" => { name => 'critical', },
});
# Instantiate cache file
$self->{statefile_value} = centreon::plugins::statefile->new(%options);
return $self;
}
.. tip::
A default value can be added to options.
Example : "warning:s" => { name => 'warning', default => '80'},
Add **check_options** method to validate options:
.. code-block:: perl
sub check_options {
my ($self, %options) = @_;
$self->SUPER::init(%options);
# Validate threshold options with threshold_validate method
if (($self->{perfdata}->threshold_validate(label => 'warning', value => $self->{option_results}->{warning})) == 0) {
$self->{output}->add_option_msg(short_msg => "Wrong warning threshold '" . $self->{option_results}->{warning} . "'.");
$self->{output}->option_exit();
}
if (($self->{perfdata}->threshold_validate(label => 'critical', value => $self->{option_results}->{critical})) == 0) {
$self->{output}->add_option_msg(short_msg => "Wrong critical threshold '" . $self->{option_results}->{critical} . "'.");
$self->{output}->option_exit();
}
# Validate cache file options using check_options method of statefile library
$self->{statefile_value}->check_options(%options);
}
Add **run** method to execute mode:
.. code-block:: perl
sub run {
my ($self, %options) = @_;
# $options{snmp} = snmp object
# Get SNMP options
$self->{snmp} = $options{snmp};
$self->{hostname} = $self->{snmp}->get_hostname();
$self->{snmp_port} = $self->{snmp}->get_port();
# SNMP oid to request
my $oid_pfsenseMemDropPackets = '.1.3.6.1.4.1.12325.1.200.1.2.6.0';
my ($result, $value);
# Get SNMP value for oid previsouly defined
$result = $self->{snmp}->get_leef(oids => [ $oid_pfsenseMemDropPackets ], nothing_quit => 1);
# $result is a hash table where keys are oids
$value = $result->{$oid_pfsenseMemDropPackets};
# Read the cache file
$self->{statefile_value}->read(statefile => 'pfsense_' . $self->{hostname} . '_' . $self->{snmp_port} . '_' . $self->{mode});
# Get cache file values
my $old_timestamp = $self->{statefile_value}->get(name => 'last_timestamp');
my $old_memDropPackets = $self->{statefile_value}->get(name => 'memDropPackets');
# Create a hash table with new values that will be write to cache file
my $new_datas = {};
$new_datas->{last_timestamp} = time();
$new_datas->{memDropPackets} = $value;
# Write new values to cache file
$self->{statefile_value}->write(data => $new_datas);
# If cache file didn't have any values, create it and wait another check to calculate value
if (!defined($old_timestamp) || !defined($old_memDropPackets)) {
$self->{output}->output_add(severity => 'OK',
short_msg => "Buffer creation...");
$self->{output}->display();
$self->{output}->exit();
}
# Fix when PfSense reboot (snmp counters initialize to 0)
$old_memDropPackets = 0 if ($old_memDropPackets > $new_datas->{memDropPackets});
# Calculate time between 2 checks
my $delta_time = $new_datas->{last_timestamp} - $old_timestamp;
$delta_time = 1 if ($delta_time == 0);
# Calculate value per second
my $memDropPacketsPerSec = ($new_datas->{memDropPackets} - $old_memDropPackets) / $delta_time;
# Calculate exit code by comparing value to thresholds
# Exit code can be : 'OK', 'WARNING', 'CRITICAL', 'UNKNOWN'
my $exit_code = $self->{perfdata}->threshold_check(value => $memDropPacketsPerSec,
threshold => [ { label => 'critical', 'exit_litteral' => 'critical' }, { label => 'warning', exit_litteral => 'warning' } ]);
# Add a performance data
$self->{output}->perfdata_add(label => 'dropped_packets_Per_Sec',
value => sprintf("%.2f", $memDropPacketsPerSec),
warning => $self->{perfdata}->get_perfdata_for_output(label => 'warning'),
critical => $self->{perfdata}->get_perfdata_for_output(label => 'critical'),
min => 0);
# Add output
$self->{output}->output_add(severity => $exit_code,
short_msg => sprintf("Dropped packets due to memory limitations : %.2f /s",
$memDropPacketsPerSec));
# Display output
$self->{output}->display();
$self->{output}->exit();
}
Declare this plugin as a perl module:
.. code-block:: perl
1;
Add a description of the mode options:
.. code-block:: perl
__END__
=head1 MODE
Check number of packets per second dropped due to memory limitations.
=over 8
=item B<--warning>
Threshold warning for dropped packets in packets per second.
=item B<--critical>
Threshold critical for dropped packets in packets per second.
=back
=cut
Command line
------------
This is an example of command line:
::
$ perl centreon_plugins.pl --plugin apps::pfsense::snmp::plugin --mode memory-dropped-packets --hostname 192.168.0.1 --snmp-community 'public' --snmp-version '2c' --warning '1' --critical '2'
Output may display:
::
OK: Dropped packets due to memory limitations : 0.00 /s | dropped_packets_Per_Sec=0.00;0;;1;2
Reference in New Issue View Git Blame Copy Permalink