...
Scripts and executables must do two things (at least) in order to work as Shinken Enterprise 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 not important to Shinken Enterprise , 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 Enterprise , consider making it a Python or python + C type plugin that is daemonized by the Shinken Enterprise poller or receiver daemons.
You can look at the existing poller daemons for how to create a module, it is very simple.
Return Code
Shinken Enterprise 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 | DOWN | |
| 2 | CRITICAL | DOWN |
| 3 | UNKNOWN | DOWN |
If the :ref:`use_aggressive_host_checking <advanced/unused-Shinken Enterprise -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 Enterprise determines whether or not a host is DOWN or UNREACHABLE is discussed :ref:`here <thebasics/networkreachability>`.
Plugin Output Spec
At least, plugins should return one of text output. Beginning with Shinken Enterprise 3, plugins can optionally return multiple lines of output. Plugins may also return optional performance data that can be processed by external applications. the metrology modules.
The basic format for plugin output is shown below:
...
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:
::
| Code Block | ||
|---|---|---|
| ||
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$SERVICEOUTPUT$ data.**
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:
::
| Code Block | ||
|---|---|---|
| ||
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 <$SERVICEOUTPUT$> data 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:
- You can choose to return no performance data whatsoever
- You can return performance data on the first line only
- You can return performance data only in subsequent lines (after the first)
...
data.
Plugin Output Length Restrictions
...