WEBServer¶
A server that listens for incoming HTTP connection and processes incoming requests. It provides both a WEB UI as well as a REST API in addition to simplifying configuration of WEB Server module.
Enable module¶
To enable this module and allow using the commands you need to add WEBServer = enabled to the [/modules] section in nsclient.ini:
[/modules]
WEBServer = enabled
Configuration¶
| Path / Section | Description |
|---|---|
| /settings/WEB/server | Web server |
| /settings/WEB/server/log | Log configuration |
| /settings/WEB/server/results | Passive result cache |
| /settings/WEB/server/roles | Web server roles |
| /settings/WEB/server/users | Web server users |
| /settings/default | Default values |
Web server ¶
Section for WEB (WEBServer.dll) (check_WEB) protocol options.
| Key | Default Value | Description |
|---|---|---|
| allow anonymous access | false | ALLOW ANONYMOUS ACCESS |
| allow insecure | false | ALLOW INSECURE (CLEARTEXT HTTP) |
| 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) |
| cache allowed hosts | true | Cache list of allowed hosts |
| certificate | ${certificate-path}/certificate.pem | TLS Certificate |
| certificate key | TLS private key | |
| disable admin user | false | DISABLE ADMIN USER |
| legacy query auth user agents | Icinga/check_nscp_api | LEGACY QUERY-STRING AUTH ALLOWLIST |
| password | Password | |
| port | 8443 | Server port |
| threads | 10 | Server threads |
# Section for WEB (WEBServer.dll) (check_WEB) protocol options.
[/settings/WEB/server]
allow anonymous access=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
disable admin user=false
legacy query auth user agents=Icinga/check_nscp_api
port=8443
threads=10
ALLOW ANONYMOUS ACCESS ¶
When false (the default) any role named `anonymous` registered via /settings/WEB/server/roles is ignored and the WEB server never answers an unauthenticated request. Set to true only if you intentionally want to expose endpoints (via the `anonymous` role grants) without authentication.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | allow anonymous access |
| Default value: | false |
Sample:
[/settings/WEB/server]
# ALLOW ANONYMOUS ACCESS
allow anonymous access=false
ALLOW INSECURE (CLEARTEXT HTTP) ¶
When false (the default) the WEB server refuses to start if the TLS certificate is missing, rather than silently serving HTTP in clear. Set to true to explicitly accept unencrypted HTTP when no certificate is present - session tokens and Basic-auth credentials will then be transmitted unencrypted, so only do this behind a TLS-terminating proxy or on a trusted loopback interface.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | allow insecure |
| Default value: | false |
Sample:
[/settings/WEB/server]
# ALLOW INSECURE (CLEARTEXT HTTP)
allow insecure=false
Allowed hosts ¶
A comma separated list of allowed hosts. You can use netmasks (/ syntax) or * to create ranges.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | allowed hosts |
| Default value: | 127.0.0.1 |
Sample:
[/settings/WEB/server]
# Allowed hosts
allowed hosts=127.0.0.1
AUTH RATE LIMIT (BLOCK SECONDS) ¶
How long an IP stays blocked when it hits `auth rate limit max failures` consecutive failures. Default 60 s. A further block doubles the wait - up to an hour - only when that IP burned its whole failure budget at machine speed (faster than one attempt every two seconds on average); a slower run, such as a monitoring client retrying a stale password, keeps the base delay however long it goes on, so one broken client cannot lock everyone sharing its address (behind NAT or a proxy) out for hours. The escalation resets on a successful authentication, or after an hour of quiet. A value of an hour or more is already longer than any escalated block and is used as configured, without doubling.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | auth rate limit block seconds |
| Default value: | 60 |
Sample:
[/settings/WEB/server]
# AUTH RATE LIMIT (BLOCK SECONDS)
auth rate limit block seconds=60
AUTH RATE LIMIT (BLOCK SECONDS) ¶
How long an IP stays blocked after hitting `auth rate limit max failures` consecutive failures. Default 60 s.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | auth rate limit block seconds |
| Default value: | 60 |
Sample:
[/settings/WEB/server]
# AUTH RATE LIMIT (BLOCK SECONDS)
auth rate limit block seconds=60
AUTH RATE LIMIT (FAILURES) ¶
How many consecutive failed authentication attempts from one client IP trigger the block. Default 10. Set to 0 to disable the limiter entirely (useful for integration test harnesses that intentionally probe failed auth).
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | auth rate limit max failures |
| Default value: | 10 |
Sample:
[/settings/WEB/server]
# AUTH RATE LIMIT (FAILURES)
auth rate limit max failures=10
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/WEB/server |
| Key: | cache allowed hosts |
| Default value: | true |
Sample:
[/settings/WEB/server]
# Cache list of allowed hosts
cache allowed hosts=true
TLS Certificate ¶
Ssl certificate to use for the ssl server
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | certificate |
| Default value: | ${certificate-path}/certificate.pem |
Sample:
[/settings/WEB/server]
# TLS Certificate
certificate=${certificate-path}/certificate.pem
TLS private key ¶
The private key for the certificate if not in the same file
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | certificate key |
| Default value: | N/A |
Sample:
[/settings/WEB/server]
# TLS private key
certificate key=
DISABLE ADMIN USER ¶
When true, suppress the built-in `admin` user entirely. The default admin is not seeded on first boot, any pre-existing `admin` entry in /settings/WEB/server/users is ignored at load time, and the fallback that auto-creates admin when no users are configured is skipped. Use this when you want the WEB server up for monitoring (queries, metrics, anonymous endpoints) but do NOT want any account that can remotely reconfigure the host - even if credentials are compromised. Define your own read-only users under /settings/WEB/server/users (or rely on `allow anonymous access` with a tightly-scoped `anonymous` role) so something remains callable.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | disable admin user |
| Default value: | false |
Sample:
[/settings/WEB/server]
# DISABLE ADMIN USER
disable admin user=false
LEGACY QUERY-STRING AUTH ALLOWLIST ¶
Comma-separated list of User-Agent substrings (case-insensitive) for clients allowed to authenticate via the legacy `?password=…` / `?TOKEN=…` query-string mechanism. The fallback was removed for security in 340b8db1 because URL parameters leak into browser history, proxy logs and Referer headers. Defaults to ‘Icinga/check_nscp_api’ so Icinga’s bundled check_nscp_api plugin keeps working without admitting any other client that happens to mention Icinga in its User-Agent. Set to empty string to disable the fallback entirely.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | legacy query auth user agents |
| Default value: | Icinga/check_nscp_api |
Sample:
[/settings/WEB/server]
# LEGACY QUERY-STRING AUTH ALLOWLIST
legacy query auth user agents=Icinga/check_nscp_api
Password ¶
Password used to authenticate against server
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | password |
| Default value: | N/A |
Sample:
[/settings/WEB/server]
# Password
password=
Server port ¶
Port to use for WEB server.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | port |
| Default value: | 8443 |
Sample:
[/settings/WEB/server]
# Server port
port=8443
Server threads ¶
The number of threads in the sever response pool.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server |
| Key: | threads |
| Default value: | 10 |
Sample:
[/settings/WEB/server]
# Server threads
threads=10
Log configuration ¶
Configure which messages from the web server are logged.
| Key | Default Value | Description |
|---|---|---|
| debug | false | Log debug |
| error | true | Log errors |
| info | false | Log info |
# Configure which messages from the web server are logged.
[/settings/WEB/server/log]
debug=false
error=true
info=false
Log debug ¶
Enable logging of debug messages from the web server.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/log |
| Key: | debug |
| Default value: | false |
Sample:
[/settings/WEB/server/log]
# Log debug
debug=false
Log errors ¶
Enable logging of errors from the web server.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/log |
| Key: | error |
| Default value: | true |
Sample:
[/settings/WEB/server/log]
# Log errors
error=true
Log info ¶
Enable logging of info messages from the web server.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/log |
| Key: | info |
| Default value: | false |
Sample:
[/settings/WEB/server/log]
# Log info
info=false
Passive result cache ¶
Available on Windows only.
Configure the channel the web server listens on for passive check results and how long they are kept.
| Key | Default Value | Description |
|---|---|---|
| channel | WEB | PASSIVE RESULT CHANNEL |
| clear on poll | true | DRAIN THE CACHE ON A POLL |
| enabled | false | ENABLE THE PASSIVE RESULT CACHE |
| max age | 0 | PASSIVE RESULT CACHE MAX AGE |
| max entries | 1000 | PASSIVE RESULT CACHE SIZE |
| mode | last | WHICH RESULT TO KEEP PER KEY |
| primary index | ${host}/${alias-or-command} | PASSIVE RESULT CACHE KEY |
# Configure the channel the web server listens on for passive check results and how long they are kept.
[/settings/WEB/server/results]
channel=WEB
clear on poll=true
enabled=false
max age=0
max entries=1000
mode=last
primary index=${host}/${alias-or-command}
PASSIVE RESULT CHANNEL ¶
The submission channel the web server registers and caches results from. Anything submitted here (by the Scheduler, by check_and_forward, by a relaying client, …) is kept in memory and served by the /api/v2/results REST endpoints, so a monitoring system that cannot be reached from this host can poll the results out instead. Set to an empty string to register no channel and disable the cache entirely. Read when the web server starts: a channel cannot be registered or moved by a settings reload, so changing this needs a service restart.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | channel |
| Default value: | WEB |
Sample:
[/settings/WEB/server/results]
# PASSIVE RESULT CHANNEL
channel=WEB
DRAIN THE CACHE ON A POLL ¶
When true (the default) GET /api/v2/results removes the results it returns, so the next poll reports what has happened since this one rather than repeating it - this is what makes `mode = worst` mean “worst since the last poll”. Only what a poll actually returns is dropped, so a filtered poll cannot discard results its caller never saw. Set to false when several consumers poll the same agent, or for a dashboard that must not consume what it displays; results then stay until they are replaced, expire or are deleted. Fetching a single result by key is a lookup rather than a poll and never drains.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | clear on poll |
| Default value: | true |
Sample:
[/settings/WEB/server/results]
# DRAIN THE CACHE ON A POLL
clear on poll=true
ENABLE THE PASSIVE RESULT CACHE ¶
When false (the default) the web server registers no submission channel, caches nothing and answers the /api/v2/results endpoints with 503. Set to true to have the agent accept passive results and hold them for a monitoring system to poll. Read when the web server starts: turning the cache on needs a service restart, since a submission channel cannot be registered by a settings reload. Turning it off does take effect on a reload (and empties the cache).
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | enabled |
| Default value: | false |
Sample:
[/settings/WEB/server/results]
# ENABLE THE PASSIVE RESULT CACHE
enabled=false
PASSIVE RESULT CACHE MAX AGE ¶
Drop cached results that have not been updated for this many seconds. 0 (the default) keeps them until they are replaced or the service restarts. Note that results are never hidden merely for being stale - every result carries an `age` field - so this is about bounding memory, not about deciding what counts as current.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | max age |
| Default value: | 0 |
Sample:
[/settings/WEB/server/results]
# PASSIVE RESULT CACHE MAX AGE
max age=0
PASSIVE RESULT CACHE SIZE ¶
How many distinct keys to keep. Since a repeat result for a key replaces the previous one, this only bites when results arrive under ever-changing keys; the least recently updated entry is then dropped. 0 is treated as 1.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | max entries |
| Default value: | 1000 |
Sample:
[/settings/WEB/server/results]
# PASSIVE RESULT CACHE SIZE
max entries=1000
WHICH RESULT TO KEEP PER KEY ¶
Only one result is kept per key, and this decides which one when a second arrives. `last` (the default) keeps the newest, so a recovery replaces the problem before it. `worst` keeps the most severe, so a CRITICAL that recovers before the next poll is still reported (an equally severe result still replaces it, keeping the message current). Severity is ordered as elsewhere in NSClient++: OK < WARNING < CRITICAL < UNKNOWN.
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | mode |
| Default value: | last |
Sample:
[/settings/WEB/server/results]
# WHICH RESULT TO KEEP PER KEY
mode=last
PASSIVE RESULT CACHE KEY ¶
The key each cached result is stored under: a new result replaces the previous result carrying the same key. Can be any string, optionally including ${host} (the submitting host), ${source} (the raw sender id), ${channel}, ${command}, ${alias} and ${alias-or-command} (alias if set, otherwise command).
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/results |
| Key: | primary index |
| Default value: | ${host}/${alias-or-command} |
Sample:
[/settings/WEB/server/results]
# PASSIVE RESULT CACHE KEY
primary index=${host}/${alias-or-command}
Web server roles ¶
A list of roles and with coma separated list of access rights.
| Key | Default Value | Description |
|---|---|---|
| client | public,info.get,info.get.version,queries.list,queries.get,queries.execute,aliases.list,login.get,modules.list | Role for read + run checks (queries.execute can run side-effecting commands) |
| full | * | Role for Full access |
| legacy | legacy,login.get | Role for legacy API |
| monitoring | public,queries.execute,aliases.list,login.get,metrics.get | Role for checks and queries only |
# A list of roles and with coma separated list of access rights.
[/settings/WEB/server/roles]
client=public,info.get,info.get.version,queries.list,queries.get,queries.execute,aliases.list,login.get,modules.list
full=*
legacy=legacy,login.get
monitoring=public,queries.execute,aliases.list,login.get,metrics.get
Role for read + run checks (queries.execute can run side-effecting commands) ¶
Default role for read + run checks (queries.execute can run side-effecting commands)
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/roles |
| Key: | client |
| Default value: | public,info.get,info.get.version,queries.list,queries.get,queries.execute,aliases.list,login.get,modules.list |
Sample:
[/settings/WEB/server/roles]
# Role for read + run checks (queries.execute can run side-effecting commands)
client=public,info.get,info.get.version,queries.list,queries.get,queries.execute,aliases.list,login.get,modules.list
Role for read only ¶
Default role for read only
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/roles |
| Key: | client |
| Default value: | public,info.get,info.get.version,queries.list,queries.get,queries.execute,aliases.list,login.get,modules.list |
Sample:
[/settings/WEB/server/roles]
# Role for read only
client=public,info.get,info.get.version,queries.list,queries.get,queries.execute,aliases.list,login.get,modules.list
Role for Full access ¶
Default role for Full access
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/roles |
| Key: | full |
| Default value: | * |
Sample:
[/settings/WEB/server/roles]
# Role for Full access
full=*
Role for legacy API ¶
Default role for legacy API
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/roles |
| Key: | legacy |
| Default value: | legacy,login.get |
Sample:
[/settings/WEB/server/roles]
# Role for legacy API
legacy=legacy,login.get
Role for checks and queries only ¶
Default role for checks and queries only
| Key | Description |
|---|---|
| Path: | /settings/WEB/server/roles |
| Key: | monitoring |
| Default value: | public,queries.execute,aliases.list,login.get,metrics.get |
Sample:
[/settings/WEB/server/roles]
# Role for checks and queries only
monitoring=public,queries.execute,aliases.list,login.get,metrics.get
Web server users ¶
Users which can access the REST API
This is a section of objects. This means that you will create objects below this point by adding sections which all look the same.
Keys:
| Key | Default Value | Description |
|---|---|---|
| alias | ALIAS | |
| is template | false | IS TEMPLATE |
| parent | default | PARENT |
| password | PASSWORD | |
| role | ROLE |
Sample:
# An example of a Web server users section
[/settings/WEB/server/users/sample]
#alias=...
is template=false
parent=default
#password=...
#role=...
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 | |
| 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 used to authenticate against server
| Key | Description |
|---|---|
| Path: | /settings/default |
| Key: | password |
| Default value: | N/A |
Sample:
[/settings/default]
# Password
password=
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