/trunk/README.md |
---|
13,10 → 13,10 |
- It is also possible to create websites which only have a machine readable part (i.e. you include your VNag output in your existing website). This machine readable part can be optionally signed and/or encrypted. |
Pre-Installed plugins |
--------------------- |
Included plugins |
---------------- |
VNag comes with the following plugins pre-installed: |
VNag comes with the following plugins pre-installed (in the bin directory): |
- **4images_version**: Checks 4images installations for updates. |
- **aastra_430_voicemail**: Checks Aastra 430 phone system for new voicemails. |
63,6 → 63,7 |
To create your own plugins, you can look at the source codes of the existing plugins |
to get inspiration and use them as templates. |
Also, a small documentation is found at the beginning of the file **framework/vnag_framework.inc.php**. |
Also, a small documentation is found in |
[doc/Plugin_Development.md](https://github.com/danielmarschall/vnag/blob/master/doc/Plugin_Development.md). |
If you have created useful plugins, we would be happy if you could share them with us! |
/trunk/TODO.md |
---|
2,7 → 2,6 |
TODO |
---- |
- make proper documentation |
- allow changing automatic help page to describe which individual ranges stand for (is it already possible, by getting the argument object and then changing its help text?) |
- everywhere getter and setter instead of accessing class member variables |
- ipfm monitor: dygraph has MIT license |
/trunk/doc/Plugin_Development.md |
---|
0,0 → 1,283 |
# VNag - Nagios Framework for PHP |
Developed by Daniel Marschall (www.viathinksoft.com) |
Licensed under the terms of the Apache 2.0 license |
## Introduction |
VNag is a small framework for Nagios Plugin Developers who use PHP CLI scripts. |
The main purpose of VNag is to make the development of plugins as easy as possible, so that |
the developer can concentrate on the actual work. VNag will try to automate as much |
as possible. |
Please note that your script should include the +x chmod flag: |
chmod +x myscript.php |
Please see the the demo/ folder for a few examples how to use this framework. |
## Arguments |
Example: |
$this->addExpectedArgument($argSilent = new VNagArgument('s', 'silent', VNagArgument::VALUE_FORBIDDEN, null, 'Description for the --silent output', $defaultValue)); |
$this->addExpectedArgument($argHost = new VNagArgument('H', 'host', VNagArgument::VALUE_REQUIRED, 'hostname', 'Description for the --host output', $defaultValue)); |
In the example above, the two argument objects $argSilent and $argHost were created. |
With these objects of the type VNagArgument, you can query the argument's value, |
how often the argument was passed and if it is set: |
$argSilent->count(); // 1 if "-s" is passed, 2 if "-s -s" is passed etc. |
$argSilent->available(); // true if "-s" is passed, false otherwise |
$argHost->getValue(); // "example.com" if "-h example.com" is passed |
It is recommended that you pass every argument to $this->addExpectedArgument() . |
Using this way, VNag can generate a --help page for you, which lists all your arguments. |
Future version of VNag may also require to have a complete list of all valid arguments, |
since the Nagios Development Guidelines recommend to output the usage information if an illegal |
argument is passed. Due to PHP's horrible bad implementation of GNU's getopt(), this check for |
unknown arguments is currently not possible, and the developer of VNag does not want to use |
dirty hacks/workarounds, which would not match to all argument notation variations/styles. |
See: https://bugs.php.net/bug.php?id=68806 |
https://bugs.php.net/bug.php?id=65673 |
https://bugs.php.net/bug.php?id=26818 |
## Setting the status: |
You can set the status with: |
$this->setStatus(VNag::STATUS_OK); |
If you don't set a status, the script will return Unknown instead. |
setStatus($status) will keep the most severe status, e.g. |
$this->setStatus(VNag::STATUS_CRITICAL); |
$this->setStatus(VNag::STATUS_OK); |
will result in a status "Critical". |
If you want to completely overwrite the status, use $force=true: |
$this->setStatus(VNag::STATUS_CRITICAL); |
$this->setStatus(VNag::STATUS_OK, true); |
The status will now be "OK". |
Possible status codes are: |
(For service plugins:) |
VNag::STATUS_OK = 0; |
VNag::STATUS_WARNING = 1; |
VNag::STATUS_CRITICAL = 2; |
VNag::STATUS_UNKNOWN = 3; |
(For host plugins:) |
VNag::STATUS_UP = 0; |
VNag::STATUS_DOWN = 1; |
## Output: |
After the callback function cbRun() of your job has finished, |
the framework will automatically output the results in the Nagios console output format, |
the visual HTML output and/or the invisible HTML output. |
In case of CLI invokation, the Shell exit code will be remembered and |
automatically returned by the shutdown handler once the script normally |
terminates. (In case you run different jobs, which is not recommended, the |
shutdown handler will output the baddest exit code). |
The Shell output format will be: |
<Service status text>: <Comma separates messages> | <whitespace separated primary performance data> |
"Verbose information:" |
<Multiline verbose output> | <Multiline secondary performance data> |
<Service status text> will be automatically created by VNag. |
Verbose information are printed below the first line. Most Nagios clients will only print the first line. |
If you have important output, use $this->setHeadline() instead. |
You can add verbose information with following method: |
$this->addVerboseMessage('foobar', $verbosity); |
Following verbosity levels are defined: |
VNag::VERBOSITY_SUMMARY = 0; // always printed |
VNag::VERBOSITY_ADDITIONAL_INFORMATION = 1; // requires at least -v |
VNag::VERBOSITY_CONFIGURATION_DEBUG = 2; // requiers at least -vv |
VNag::VERBOSITY_PLUGIN_DEBUG = 3; // requiers at least -vvv |
All STDOUT outputs of your script (e.g. by echo) will be interpreted as "verbose" output |
and is automatically collected, so |
echo "foobar"; |
has the same functionality as |
$this->addVerboseMessage('foobar', VNag::VERBOSITY_SUMMARY); |
You can set messages (which will be added into the first line, which is preferred for plugin outputs) |
using |
$this->setHeadline($msg, $append, $verbosity); |
Using the flag $append, you can choose if you want to append or replace the message. |
VNag will catch Exceptions of your script and will automatically end the plugin, |
returning a valid Nagios output. |
## Automatic handling of basic arguments: |
VNag will automatic handle of following CLI arguments: |
-? |
-V --version |
-h --help |
-v --verbose |
-t --timeout (only works if you set declare(ticks=1) at the beginning of each of your scripts) |
-w --warning |
-c --critical |
You can performe range checking by using: |
$example_value = '10MB'; |
$this->checkAgainstWarningRange($example_value); |
this is more or less the same as: |
$example_value = '10MB'; |
$wr = $this->getWarningRange(); |
if (isset($wr) && $wr->checkAlert($example_value)) { |
$this->setStatus(VNag::STATUS_WARNING); |
} |
In case that your script allows ranges which can be relative and absolute, you can provide multiple arguments; |
$wr->checkAlert() will be true, as soon as one of the arguments is in the warning range. |
The check will be done in this way: |
$example_values = array('10MB', '5%'); |
$this->checkAgainstWarningRange($example_values); |
this is more or less the same as: |
$example_values = array('10MB', '5%'); |
$wr = $this->getWarningRange(); |
if (isset($wr) && $wr->checkAlert($example_values)) { |
$this->setStatus(VNag::STATUS_WARNING); |
} |
Note that VNag will automatically detect the UOM (Unit of Measurement) and is also able to convert them, |
e.g. if you use the range "-w 20MB:40MB", your script will be able to use $wr->checkAlert('3000KB') |
Please note that only following UOMs are accepted (as defined in the Plugin Development Guidelines): |
- no unit specified: assume a number (int or float) of things (eg, users, processes, load averages) |
- s, ms, us: seconds |
- %: percentage |
- B, KB, MB, TB: bytes // NOTE: GB is not in the official development guidelines,probably due to an error, so I've added them anyway |
- c: a continous counter (such as bytes transmitted on an interface) |
## Multiple warning/critical ranges: |
The arguments -w and -c can have many different values, separated by comma. |
We can see this feature e.g. with the official plugin /usr/lib/nagios/plugins/check_ping: |
It has following syntax for the arguments -w and -c: <latency>,<packetloss>% |
When you are using checkAgainstWarningRange, you can set the fourth argument to the range number |
you would like to check (beginning with 0). |
Example: |
// -w 1MB:5MB,5%:10% |
$this->checkAgainstWarningRange('4MB', true, true, 0); // check value 4MB against range "1MB:5MB" (no warning) |
$this->checkAgainstWarningRange('15%', true, true, 1); // check value 15% gainst range "5%:10%" (gives warning) |
## Visual HTTP output: |
Can be enabled/disabled with $this->http_visual_output |
Valid values: |
VNag::OUTPUT_SPECIAL = 1; // illegal usage / help page, version page |
VNag::OUTPUT_NORMAL = 2; |
VNag::OUTPUT_EXCEPTION = 4; |
VNag::OUTPUT_ALWAYS = 7; |
VNag::OUTPUT_NEVER = 0; |
## Encryption and Decryption: |
In case you are emitting machine-readable code in your HTTP output |
(can be enabled/disabled by $this->http_invisible_output), |
you can encrypt the machine-readable part of your HTTP output by |
setting $this->password_out . If you want to read the information, |
you need to set $this->password_in at the web-reader plugin. |
The visual output is not encrypted. So, if you want to hide the information, |
then you must not enable visual HTML output. |
If you don't want to encrypt the machine-readable output, |
please set $this->password_out to null or empty string. |
Attention! |
- Encryption and decryption require the OpenSSL extension in PHP. |
## Digital signature: |
You can sign the output by setting $this->privkey with a filename containing |
a private key created by OpenSSL. If it is encrypted, please also set |
$this->privkey_password . |
To check the signature, set $this->pubkey at your web-reader plugin with |
the filename of the public key file. |
Attention! |
- Signatures require the OpenSSL extension in PHP. |
## Performance data: |
You can add performance data using |
$this->addPerformanceData(new VNagPerformanceData($label, $value, $warn, $crit, $min, $max)); |
or by the alternative constructor |
$this->addPerformanceData(VNagPerformanceData::createByString("'XYZ'=100;120;130;0;500")); |
$value may contain an UOM, e.g. "10MB". All other parameters may not contain an UOM. |
## Guidelines: |
This framework currently supports meets following guidelines: |
- https://nagios-plugins.org/doc/guidelines.html#PLUGOUTPUT (Plugin Output for Nagios) |
- https://nagios-plugins.org/doc/guidelines.html#AEN33 (Print only one line of text) |
- https://nagios-plugins.org/doc/guidelines.html#AEN41 (Verbose output) |
- https://nagios-plugins.org/doc/guidelines.html#AEN78 (Plugin Return Codes) |
- https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT (Threshold and ranges) |
- https://nagios-plugins.org/doc/guidelines.html#AEN200 (Performance data) |
- https://nagios-plugins.org/doc/guidelines.html#PLUGOPTIONS (Plugin Options) |
- https://nagios-plugins.org/doc/guidelines.html#AEN302 (Option Processing) |
Note: The screen output of the help page will (mostly) be limited to 80 characters width; but the max recommended length of 23 lines cannot be guaranteed. |
This framework does currently NOT support following guidelines: |
- https://nagios-plugins.org/doc/guidelines.html#AEN74 (Screen Output) |
- https://nagios-plugins.org/doc/guidelines.html#AEN239 (Translations) |
- https://nagios-plugins.org/doc/guidelines.html#AEN293 (Use DEFAULT_SOCKET_TIMEOUT) |
- https://nagios-plugins.org/doc/guidelines.html#AEN296 (Add alarms to network plugins) |
- https://nagios-plugins.org/doc/guidelines.html#AEN245 (Don't execute system commands without specifying their full path) |
- https://nagios-plugins.org/doc/guidelines.html#AEN249 (Use spopen() if external commands must be executed) |
- https://nagios-plugins.org/doc/guidelines.html#AEN253 (Don't make temp files unless absolutely required) |
- https://nagios-plugins.org/doc/guidelines.html#AEN259 (Validate all input) |
- https://nagios-plugins.org/doc/guidelines.html#AEN317 (Plugins with more than one type of threshold, or with threshold ranges) |
We will intentionally NOT follow the following guidelines: |
- https://nagios-plugins.org/doc/guidelines.html#AEN256 (Don't be tricked into following symlinks) |
Reason: We believe that this guideline is contraproductive. |
Nagios plugins usually run as user 'nagios'. It is the task of the system administrator |
to ensure that the user 'nagios' must not read/write to files which are not intended |
for access by the Nagios service. Symlinks, on the other hand, are useful for several tasks. |
See also https://stackoverflow.com/questions/27112949/nagios-plugins-why-not-following-symlinks |
## VNag over HTTP: |
A script that uses the VNag framework can run as CLI script (normal Nagios plugin) or as web site (or both). |
Having the script run as website, you can include a Nagios information combined with a human friendly HTML output which can |
include colors, graphics (like charts) etc. |
For example: |
A script that measures traffic can have a website which shows graphs, |
and has a hidden Nagios output included, which can be read by a Nagios plugin that |
converts the hidden information on that website into an output that Nagios can evaluate. |
Here is a comparison of the usage and behavior of VNag in regards to CLI and HTTP calls: |
| CLI script | HTTP script |
|-------------------------------------------|----------------------------------------------| |
| * "echo" will be discarded. | * "echo" output will be discarded. | |
|-------------------------------------------|----------------------------------------------| |
| * Exceptions will be handled. | * Exceptions will be handled. | |
|-------------------------------------------|----------------------------------------------| |
| * outputHTML() will be ignored. | * outputHTML() will be handled. | |
| (This allows you to have the same | | |
| script running as CLI and HTML) | | |
|-------------------------------------------|----------------------------------------------| |
| * Arguments are passed via CLI. | * Arguments are passed via $_REQUEST | |
| | (i.e. GET or POST) | |
|-------------------------------------------|----------------------------------------------| |
| * Arguments: "-vvv" | * Arguments: GET ?v[]=&v[]=&v[]= or POST | |
|-------------------------------------------|----------------------------------------------| |
| * When run() has finished, the program | * When run() has finished, the program | |
| flow continues, although it is not | flow continues. | |
| recommended that you do anything after | | |
| it. (The exit code is remembered for | | |
| the shutdown handler) | | |
|-------------------------------------------|----------------------------------------------| |
| * Exactly 1 job must be called, resulting | * You can call as many jobs as you want. | |
| in a single output of that job. | A website can include more than one | |
| | Nagios output which are enumerated with | |
| | a serial number (0,1,2,3,...) or manual ID.| |
|-------------------------------------------|----------------------------------------------| |
/trunk/src/framework/vnag_framework.inc.php |
---|
17,287 → 17,8 |
/**************************************************************************************************** |
Introduction: |
More information on how to develop your plugin, see doc/Plugin_Development.md |
VNag is a small framework for Nagios Plugin Developers who use PHP CLI scripts. |
The main purpose of VNag is to make the development of plugins as easy as possible, so that |
the developer can concentrate on the actual work. VNag will try to automate as much |
as possible. |
Please note that your script should include the +x chmod flag: |
chmod +x myscript.php |
Please see the the demo/ folder for a few examples how to use this framework. |
Arguments: |
Example: |
$this->addExpectedArgument($argSilent = new VNagArgument('s', 'silent', VNagArgument::VALUE_FORBIDDEN, null, 'Description for the --silent output', $defaultValue)); |
$this->addExpectedArgument($argHost = new VNagArgument('H', 'host', VNagArgument::VALUE_REQUIRED, 'hostname', 'Description for the --host output', $defaultValue)); |
In the example above, the two argument objects $argSilent and $argHost were created. |
With these objects of the type VNagArgument, you can query the argument's value, |
how often the argument was passed and if it is set: |
$argSilent->count(); // 1 if "-s" is passed, 2 if "-s -s" is passed etc. |
$argSilent->available(); // true if "-s" is passed, false otherwise |
$argHost->getValue(); // "example.com" if "-h example.com" is passed |
It is recommended that you pass every argument to $this->addExpectedArgument() . |
Using this way, VNag can generate a --help page for you, which lists all your arguments. |
Future version of VNag may also require to have a complete list of all valid arguments, |
since the Nagios Development Guidelines recommend to output the usage information if an illegal |
argument is passed. Due to PHP's horrible bad implementation of GNU's getopt(), this check for |
unknown arguments is currently not possible, and the developer of VNag does not want to use |
dirty hacks/workarounds, which would not match to all argument notation variations/styles. |
See: https://bugs.php.net/bug.php?id=68806 |
https://bugs.php.net/bug.php?id=65673 |
https://bugs.php.net/bug.php?id=26818 |
Setting the status: |
You can set the status with: |
$this->setStatus(VNag::STATUS_OK); |
If you don't set a status, the script will return Unknown instead. |
setStatus($status) will keep the most severe status, e.g. |
$this->setStatus(VNag::STATUS_CRITICAL); |
$this->setStatus(VNag::STATUS_OK); |
will result in a status "Critical". |
If you want to completely overwrite the status, use $force=true: |
$this->setStatus(VNag::STATUS_CRITICAL); |
$this->setStatus(VNag::STATUS_OK, true); |
The status will now be "OK". |
Possible status codes are: |
(For service plugins:) |
VNag::STATUS_OK = 0; |
VNag::STATUS_WARNING = 1; |
VNag::STATUS_CRITICAL = 2; |
VNag::STATUS_UNKNOWN = 3; |
(For host plugins:) |
VNag::STATUS_UP = 0; |
VNag::STATUS_DOWN = 1; |
Output: |
After the callback function cbRun() of your job has finished, |
the framework will automatically output the results in the Nagios console output format, |
the visual HTML output and/or the invisible HTML output. |
In case of CLI invokation, the Shell exit code will be remembered and |
automatically returned by the shutdown handler once the script normally |
terminates. (In case you run different jobs, which is not recommended, the |
shutdown handler will output the baddest exit code). |
The Shell output format will be: |
<Service status text>: <Comma separates messages> | <whitespace separated primary performance data> |
"Verbose information:" |
<Multiline verbose output> | <Multiline secondary performance data> |
<Service status text> will be automatically created by VNag. |
Verbose information are printed below the first line. Most Nagios clients will only print the first line. |
If you have important output, use $this->setHeadline() instead. |
You can add verbose information with following method: |
$this->addVerboseMessage('foobar', $verbosity); |
Following verbosity levels are defined: |
VNag::VERBOSITY_SUMMARY = 0; // always printed |
VNag::VERBOSITY_ADDITIONAL_INFORMATION = 1; // requires at least -v |
VNag::VERBOSITY_CONFIGURATION_DEBUG = 2; // requiers at least -vv |
VNag::VERBOSITY_PLUGIN_DEBUG = 3; // requiers at least -vvv |
All STDOUT outputs of your script (e.g. by echo) will be interpreted as "verbose" output |
and is automatically collected, so |
echo "foobar"; |
has the same functionality as |
$this->addVerboseMessage('foobar', VNag::VERBOSITY_SUMMARY); |
You can set messages (which will be added into the first line, which is preferred for plugin outputs) |
using |
$this->setHeadline($msg, $append, $verbosity); |
Using the flag $append, you can choose if you want to append or replace the message. |
VNag will catch Exceptions of your script and will automatically end the plugin, |
returning a valid Nagios output. |
Automatic handling of basic arguments: |
VNag will automatic handle of following CLI arguments: |
-? |
-V --version |
-h --help |
-v --verbose |
-t --timeout (only works if you set declare(ticks=1) at the beginning of each of your scripts) |
-w --warning |
-c --critical |
You can performe range checking by using: |
$example_value = '10MB'; |
$this->checkAgainstWarningRange($example_value); |
this is more or less the same as: |
$example_value = '10MB'; |
$wr = $this->getWarningRange(); |
if (isset($wr) && $wr->checkAlert($example_value)) { |
$this->setStatus(VNag::STATUS_WARNING); |
} |
In case that your script allows ranges which can be relative and absolute, you can provide multiple arguments; |
$wr->checkAlert() will be true, as soon as one of the arguments is in the warning range. |
The check will be done in this way: |
$example_values = array('10MB', '5%'); |
$this->checkAgainstWarningRange($example_values); |
this is more or less the same as: |
$example_values = array('10MB', '5%'); |
$wr = $this->getWarningRange(); |
if (isset($wr) && $wr->checkAlert($example_values)) { |
$this->setStatus(VNag::STATUS_WARNING); |
} |
Note that VNag will automatically detect the UOM (Unit of Measurement) and is also able to convert them, |
e.g. if you use the range "-w 20MB:40MB", your script will be able to use $wr->checkAlert('3000KB') |
Please note that only following UOMs are accepted (as defined in the Plugin Development Guidelines): |
- no unit specified: assume a number (int or float) of things (eg, users, processes, load averages) |
- s, ms, us: seconds |
- %: percentage |
- B, KB, MB, TB: bytes // NOTE: GB is not in the official development guidelines,probably due to an error, so I've added them anyway |
- c: a continous counter (such as bytes transmitted on an interface) |
Multiple warning/critical ranges: |
The arguments -w and -c can have many different values, separated by comma. |
We can see this feature e.g. with the official plugin /usr/lib/nagios/plugins/check_ping: |
It has following syntax for the arguments -w and -c: <latency>,<packetloss>% |
When you are using checkAgainstWarningRange, you can set the fourth argument to the range number |
you would like to check (beginning with 0). |
Example: |
// -w 1MB:5MB,5%:10% |
$this->checkAgainstWarningRange('4MB', true, true, 0); // check value 4MB against range "1MB:5MB" (no warning) |
$this->checkAgainstWarningRange('15%', true, true, 1); // check value 15% gainst range "5%:10%" (gives warning) |
Visual HTTP output: |
Can be enabled/disabled with $this->http_visual_output |
Valid values: |
VNag::OUTPUT_SPECIAL = 1; // illegal usage / help page, version page |
VNag::OUTPUT_NORMAL = 2; |
VNag::OUTPUT_EXCEPTION = 4; |
VNag::OUTPUT_ALWAYS = 7; |
VNag::OUTPUT_NEVER = 0; |
Encryption and Decryption: |
In case you are emitting machine-readable code in your HTTP output |
(can be enabled/disabled by $this->http_invisible_output), |
you can encrypt the machine-readable part of your HTTP output by |
setting $this->password_out . If you want to read the information, |
you need to set $this->password_in at the web-reader plugin. |
The visual output is not encrypted. So, if you want to hide the information, |
then you must not enable visual HTML output. |
If you don't want to encrypt the machine-readable output, |
please set $this->password_out to null or empty string. |
Attention! |
- Encryption and decryption require the OpenSSL extension in PHP. |
Digital signature: |
You can sign the output by setting $this->privkey with a filename containing |
a private key created by OpenSSL. If it is encrypted, please also set |
$this->privkey_password . |
To check the signature, set $this->pubkey at your web-reader plugin with |
the filename of the public key file. |
Attention! |
- Signatures require the OpenSSL extension in PHP. |
Performance data: |
You can add performance data using |
$this->addPerformanceData(new VNagPerformanceData($label, $value, $warn, $crit, $min, $max)); |
or by the alternative constructor |
$this->addPerformanceData(VNagPerformanceData::createByString("'XYZ'=100;120;130;0;500")); |
$value may contain an UOM, e.g. "10MB". All other parameters may not contain an UOM. |
Guidelines: |
This framework currently supports meets following guidelines: |
- https://nagios-plugins.org/doc/guidelines.html#PLUGOUTPUT (Plugin Output for Nagios) |
- https://nagios-plugins.org/doc/guidelines.html#AEN33 (Print only one line of text) |
- https://nagios-plugins.org/doc/guidelines.html#AEN41 (Verbose output) |
- https://nagios-plugins.org/doc/guidelines.html#AEN78 (Plugin Return Codes) |
- https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT (Threshold and ranges) |
- https://nagios-plugins.org/doc/guidelines.html#AEN200 (Performance data) |
- https://nagios-plugins.org/doc/guidelines.html#PLUGOPTIONS (Plugin Options) |
- https://nagios-plugins.org/doc/guidelines.html#AEN302 (Option Processing) |
Note: The screen output of the help page will (mostly) be limited to 80 characters width; but the max recommended length of 23 lines cannot be guaranteed. |
This framework does currently NOT support following guidelines: |
- https://nagios-plugins.org/doc/guidelines.html#AEN74 (Screen Output) |
- https://nagios-plugins.org/doc/guidelines.html#AEN239 (Translations) |
- https://nagios-plugins.org/doc/guidelines.html#AEN293 (Use DEFAULT_SOCKET_TIMEOUT) |
- https://nagios-plugins.org/doc/guidelines.html#AEN296 (Add alarms to network plugins) |
- https://nagios-plugins.org/doc/guidelines.html#AEN245 (Don't execute system commands without specifying their full path) |
- https://nagios-plugins.org/doc/guidelines.html#AEN249 (Use spopen() if external commands must be executed) |
- https://nagios-plugins.org/doc/guidelines.html#AEN253 (Don't make temp files unless absolutely required) |
- https://nagios-plugins.org/doc/guidelines.html#AEN259 (Validate all input) |
- https://nagios-plugins.org/doc/guidelines.html#AEN317 (Plugins with more than one type of threshold, or with threshold ranges) |
We will intentionally NOT follow the following guidelines: |
- https://nagios-plugins.org/doc/guidelines.html#AEN256 (Don't be tricked into following symlinks) |
Reason: We believe that this guideline is contraproductive. |
Nagios plugins usually run as user 'nagios'. It is the task of the system administrator |
to ensure that the user 'nagios' must not read/write to files which are not intended |
for access by the Nagios service. Symlinks, on the other hand, are useful for several tasks. |
See also https://stackoverflow.com/questions/27112949/nagios-plugins-why-not-following-symlinks |
VNag over HTTP: |
A script that uses the VNag framework can run as CLI script (normal Nagios plugin) or as web site (or both). |
Having the script run as website, you can include a Nagios information combined with a human friendly HTML output which can |
include colors, graphics (like charts) etc. |
For example: |
A script that measures traffic can have a website which shows graphs, |
and has a hidden Nagios output included, which can be read by a Nagios plugin that |
converts the hidden information on that website into an output that Nagios can evaluate. |
Here is a comparison of the usage and behavior of VNag in regards to CLI and HTTP calls: |
------------------------------------------------------------------------------------------ |
CLI script HTTP script |
------------------------------------------------------------------------------------------ |
* "echo" will be discarded. * "echo" output will be discarded. |
* Exceptions will be handled. * Exceptions will be handled. |
* outputHTML() will be ignored. * outputHTML() will be handled. |
(This allows you to have the same script |
running as CLI and HTML) |
* Arguments are passed via CLI. * Arguments are passed via $_REQUEST |
(i.e. GET or POST) |
* Arguments: "-vvv" * Arguments: GET ?v[]=&v[]=&v[]= or POST |
* When run() has finished, the program * When run() has finished, the program |
flow continues, although it is not flow continues. |
recommended that you do anything after it. |
(The exit code is remembered for the |
shutdown handler) |
* Exactly 1 job must be called, resulting * You can call as many jobs as you want. |
in a single output of that job. A website can include more than one |
Nagios output which are enumerated with |
a serial number (0,1,2,3,...) or manual ID. |
------------------------------------------------------------------------------------------ |
****************************************************************************************************/ |
if (!VNag::is_http_mode()) error_reporting(E_ALL); |
/trunk/src/plugins/overview |
---|
File deleted |
/trunk/src/plugins/README.md |
---|
0,0 → 1,52 |
VNag plugin overview |
==================== |
+---------------------------+----------------------------+----------------+-------------------+-----------------------------------------------------------------------+ |
| 2011 StatMon (deprecated) | 2018 VNag Command | WebOptimized? | Generic/Internal? | Notes | |
+---------------------------+----------------------------+----------------+-------------------+-----------------------------------------------------------------------+ |
| 4images_version | vnag_4images_version | No | Generic | | |
| aptitude_monitor | (Obsolete) | - | - | Functionality part of Icinga's command "apt". | |
| certificate_monitor | vnag_x509_expire | No | Generic | See also Icinga's "ssl" command, which checks certs of live websites. | |
| hdd_usage (hdd_size) | (Obsolete) | - | - | Functionality part of Icinga's command "disk". | |
| ipfm_mon | vnag_ipfm | Yes | Generic | | |
| joomla_version | vnag_joomla_version | No | Generic | | |
| lastmon | vnag_last | No | Generic | | |
| mdstat_test | vnag_mdstat | No | Generic | | |
| mediawiki_version | vnag_mediawiki_version | No | Generic | | |
| mem | vnag_virtual_mem | No | Generic | Checks real+swap memory. Icinga's "swap" command only checks swap. | |
| net2ftp_version | vnag_net2ftp_version | No | Generic | | |
| nocc_version | vnag_nocc_version | No | Generic | | |
| open_deleted_files | vnag_open_deleted_files | No | Generic | To see the files which are inaccessible, run "lsof -n | grep deleted" | |
| openbugbounty | vnag_openbugbounty | No | Generic | | |
| phpbb3_version | vnag_phpbb_version | No | Generic | | |
| phpmyadmin_version | vnag_phpmyadmin_version | No | Generic | | |
| ping | vnag_ping | Yes | Generic | | |
| positive_responder | (Discontinued) | - | - | Was only intended as test monitor. | |
| roundcube_version | vnag_roundcube_version | No | Generic | | |
| smart_test | vnag_smart | No | Generic | | |
| static_ping | (Obsolete) | - | - | Functionality part of Icinga's command "ping-common". | |
| timestamp | vnag_file_timestamp | No | Generic | | |
| universal_ping | (Obsolete) | - | - | Functionality part of Icinga's command "ping-common". | |
| verteiler | (Obsolete) | - | - | Functionality part of Icinga. | |
| website_monitor | (Discontinued) | - | - | | |
| wordpress_version | vnag_wordpress_version | No | Generic | | |
| | vnag_webreader | No | Generic | | |
| | vnag_disk_running | No | Generic | For monitoring disks which do not have SMART functionality. | |
| | vnag_pmwiki_version | No | Generic | | |
| | vnag_gitlab_version | No | Generic | | |
| | vnag_nextcloud_version | No | Generic | | |
| | vnag_owncloud_version | No | Generic | | |
| | vnag_hp_smartarray | No | Generic | | |
| | vnag_minecraft_java_version| No | Generic | | |
| | vnag_aastra_430_voicemail | No | Generic | | |
| | vnag_websvn_version | No | Generic | | |
| | vnag_viewvc_version | No | Generic | | |
+---------------------------+----------------------------+----------------+-------------------+-----------------------------------------------------------------------+ |
| | vnag_faindex | No | VTS Internal | | |
| | vnag_fasearch | No | VTS Internal | | |
| | vnag_bulbcam_* (Discont.) | No | VTS Internal | | |
| | vnag_oidinfo_linkcheck | No | VTS Internal | | |
| | vnag_vts_command_listener | No | VTS Internal | | |
| | vnag_vwi_timestamp | Yes | VTS Internal | Available here: https://whois.viathinksoft.de/vnag/ | |
+---------------------------+----------------------------+----------------+-------------------+-----------------------------------------------------------------------+ |
/trunk/web/README.md |
---|
0,0 → 1,10 |
In this folder you can find some examples which are "web optimized", |
meaning these VNag scripts can be used in the browser |
(either visible or invisible). |
Web optimized scripts can be viewed by a human (if the output is visible) |
or by a remote machine using the VNag webreader plugin. |
The detection if the plugin is accessed through a browser |
or the CLI is a core functionality of VNag. |
/trunk/web/ping/index.php |
---|
38,12 → 38,16 |
require_once __DIR__ . '/../../src/plugins/ping/PingCheck.class.php'; |
$job = new PingCheck(); |
$job->http_visual_output = VNag::OUTPUT_EXCEPTION; |
$job->http_visual_output = ($_REQUEST['H']??'')=='' ? VNag::OUTPUT_NEVER : VNag::OUTPUT_EXCEPTION; |
$job->http_invisible_output = VNag::OUTPUT_ALWAYS; |
$job->run(); |
unset($job); |
?> |
<p>Please note that this page also outputs an invisible <a href="https://www.viathinksoft.de/projects/vnag">VNag</a> |
machine-readable part which can be read using the webreader plugin.</p> |
</body> |
</html> |