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 service 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\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. Prior to NCPA 3, NCPA ran as two separate services. The decision was made to have each service have its own log file. These log files were not merged together in the move to NCPA 3, and may or may not be merged in future releases.

= 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 run through NCPA 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.
loglevel info The level of message that will be logged to the log file. Valid loglevels are info, error, warning, and debug.
logfile var/log/ncpa_listener.log The named file location where the log file for active checks 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.
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.
pidfile var/run/ncpa.pid The name and location of where to place the NCPA Listener PID file. Linux and Mac OS X only.
exclude_fs_types aufs, autofs, binfmt_misc, cifs, cgroup, configfs, debugfs, devpts, devtmpfs, encryptfs efivarfs, fuse, fusectl, hugetlbfs, mqueue, nfs, overlayfs, proc, pstore, rpc_pipefs, securityfs, selinuxfs, smb, sysfs, tmpfs, tracefs A comma separated list of file system types to remove from the disk endpoint.
default_units Gi Sets the default value of the units parameter that can be sent to convert bytes (B) into more readable versions such as GB or GiB. If this value is set and no units is given in the check or call, it will set units to this value.

[listener]

This section is for configuring options related to the NCPA service itself. 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 :: This determines what IP the service will listen on. By default, it uses the value ::, which means it will listen on all IPv4 and IPv6 interfaces and all hostname references on most linux systems. On Windows, the value :: will only listen to IPv6 interfaces. By default on Windows the value is set to 0.0.0.0 which listens on all IPv4 instances only. 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.
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>,<path to key>
ssl_ciphers Set the list of accepted SSL ciphers in theformat <cipher>:<cipher>:<cipher>.
Example: AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:CAMELLIA256-SHA
logfile var/log/ncpa_listener.log The named file location where the log file related to active checks will be stored.
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 service.
max_connections The max amount of concurrent connections to the NCPA service.
allowed_hosts A comma separated list of ip addresses of hosts that would be allowed to connect to NCPA.
allowed_sources Allow a host/domain to load the NCPA GUI inside a frame by adding it to X-Frame-Options and Content-Security-Policy frame-ancestors.

[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 passive checks. Here you can specify the location of log files, the handlers you'd like to use (currently, only NRDP) and other related settings needed by the service.

Option Default Description
handlers None
Handlers are what tell the NCPA service what to do with configured passive checks while running. Currently there are only two options here: none, and nrdp.
If none is selected, effectively passive checks are disabled. No handlers will execute, no configured checks will execute.
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
sleep 300 The time, in seconds, in which the service will run any configured passive checks that do not have their own time frame specified.
logfile var/log/ncpa_passive.log The named file location where the log file for passive checks will be stored.
delay_start 0 The amount to seconds to wait before starting the NCPA Passive service. Typically passive checks are run right away when the service is restarted so if you would like to force the NCPA Passive service to wait before running the cheks, set this value.

[nrdp]

The value nrdp must be present in the [passive] handlers option for the NCPA 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. Can also be a comma separated list.
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. Can also be a comma separated list.
hostname NCPA This is the value that will be used for the %HOSTNAME% macro in the [passive checks] configuration section.
connection_timeout 10 Connection timeout in seconds that will be used for transmitting the passive check results via HTTP POST requests to the NRDP server.

[kafkaproducer]

The value kafkaproducer must be present in the [passive] handlers option for the NCPA service to run the checks and send the results to the specified Kafka receiver.

Option Default Description
hostname None The hostname, which may not need to be specified.
servers localhost:9092 A comma separated list of Kafka server(s) that will receive messages.
clientname NCPA-Kafka This represents what is giving the message to Kafka, this is just a standard client name.
topic ncpa The topic slug to send in with the check data.

[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.
follow_symlinks 0 Follow symlinks located in the plugin path. Linux and Mac OS X only.
plugin_timeout 59 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
.py = python3 $plugin_name $plugin_args
.pl = perl $plugin_name $plugin_args
.php = php $plugin_name $plugin_args
.ps1 = powershell -ExecutionPolicy Bypass -File $plugin_name $plugin_args
.vbs = cscript $plugin_name $plugin_args //NoLogo
.wsf = cscript $plugin_name $plugin_args //NoLogo
.bat = cmd /c $plugin_name $plugin_args

[passive checks]

Starting in NCPA 2, this section 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