Shinken includes a set of scalable internal mechanisms for checking the status of hosts and services on your network. These are called modules and can be loaded by the various Shinken daemons involved in data acquisition (Poller daemons, Receiver daemons, Arbiter Daemon)
Shinken also relies on external programs (called check plugins) to monitor a very wide variety of devices, applications and networked services.
Plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.) that can be run from a command line to check the status of a host or service. Shinken uses the results from plugins to determine the current status of hosts and services on your network and obtain performance data about the monitored service.
Shinken will execute a plugin whenever there is a need to check the status of a service or host. The plugin does something (notice the very general term) to perform the check and then simply returns the results to Shinken. It will process the results that it receives from the plugin and take any necessary actions (running event handlers, sending out notifications, etc).
Plugins act as an abstraction layer between the monitoring logic present in the Shinken daemon and the actual services and hosts that are being monitored.
The upside of this type of plugin architecture is that you can monitor just about anything you can think of.
If you can automate the process of checking something, you can monitor it with Shinken.
There are already literally thousands of plugins that have been created in order to monitor basic resources such as processor load, disk usage, ping rates, etc.
If you want to monitor something else, take a look at the documentation on :ref:`writing plugins <development/pluginapi>` and roll your own. It's simple!
The downside to this type of plugin architecture is the fact that Shinken has absolutely no idea about what is monitored.
You could be monitoring network traffic statistics, data error rates, room temperate, CPU voltage, fan speed, processor load, disk space, or the ability of your super-fantastic toaster to properly brown your bread in the morning...
Shinken doesn't understand the specifics of what's being monitored - it just tracks changes in the state of those resources.
Only the plugins know exactly what they're monitoring and how to perform the actual checks.
There are plugins to monitor many different kinds of devices and services.
They use basic monitoring protocols including: WMI, SNMP, SSH, NRPE, TCP, UDP, ICMP, OPC, LDAP and more
They can monitor pretty much anything:
Shinken also organizes monitoring configuration packages. These are pre-built for fast no nonsense deployments.
They include the check command definitions, service templates, host templates, discovery rules and integration hooks to the Community web site.
The integration with the community web site permits deployment and updates of monitoring packs.
Get started with :ref:`Shinken Monitoring Packages "Packs" <contributing/create-and-push-packs>` today.
The plugins themselves are not distributed with Shinken, but you can download the official Monitoring-plugins and many additional plugins created and maintained by shinken users from the following locations:
Most plugins will display basic usage information when you execute them using "-h" or "--help" on the command line.
For example, if you want to know how the **check_http*plugin works or what options it accepts, you should try executing the following command:
./check_http --help |
Scripts and executables must do two things (at a minimum) in order to function as Shinken plugins:
Exit with one of several possible return values
Return at least one line of text output to "STDOUT"
The inner workings of your plugin are unimportant to Shinken, interface between them is important.
Your plugin could check the status of a TCP port, run a database query, check disk free space, or do whatever else it needs to check something.
The details will depend on what needs to be checked - that's up to you.
If you are interested in having a plugin that is performant to use with Shinken, consider making it a Python or python + C type plugin that is daemonized by the Shinken poller or receiver daemons.
You can look at the existing poller daemons for how to create a module, it is very simple.
Shinken determines the status of a host or service by evaluating the return code from plugins.
The following tables shows a list of valid return codes, along with their corresponding service or host states.
================== ============= =======================
Plugin Return Code Service State Host State
0 OK UP
1 WARNING UP or DOWN/UNREACHABLE*
2 CRITICAL DOWN/UNREACHABLE
3 UNKNOWN DOWN/UNREACHABLE
================== ============= =======================
If the :ref:`use_aggressive_host_checking <advanced/unused-shinken-parameters#use_aggressive_host_checking>` option is enabled, return codes of 1 will result in a host state of DOWN or UNREACHABLE. Otherwise return codes of 1 will result in a host state of UP. The process by which shinken determines whether or not a host is DOWN or UNREACHABLE is discussed :ref:`here <thebasics/networkreachability>`.
At a minimum, plugins should return at least one of text output. Beginning with shinken 3, plugins can optionally return multiple lines of output. Plugins may also return optional performance data that can be processed by external applications. The basic format for plugin output is shown below:
TEXT OUTPUT | OPTIONAL PERFDATALONG TEXT LINE 1LONG TEXT LINE 2...LONG TEXT LINE N | PERFDATA LINE 2PERFDATA LINE 3...PERFDATA LINE N
The performance data is optional.
If a plugin returns performance data in its output, it must separate the performance data from the other text output using a pipe (|) symbol.
Additional lines of long text output are also optional.
Let's see some examples of possible plugin output...
**Case 1: One line of output (text only)**
Assume we have a plugin that returns one line of output that looks like this:
::
DISK OK - free space: / 3326 MB (56%);
If this plugin was used to perform a service check, the entire line of output will be stored in the :ref:`$SERVICEOUTPUT$ <$SERVICEOUTPUT$>` macro.
**Case 2: One line of output (text and perfdata)**
A plugin can return optional performance data for use by external applications. To do this, the performance data must be separated from the text output with a pipe (|) symbol like such:
::
DISK OK - free space: / 3326 MB (56%);
"|"
/=2643MB;5948;5958;0;5968
If this plugin was used to perform a service check, the"red"portion of output (left of the pipe separator) will be stored in the :ref:`$SERVICEOUTPUT$ <$SERVICEOUTPUT$>` macro and the"orange"portion of output (right of the pipe separator) will be stored in the :ref:`$SERVICEPERFDATA$ <thebasics/macrolist#serviceperfdata>` macro.
**Case 3: Multiple lines of output (text and perfdata)**
A plugin optionally return multiple lines of both text output and perfdata, like such:
DISK OK - free space: / 3326 MB (56%);"|"/=2643MB;5948;5958;0;5968/ 15272 MB (77%);/boot 68 MB (69%);/home 69357 MB (27%);/var/log 819 MB (84%);"|"/boot=68MB;88;93;0;98/home=69357MB;253404;253409;0;253414 /var/log=818MB;970;975;0;980
If this plugin was used to perform a service check, the red portion of first line of output (left of the pipe separator) will be stored in the :ref:`$SERVICEOUTPUT$ <$SERVICEOUTPUT$>` macro. The orange portions of the first and subsequent lines are concatenated (with spaces) are stored in the :ref:`$SERVICEPERFDATA$ <thebasics/macrolist#serviceperfdata>` macro. The blue portions of the 2nd _ 5th lines of output will be concatenated (with escaped newlines) and stored in :ref:`$LONGSERVICEOUTPUT$ <thebasics/macrolist#longserviceoutput>` the macro.
The final contents of each macro are listed below:
=================== =================================================================================================================
Macro Value
$SERVICEOUTPUT$ DISK OK - free space: / 3326 MB (56%);
$SERVICEPERFDATA$ /=2643MB;5948;5958;0;5968"/boot=68MB;88;93;0;98"/home=69357MB;253404;253409;0;253414"/var/log=818MB;970;975;0;980
$LONGSERVICEOUTPUT$ / 15272 MB (77%);\n/boot 68 MB (69%);\n/var/log 819 MB (84%);
=================== =================================================================================================================
With regards to multiple lines of output, you have the following options for returning performance data:
shinken will only read the first 64 KB of data that a plugin returns. This is done in order to prevent runaway plugins from dumping megs or gigs of data back to shinken.