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.
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.
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.
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
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. | |
| exclude_fs_types | aufs, autofs, binfmt_misc, cifs, cgroup, configfs, debugfs, devpts, devtmpfs, encryptfs efivarfs, fuse, 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. |
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 | :: | 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. | |
| 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
|
|
| ssl_ciphers |
Set the list of accepted SSL ciphers. List should be separated with colons (:).
Example: AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:CAMELLIA256-SHA
|
||
| 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 on startup if one does not already exist. The default cert is located in the main install directory at /usr/local/ncpa/var/ncpa.crt on install. For custom certificates you must give the location to the .crt and the .key file as a comma separated value.
Options: adhoc or <path to .crt>,<path to .key>
|
|
| 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. | |
| max_connections | The max amount of concurrent connections to the NCPA Listener service. | ||
| allowed_hosts | A comma separated list of ip addresses or hostnames 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. |
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. |
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. |
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. 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. |
The value kafkaproducer must be present in the [passive] handlers option for the NCPA Passive 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. |
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. |
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 = python $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 |
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.
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>
| %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 |