Active Checks

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 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 plugin.

Note: All the examples in this page are from a Nagios server (either Nagios XI or Nagios Core) because the active checks are set up in Nagios and do not require any changes to be done in NCPA, besides setting up plugin directives or configuring how to access the API.

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.

Tip: If you are using Nagios XI, you can skip installing the plugin manually. By default, Nagios XI comes with a config wizard for NCPA. You can check for updates by going to the Admin > Manage Config Wizards page and clicking on Check for Updates. You can then click the install link in the NCPA config wizard table row to upgrade to the latest version if a new one is available. The config wizard upgrade script will install the latest version of the plugin for you. Running the config wizard is the fastest way to get started with NCPA active checks since it requires no manual configuration.

Running an Active Check

While you can run a check through the API in your browser, you will want to use the 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.

Note: You will need to make sure to wrap any node endpoint that uses the 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:|'

Example Check

A simple check to demonstrate how the plugin works is checking for the used memory percent:

./ -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 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.

Example Check and Specifying Units

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:

./ -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;;;

Using the Plugin

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.

Note: If you encounter problems with the plugin, you can use the -v argument to enable verbose output of problems. There is also a -D argument that enables debugging output.

Warning and Critical Values

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.

./ -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.

Sending a Query String

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 with the -q argument because we need to tell NCPA how to aggregate the CPU usage results. The check would be the following:

./ -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.

Running Plugins with Arguments

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. 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, running it from the command line may look something like this:

./ -u 'one argument' -p 'another argument'

To run the above script using NCPA and the plugin:

./ -H <ncpaserver> -t mytoken -M 'plugins/' -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:

./ -H <ncpaserver> -t mytoken -M 'plugins/' -q "args=-u 'one argument',args=-p 'another argument'"

The above would give you the following URL:

https://<ncpaserver>/api/plugins/ 'one argument'&args=-p 'another argument'
./ -H <ncpaserver> -t mytoken -M 'plugins/' -q "args=-u one argument,args=-p another argument"

The above would give you the following URL:

https://<ncpaserver>/api/plugins/ one argument&args=-p another argument

Additional Features

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.

Listing Available Nodes

You can also use 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:

./ -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.