Configuration

On a successful install, NCPA will start working right out of the box. However, to tailor it to your needs, you will want to edit the configuration. You can set up NCPA security and web GUI settings, along with configuring passive check settings.

This is meant to be a reference for all the configuration options available. Some configuration options are required, while others are just optional. We recommend keeping the configuration options that are defined by default, and tweaking them to your desired configuration. Doing it this way ensures that all non-default options will be defined.

After editing the configuration, you must restart the NCPA Passive and NCPA Listener services to apply the new configuration.

Note: On Linux and Mac OS X, the default API token is set to mytoken and you will want to change this after install. Windows sets the token on install based on user input in the installer.

Config Locations

In order to configure NCPA, you will need to edit its configuration file, which is kept on the file system. On a default install, most of the configuration will be located in the ncpa.cfg file in the following directories on the selected operating system:

C:\Program Files (x86)\Nagios\NCPA\etc\
/usr/local/ncpa/etc/
/usr/local/ncpa/etc/

As of NCPA 2, there is also an ncpa.cfg.d folder which includes all .cfg files inside of it into the main nagios.cfg when parsing the configuration. Another change to the way configuration works in NCPA 2 is that changing the passive check configuration requires a restart of the NCPA Passive service. By default NCPA 2 will have an ncpa.cfg.d/example.cfg file in the config directory on all operating systems. On windows, you are able to select whether or not you are going to enable NRDP during the install - including setting up your basic default checks - placed in nrdp.cfg.d/nrdp.cfg.

Config Option Reference

Below is a list of all available options for the configuration file. The configuration is a standard INI-style config using the name = value notation. However, note that the config file is sectioned off by the square brackets. These different sections affect different portions of NCPA's operation. Each section is separately listed below.

Note: You might notice that there appears to be duplicate entries. For instance, both [listener] and [passive] sections have a specification for logfile. Since these are two separate services, they maintain separate log files and each sections log related options only apply to that service's log files. Many other options follow similar logic.

= Required option

[general]

This section holds general options that are typically for all of NCPA such as database settings, limits, and other global variables.

Option Default Description
check_logging 1 This option enables logging of checks ran through NCPA (both active and passive) and is on by default. If you'd like to turn logging off, set this to 0.
check_logging_time 30 The amount of time to retain log data for, if you have logging enabled. THe value is in days. The default is 30 days.

[listener]

This section is for the NCPA Listener service. It controls the web GUI, external authentication, the external API location, graphing integration, and active check settings. The NCPA Listener also runs an HTTP server to handle the API requests for both the API, GUI, and graphing sections. For this reason, this section is the only one that will require an address and a port to listen on.

Option Default Description
ip 0.0.0.0 This determines what IP the service will listen on. By default, it uses the value 0.0.0.0, which means it will listen on all interfaces and all hostname references. Change this if you would like the service to listen on a specific IP or hostname.
port 5693 This specifies the TCP port the service will bind to.
uid nagios Determines which user the service will run as. Linux and Mac OS X only.
gid nagios Determines which group the service will run as. Linux and Mac OS X only.
ssl_version TLSv1_2 Set the SSL protocol version to allow for connecting to the HTTPS server.
Options: TLSv1, TLSv1_1, or TLSv1_2
certificate adhoc Allows you to specify the file name for the SSL certificate you wish to use with the internal HTTPS server. If using adhoc - a new self-signed certificate will be generated and used for the server. The default cert is located in the main install directory at /usr/local/ncpa/var/ncpa.crt on install.
Options: adhoc or <path to certificate>
pidfile var/run/ncpa_listener.pid The name and location of where to place the NCPA Listener PID file. Linux and Mac OS X only.
loglevel info The level of message that will be logged to the log file. Valid log levels are info, error, warning, and debug.
logfile var/log/ncpa_listener.log The named file location where the log file for the NCPA Listener will be stored.
logmaxmb 5 The max size allowed for a log file in MB. When the log becomes larger than this size, the log will be rolled over and a new log will be started.
logbackups 5 The max number of log rollovers that will be kept.
admin_gui_access 1 This setting controls the Admin section. Setting this to 0 will cause the Admin panel to not be accessible from the GUI.
admin_password None If the admin panel is available by having admin_gui_access = 1, this option is used for adding extra authentication. Leaving this as None will cause it to automatically allow access to the admin section once authenticated into the GUI. If it's set to any other value, it will require that password when trying to access the Admin section. This password is also used as a way to authenticate GUI access if admin_auth_only = 1.
admin_auth_only 0 Setting this variable to 1 will force NCPA to require admin authentication on GUI login/access. This is useful if you don't want anyone to log into the GUI using the API token defined by community_string in the section below. This requires you to have a password set for admin_password too, since it will never allow authentication when admin_password = None.
delay_start 0 The amount to seconds to wait before starting the NCPA Listener service.

