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 and allow using the commands you need to ass WEBServer = enabled to the [/modules] section in nsclient.ini:

[/modules]
WEBServer = enabled

Configuration

Path / Section	Description
/settings/default	Default values
/settings/WEB/server	Web server
/settings/WEB/server/log	Log configuration
/settings/WEB/server/roles	Web server roles
/settings/WEB/server/users	Web server users

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

Web server

Section for WEB (WEBServer.dll) (check_WEB) protocol options.

Key	Default Value	Description
allow anonymous access	false	ALLOW ANONYMOUS ACCESS
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
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

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

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