1nsca-ng.cfg(5)                The NSCA-ng Manual                nsca-ng.cfg(5)
2
3
4

NAME

6       nsca-ng.cfg - NSCA-ng server configuration file
7

SYNOPSIS

9       /etc/nsca-ng.cfg
10

DESCRIPTION

12       The nsca-ng(8) process reads configuration data from the file specified
13       with -c on the command line or from /etc/nsca-ng.cfg.
14
15   File Format
16       Zero or more global settings and one or more authorizations must be de‐
17       fined in the configuration file (see the Global Settings subsection and
18       the Authorizations subsection, respectively).  They may appear in arbi‐
19       trary order.  An authorization is specified using the authorize keyword
20       followed by a (possibly quoted) client identity string and a  brace-en‐
21       closed  block of corresponding authorization settings.  However, an au‐
22       thorization setting may also be specified as a global  setting  outside
23       of these authorize sections.  In this case, it serves as a global fall‐
24       back for authorization sections that don't define the setting in  ques‐
25       tion.
26
27       Global  settings and authorization settings are defined by specifying a
28       variable name followed by an equals sign (“=”) and a value (or possibly
29       a  list of values).  Values can be strings, integers, or floating-point
30       numbers.  Strings have to be enclosed in single  or  double  quotes  if
31       they  contain  whitespace  characters, hash mark characters, or literal
32       quotation marks.  Otherwise, quoting is optional.  To specify a literal
33       single  or  double  quote in a string, either escape it by preceding it
34       with a backslash (“\”) or quote the string using the other quote  char‐
35       acter.  A literal backslash must be preceded with a second backslash if
36       the string is enclosed in double quotes.
37
38       A variable can be set to the value of an environment variable by speci‐
39       fying  ${FOO},  where FOO is the name of the environment variable.  The
40       same can be done by specifying ${FOO:-bar}, except that in  this  case,
41       the value bar will be assigned when the environment variable FOO is not
42       set.
43
44       Any whitespace surrounding tokens is ignored.  Empty lines and comments
45       are  also  ignored.  Comments are introduced with a hash mark character
46       (“#”) and span to the end of the line.  If the last character of a line
47       is  a backslash (“\”), the subsequent line is treated as a continuation
48       of the current line (and the backslash is otherwise ignored).
49
50       The special directive include("file") tells  nsca-ng(8)  to  treat  the
51       contents of the specified file as if those contents had appeared at the
52       point where this directive appears.  If a directory  is  specified  in‐
53       stead  of  a file, all files with a .cfg or .conf extension in this di‐
54       rectory and all subdirectories will be included.   Symbolic  links  are
55       followed.
56
57       In  the  following subsections, the type of each value is denoted after
58       an equals sign in angle brackets.
59
60   Global Settings
61       The nsca-ng(8) server recognizes the following global variables.
62
63       chroot = <string>
64              On startup, perform a chroot(2) operation to the  specified  di‐
65              rectory.   By  default,  nsca-ng(8) does not call chroot(2).  If
66              this directive is used, the command_file, pid_file, and temp_di‐
67              rectory must be specified relative to this directory.
68
69       command_file = <string>
70              Submit  monitoring  commands  to  the specified path name.  This
71              should be the named pipe (FIFO) that  Nagios  (or  a  compatible
72              monitoring  solution)  checks  for external commands to process.
73              The default is /var/nagios/rw/nagios.cmd.  The  specified  value
74              will be overridden if nsca-ng(8) is called with the -C option.
75
76       listen = <string>
77              Bind to the specified IP address or host name.  The default set‐
78              ting is “*”, which tells nsca-ng(8) to listen on  all  available
79              interfaces.   A  colon  (“:”) followed by a service name or port
80              number may be appended to override the default port (5668)  used
81              by  the  nsca-ng(8) server.  The specified value will be ignored
82              if nsca-ng(8) is called with the -b option, of if it  is  socket
83              activated by systemd(1).
84
85       log_level = <integer>
86              Use  the specified log level, which must be an integer value be‐
87              tween 0 and 5 inclusive.  A value of 0 tells nsca-ng(8) to  gen‐
88              erate  only  fatal  error  messages, 1 adds non-fatal error mes‐
89              sages, 2 adds warnings, 3 additionally spits out every submitted
90              command  (plus  startup  and shutdown notices), 4 also logs each
91              message sent or received at the protocol level, and 5  generates
92              additional debug output.  The default log level is 3.  The spec‐
93              ified value will be overridden if nsca-ng(8) is called with  the
94              -l option.
95
96       max_command_size = <integer>
97              Refuse  monitoring commands (including check result submissions)
98              which are longer than the specified number  of  bytes.   Setting
99              this  variable to 0 tells nsca-ng(8) to accept commands of arbi‐
100              trary length.  The default value is 16384.
101
102       max_queue_size = <integer>
103              Don't queue more than the specified number of megabytes worth of
104              monitoring  commands  while Nagios isn't running (or not reading
105              the command file).  When the amount of  available  data  exceeds
106              this  threshold,  the queued data is thrown away.  If this vari‐
107              able is set to 0, nsca-ng(8) queues an unlimited amount of  data
108              (until  it  exits  due  to  running out of memory).  The default
109              value is 1024 (i.e., 1 gigabyte).
110
111       pid_file = <string>
112              During startup, try to create and lock the  specified  file  and
113              write the process ID of the nsca-ng(8) daemon into it.  Bail out
114              if another process holds a lock on that file.   By  default,  no
115              such  PID file is written.  The specified value will be overrid‐
116              den if nsca-ng(8) is called with the -p option.
117
118       temp_directory = <string>
119              Write temporary files to  the  specified  directory.   Temporary
120              files  are  only  written  if clients submit very large commands
121              (which cannot be written to the named pipe atomically).   It  is
122              recommended  to  specify  a  directory which resides on a memory
123              file system.  By default, /tmp is used.
124
125       timeout = <floating-point>
126              Close the connection if a client didn't show  any  activity  for
127              the  specified  number of seconds.  If this value is set to 0.0,
128              nsca-ng(8) won't enforce connection timeouts.  The default  set‐
129              ting is 60.0 seconds.
130
131       tls_ciphers = <string>
132              Limit the acceptable TLS-PSK cipher suites to the specified list
133              of ciphers.  The format of the string is described  in  the  ci‐
134              phers(1)  manual.   By  default,  the  ciphers  in the list PSK-
135              AES256-CBC-SHA:PSK-AES128-CBC-SHA:PSK-3DES-EDE-CBC-SHA:PSK-
136              RC4-SHA will be accepted.
137
138       user = <string>
139              Switch to the specified user, and to the groups the user belongs
140              to.  This is done early on startup: after the configuration file
141              has  been  read,  but before the listening socket and (possibly)
142              the PID file are created.  By default, nsca-ng(8) runs with  the
143              privileges of the invoking user.
144
145   Authorizations
146       As mentioned above, an authorization section is introduced with the au‐
147       thorize keyword and a client identity field followed by a  brace-delim‐
148       ited  block  of  one or more authorization settings.  A client provides
149       its identity during the connection handshake.  The server uses the pro‐
150       vided  identity  string for looking up the authorize section applicable
151       to the client.  The corresponding section, if any, defines the  authen‐
152       tication  and authorization settings for the client in question.  If no
153       section explicitly defined for this client identity  is  found,  but  a
154       section  for  the special client identity "*" (including the quotes) is
155       defined, this section is used as a fallback.  Note that no other  wild‐
156       card  characters  are available, and that the “*” character has no spe‐
157       cial meaning in the client identity field except when specified exactly
158       as described.
159
160       Within  the  brace-delimited  block of an authorization section, values
161       may be assigned to the variables listed below.  The pattern strings as‐
162       signed  to  the  commands, hosts, and services variables are POSIX “ex‐
163       tended” regular expressions, but with an implicit “^” at the  beginning
164       and “$” at the end of the patterns.  Multiple patterns can be specified
165       as a brace-enclosed, comma-separated list; check results  and  commands
166       will  then  be  accepted  if  they match any of the specified patterns.
167       Commands and check results will be rejected unless these  settings  au‐
168       thorize the client to submit them.
169
170       commands = <(list of) string(s)>
171              Match the specified regular expression(s) against submitted mon‐
172              itoring commands and accept commands that match any of these ex‐
173              pressions.   The  patterns  are matched against the full command
174              string supplied by the client, except for the leading  bracketed
175              timestamp and any whitespace following that timestamp.
176
177       hosts = <(list of) string(s)>
178              Match  the  specified  regular  expression(s)  against the “host
179              name” field of  client-supplied  PROCESS_HOST_CHECK_RESULT  com‐
180              mands  and  accept  such commands if they match any of these ex‐
181              pressions.
182
183       password = <string>
184              Reject connections from clients that  don't  use  the  specified
185              password.  This setting is mandatory.
186
187       services = <(list of) string(s)>
188              Match  the  specified regular expression(s) against the “service
189              description” field of client-supplied  PROCESS_SERVICE_CHECK_RE‐
190              SULT  commands  and  accept  such  commands if they match any of
191              these expressions.  If a specified string includes one  or  more
192              at  signs  (“@”),  only  the part preceding the last of these at
193              signs is matched against the “service description”  field.   The
194              part  following this at sign is used as a separate pattern which
195              is matched against the “host name” field of the same command.  A
196              service  check result is then accepted only if both matches suc‐
197              ceed for a given command.
198