[api]

This section controls the authentication token for the API and any other options that control access or change the way the API works. Currently there is only one option for this section.

Option Default Description
community_string mytoken The token used to authenticate when accessing the API.
The token is also used to authenticate to the web GUI unless admin_auth_only = 1 in the [listener] section an admin_password is provided.

[passive]

This section is for the NCPA Passive service. Here you can specify the location of log files, the handlers you'd like to use (NRDP only currently) and other related settings needed by the service.

Option Default Description
handlers None Handlers are what tell the NCPA Passive service what to do while running. There is currently only one handler available: NRDP. The NRDP handler handles sending passive check results to the NRDP server you choose. This is a comma separated list. Example of this setting is handlers = nrdp.
Options: None or nrdp
uid nagios Determines which user the service will run as. Linux and Mac OS X only.
gid nagios Determines which group the service will run as. Linux and Mac OS X only.
sleep 300 The time in seconds which the service will wait until running again. Upon waking up, the service will check to see if it has anything to do. If it has nothing to do it will sleep again for the specified time.
pidfile var/run/ncpa_passive.pid The named file location where the PID file for the NCPA passive service will be stored and maintained. Linux and Mac OS X only.
loglevel info The level of message that will be deemed important enough to be logged to the log file. Valid log levels are info, error, warning, and debug.
logfile var/log/ncpa_passive.log The named file location where the log file for the NCPA passive service will be stored.
logmaxmb 5 The max size allowed for a log file in megabytes. When the log becomes larger than this, the log will be rolled over and a new log will be started.
logbackups 5 The max number of log rollovers that will be kept.
delay_start 0 The amount to seconds to wait before starting the NCPA Passive service. Typically passive checks are ran right away when the service is restarted so if you would like to force the NCPA Passive service to wait before running the checks, set this value.

[nrdp]

The value nrdp must be present in the [passive] handlers option for the NCPA Passive service to run the checks and send the results to the specified NRDP server. While this section is optional, you must set all configuration options in order for the service to send the passive checks to NRDP.

Option Default Description
parent The Nagios server's NRDP URL to which the passive check results should be sent. The reason for the option name of parent is because you can use NCPA as an NRDP forwarder for those who have restrictive firewall configurations.
token The token to use to send check results to the NRDP server URL specified in parent. This token is created on the NRDP server side.
hostname NCPA This is the value that will be used for the %HOSTNAME% macro in the [passive checks] configuration section.

[plugin directives]

This section is where you can specify both the plugin directory and special command line arguments that should passed to a given file type when it is executed by NCPA.

Option Default Description
plugin_path plugins/ The path to the directory containing any third party plugins that you would like to be able to run. Note that the forward slash at the beginning is left off. This makes it a relative path to the location of the NCPA directory. You can use a full directory path also.
Requires nagios:nagios (or whatever your uid:gid is set to) permissions on the plugin location. The user must also be able to execute the plugins.
plugin_timeout 60 The plugin execution timeout on the NCPA side. For both active and passive checks. There is also a timeout specified in check_ncpa.py.
Plugin Extensions

Part of the plugin directives, we define file type extensions of valid plugins. The option is the name of the extension while the value denotes how NCPA will try to run the plugin from the command line. There are two special macros, $plugin_name and $plugin_args, that will be replaced with the filename and all arguments passed. The default values for this section are shown below.

.sh = /bin/sh $plugin_name $plugin_args
.ps1 = powershell -ExecutionPolicy Bypass -File $plugin_name $plugin_args
.vbs = cscript $plugin_name $plugin_args //NoLogo
.py = python $plugin_name $plugin_args

[passive checks]

This section, in NCPA 2, is typically in a separate file located in the etc/ncpa.cfg.d directory. You can view the example.cfg configuration to see how you can create these files. For information on the specifics of setting up passive checks, see the section on creating Passive Checks.

Check Definitions

Shown below is the basis for how to define a check. Typically hostname is set to %HOSTNAME%. Check interval is optional, and you can define a check without the last |. The servicename of __HOST__ is special, and refers to the host check - so the results of that check will appear as the specified host's check results.

<hostname>|<servicename>|<check interval in sec> = <api endpoint> --warning <value> --critical <value> <other options>
Examples
%HOSTNAME%|__HOST__ = /system/agent_version
%HOSTNAME%|CPU Usage = /cpu/percent --warning 60 --critical 80 --aggregate avg
%HOSTNAME%|Memory Usage = /memory/virtual --warning 80 --critical 90 --units G