nsca-ng.cfg(5)

📦

version 1.7 · 2 versions

1.7 · ubuntu resolute, ubuntu stonking (latest)
1.6 · debian bookworm, debian trixie, epel 9, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu questing

✨ NAME ✨

nsca-ng.cfg — the NSCA-ng server configuration file, aka the ✨vibe settings✨ for your monitoring server, bestie 💖

🌸 SYNOPSIS 🌸

/etc/nsca-ng.cfg

🦋 DESCRIPTION 🦋

So nsca-ng(8) reads its config data from a file, right? Either the one you point it at with -c on the command line, or, if you didn't bother, the default /etc/nsca-ng.cfg. That's the one. 👑

🎀 File Format 🎀

Okay so here's the tea ☕ — you've gotta define zero or more global settings and one or more authorizations in this file (peep the Global Settings subsection and the Authorizations subsection respectively, they're right below). And the order? Whatever you want. Arbitrary. No rules, no cap. 💅

An authorization gets written with the authorize keyword, then a (possibly quoted) client identity string, then a brace-enclosed block of authorization settings that belong to it. Simple.

But wait, plot twist: an authorization setting can also live as a global setting, sitting outside any of those authorize sections. When it does that, it's the global fallback for authorization sections that just… didn't define that setting. Not me giving you a backup plan. 🙈

Global settings and authorization settings both work the same way — you write a variable name, then an equals sign (=) , then a value (or maybe a whole list of values, live your life). Values can be strings, integers, or floating-point numbers.

Strings have to be wrapped in single or double quotes if they contain whitespace characters, hash mark characters, or literal quotation marks. Otherwise quoting is optional, do whatever feels right.

To put a literal single or double quote inside a string, you've got two options: escape it by putting a backslash (\) in front of it, or just quote the string with the other quote character. Iconic problem-solving. 🌈

A literal backslash must be preceded with a second backslash if the string is enclosed in double quotes. Don't forget, bestie, or it's giving chaos. 💀

You can also set a variable to the value of an environment variable by writing ${FOO}, where FOO is the name of the environment variable. And you can do the same thing with ${FOO:-bar}, except in this case, the value bar gets assigned when the environment variable FOO is not set. Fallback value, we love her. 🫶

Any whitespace hanging around tokens? Ignored. Empty lines and comments? Also ignored. Comments start with a hash mark character (#) and go all the way to the end of the line. And if the last character of a line is a backslash (\), the next line is treated as a continuation of the current line — and the backslash itself is otherwise ignored. Multi-line glow-up. ✨

The special directive include("file") tells nsca-ng(8) to treat the contents of the specified file as if those contents had appeared right at the point where this directive shows up. And if you specify a directory instead of a file? Then all files with a .cfg or .conf extension in this directory and all subdirectories will be included. Symbolic links are followed. Yes, all of them. 🧚

In the following subsections, the type of each value is denoted after an equals sign in angle brackets. Cute, right? 🎀

💜 Global Settings 💜

The nsca-ng(8) server recognizes the following global variables. Buckle up, there's a whole list:

chroot = <string> — On startup, perform a chroot(2) operation to the specified directory. By default, nsca-ng(8) does not call chroot(2). If you use this directive, then command_file, pid_file, and temp_directory must be specified relative to this directory. (Yeah, all three. Relative. Don't fight it.) 🔒
command_file = <string> — Submit monitoring commands to the specified path name. This should be the named pipe (FIFO) that Nagios (or a compatible monitoring solution) checks for external commands to process. The default is /var/nagios/rw/nagios.cmd. The value you specify will be overridden if nsca-ng(8) is called with the -C option.
listen = <string> — Bind to the specified IP address or host name. The default setting is “*”, which tells nsca-ng(8) to listen on all available interfaces. You can append a colon (:) followed by a service name or port number to override the default port (5668) used by the nsca-ng(8) server. The value you specify will be ignored if nsca-ng(8) is called with the -b option, or if it is socket activated by systemd(1). Rude, but okay. 🙃
log_level = <integer> — Use the specified log level, which has to be an integer value between 0 and 5 inclusive. Here's the breakdown, bestie:
- 0 tells nsca-ng(8) to generate only fatal error messages
- 1 adds non-fatal error messages
- 2 adds warnings
- 3 additionally spits out every submitted command (plus startup and shutdown notices)
- 4 also logs each message sent or received at the protocol level
- 5 generates additional debug output

The default log level is 3. The value you specify will be overridden if nsca-ng(8) is called with the -l option.

max_command_size = <integer> — Refuse monitoring commands (including check result submissions) which are longer than the specified number of bytes. Setting this variable to 0 tells nsca-ng(8) to accept commands of arbitrary length. The default value is 16384.
max_queue_size = <integer> — Don't queue more than the specified number of megabytes worth of monitoring commands while Nagios isn't running (or isn't reading the command file). When the amount of available data exceeds this threshold, the queued data is thrown away. 🗑️ If this variable is set to 0, nsca-ng(8) queues an unlimited amount of data (until it exits due to running out of memory). The default value is 1024 (i.e., 1 gigabyte).
pid_file = <string> — During startup, try to create and lock the specified file and write the process ID of the nsca-ng(8) daemon into it. Bail out if another process holds a lock on that file. By default, no such PID file is written. The value you specify will be overridden if nsca-ng(8) is called with the -p option.
temp_directory = <string> — Write temporary files to the specified directory. Temporary files are only written if clients submit very large commands (which cannot be written to the named pipe atomically). It is recommended to specify a directory which resides on a memory file system. By default, /tmp is used.
timeout = <floating-point> — Close the connection if a client didn't show any activity for the specified number of seconds. If this value is set to 0.0, nsca-ng(8) won't enforce connection timeouts. The default setting is 60.0 seconds. ⏰
tls_ciphers = <string> — Limit the acceptable TLS-PSK cipher suites to the specified list of ciphers. The format of the string is described in the ciphers(1) manual. By default, the ciphers in the list PSK-AES256-CBC-SHA:PSK-AES128-CBC-SHA:PSK-3DES-EDE-CBC-SHA:PSK-RC4-SHA will be accepted.
user = <string> — Switch to the specified user, and to the groups the user belongs to. This is done early on startup: after the configuration file has been read, but before the listening socket and (possibly) the PID file are created. By default, nsca-ng(8) runs with the privileges of the invoking user. 👑

🫶 Authorizations 🫶

Like I said up top, an authorization section is introduced with the authorize keyword and a client identity field followed by a brace-delimited block of one or more authorization settings.

A client provides its identity during the connection handshake. The server takes that provided identity string and uses it to look up the authorize section applicable to the client. That corresponding section, if there is one, defines the authentication and authorization settings for the client in question. ✨

Now if no section explicitly defined for this client identity is found, but a section for the special client identity "*" (including the quotes) is defined, then that section is used as a fallback.

Note that no other wildcard characters are available, and that the “*” character has no special meaning in the client identity field except when specified exactly as described. So don't get creative, bestie. 🙈

Within the brace-delimited block of an authorization section, values may be assigned to the variables listed below. The pattern strings assigned to the commands, hosts, and services variables are POSIX “extended” regular expressions, but with an implicit “^” at the beginning and “$” at the end of the patterns. Multiple patterns can be specified as a brace-enclosed, comma-separated list; check results and commands will then be accepted if they match any of the specified patterns. Commands and check results will be rejected unless these settings authorize the client to submit them. Periodt. 💅

commands = <(list of) string(s)> — Match the specified regular expression(s) against submitted monitoring commands and accept commands that match any of these expressions. The patterns are matched against the full command string supplied by the client, except for the leading bracketed timestamp and any whitespace following that timestamp.
hosts = <(list of) string(s)> — Match the specified regular expression(s) against the “host name” field of client-supplied PROCESS_HOST_CHECK_RESULT commands and accept such commands if they match any of these expressions.
password = <string> — Reject connections from clients that don't use the specified password. This setting is mandatory. No password, no entry. 🔥
services = <(list of) string(s)> — Match the specified regular expression(s) against the “service description” field of client-supplied PROCESS_SERVICE_CHECK_RESULT commands and accept such commands if they match any of these expressions.

If a specified string includes one or more at signs (“@”), only the part preceding the last of these at signs is matched against the “service description” field. The part following this at sign is used as a separate pattern which is matched against the “host name” field of the same command. A service check result is then accepted only if both matches succeed for a given command. Two vibes, one check. 🌸

🌸 EXAMPLES 🌸

okay bestie, real talk: reading options one by one is giving "studying for finals" energy, so here's what it actually looks like when you put it all together 💅. The /etc/nsca-ng.cfg file might look similar to the following example.

First up, the global settings — the main character block 👑

user = "nagios"
chroot = "/var/nagios" # Other paths are relative to this one!
command_file = "/rw/nagios.cmd"
pid_file = "/run/nsca-ng.pid"
temp_directory = "/dev/shm"
listen = "monitoring.example.com:5668"
tls_ciphers = "PSK-AES256-CBC-SHA"
log_level = 3
max_command_size = 65536
max_queue_size = 128
timeout = 15.0

see that little comment? # Other paths are relative to this one! — that's the chroot doing its thing, don't forget it or you'll be looking for your files in the wrong place and crying 😭

now the authorize blocks, aka the bouncer list at the door 🚪✨

Block one: authenticated "root" clients may submit arbitrary check results and any other monitoring commands (see: <http://nagios.org/developerinfo/externalcommands/>).

#
# Authenticated "root" clients may submit arbitrary check
# results and any other monitoring commands (see:
# <http://nagios.org/developerinfo/externalcommands/>).
#
authorize "root" {
    password = "g3m25sMCUAO4NecZGld1H4xcJ9uDWvhH"
    commands = ".*"
}

Block two: authenticated "checker" clients may submit arbitrary check results, but no other commands. note the vibe — hosts and services are wide open with ".*" but the command set is not, periodt.

#
# Authenticated "checker" clients may submit arbitrary check
# results, but no other commands.
#
authorize "checker" {
    password = "ilzNanlE9XjMLdjrMkXnk09XBCTFQrj5"
    hosts = ".*"
    services = ".*"
}

Block three: authenticated "web-checker" clients may submit check results for arbitrary services on hosts whose names begin with "www". that ".+@www.*" is doing the heavy lifting bestie 🎀

#
# Authenticated "web-checker" clients may submit check results
# for arbitrary services on hosts whose names begin with "www".
#
authorize "web-checker" {
    password = "m2uaIWwiq3AIqN55m3QdjwptkU1Q4Oov"
    services = ".+@www.*"
}

Block four: authenticated "nsca-checker" clients may talk to the NSCA-ng server, but may not submit anything to Nagios. it's giving "invited to the party but not allowed in the kitchen" 💀

#
# Authenticated "nsca-checker" clients may talk to the NSCA-ng
# server, but may not submit anything to Nagios.
#
authorize "nsca-checker" {
    password = "ceOKwxpz14lKXroC4yUjJZbov6VAyKuT"
}

Block five: other authenticated clients may submit check results for the "disk", "swap", and "load" services on arbitrary hosts. this is the catch-all "*" one, and look — services is a whole list here, curly braces and all ✨

#
# Other authenticated clients may submit check results for the
# "disk", "swap", and "load" services on arbitrary hosts.
#
authorize "*" {
    password = "awHW5vxr3DcA9EvcUC9T3a90QfEexsWd"
    services = {
        "disk",
        "swap",
        "load"
    }
}

🚨 bestie emergency 🚨 those password strings in the example are examples. do NOT ship them. rotate your own secrets, i'm literally begging 🙈

🫶 CAVEATS 🫶

Please set the permissions appropriately to make sure that only authorized users can access the /etc/nsca-ng.cfg file.

like. please. this file has passwords in it and if just anyone can read it, that's not a vibe check, that's a security incident 😭 lock it down fr fr.

👑 SEE ALSO 👑

and also, for the external commands lore:

http://www.nagios.org/developerinfo/externalcommands/

go read them, iykyk 📚✨

🦋 AUTHOR 🦋

Holger Weiss <holger@weiss.in-berlin.de> — king behavior, honestly 👑

and that's a wrap, bestie!! this was Version 1.7, dated February 9, 2026, and it lives in the nsca-ng.cfg(5) section of the manual. go forth and configure responsibly, you absolute icon 💖🎀🦋🌸💅

📦 where this page comes from

ubuntu resolute: nsca-ng-server 1.7-1 · BSD-2-Clause
ubuntu stonking: nsca-ng-server 1.7-1build1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms