Description

“centreon-plugins” is a free and open source project to monitor systems. The project can be used with Centreon, Icinga and all monitoring softwares compatible Nagios plugins.

The lastest version is available on following git repository: https://github.com/centreon/centreon-plugins.git

Installation

Debian Wheezy

Get the last version of “centreon-plugins” from the repository:

# aptitude install git
# git clone https://github.com/centreon/centreon-plugins.git

To monitor SNMP systems, you need to install the following packages:

# aptitude install perl libsnmp-perl

You can install other packages to use more plugins:

# aptitude install libxml-libxml-perl libjson-perl libwww-perl libxml-xpath-perl libnet-telnet-perl libnet-ntp-perl libnet-dns-perl libdbi-perl libdbd-mysql-perl libdbd-pg-perl

To use ‘memcached’ functionality, you need to install the following CPAN module (no debian package): http://search.cpan.org/~wolfsage/Memcached-libmemcached-1.001702/libmemcached.pm

Centos/Rhel 6

Get the last version of “centreon-plugins” from the repository:

# yum install git
# git clone https://github.com/centreon/centreon-plugins.git

To monitor SNMP systems, you need to install the following packages:

# yum install perl net-snmp-perl

You can install other packages to use more plugins:

# yum install perl-XML-LibXML perl-JSON perl-libwww-perl perl-XML-XPath perl-Net-Telnet perl-Net-DNS perl-DBI perl-DBD-MySQL perl-DBD-Pg

To use ‘memcached’ functionality, you need to install the following CPAN module (package available in ‘rpmforge’): http://search.cpan.org/~wolfsage/Memcached-libmemcached-1.001702/libmemcached.pm

Basic Usage

We’ll use a basic example to show you how to monitor a system. I have finished the install section and i want to monitor a Linux in SNMP. First, i need to find the plugin to use in the list:

$ perl centreon_plugins.pl --list-plugin | grep -i linux | grep 'PLUGIN'
PLUGIN: os::linux::local::plugin
PLUGIN: os::linux::snmp::plugin

It seems that ‘os::linux::snmp::plugin’ is the good one. So i verify with the option --help to be sure:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --help
...
Plugin Description:
  Check Linux operating systems in SNMP.

It’s exactly what i need. Now i’ll the option --list-mode to know what can i do with it:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --list-mode
...
Modes Available:
 processcount
 time
 list-storages
 disk-usage
 diskio
 uptime
 swap
 cpu-detailed
 load
 traffic
 cpu
 inodes
 list-diskspath
 list-interfaces
 packet-errors
 memory
 tcpcon
 storage

I would like to test the ‘load’ mode:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=load
UNKNOWN: Missing parameter --hostname.

It’s not working because some options are missing. I can have a description of the mode and options with the option --help:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=load --help

Eventually, i have to configure some SNMP options:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=load --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public
OK: Load average: 0.00, 0.00, 0.00 | 'load1'=0.00;;;0; 'load5'=0.00;;;0; 'load15'=0.00;;;0;

I can set threshold with options --warning and --critical:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=load --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --warning=1,2,3 --critical=2,3,4
OK: Load average: 0.00, 0.00, 0.00 | 'load1'=0.00;0:1;0:2;0; 'load5'=0.00;0:2;0:3;0; 'load15'=0.00;0:3;0:4;0;

FAQ

What can i monitor ?

The option --list-plugin can be used to get the list of plugins and a short description.

Headers of the table mean:

  • Transport: The check has internal options for the transport.
  • Protocol: what is used to get the monitoring datas.
  • Experimental: The check is still in development.
Category Check Transport Protocol Experimental Comment Perl dependencies
SSH TELNET WSMAN SNMP HTTP WMI JMX custom
Application Active Directory              
  Use ‘dcdiag’ command. Must be installed on Windows. Win32::Job
Apache        
        Need Apache ‘mod_status’ module. LWP::UserAgent, URI, HTTP::Cookies
Apc        
          LWP::UserAgent, URI, HTTP::Cookies
Apcupsd
           
  Use ‘apcupsd’ commands.  
Bluemind        
        Use ‘influxdb’ API. JSON, LWP::UserAgent, URI, HTTP::Cookies
Checkmyws        
          JSON, LWP::UserAgent, URI, HTTP::Cookies
Elasticsearch        
          JSON, LWP::UserAgent, URI, HTTP::Cookies
Exchange              
  Use powershell script. Must be installed on Windows. Win32::Job
Github        
        Use ‘github’ API. JSON, LWP::UserAgent, URI, HTTP::Cookies, DateTime
Hddtemp              
  Open a TCP custom communication  
IIS          
      Must be installed on Windows. Win32::OLE
   
   
   
  openwsman, MIME::Base64
Jenkins        
          JSON, LWP::UserAgent, URI, HTTP::Cookies
Kayako        
        Use ‘kayako’ API. XML::XPath, Digest::SHA, LWP::UserAgent, URI, HTTP::Cookies
Lmsensors      
             
Msmq              
Must be installed on Windows. Not developed yet.  
Nginx        
        Need ‘HttpStubStatusModule’ module. LWP::UserAgent, URI, HTTP::Cookies
Pacemaker
           
  Use ‘crm_mon’ command.  
Pfsense      
             
Selenium              
  Connect to a selenium server to play a scenario. XML::XPath, WWW::Selenium
Tomcat        
        Need tomcat webmanager. XML::XPath, LWP::UserAgent, URI, HTTP::Cookies
Varnish
           
  Use varnish commands.  
VMWare              
  Need ‘centreon_esxd’ connector from Merethis.  
Pfsense      
             
Protocols Bgp      
             
Dhcp              
    Net::DHCP::Packet, Net::Subnet
Dns              
    Net::DNS
Ftp              
    Net::FTP, Net::FTPSSL
Http        
          LWP::UserAgent, URI, HTTP::Cookies, JSON, JSON::Path, XML::XPath
Ftp              
    Net::FTP, Net::FTPSSL
Imap              
    Net::IMAP::Simple
Jmx            
      JSON::Path, JMX::Jmx4Perl
Ldap              
    Net::LDAP
Ntp              
    Net::NTP
Radius              
    Authen::Radius
Smtp              
    Email::Send::SMTP::Gmail
Tcp              
    IO::Socket::SSL
Udp              
     
x509              
    IO::Socket::SSL
Database Informix              
    DBI, DBD::Informix
MS SQL              
    DBI, DBD::Sybase
MySQL              
    DBI, DBD::mysql
Oracle              
    DBI, DBD::oracle, DateTime
Postgres              
    DBI, DBD::Pg
Hardware ATS Apc      
       
   
PDU Apc      
       
   
PDU Eaton      
       
   
Standard Printers      
             
Sensorip      
             
Sensormetrix Em01        
          LWP::UserAgent, URI, HTTP::Cookies
Serverscheck      
             
Cisco UCS      
             
Dell CMC      
             
Dell iDrac      
             
Dell Openmanage      
          Need ‘openmanage agent’ on the operating system.  
HP Proliant      
          Need ‘HP Insight agent’ on the operating system.  
HP Blade Chassis      
             
IBM BladeCenter      
             
IBM HMC
           
   
IBM IMM      
             
Sun hardware
 
     
  Can monitor many sun hardware. Net::Telnet, SNMP
UPS Mge      
             
UPS Standard      
             
UPS Powerware      
             
Network Alcatel Omniswitch      
             
Arkoon      
             
Aruba      
             
Bluecoat      
             
Brocade      
             
Checkpoint      
             
Cisco      
          Many cisco (2800, Nexus, Wlc, Ironport,...)  
Citrix Netscaler      
             
Dell Powerconnect      
             
Dlink      
             
Extreme      
             
F5 Big-Ip      
             
Fortinet Fortigate      
             
Fritzbox      
             
H3C      
             
Hirschmann      
             
HP Procurve      
             
Juniper      
          Can monitor ‘SSG’, ‘SA’, ‘SRX’, ‘MAG’, ‘EX’, ‘Ggsn’.  
Netasq      
             
Palo Alto      
             
Radware Alteon      
       
   
Redback      
             
Riverbed      
             
Ruggedcom      
             
Securactive      
             
Stonesoft      
             
Operating
System
AIX
           
  Use AIX commands.  
         
         
Freebsd      
          Need ‘bsnmpd’ agent.  
