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.
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.
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. 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
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. |
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. |
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 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. |
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. |
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. |
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. |
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 |
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.
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 |