EXAMPLES

200       The /etc/nsca-ng.cfg file might look similar to the following example.
201
202              user = "nagios"
203              chroot = "/var/nagios" # Other paths are relative to this one!
204              command_file = "/rw/nagios.cmd"
205              pid_file = "/run/nsca-ng.pid"
206              temp_directory = "/dev/shm"
207              listen = "monitoring.example.com:5668"
208              tls_ciphers = "PSK-AES256-CBC-SHA"
209              log_level = 3
210              max_command_size = 65536
211              max_queue_size = 128
212              timeout = 15.0
213
214              #
215              # Authenticated "root" clients may submit arbitrary check
216              # results and any other monitoring commands (see:
217              # <http://nagios.org/developerinfo/externalcommands/>).
218              #
219              authorize "root" {
220                  password = "g3m25sMCUAO4NecZGld1H4xcJ9uDWvhH"
221                  commands = ".*"
222              }
223
224              #
225              # Authenticated "checker" clients may submit arbitrary check
226              # results, but no other commands.
227              #
228              authorize "checker" {
229                  password = "ilzNanlE9XjMLdjrMkXnk09XBCTFQrj5"
230                  hosts = ".*"
231                  services = ".*"
232              }
233
234              #
235              # Authenticated "web-checker" clients may submit check results
236              # for arbitrary services on hosts whose names begin with "www".
237              #
238              authorize "web-checker" {
239                  password = "m2uaIWwiq3AIqN55m3QdjwptkU1Q4Oov"
240                  services = ".+@www.*"
241              }
242
243              #
244              # Authenticated "nsca-checker" clients may talk to the NSCA-ng
245              # server, but may not submit anything to Nagios.
246              #
247              authorize "nsca-checker" {
248                  password = "ceOKwxpz14lKXroC4yUjJZbov6VAyKuT"
249              }
250
251              #
252              # Other authenticated clients may submit check results for the
253              # "disk", "swap", and "load" services on arbitrary hosts.
254              #
255              authorize "*" {
256                  password = "awHW5vxr3DcA9EvcUC9T3a90QfEexsWd"
257                  services = {
258                      "disk",
259                      "swap",
260                      "load"
261                  }
262              }
263

CAVEATS

265       Please set the permissions appropriately to make sure that only  autho‐
266       rized users can access the /etc/nsca-ng.cfg file.
267

SEE ALSO

269       nsca-ng(8), send_nsca(8), send_nsca.cfg(5), regex(7)
270
271       http://www.nagios.org/developerinfo/externalcommands/
272

AUTHOR

274       Holger Weiss <holger@weiss.in-berlin.de>
275
276
277
278Version 1.6                     March 19, 2019                  nsca-ng.cfg(5)
Impressum