Linux
           
  Use Linux commands.  
     
             
Solaris
           
  Use Solaris commands.  
         
         
Windows      
             
   
   
   
   
Storage Dell EqualLogic      
             
Dell MD3000              
  Need ‘SMcli’ command.  
Dell TL2000      
             
EMC Celerra
           
  Use appliance commands.  
EMC Clariion              
  Need ‘navisphere’ command.  
EMC DataDomain      
             
EMC Recoverypoint
           
  Use appliance commands.  
HP 3par
           
  Use appliance commands.  
HP Lefthand      
             
HP MSA2000      
             
HP p2000          
      Use the XML API. XML::XPath, LWP::UserAgent, URI, HTTP::Cookies
IBM DS3000              
  Use ‘SMcli’ command.  
IBM DS4000              
  Use ‘SMcli’ command.  
IBM DS5000              
  Use ‘SMcli’ command.  
IBM TS3100      
             
IBM TS3200      
             
Netapp      
            DateTime
Panzura      
             
Qnap      
             
Synology      
             
Violin 3000      
             

How can i remove perfdatas ?

For example, i check TCP connections from a linux in SNMP with following command:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=tcpcon --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public
OK: Total connections: 1 | 'total'=1;;;0; 'con_closed'=0;;;0; 'con_closeWait'=0;;;0; '  con_synSent'=0;;;0; 'con_established'=1;;;0; 'con_timeWait'=0;;;0; 'con_lastAck'=0;;;0  ; 'con_listen'=5;;;0; 'con_synReceived'=0;;;0; 'con_finWait1'=0;;;0; 'con_finWait2'=0;  ;;0; 'con_closing'=0;;;0;

There are too many perfdatas and i want to keep ‘total’ perfdata only. I use the option --filter-perfdata='total':

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=tcpcon --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --filter-perfdata='total'
OK: Total connections: 1 | 'total'=1;;;0;

I can use regexp in --filter-perfdata option. So, i can exclude perfdata beginning by ‘total’:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=tcpcon --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --filter-perfdata='^(?!(total))'
OK: Total connections: 1 | 'con_closed'=0;;;0; 'con_closeWait'=0;;;0; 'con_synSent'=0;;;0; 'con_established'=1;;;0; 'con_timeWait'=0;;;0; 'con_lastAck'=0;;;0; 'con_listen'=5;;;0; 'con_synReceived'=0;;;0; 'con_finWait1'=0;;;0; 'con_finWait2'=0;;;0; 'con_closing'=0;;;0;

How can i set threshold: critical if value < X ?

“centreon-plugins” can manage Nagios threshold ranges: https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT

For example, i want to check that ‘crond’ is running (if there is less than 1 process, critical). I have two ways:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=processcount --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --process-name=crond --critical=1:
CRITICAL: Number of current processes running: 0 | 'nbproc'=0;;1:;0;

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=processcount --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --process-name=crond --critical=@0:0
CRITICAL: Number of current processes running: 0 | 'nbproc'=0;;@0:0;0;

How can i check a generic SNMP OID value ?

There is a generic SNMP plugin to check it. An example to get ‘SysUptime’ SNMP OID:

$ perl centreon_plugins.pl --plugin=snmp_standard::plugin --mode=numeric-value --oid='.1.3.6.1.2.1.1.3.0' --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public

How can i check ipv6 equipment in SNMP ?

To check ipv6 equipment, use the following syntax (udp6:[xxxx]):

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --hostname='udp6:[fe80::250:56ff:feb5:6ae0]' --mode=storage --snmp-version=2c --snmp-community=public

How to use memcached server for retention datas ?

Some plugins need to store datas. Two ways to store it:

  • File on a disk (by default).
  • Memcached server.

