Running active checks against NCPA is fairly straight-forward and follows a similar style as check_nrpe. You should download the latest version of the check_ncpa.py plugin from GitHub. This plugin works with NCPA 2+ and is backwards compatible with NCPA 1. This plugin is the standard method for executing active checks. However, because of the design of NCPA, it makes it very easy to use your own methods to collect data at perform active checks, even from a simple curl command. We will leave the choice to you, but we will support active checks through the check_ncpa.py plugin.
Using the plugin will require some knowledge of how the API works. You will also need to make sure you install the plugin in the Nagios libexec (typically /usr/local/nagios/libexec) directory.
While you can run a check through the API in your browser, you will want to use the check_ncpa.py plugin to run these active checks from your Nagios server to have your results show up in Nagios. Once you've installed your plugin on the Nagios server in your libexec directory, you can run it just like any other plugin.
The most important part you'll need to do is specify the API endpoint that you want to run the check on. This is done by passing the node endpoint (or as the plugin calls this value, the metric) by the -M argument.
disk module with single quotes. This is because NCPA uses the | character instead of slashes. This is to help with running values from URLs in the API. However, the pipe character is a special character in the linux shell and must be escaped by single quotes. Example: -M 'disk/logical/C:|'
A simple check to demonstrate how the plugin works is checking for the used memory percent:
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'memory/virtual/percent'
The above check will return the following:
OK: Percent was 36.20 % | 'percent'=36.20%;;;
This is a pretty simple check - you can do a lot of tweaking to get different output. Read on in the section that explains how to use the check_ncpa.py plugin to see more options. Most of the base nodes, such as memory/virtual, have special checks that encompass all the child endpoints. You can see an example of that below.
Say we want to see the amount of memory we are using in GB, but NCPA returns the value in B by default. Typically we would add units=G in the API call, but the plugin will do this for us. See the example below:
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'memory/virtual/used' -u G
Will return the GB value instead of the B value:
OK: Used was 13.16 GB | 'used'=13.16GB;;;
In this section, we will cover some of the standard use cases and how to use the plugin to achieve specific output. While this section will go over most of the arguments that are available in the plugin, you can also view all the available arguments by using --help.
-v argument to enable verbose output of problems. There is also a -D argument that enables debugging output.
You can send warning (-w or --warning=) and critical (-c or --critical=) values to any value that comes from the API nodes besides the plugins node since these values do not work with plugins. If you need to send the warning and critical values to your plugins, you'll have to pass them as plugin arguments.
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'processes' --warning=100 --critical=200
The output would look something like this:
WARNING: Process count was 177 | 'process_count'=177;100;200;
You can see that now the perfdata has the warning and critical values set. Also, we see that the system we are checking has over 100 processes and so it shows up as a warning.
You can send additional query string arguments in a comma separated list of key=value pairs. If we were interested in getting the CPU Usage (average percent over all cores) of the host that we installed NCPA on, we would run the check_ncpa.py with the -q argument because we need to tell NCPA how to aggregate the CPU usage results. The check would be the following:
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'cpu/percent' -q 'aggregate=avg'
The above would output the following:
OK: Percent was 2.16 % | 'percent'=2.16%;;;
If we removed the -q 'aggregate=avg', which is passing arguments to the URL that the plugin is generating, we would get:
OK: Percent was 7.70 %, 0.00 %, 11.10 %, 0.00 %, 0.00 %, 0.00 %, 3.00 %, 0.00 %, 0.00 %, 0.00 %, 0.00 %, 1.50 %, 0.00 %, 1.50 %, 0.00 %, 3.20 % | 'percent_0'=7.70%;;; 'percent_1'=0.00%;;; 'percent_2'=11.10%;;; 'percent_3'=0.00%;;; 'percent_4'=0.00%;;; 'percent_5'=0.00%;;; 'percent_6'=3.00%;;; 'percent_7'=0.00%;;; 'percent_8'=0.00%;;; 'percent_9'=0.00%;;; 'percent_10'=0.00%;;; 'percent_11'=1.50%;;; 'percent_12'=0.00%;;; 'percent_13'=1.50%;;; 'percent_14'=0.00%;;; 'percent_15'=3.20%;;;
This check represents an 8 core processor with 16 threads. You can see how it might be helpful to send these extra variables in your checks. If we were to define a warning and critical value above, it would apply to each of the threads instead of the check as a whole.
If you are using the plugins module to execute your own custom scripts, you will likely want to be able to pass arguments to the executed script. To do this, pass the args parameter. check_ncpa.py has -q, which allows you to pass parameters with the request. Make sure you quote the arguments right when you send them; single quotes and double quotes matter here.
If we had a script called test.sh, running it from the command line may look something like this:
./test.sh -u 'one argument' -p 'another argument'
To run the above script using NCPA and the check_ncpa.py plugin:
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'plugins/test.sh' -q "args=-u 'one argument',args=-p 'another argument'"
The quotes matter for how the plugin is going to be interpreted by NCPA when it is ran. To see this clearly, check out these examples of how the plugin would create the API call for each quoting example:
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'plugins/test.sh' -q "args=-u 'one argument',args=-p 'another argument'"
The above would give you the following URL:
https://<ncpaserver>/api/plugins/test.sh?args=-u 'one argument'&args=-p 'another argument'
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'plugins/test.sh' -q "args=-u one argument,args=-p another argument"
The above would give you the following URL:
https://<ncpaserver>/api/plugins/test.sh?args=-u one argument&args=-p another argument
There are some special arguments that do not run checks that can be used to help test out using the plugin for a specific check.
You can also use check_ncpa.py to return a representation of all the values you can monitor in a specific API node. This can be very helpful when you are in a terminal without the use of a web browser. You can use the --list (or -l) command to have it list, rather than run a check, on a particular node:
./check_ncpa.py -H <ncpaserver> -t mytoken -M 'disk' --list
The list command will also work with no specified -M and will list all the base modules available in the API.