While NCPA has many features, configuring your initial NCPA install can be tricky. This help documentation is here to explain the inner workings of NCPA as well as a reference when configuring and setting up NCPA instances.

This help documentation is geared towards those who have already installed NCPA and are looking at more advanced configuration and setup using this help as a reference. To start off, below is a brief overview of the parts of NCPA and what they are responsible for.

The Two Parts of NCPA

NCPA is actually two separate services that make up a single monitoring agent. This separation allows the ability for the agent to run passive checks without needing to allow connections to the web GUI or allow external calls to the API. It also allows the passive portion of the agent to be disabled if it's not in use to save resources even though the passive portion requires very few resources while running in the background.

By default in NCPA 2, both services run as the nagios user and nagios group. The user and group can be changed in the ncpa.cfg.

NCPA Listener

The NCPA Listener service does the following:

  • Serves and handles connections to the web GUI
  • Handles external API requests (including those for active checks)
  • Provides API for live graphing and top processes
  • Provides and "offline" internal API for the NCPA Passive service

NCPA Passive

The NCPA Passive service does the following:

  • Runs passive checks defined in the [passive checks] configuration section
  • Connects and sends passive check results to the defined NRDP URL

Restarting the NCPA Services

Because NCPA is made up of these two separate services, you will need to restart both of them if you are using both the active and passive capabilities. Below is the naming conventions and the command line way of restarting both services. In the configuration section you'll find that you will need to restart the services each time configuration changes are made.

You can also view the services in the windows services administration panel, but you can also do it easily from the command line.

net stop ncpalistener
net start ncpalistener
net stop ncpapassive
net stop ncpapassive

This is an example for CentOS 6. However, the services are named the same in all Linux distros we build for.

service ncpa_listener restart
service ncpa_passive restart

Unfortunately there is not a restart command for launchctl at this time.

sudo launchctl stop com.nagios.ncpa.listener
sudo launchctl start com.nagios.ncpa.listener
sudo launchctl stop com.nagios.ncpa.passive
sudo launchctl start com.nagios.ncpa.passive

Changes from 2.0 to 2.1

You can also view the full changelog on the NCPA GitHub repository .

  1. Passing arguments via parameters for plugins - You can now pass plugin arguments using parameters instead of through the path, so using ?args=<arg1>&args=<arg2> instead of /arg1/arg2 alleviates some problems passing certain variables. Certain things, like drive names, will pass properly using parameters.
  2. Long output - Both the processes and logs endpoints now return long output. Both show data on what was returned from the check.
  3. Processes check returns total perfdata - Process checks return the total amount of cpu usage, memory, etc that all processes that match are using.
  4. New configuration options - New configuration options available:
    1. run_with_sudo - Comma separated list of plugin names that should be ran through sudo
    2. allowed_hosts - Comma separated list of IP addresses that can access the agent
    3. default_units - The default units to use (G, Gi, etc)
    4. exclude_fs_types - Comma separated list of file system types to ignore
  5. Multiple NRDP receivers - You can now put multiple NRDP parents in the configuration (and tokens for those parents) using a comma separated list.
  6. Added Kafka for passive checks - Thanks to a contributer on GitHub, you can now send passive checks out through Kafka. Configuration options example in the nagios.cfg file.
  7. Interface checks - The interface node checks can now be performed on an interface, which will show the entire status of packets/bytes sent and received all in one check.

Changes from 1.x to 2.x

The latest version of NCPA has a lot of major changes that affect users of older versions of NCPA. Since these changes are in multiple sections of NCPA 2, we have created list of the most notable changes that could affect your system when upgrading from an older version.

  1. Updated check_ncpa.py plugin - There is a new version of check_ncpa.py (version 1.0) and should be updated. Version 1.0+ is compatible with NCPA 1.x and 2.x so you can update at any time. If you are using Nagios XI, update your NCPA wizard in the Admin > Manage Config Wizards section. If you are using Nagios Core, you can download the new plugin from GitHub .
  2. API output JSON format - With NCPA 2, the JSON output no longer sends value. Instead, it's output is just a JSON object, formatted the way it should be returned based on the node that was called and whether or not it is a check. This change is already accounted for in the new check_ncpa.py plugin (version 1.0+) and is available in both Nagios XI and Nagios Core. See above for instructions.
  3. Configuration folder - You can now put configuration files into the ncpa.cfg.d folder to be included into the main ncpa.cfg configuration file.
  4. Renamed agent/plugin node to plugins - Due to the confusion of the naming convention for the api/agent/plugin node, we have renamed this node to api/plugins which fits the current node layout better. This change affects both active and passive checks. The old node is still able to be used, so no immediate changes are necessary, but it is deprecated and will be removed in future versions of NCPA.
  5. Changes to unit types - Most units that were considered bytes returned the unit b instead of the proper unit B. The units variable also now will only affect the B and b unit types. All other types can only be overridden by unit, which sets the unit to something other than the default unit used.
  6. Deprecated service and process nodes - With older versions of NCPA, it was typical to use the format api/service/<servicename> and api/process/<processname> for both the service and process nodes. However, in NCPA 2, the nodes will forward to the new api/services?service=<servicename> and api/processes?name=<processname> instead. The old node endpoints will be removed in future versions of NCPA.
  7. Individual passive check intervals - You can now define an individual passive check interval by appending |<check interval in seconds> after there service name. If an individual check interval is not defined, the global default sleep value set in your config will be used.
  8. Renamed ncpa_posix_listener and ncpa_posix_passive service names to ncpa_listener and ncpa_passive - Due to the services being named ncpa_listener and ncpa_passive in the init.d scripts, it makes more sense to not name them with the posix section anymore.


Sometimes when setting up NCPA things don't work out the first time. We've compiled a few troubleshooting tips and things that could happen that might give people headaches.

Checking for problems in the logs

Typically if there is an error you will always see that error logged, no matter what your log level since error is the most filtered log level available. However, sometimes Python errors will occur before logging starts in Windows systems. You can normally find these errors in the log files located in the same directory as the .exe files in the Windows Program Files directory that you installed NCPA into.

That being said, a good habit to get into is setting your loglevel to debug when you are running into trouble where something is not working correctly. If you do this, and restart your NCPA services, we can get a better idea of what is going on and when it's going in the code. If you can't figure out the issue from reading the debug log, post it in an issue on GitHub and the developers can take a look.

Make sure your checks do not use api node

For both passive and active checks, when you are configuring them, do not use the api section when specifying the endpoint to run. Examples below:

./check_ncpa.py -H <ncpa server> -t '<your token>' -M 'disk/logical/C:|' --units G
%HOSTNAME%|<service name> = disk/logical/C:| --units G

Note that the disk/logical/C:| does not have the api portion applied. Remember that checks do not need a beginning forward slash. A good way to avoid using the wrong path is by viewing an example check for the endpoint you are making a check for from the API tab.