To use ‘memcached’, you must have a memcached server and the CPAN ‘Memcached::libmemcached’ module installed. You can set the memcached server with the option --memcached:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=traffic --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --verbose --skip --skip-speed0 --memcached=127.0.0.1
OK: All traffic are ok | 'traffic_in_lo'=197.40b/s;;;0;10000000 'traffic_out_lo'=197.40b/s;;;0;10000000 'traffic_in_eth0'=14539.11b/s;;;0;1000000000 'traffic_out_eth0'=399.59b/s;;;0;1000000000 'traffic_in_eth1'=13883.82b/s;;;0;1000000000 'traffic_out_eth1'=1688.66b/s;;;0;1000000000
Interface 'lo' Traffic In : 197.40b/s (0.00 %), Out : 197.40b/s (0.00 %)
Interface 'eth0' Traffic In : 14.54Kb/s (0.00 %), Out : 399.59b/s (0.00 %)
Interface 'eth1' Traffic In : 13.88Kb/s (0.00 %), Out : 1.69Kb/s (0.00 %)

Tip

Local file is used if the memcached server is not responding.

What does --dyn-mode option do ?

With the option, you can used a mode with a plugin. It commonly used for database checks. For example, i have an application which stores some monitoring information on a database. The developer can use another plugin to create the check (no need to do the SQL connections,... It saves time):

$ perl centreon_plugins.pl --plugin=database::mysql::plugin --dyn-mode=apps::centreon::mysql::mode::pollerdelay --host=10.30.3.75 --username='test' --password='testpw' --verbose
OK: All poller delay for last update are ok | 'delay_Central'=2s;0:300;0:600;0; 'delay_Poller-Engine'=2s;0:300;0:600;0;
Delay for last update of Central is 2 seconds
Delay for last update of Poller-Engine is 2 seconds

Warning

A mode using the following system must notice it (in the help description). So you should open the file with an editor and read at the end the description.

How can i check the plugin version ?

You can check the version of plugins and modes with option --version:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --version
Plugin Version: 0.1
$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=storage --version
Mode Version: 1.0

You can also use the option --mode-version to execute the mode only if there is the good version. For example, we want to execute the mode only if the version >= 2.x:

$  perl  centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=storage --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --verbose --mode-version='2.x'
UNKNOWN: Not good version for plugin mode. Excepted at least: 2.x. Get: 1.0

Troubleshooting

SNMP

I get the SNMP error: ‘UNKNOWN:.* (tooBig).*’

The following error can happened with some equipments. You can resolve it if you set following options:

  • --subsetleef=20 --maxrepetitions=20

I get the SNMP error: ‘UNKNOWN:.*Timeout’

The following error means:

  • Don’t have network access to the target SNMP Server (a firewall can block UDP 161).
  • Wrong SNMP community name or SNMP version set.

I get the SNMP error: ‘UNKNOWN:.*Cant get a single value’

The following error means: SNMP access is working but you can’t retrieve SNMP values. Very possible reasons:

  • SNMP value is not set yet (can be happened when a SNMP server is just started).
  • SNMP value is not implemented by the constructor.
  • SNMP value is set on a specific firmware or OS.

Seems that process check is not working well for some arguments filter

In SNMP, there is a limit in argument length of 128 characters. So, if you try to filter with an argument after 128 characters, it won’t work. It can happen with Java arguments. To solve the problem, you should prefer a NRPE check.

Can’t access in SNMP v3

First, you need to validate SNMP v3 connection with snmpwalk. When it’s working, you set SNMP v3 options in command line. The mapping between ‘snmpwalk’ options and “centreon-plugins” options:

  • -a => --authprotocol
  • -A => --authpassphrase
  • -u => --snmp-username
  • -x => --privprotocol
  • -X => --privpassphrase
  • -l => not needed (automatic)
  • -e => --securityengineid
  • -E => --contextengineid

Miscellaneous

I get the error: “UNKNOWN: Need to specify ‘–custommode’.”

Some plugins need to set the option --custommode. You can know the value to set with the option --list-custommode. An example:

$ perl centreon_plugins.pl --plugin=storage::ibm::DS3000::cli::plugin --list-custommode
...
Custom Modes Available:
 smcli

$ perl centreon_plugins.pl --plugin=storage::ibm::DS3000::cli::plugin --custommode=smcli --list-mode

I get the error: “UNKNOWN: Cannot write statefile .*”

You must create the directory (with write permissions) to let the plugin stores some datas on disk.

I get the error: “UNKNOWN: Cannot load module ‘xxx’.”

The problem can be:

  • A prerequisite CPAN module is missing. You need to install it.
  • The CPAN module cannot be loaded because of its path. Perl modules must be installed on some specific paths.

