NCPAServer¶
Experimental
This module is experimental: it works, but its options, filter keywords and output may change in a future release. Please try it and report anything that does not behave the way you expect.
A server that serves the Nagios NCPA HTTP API, so Nagios Core and XI can poll NSClient++ with the stock check_ncpa.py plugin and the XI NCPA wizard.
NCPAServer serves the Nagios Cross-Platform Agent (NCPA) HTTP API on
port 5693, so Nagios Core and Nagios XI can poll NSClient++ with the stock check_ncpa.py plugin and the XI NCPA
wizard, unmodified. The module measures nothing itself: it authenticates the request with the NCPA token and answers
it from the agent’s own checks.
This first release serves the plugins/ node, which puts every NSClient++ check, alias and external script behind
check_ncpa.py -M plugins/<name>. The built-in NCPA node tree (cpu/, memory/, disk/, interface/,
services/, processes/, system/, user/) is not served yet; asking for one of those nodes is answered the way
NCPA answers any node that does not exist.
To use this module you need to enable it and give it a token:
[/modules]
NCPAServer = enabled
[/settings/default]
allowed hosts = 127.0.0.1,192.168.0.10
nscp ncpa token --set <a long random string>
The command stores a hash of the token (pbkdf2-sha256$...) under [/settings/NCPA/server], so the token cannot be
read back out of the configuration; the agent verifies the clear text check_ncpa.py sends against it. Writing
token = <the string> into the file by hand works too, and is compared in constant time, but then anyone who can read
the file has the token.
Running checks with check_ncpa.py¶
The -a string is split into tokens, and each token is passed to the check as one argument, the way the REST API
passes key=value. Quote a token that contains spaces:
check_ncpa.py -H agent.example.com -t '<token>' -M plugins/check_cpu
check_ncpa.py -H agent.example.com -t '<token>' -M plugins/check_cpu -a '"warning=load > 80" "critical=load > 90"'
check_ncpa.py -H agent.example.com -t '<token>' -M plugins -l
The answer is the check’s own output, unchanged: the Nagios exit code becomes returncode and the message, followed by
| and the performance data, becomes stdout. The -w, -c, -u and -n options of check_ncpa.py do not
apply to plugins/: the thresholds belong in the check’s own arguments.
check_ncpa.py -M plugins -l lists the queries the server exposes, aliases included.
The arguments are split the way NCPA splits them: any args= parameters first, then the path segments after the query
name, joined with spaces and split again. The quoting rules are those of the NSClient++ prompt:
| Written | Reaches the check as | Why |
|---|---|---|
"warning=load > 80" |
warning=load > 80 |
double quotes group and are removed |
path='C:\Program Files\app' |
path=C:\Program Files\app |
a single quote groups where a whole value starts |
filter=core='total' |
filter=core='total' |
a single quote anywhere else is kept, for the filter syntax |
path=C:\Windows\Temp |
path=C:\Windows\Temp |
a backslash is an ordinary character |
A backslash is never an escape, not even before a quote, so "path=C:\Temp\" ends where it appears to. To pass a
double quote, put the value in single quotes.
Securing the server¶
token- required. There is no default: until one is set every request is refused, and the log says why. The plugin passes it with-t, and it travels in the query string, so it is only as private as the connection: keep TLS on.nscp ncpa token --set <token>stores it hashed (pbkdf2-sha256$..., the same form as the WEB password), so reading the configuration does not give it away; a clear-text value written by hand is accepted as well and compared in constant time. The token is never logged. A wrong or missing token is answered with{"error": "Incorrect credentials given."}, whichcheck_ncpa.pyreports asCRITICAL, and ten wrong tokens in a row from one address block it for a minute (auth rate limit max failures,auth rate limit block seconds). A block survives a settings reload.backup token- a second accepted token, so the token can be rotated without a window where pollers fail.nscp ncpa token --set <token> --backupstores it hashed.allowed hosts- which addresses may connect at all, inherited from[/settings/default]. A connection from a host outside the list is closed as soon as it is accepted, before the TLS handshake, and logged - once a minute per address, with a count of the refusals left out in between. Host names in the list are resolved when the listener starts and, withcache allowed hosts = false, again for every connection, as on the other servers.allow arguments-falseby default, with the same meaning as the NRPE server’s: a request toplugins/that carries arguments is refused withUNKNOWN. The caller can run the commands the agent defines but cannot shape what they do. Define an alias to give a check fixed arguments, or setallow arguments = true.plugins- which queriesplugins/exposes:any(the default, every registered query),scripts(only what CheckExternalScripts registers) or a comma-separated list of names. A query that is not exposed is answered exactly like one that does not exist.
TLS¶
The listener serves HTTPS with the same certificate as the WEB server (${certificate-path}/certificate.pem, generated
on first start when missing), so one certificate serves both. check_ncpa.py does not verify the certificate unless it
is run with -s, so the generated self-signed one works out of the box; give it a real one and pass -s to have the
monitoring server check it. Unless the certificate and its key actually load (and belong together), the listener
refuses to start rather than send the token in clear.
To serve plain HTTP, for instance behind a TLS-terminating proxy, both settings are needed: an empty certificate
(otherwise the default one is generated and used) and allow insecure = true (otherwise a missing certificate stops
the listener). allow insecure covers a missing certificate only, as on the WEB server: a certificate that is
configured but does not load (no key, a key for another certificate, an unreadable file) stops the listener whatever
the flag says, so a damaged file never turns into a cleartext listener.
[/settings/NCPA/server]
certificate =
allow insecure = true
Listening address¶
The listener binds to bind to, set under [/settings/NCPA/server] or inherited from [/settings/default] like the
NRPE and NSCA servers, and to every interface when that is empty. An IPv6 address is written bare (bind to = ::1).
Concurrency¶
Up to threads requests (default 10) are answered at the same time, so a slow check - an external script close to its
timeout - only delays the polls behind it once every thread is busy.
The NCPA server and the WEB server are separate listeners with separate credentials and allow-lists, so either can run without the other.
Enable module¶
To enable this module and allow using the commands you need to add NCPAServer = enabled to the [/modules] section in nsclient.ini:
[/modules]
NCPAServer = enabled
Configuration¶
| Path / Section | Description |
|---|---|
| /settings/NCPA/server | NCPA server |
| /settings/NCPA/server/log | Log configuration |
| /settings/default | Default values |
NCPA server ¶
Section for the NCPA (NCPAServer) protocol: the Nagios NCPA HTTP API, polled with check_ncpa.py and the Nagios XI NCPA wizard.
| Key | Default Value | Description |
|---|---|---|
| allow arguments | false | ALLOW ARGUMENTS |
| allow insecure | false | ALLOW INSECURE (CLEARTEXT HTTP) |
| allowed ciphers | ALLOWED CIPHERS | |
| allowed hosts | 127.0.0.1 | Allowed hosts |
| auth rate limit block seconds | 60 | AUTH RATE LIMIT (BLOCK SECONDS) |
| auth rate limit max failures | 10 | AUTH RATE LIMIT (FAILURES) |
| backup token | BACKUP TOKEN | |
| bind to | BIND TO ADDRESS | |
| cache allowed hosts | true | Cache list of allowed hosts |
| certificate | ${certificate-path}/certificate.pem | TLS CERTIFICATE |
| certificate key | TLS PRIVATE KEY | |
| plugins | any | EXPOSED PLUGINS |
| port | 5693 | PORT NUMBER |
| threads | 10 | WORKER THREADS |
| tls version | 1.2+ | TLS VERSION |
| token | TOKEN |
# Section for the NCPA (NCPAServer) protocol: the Nagios NCPA HTTP API, polled with check_ncpa.py and the Nagios XI NCPA wizard.
[/settings/NCPA/server]
allow arguments=false
allow insecure=false
allowed hosts=127.0.0.1
auth rate limit block seconds=60
auth rate limit max failures=10
cache allowed hosts=true
certificate=${certificate-path}/certificate.pem
plugins=any
port=5693
threads=10
tls version=1.2+
ALLOW ARGUMENTS ¶
Whether a request to the plugins node may carry arguments - path segments after the query name (check_ncpa -a) or `args=` parameters. False (the default) runs only the commands the agent defines, exactly as the NRPE server’s `allow arguments`; define an alias to give a check fixed arguments.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | allow arguments |
| Default value: | false |
Sample:
[/settings/NCPA/server]
# ALLOW ARGUMENTS
allow arguments=false
ALLOW INSECURE (CLEARTEXT HTTP) ¶
When false (the default) the listener refuses to start without a TLS certificate, rather than serve the token in clear. True covers a missing certificate only, as on the WEB server: a certificate that is there but does not load (no key, a key for another certificate, an unreadable file) stops the listener whatever this says, since serving in clear would turn a broken file into a leaked token. A missing default certificate is generated, so it never counts as missing: to serve plain HTTP - behind a TLS-terminating proxy, or on loopback - set `certificate` to empty as well as this to true. Note that check_ncpa.py always connects with https.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | allow insecure |
| Default value: | false |
Sample:
[/settings/NCPA/server]
# ALLOW INSECURE (CLEARTEXT HTTP)
allow insecure=false
ALLOWED CIPHERS ¶
OpenSSL cipher list the listener is restricted to. Empty (the default) leaves the library’s own selection in place.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | allowed ciphers |
| Default value: | N/A |
Sample:
[/settings/NCPA/server]
# ALLOWED CIPHERS
allowed ciphers=
Allowed hosts ¶
A comma separated list of allowed hosts. You can use netmasks (/ syntax) or * to create ranges.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | allowed hosts |
| Default value: | 127.0.0.1 |
Sample:
[/settings/NCPA/server]
# Allowed hosts
allowed hosts=127.0.0.1
AUTH RATE LIMIT (BLOCK SECONDS) ¶
How long a blocked address stays blocked. Default 60 s, doubling for an address that keeps guessing at machine speed, up to an hour - the same limiter the WEB server uses.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | auth rate limit block seconds |
| Default value: | 60 |
Sample:
[/settings/NCPA/server]
# AUTH RATE LIMIT (BLOCK SECONDS)
auth rate limit block seconds=60
AUTH RATE LIMIT (FAILURES) ¶
How many consecutive wrong tokens from one address block it. Default 10; 0 disables the limiter.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | auth rate limit max failures |
| Default value: | 10 |
Sample:
[/settings/NCPA/server]
# AUTH RATE LIMIT (FAILURES)
auth rate limit max failures=10
BACKUP TOKEN ¶
A second accepted token (NCPA’s `backup_community_string`), so the token can be rotated without a window where pollers fail. Empty (the default) accepts only `token`. Stored hashed by `nscp ncpa token –set
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | backup token |
| Default value: | N/A |
Sample:
[/settings/NCPA/server]
# BACKUP TOKEN
backup token=
BIND TO ADDRESS ¶
Allows you to bind server to a specific local address. This has to be a dotted ip address not a host name. Leaving this blank will bind to all available IP addresses.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | bind to |
| Default value: | N/A |
Sample:
[/settings/NCPA/server]
# BIND TO ADDRESS
bind to=
Cache list of allowed hosts ¶
If host names (DNS entries) should be cached, improves speed and security somewhat but won’t allow you to have dynamic IPs for your Nagios server.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | cache allowed hosts |
| Default value: | true |
Sample:
[/settings/NCPA/server]
# Cache list of allowed hosts
cache allowed hosts=true
TLS CERTIFICATE ¶
The certificate the listener serves. The default is the same file the WEB server uses, so one certificate serves both; a default one is generated when it is missing. check_ncpa.py only verifies it when run with -s.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | certificate |
| Default value: | ${certificate-path}/certificate.pem |
Sample:
[/settings/NCPA/server]
# TLS CERTIFICATE
certificate=${certificate-path}/certificate.pem
TLS PRIVATE KEY ¶
The private key for the certificate if it is not in the same file.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | certificate key |
| Default value: | N/A |
Sample:
[/settings/NCPA/server]
# TLS PRIVATE KEY
certificate key=
EXPOSED PLUGINS ¶
Which queries the plugins node exposes: `any` (every registered query - checks, aliases and external scripts), `scripts` (only the commands CheckExternalScripts registers) or a comma-separated list of query names. A query that is not exposed answers exactly like one that does not exist.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | plugins |
| Default value: | any |
Sample:
[/settings/NCPA/server]
# EXPOSED PLUGINS
plugins=any
PORT NUMBER ¶
Port to listen on. 5693 is the port check_ncpa.py and the XI wizard default to.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | port |
| Default value: | 5693 |
Sample:
[/settings/NCPA/server]
# PORT NUMBER
port=5693
WORKER THREADS ¶
How many requests are answered at the same time. A check blocks the thread answering it until it returns, so a slow external script only delays the polls behind it once all threads are busy. Default 10.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | threads |
| Default value: | 10 |
Sample:
[/settings/NCPA/server]
# WORKER THREADS
threads=10
TLS VERSION ¶
Which TLS versions the listener negotiates, in the same vocabulary as the WEB server: an exact version (1.0, 1.1, 1.2, 1.3), a trailing + for that version or later, or `any`. Honoured on builds using the beast web backend (all Linux packages).
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | tls version |
| Default value: | 1.2+ |
Sample:
[/settings/NCPA/server]
# TLS VERSION
tls version=1.2+
TOKEN ¶
The NCPA token (NCPA’s `community_string`), passed by check_ncpa.py as -t. There is no default: until one is set every request is refused. Set it with `nscp ncpa token –set
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server |
| Key: | token |
| Default value: | N/A |
Sample:
[/settings/NCPA/server]
# TOKEN
token=
Log configuration ¶
Configure which messages from the NCPA listener are logged.
| Key | Default Value | Description |
|---|---|---|
| debug | false | LOG DEBUG |
| error | true | LOG ERRORS |
| info | false | LOG INFO |
# Configure which messages from the NCPA listener are logged.
[/settings/NCPA/server/log]
debug=false
error=true
info=false
LOG DEBUG ¶
Log debug messages from the HTTP listener.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server/log |
| Key: | debug |
| Default value: | false |
Sample:
[/settings/NCPA/server/log]
# LOG DEBUG
debug=false
LOG ERRORS ¶
Log errors from the HTTP listener.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server/log |
| Key: | error |
| Default value: | true |
Sample:
[/settings/NCPA/server/log]
# LOG ERRORS
error=true
LOG INFO ¶
Log informational messages from the HTTP listener.
| Key | Description |
|---|---|
| Path: | /settings/NCPA/server/log |
| Key: | info |
| Default value: | false |
Sample:
[/settings/NCPA/server/log]
# LOG INFO
info=false
Default values ¶
Default values used in other config sections.
| Key | Default Value | Description |
|---|---|---|
| allowed hosts | 127.0.0.1 | Allowed hosts |
| bind to | BIND TO ADDRESS | |
| cache allowed hosts | true | Cache list of allowed hosts |
| encoding | NRPE PAYLOAD ENCODING | |
| inbox | inbox | INBOX |
| password | Password | |
| script root | Script root | |
| socket queue size | 0 | LISTEN QUEUE |
| thread pool | 10 | THREAD POOL |
| timeout | 30 | TIMEOUT |
| timezone | local | Timezone |
# Default values used in other config sections.
[/settings/default]
allowed hosts=127.0.0.1
cache allowed hosts=true
inbox=inbox
socket queue size=0
thread pool=10
timeout=30
timezone=local
Allowed hosts ¶
A comma separated list of allowed hosts. You can use netmasks (/ syntax) or * to create ranges.
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | allowed hosts |
| Default value: | 127.0.0.1 |
Sample:
[/settings/default]
# Allowed hosts
allowed hosts=127.0.0.1
BIND TO ADDRESS ¶
Allows you to bind server to a specific local address. This has to be a dotted ip address not a host name. Leaving this blank will bind to all available IP addresses.
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | bind to |
| Default value: | N/A |
Sample:
[/settings/default]
# BIND TO ADDRESS
bind to=
Cache list of allowed hosts ¶
If host names (DNS entries) should be cached, improves speed and security somewhat but won’t allow you to have dynamic IPs for your Nagios server.
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | cache allowed hosts |
| Default value: | true |
Sample:
[/settings/default]
# Cache list of allowed hosts
cache allowed hosts=true
NRPE PAYLOAD ENCODING ¶
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | encoding |
| Advanced: | Yes (means it is not commonly used) |
| Default value: | N/A |
Sample:
[/settings/default]
# NRPE PAYLOAD ENCODING
encoding=
INBOX ¶
The default channel to post incoming messages on
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | inbox |
| Default value: | inbox |
Sample:
[/settings/default]
# INBOX
inbox=inbox
Password ¶
Password an inbound caller has to present. Stored hashed (pbkdf2-sha256$…) when written by `nscp web install` or `nscp web password –set`; a clear-text value written by hand is still accepted, and is hashed in place when re-set. This is a password to verify against, not key material: NSCA encrypts with its shared secret instead of verifying it, so it keeps its own key under /settings/NSCA/server (or the NSCAClient default target) and never reads this one.
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | password |
| Default value: | N/A |
Sample:
[/settings/default]
# Password
password=
Script root ¶
The folder this module’s scripts live in: ${scripts} by default (empty, or `default`). `fleet` is ${fleet-folder}/scripts, where the fleet sync stages a bundle’s `scripts/` entries - a bundle that ships scripts sets this to `fleet` and refers to them as `scripts\
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | script root |
| Default value: | N/A |
Sample:
[/settings/default]
# Script root
script root=
Script root ¶
The folder this module’s scripts live in: ${scripts} by default (empty, or `default`). `fleet` is ${fleet-folder}/scripts, where the fleet sync stages a bundle’s `scripts/` entries - a bundle that ships scripts sets this to `fleet` and refers to them as `scripts\
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | script root |
| Default value: | N/A |
Sample:
[/settings/default]
# Script root
script root=
LISTEN QUEUE ¶
Number of sockets to queue before starting to refuse new incoming connections. This can be used to tweak the amount of simultaneous sockets that the server accepts.
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | socket queue size |
| Advanced: | Yes (means it is not commonly used) |
| Default value: | 0 |
Sample:
[/settings/default]
# LISTEN QUEUE
socket queue size=0
THREAD POOL ¶
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | thread pool |
| Advanced: | Yes (means it is not commonly used) |
| Default value: | 10 |
Sample:
[/settings/default]
# THREAD POOL
thread pool=10
TIMEOUT ¶
Timeout (in seconds) when reading packets on incoming sockets. If the data has not arrived within this time we will bail out.
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | timeout |
| Default value: | 30 |
Sample:
[/settings/default]
# TIMEOUT
timeout=30
Timezone ¶
Timezone used to render dates such as boot time. Accepts ‘local’ (default), ‘utc’, or any POSIX TZ string parseable by Boost.Date_time (e.g. ‘MST-07’ or ‘EST-05EDT,M3.2.0,M11.1.0’).
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | timezone |
| Advanced: | Yes (means it is not commonly used) |
| Default value: | local |
Sample:
[/settings/default]
# Timezone
timezone=local