Passive Checks

Telling NCPA to run passive checks in the NCPA Passive service is done by editing the [passive checks] section in the configuration. By default, your NCPA install will have an example [passive checks] section in etc/ncpa.cfg.d/example.cfg. If you installed on Windows, you may have some checks already defined and running if you set them up during the install process.

To set up passive checks, you'll use the API endpoint just like we do with active checks and the check_ncpa.py plugin. If you are not that familiar with the API endpoints, you can read the API reference section or you can use it live in the GUI under the API tab.

Note: If you are only using active checks and don't want the GUI to be available, you can turn off the NCPA Listener service since it does not need to be running for the passive checks to be ran. The NCPA Passive service accesses the API endpoints internally to get the check results.

Configuring Passive Checks

The first step is to configure your NCPA Passive service to send passive checks to NRDP. Once you've configured your NRDP server you can define the checks that you'd like to send. This can be accomplished by updating the [nrdp] section with the proper values. You should set the parent to the target NRDP URL and set the token to the value of a token you've set up on the NRDP server side.

Tip: If you are using Nagios XI, then NRDP is already installed. You can find the NRDP URL and the available tokens in the Admin > Inbound Transfers and use these values for your NCPA configuration.

Defining Passive Checks

Somewhere in your NCPA configuration there should be a section titled [passive checks]. On a fresh, default install of NCPA, it should come with a configuration file that has some examples of standard passive checks that you would use in etc/ncpa.cfg.d/example.cfg.

The structure of a passive check is straightforward. Here are some of the examples from the example config:

%HOSTNAME%|__HOST__ = system/agent_version
%HOSTNAME%|CPU Usage = cpu/percent --warning 60 --critical 80 --aggregate avg
%HOSTNAME%|Swap Usage = memory/swap --warning 60 --critical 80 --units Gi
%HOSTNAME%|Memory Usage = memory/virtual --warning 80 --critical 90 --units Gi
%HOSTNAME%|Process Count = processes --warning 300 --critical 400

When the NCPA Passive service starts, it parses any definitions that it finds defined. For each entry, NCPA takes the string of text before the equals, and splits it on |. The result is the hostname, servicename, and sometimes a check interval in seconds.

The %HOSTNAME% macro is populated when running the check with the hostname defined in the config file. The __HOST__ is a special service name, which represents the host check in Nagios.

Note: Certain nodes in the above example have combined check results, such as memory/virtual, memory/swap, and processes. For a full list, check out the API reference for combined check results.

Check Definition Format

There are two different formats that can be used when defining checks.

Command Line Formatting

The general passive check definition format is below. Options in bold are optional

<hostname>|<servicename>|<checkinterval> = <api endpoint> --warning x --critical y <other arguments>

URL Formatting

You can pass URL-based check definitions by passing the api endpoint and the parameters in URL format. You do need to urlencode the URL that is given.

<hostname>|<servicename>|<checkinterval> = <api endpoint>?parameter=value&parameter2=value

Check Intervals

In NCPA 2, there is now the option to set per-check intervals. The check interval is determined by the value given after the second | character. If no check interval is defined, then the sleep value from the [passive] configuration section is used as the default. This value is set to 300 seconds (5 minutes) in a default installation.

An example of a CPU Usage check that is performed every 30 seconds would look like this:

%HOSTNAME%|CPU Usage|30 = cpu/percent --warning 60 --critical 80 --aggregate avg

The bold portion represents the amount of seconds between checks.

Sending Multiple Hosts

While %HOSTNAME% gets replaced by the hostname option in the [nrdp] section of the configuration, you can also define your own hostnames. The reason for allowing this is so that if you have plugins that are actually checking another host, you have the flexibility of sending the passive check to Nagios with a different hostname. Here is an example set of passive checks that demonstrate this:

server1.local|CPU Usage = plugins/check_cpu/-H server1.local/-w 60/-c 80
server2.local|CPU Usage = plugins/check_cpu/-H server2.local/-w 60/-c 80
%HOSTNAME%|CPU Usage = cpu/percent --warning 60 --critical 80 --aggregate avg

You can see how the above could be helpful if these hosts were not accessible from anywhere except the host that NCPA is installed on.