I can’t see help messages

“centreon-plugins” files must Unix format (no Windows carriage returns). You can change it with the following command:

$ find . -name "*.p[ml]" -type f -exec dos2unix \{\} \;

Warning

Execute the command in “centreon-plugins” directory.

Command Samples

Windows

Check all disks in SNMP

Warning if space used > 80% and critical if space used > 90%:

$ perl centreon_plugins.pl --plugin=os::windows::snmp::plugin --mode=storage --hostname=xxx.xxx.xxx.xxx --snmp-version=2c --snmp-public=community  --verbose --storage='.*' --name --regexp --display-transform-src='(..).*' --display-transform-dst='$1' --warning=80 --critical=90
OK: All storages are ok. | used_C:'=38623698944B;0:108796887040;0:122396497920;0;135996108800 used_D:'=38623698944B;0:108796887040;0:122396497920;0;135996108800
Storage 'C:' Total: 126.66 GB Used: 35.97 GB (28.40%) Free: 90.69 GB (71.60%)
Storage 'D:' Total: 126.66 GB Used: 35.97 GB (28.40%) Free: 90.69 GB (71.60%)

Warning if space free < 5G and critical if space free < 2G:

$ perl centreon_plugins.pl --plugin=os::windows::snmp::plugin --mode=storage --hostname=xxx.xxx.xxx.xxx --snmp-version=2c --snmp-public=community  --verbose --storage='.*' --name --regexp --display-transform-src='(..).*' --display-transform-dst='$1' --warning=5497558138880 --critical=2199023255552 --units='B' --free
OK: All storages are ok. | 'free_C:'=97372344320B;0:5497558138880;0:2199023255552;0;135996108800 'free_D:'=97372344320B;0:5497558138880;0:2199023255552;0;135996108800
Storage 'C:' Total: 126.66 GB Used: 35.97 GB (28.40%) Free: 90.69 GB (71.60%)
Storage 'D:' Total: 126.66 GB Used: 35.97 GB (28.40%) Free: 90.69 GB (71.60%)

Linux

Check all interface traffics in SNMP

Warning if traffic in/out used > 80% and critical if traffic in/out used > 90%:

$ perl centreon_plugins.pl --plugin=os::linux::snmp::plugin --mode=interfaces --hostname=127.0.0.1 --snmp-version=2c --snmp-community=public --verbose --interface='.*' --name --add-traffic --warning-in-traffic=80 --critical-in-traffic=90 --warning-out-traffic=80 --critical-out-traffic=90
OK: All traffic are ok | 'traffic_in_lo'=126.58b/s;0.00:8000000.00;0.00:9000000.00;0;10000000 'traffic_out_lo'=126.58b/s;0.00:8000000.00;0.00:9000000.00;0;10000000 'traffic_in_eth0'=1872.00b/s;0.00:800000000.00;0.00:900000000.00;0;1000000000 'traffic_out_eth0'=266.32b/s;0.00:800000000.00;0.00:900000000.00;0;1000000000 'traffic_in_eth1'=976.65b/s;0.00:800000000.00;0.00:900000000.00;0;1000000000 'traffic_out_eth1'=1021.68b/s;0.00:800000000.00;0.00:900000000.00;0;1000000000
Interface 'lo' Traffic In : 126.58b/s (0.00 %), Out : 126.58b/s (0.00 %)
Interface 'eth0' Traffic In : 1.87Kb/s (0.00 %), Out : 266.32b/s (0.00 %)
Interface 'eth1' Traffic In : 976.65b/s (0.00 %), Out : 1.02Kb/s (0.00 %)

HTTP Protocol

Check authentification of an application (POST request)

An example for authentification form of demo.centreon.com:

$ perl centreon_plugins.pl --plugin=apps::protocols::http::plugin --mode=expected-content --hostname=demo.centreon.com  --method='POST' --post-param='useralias=admin' --post-param='password=centreon'  --cookies-file='/tmp/lwp_cookies.dat' --urlpath='/centreon/index.php' --expected-string='color_UNREACHABLE'
OK: 'color_UNREACHABLE' is present in content. | 'time'=0.575s;;;0; 'size'=20708B;;;0;